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.
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.
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.
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 trueArray methods will settle any promises in an array before processing them.
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:
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 6Easy peasy, just
$ npm install --save async-af,
right?
Easy 👍
🔹 npm:
$ npm install --save async-af
🔸 yarn: $ yarn add async-af
🔹 bower: async-af is no longer published to bower. To continue using it with bower, look into bower-npm-resolver.
🔸 cdn: See the table for which script tag to use:
| mode | browsers | script tag |
|---|---|---|
| development | modern (ES6+) | <script src="https://unpkg.com/async-af/index.js"></script> |
| development | legacy (ES5+) | <script src="https://unpkg.com/async-af/legacy/index.js"></script> |
| production | modern (ES6+) | <script src="https://unpkg.com/async-af/min.js"></script> |
| production | legacy (ES5+) | <script src="https://unpkg.com/async-af/legacy/min.js"></script> |
More Complex 🤔
🔹 scoped packages:
Instead of pulling in the entire AsyncAF library, you can install smaller standalone packages for each of the AsyncAF methods you intend to use; for example,
@async-af/mapand/or@async-af/filter; see further instructions in the documentation for AsyncAfWrapper and AsyncAfWrapper.use.
🔸 scoped packages + babel-plugin-transform-imports:
If you use more than a few AsyncAF scoped packages in a file, you might start to build a wall of
importstatements to pull them all in. If this is an eyesore for you, look intobabel-plugin-transform-importsand condense that ugly wall down to a singleimportstatement! See Wrapper/Use: Too Many 🤬 Imports!? for a tutorial.
🔹 es modules:
AsyncAF as well as its scoped packages are also published as es modules. This gives an opportunity to conditionally load
async-afwith ES6+ features in modern browsers andasync-afwith ES5-compatible features in legacy browsers.Using the cdn scripts as an example:
<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>or minimized for production:
<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>
The script with
<script type="module">will load in any browser capable of loading es modules, while the script with<script nomodule>will act as a fallback for legacy browsers.
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:
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 secsOther times, processing promises in parallel will be faster:
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 secsAnd yet other times, processing promises in series will be faster:
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 secsBeing 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.
See something to improve? File an issue or see how to contribute.💙
AsyncAF is licensed under the MIT License, so you can pretty much use it however you want
(but click here or here to get into specifics).
