Async.js
Async is a utility module which provides straight-forward, powerful functions
for working with asynchronous JavaScript. Although originally designed for
use with Node.js and installable via npm install async
,
it can also be used directly in the browser.
Async is also installable via:
- bower:
bower install async
- component:
component install caolan/async
- jam:
jam install async
- spm:
spm install async
Async provides around 20 functions that include the usual 'functional'
suspects (map
, reduce
, filter
, each
…) as well as some common patterns
for asynchronous control flow (parallel
, series
, waterfall
…). All these
functions assume you follow the Node.js convention of providing a single
callback as the last argument of your async
function.
Quick Examples
async.map(['file1','file2','file3'], fs.stat, function(err, results){
// results is now an array of stats for each file
});
async.filter(['file1','file2','file3'], fs.exists, function(results){
// results now equals an array of the existing files
});
async.parallel([
function(){ ... },
function(){ ... }
], callback);
async.series([
function(){ ... },
function(){ ... }
]);
There are many more functions available so take a look at the docs below for a full list. This module aims to be comprehensive, so if you feel anything is missing please create a GitHub issue for it.
Common Pitfalls (StackOverflow)
Synchronous iteration functions
If you get an error like RangeError: Maximum call stack size exceeded.
or other stack overflow issues when using async, you are likely using a synchronous iterator. By synchronous we mean a function that calls its callback on the same tick in the javascript event loop, without doing any I/O or using any timers. Calling many callbacks iteratively will quickly overflow the stack. If you run into this issue, just defer your callback with async.setImmediate
to start a new call stack on the next tick of the event loop.
This can also arise by accident if you callback early in certain cases:
async.eachSeries(hugeArray, function iterator(item, callback) {
if (inCache(item)) {
callback(null, cache[item]); // if many items are cached, you'll overflow
} else {
doSomeIO(item, callback);
}
}, function done() {
//...
});
Just change it to:
async.eachSeries(hugeArray, function iterator(item, callback) {
if (inCache(item)) {
async.setImmediate(function () {
callback(null, cache[item]);
});
} else {
doSomeIO(item, callback);
//...
Async guards against synchronous functions in some, but not all, cases. If you are still running into stack overflows, you can defer as suggested above, or wrap functions with async.ensureAsync
Functions that are asynchronous by their nature do not have this problem and don't need the extra callback deferral.
If JavaScript's event loop is still a bit nebulous, check out this article or this talk for more detailed information about how it works.
Multiple callbacks
Make sure to always return
when calling a callback early, otherwise you will cause multiple callbacks and unpredictable behavior in many cases.
async.waterfall([
function (callback) {
getSomething(options, function (err, result) {
if (err) {
callback(new Error("failed getting something:" + err.message));
// we should return here
}
// since we did not return, this callback still will be called and
// `processData` will be called twice
callback(null, result);
});
},
processData
], done)
It is always good practice to return callback(err, result)
whenever a callback call is not the last statement of a function.
Binding a context to an iterator
This section is really about bind
, not about async
. If you are wondering how to
make async
execute your iterators in a given context, or are confused as to why
a method of another library isn't working as an iterator, study this example:
// Here is a simple object with an (unnecessarily roundabout) squaring method
var AsyncSquaringLibrary = {
squareExponent: 2,
square: function(number, callback){
var result = Math.pow(number, this.squareExponent);
setTimeout(function(){
callback(null, result);
}, 200);
}
};
async.map([1, 2, 3], AsyncSquaringLibrary.square, function(err, result){
// result is [NaN, NaN, NaN]
// This fails because the `this.squareExponent` expression in the square
// function is not evaluated in the context of AsyncSquaringLibrary, and is
// therefore undefined.
});
async.map([1, 2, 3], AsyncSquaringLibrary.square.bind(AsyncSquaringLibrary), function(err, result){
// result is [1, 4, 9]
// With the help of bind we can attach a context to the iterator before
// passing it to async. Now the square function will be executed in its
// 'home' AsyncSquaringLibrary context and the value of `this.squareExponent`
// will be as expected.
});
Download
The source is available for download from
GitHub.
Alternatively, you can install using Node Package Manager (npm
):
npm install async
As well as using Bower:
bower install async
Development: async.js - 29.6kb Uncompressed
In the Browser
So far it's been tested in IE6, IE7, IE8, FF3.6 and Chrome 5.
Usage:
<script type="text/javascript" src="async.js"></script>
<script type="text/javascript">
async.map(data, asyncProcess, function(err, results){
alert(results);
});
</script>
Documentation
Some functions are also available in the following forms:
<name>Series
- the same as<name>
but runs only a single async operation at a time<name>Limit
- the same as<name>
but runs a maximum oflimit
async operations at a time
Collections
each
,eachSeries
,eachLimit
forEachOf
,forEachOfSeries
,forEachOfLimit
map
,mapSeries
,mapLimit
filter
,filterSeries
,filterLimit
reject
,rejectSeries
,rejectLimit
reduce
,reduceRight
detect
,detectSeries
,detectLimit
sortBy
some
,someLimit
every
,everyLimit
concat
,concatSeries