async-af

Working with promises or async/await?

Use AsyncAF to transform your code into beautiful asynchronous JavaScript chains, with methods similar to the ones we all know (and love! 😍) such as map, forEach, filter, reduce, and more.

Check out the docs
for all available methods. 💙

Usage

``js
const AsyncAF = require('async-af');

function getActiveUsers(userIds) {
return AsyncAF(userIds)
// map user ids to user objects with an async function
.mapAF(async userId => {
const user = await fetch(fake-game-api/users/${userId});
return user.json();
})
// filter by active users
.filterAF(user => user.isActive);
}
`

AsyncAF methods are await-able and then-able.

`js
async function sendMsgToActiveUsers(msg) {
const activeUsers = await getActiveUsers([1, 2, 3]);
// send each active user a msg in series
await AsyncAF(activeUsers).series.forEachAF(async ({id}) => {
await sendMsg(id, msg); // hypothetical msg service that's rate-limited
});
console.log('message sent!');
}

function doSomethingElseWithActiveUsers() {
return getActiveUsers([1, 2, 3]).then(activeUsers => {
// ... do something else
});
}
`

If a Promise is passed into AsyncAF, it will be settled before a method processes it.

`js
const userMsg = Promise.resolve('I\'m [restricted word] AF right now')

const msgContainsBadWord = (msg, word = '[restricted word]') => AsyncAF(msg).includesAF(word);

msgContainsBadWord(userMsg); // resolves to true
`

Array methods will settle any promises in an array before processing them.

`js
const findHighScoringUser = () => AsyncAF([
fetch('fake-game-api/users/1').then(user => user.json()), // {id: 1, name: Aiden, score: 9001, ...}
{id: 2, name: 'Bill', score: 3600, / ... /},
{id: 3, name: 'Cari', score: 5800, / ... /},
])
.findAF(({score}) => score > 9000);

findHighScoringUser(); // resolves to {id: 1, name: Aiden, score: 9001, ...}
`

Note: All 'AF' methods have an 'AF-less' alias so you can choose whether or not to make it obvious that they're AsyncAF methods.

For example:

`js
const promises = [1, 2, 3].map(n => Promise.resolve(n));

AsyncAF(promises).map(n => n * 2).filter(n => n !== 4).forEach(n => console.log(n));
// or
AsyncAF(promises).mapAF(n => n * 2).filterAF(n => n !== 4).forEachAF(n => console.log(n));
// both log 2 then 6
`

Installation 💾

Easy peasy, just

$ npm install --save async-af,

right?

⚠️ Not so fast; there's actually several ways to include AsyncAF in your project/production site from easy to more complex:

><script type="module" src="https://unpkg.com/async-af/esm/index.js"></script>
><script nomodule src="https://unpkg.com/async-af/legacy/index.js"></script>

><script type="module" src="https://unpkg.com/async-af/esm/min.js"></script>
><script nomodule src="https://unpkg.com/async-af/legacy/min.js"></script>

Despite AsyncAF's name (Async/Await Fun), its source code is written entirely without the use of async/await. Its chainable asynchronous JavaScript methods _are_, however, highly useful when _your_ code makes use of async/await or Promises. This is important for performance because transpiling an async function with babel currently results in some loooong code due to pulling in things like Facebook's regenerator and others to make it work.

Because AsyncAF instead runs your code with Promises behind the scenes, there's no need to transpile async/await in its ES6 or ES5-compatible distributions. This boils down to much smaller bundles when compared to an equivalent async library written _with_ async/await.

#### Use series wisely

The majority of AsyncAF's Array methods process promises in parallel by default. However, many methods have an option to process promises in series as well. You can tell AsyncAF to process promises in series within the next method invocation by setting a flag with series or its alias io (in order). See the documentation for series for a full list of methods this works on.

In some cases, the time it takes to resolve an AsyncAF expression won't differ; for example:

`js
import AsyncAF, {logAF} from 'async-af';
import delay from 'delay';

logAF.options({label: false});

const bools = [
() => delay(3000, {value: true}),
() => delay(2000, {value: false}),
() => delay(1000, {value: false}),
];

logAF('parallel', AsyncAF(bools).someAF(n => n()));
logAF('series', AsyncAF(bools).series.someAF(n => n()));

// series true
// in 3.000 secs
// parallel true
// in 3.000 secs
`

Other times, processing promises in parallel will be faster:

`js
const bools = [
() => delay(3000, {value: false}),
() => delay(2000, {value: true}),
() => delay(1000, {value: false}),
];

logAF('parallel', AsyncAF(bools).someAF(n => n()));
logAF('series', AsyncAF(bools).series.someAF(n => n()));

// parallel true
// in 3.000 secs
// series true
// in 5.000 secs
`

And yet other times, processing promises in series will be faster:

`js
const bools = [
() => delay(3000, {value: true}),
() => delay(4000, {value: false}),
() => delay(5000, {value: false}),
];

logAF('parallel', AsyncAF(bools).someAF(n => n()));
logAF('series', AsyncAF(bools).series.someAF(n => n()));

// series true
// in 3.000 secs
// parallel true
// in 5.000 secs
`

Being cognizant of when to use series vs. when to rely on the default parallel behavior can help increase the performance of your asynchronous code.

Another use case for series` might be if you're sending multiple requests to a rate-limited API. In that case you may not want to throw a ton of parallel requests at the API, but rather wait for each one in series.

Love AsyncAF?

See something to improve? File an issue or
see how to contribute.💙

License

(but click here or here to get into specifics).