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
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 true
Array
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 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:
🔸 yarn: 🔹 bower: 🔸 cdn: See the table for which script tag to use:Easy 👍
🔹 npm: $ npm install --save async-af
$ yarn add async-af
async-af
is no longer published to bower. To continue using it with bower, look into bower-npm-resolver
.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>
🔹 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, 🔸 scoped packages + If you use more than a few AsyncAF scoped packages in a file, you might start to build a wall of 🔹 es modules: AsyncAF as well as its scoped packages are also published as es modules. This gives an opportunity to conditionally load Using the cdn scripts as an example: or minimized for production: The script with More Complex 🤔
@async-af/map
and/or @async-af/filter
; see further instructions in the documentation for AsyncAfWrapper and AsyncAfWrapper.use.babel-plugin-transform-imports
:import
statements to pull them all in. If this is an eyesore for you, look into babel-plugin-transform-imports
and condense that ugly wall down to a single import
statement! See Wrapper/Use: Too Many 🤬 Imports!? for a tutorial.async-af
with ES6+ features in modern browsers and async-af
with ES5-compatible features in legacy browsers.
<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>
<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.
A couple notes on performance 🚀
Built on Promises
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 secs
Other 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 secs
And 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 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.
See something to improve? File an issue or see how to contribute.💙
License
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).