3 [![Build Status via Travis CI](https://travis-ci.org/caolan/async.svg?branch=master)](https://travis-ci.org/caolan/async)
4 [![NPM version](http://img.shields.io/npm/v/async.svg)](https://www.npmjs.org/package/async)
5 [![Coverage Status](https://coveralls.io/repos/caolan/async/badge.svg?branch=master)](https://coveralls.io/r/caolan/async?branch=master)
6 [![Join the chat at https://gitter.im/caolan/async](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/caolan/async?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
9 Async is a utility module which provides straight-forward, powerful functions
10 for working with asynchronous JavaScript. Although originally designed for
11 use with [Node.js](http://nodejs.org) and installable via `npm install async`,
12 it can also be used directly in the browser.
14 Async is also installable via:
16 - [bower](http://bower.io/): `bower install async`
17 - [component](https://github.com/component/component): `component install
19 - [jam](http://jamjs.org/): `jam install async`
20 - [spm](http://spmjs.io/): `spm install async`
22 Async provides around 20 functions that include the usual 'functional'
23 suspects (`map`, `reduce`, `filter`, `each`…) as well as some common patterns
24 for asynchronous control flow (`parallel`, `series`, `waterfall`…). All these
25 functions assume you follow the Node.js convention of providing a single
26 callback as the last argument of your `async` function.
32 async.map(['file1','file2','file3'], fs.stat, function(err, results){
33 // results is now an array of stats for each file
36 async.filter(['file1','file2','file3'], fs.exists, function(results){
37 // results now equals an array of the existing files
51 There are many more functions available so take a look at the docs below for a
52 full list. This module aims to be comprehensive, so if you feel anything is
53 missing please create a GitHub issue for it.
55 ## Common Pitfalls <sub>[(StackOverflow)](http://stackoverflow.com/questions/tagged/async.js)</sub>
56 ### Synchronous iteration functions
58 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.
60 This can also arise by accident if you callback early in certain cases:
63 async.eachSeries(hugeArray, function iterator(item, callback) {
65 callback(null, cache[item]); // if many items are cached, you'll overflow
67 doSomeIO(item, callback);
77 async.eachSeries(hugeArray, function iterator(item, callback) {
79 async.setImmediate(function () {
80 callback(null, cache[item]);
83 doSomeIO(item, callback);
87 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`](#ensureAsync) Functions that are asynchronous by their nature do not have this problem and don't need the extra callback deferral.
89 If JavaScript's event loop is still a bit nebulous, check out [this article](http://blog.carbonfive.com/2013/10/27/the-javascript-event-loop-explained/) or [this talk](http://2014.jsconf.eu/speakers/philip-roberts-what-the-heck-is-the-event-loop-anyway.html) for more detailed information about how it works.
92 ### Multiple callbacks
94 Make sure to always `return` when calling a callback early, otherwise you will cause multiple callbacks and unpredictable behavior in many cases.
99 getSomething(options, function (err, result) {
101 callback(new Error("failed getting something:" + err.message));
102 // we should return here
104 // since we did not return, this callback still will be called and
105 // `processData` will be called twice
106 callback(null, result);
113 It is always good practice to `return callback(err, result)` whenever a callback call is not the last statement of a function.
116 ### Binding a context to an iterator
118 This section is really about `bind`, not about `async`. If you are wondering how to
119 make `async` execute your iterators in a given context, or are confused as to why
120 a method of another library isn't working as an iterator, study this example:
123 // Here is a simple object with an (unnecessarily roundabout) squaring method
124 var AsyncSquaringLibrary = {
126 square: function(number, callback){
127 var result = Math.pow(number, this.squareExponent);
128 setTimeout(function(){
129 callback(null, result);
134 async.map([1, 2, 3], AsyncSquaringLibrary.square, function(err, result){
135 // result is [NaN, NaN, NaN]
136 // This fails because the `this.squareExponent` expression in the square
137 // function is not evaluated in the context of AsyncSquaringLibrary, and is
138 // therefore undefined.
141 async.map([1, 2, 3], AsyncSquaringLibrary.square.bind(AsyncSquaringLibrary), function(err, result){
142 // result is [1, 4, 9]
143 // With the help of bind we can attach a context to the iterator before
144 // passing it to async. Now the square function will be executed in its
145 // 'home' AsyncSquaringLibrary context and the value of `this.squareExponent`
146 // will be as expected.
152 The source is available for download from
153 [GitHub](https://github.com/caolan/async/blob/master/lib/async.js).
154 Alternatively, you can install using Node Package Manager (`npm`):
158 As well as using Bower:
162 __Development:__ [async.js](https://github.com/caolan/async/raw/master/lib/async.js) - 29.6kb Uncompressed
166 So far it's been tested in IE6, IE7, IE8, FF3.6 and Chrome 5.
171 <script type="text/javascript" src="async.js"></script>
172 <script type="text/javascript">
174 async.map(data, asyncProcess, function(err, results){
183 Some functions are also available in the following forms:
184 * `<name>Series` - the same as `<name>` but runs only a single async operation at a time
185 * `<name>Limit` - the same as `<name>` but runs a maximum of `limit` async operations at a time
189 * [`each`](#each), `eachSeries`, `eachLimit`
190 * [`forEachOf`](#forEachOf), `forEachOfSeries`, `forEachOfLimit`
191 * [`map`](#map), `mapSeries`, `mapLimit`
192 * [`filter`](#filter), `filterSeries`, `filterLimit`
193 * [`reject`](#reject), `rejectSeries`, `rejectLimit`
194 * [`reduce`](#reduce), [`reduceRight`](#reduceRight)
195 * [`detect`](#detect), `detectSeries`, `detectLimit`
196 * [`sortBy`](#sortBy)
197 * [`some`](#some), `someLimit`
198 * [`every`](#every), `everyLimit`
199 * [`concat`](#concat), `concatSeries`
203 * [`series`](#seriestasks-callback)
204 * [`parallel`](#parallel), `parallelLimit`
205 * [`whilst`](#whilst), [`doWhilst`](#doWhilst)
206 * [`until`](#until), [`doUntil`](#doUntil)
207 * [`during`](#during), [`doDuring`](#doDuring)
208 * [`forever`](#forever)
209 * [`waterfall`](#waterfall)
210 * [`compose`](#compose)
212 * [`applyEach`](#applyEach), `applyEachSeries`
213 * [`queue`](#queue), [`priorityQueue`](#priorityQueue)
217 * [`iterator`](#iterator)
218 * [`times`](#times), `timesSeries`, `timesLimit`
223 * [`nextTick`](#nextTick)
224 * [`memoize`](#memoize)
225 * [`unmemoize`](#unmemoize)
226 * [`ensureAsync`](#ensureAsync)
227 * [`constant`](#constant)
228 * [`asyncify`](#asyncify)
229 * [`wrapSync`](#wrapSync)
232 * [`noConflict`](#noConflict)
238 ### each(arr, iterator, [callback])
240 Applies the function `iterator` to each item in `arr`, in parallel.
241 The `iterator` is called with an item from the list, and a callback for when it
242 has finished. If the `iterator` passes an error to its `callback`, the main
243 `callback` (for the `each` function) is immediately called with the error.
245 Note, that since this function applies `iterator` to each item in parallel,
246 there is no guarantee that the iterator functions will complete in order.
250 * `arr` - An array to iterate over.
251 * `iterator(item, callback)` - A function to apply to each item in `arr`.
252 The iterator is passed a `callback(err)` which must be called once it has
253 completed. If no error has occurred, the `callback` should be run without
254 arguments or with an explicit `null` argument. The array index is not passed
255 to the iterator. If you need the index, use [`forEachOf`](#forEachOf).
256 * `callback(err)` - *Optional* A callback which is called when all `iterator` functions
257 have finished, or an error occurs.
263 // assuming openFiles is an array of file names and saveFile is a function
264 // to save the modified contents of that file:
266 async.each(openFiles, saveFile, function(err){
267 // if any of the saves produced an error, err would equal that error
272 // assuming openFiles is an array of file names
274 async.each(openFiles, function(file, callback) {
276 // Perform operation on file here.
277 console.log('Processing file ' + file);
279 if( file.length > 32 ) {
280 console.log('This file name is too long');
281 callback('File name too long');
283 // Do work to process file here
284 console.log('File processed');
288 // if any of the file processing produced an error, err would equal that error
290 // One of the iterations produced an error.
291 // All processing will now stop.
292 console.log('A file failed to process');
294 console.log('All files have been processed successfully');
301 * eachSeries(arr, iterator, [callback])
302 * eachLimit(arr, limit, iterator, [callback])
304 ---------------------------------------
306 <a name="forEachOf" />
309 ### forEachOf(obj, iterator, [callback])
311 Like `each`, except that it iterates over objects, and passes the key as the second argument to the iterator.
315 * `obj` - An object or array to iterate over.
316 * `iterator(item, key, callback)` - A function to apply to each item in `obj`.
317 The `key` is the item's key, or index in the case of an array. The iterator is
318 passed a `callback(err)` which must be called once it has completed. If no
319 error has occurred, the callback should be run without arguments or with an
320 explicit `null` argument.
321 * `callback(err)` - *Optional* A callback which is called when all `iterator` functions have finished, or an error occurs.
326 var obj = {dev: "/dev.json", test: "/test.json", prod: "/prod.json"};
329 async.forEachOf(obj, function (value, key, callback) {
330 fs.readFile(__dirname + value, "utf8", function (err, data) {
331 if (err) return callback(err);
333 configs[key] = JSON.parse(data);
340 if (err) console.error(err.message);
341 // configs is now a map of JSON data
342 doSomethingWith(configs);
348 * forEachOfSeries(obj, iterator, [callback])
349 * forEachOfLimit(obj, limit, iterator, [callback])
351 ---------------------------------------
354 ### map(arr, iterator, [callback])
356 Produces a new array of values by mapping each value in `arr` through
357 the `iterator` function. The `iterator` is called with an item from `arr` and a
358 callback for when it has finished processing. Each of these callback takes 2 arguments:
359 an `error`, and the transformed item from `arr`. If `iterator` passes an error to its
360 callback, the main `callback` (for the `map` function) is immediately called with the error.
362 Note, that since this function applies the `iterator` to each item in parallel,
363 there is no guarantee that the `iterator` functions will complete in order.
364 However, the results array will be in the same order as the original `arr`.
368 * `arr` - An array to iterate over.
369 * `iterator(item, callback)` - A function to apply to each item in `arr`.
370 The iterator is passed a `callback(err, transformed)` which must be called once
371 it has completed with an error (which can be `null`) and a transformed item.
372 * `callback(err, results)` - *Optional* A callback which is called when all `iterator`
373 functions have finished, or an error occurs. Results is an array of the
374 transformed items from the `arr`.
379 async.map(['file1','file2','file3'], fs.stat, function(err, results){
380 // results is now an array of stats for each file
385 * mapSeries(arr, iterator, [callback])
386 * mapLimit(arr, limit, iterator, [callback])
388 ---------------------------------------
392 ### filter(arr, iterator, [callback])
396 Returns a new array of all the values in `arr` which pass an async truth test.
397 _The callback for each `iterator` call only accepts a single argument of `true` or
398 `false`; it does not accept an error argument first!_ This is in-line with the
399 way node libraries work with truth tests like `fs.exists`. This operation is
400 performed in parallel, but the results array will be in the same order as the
405 * `arr` - An array to iterate over.
406 * `iterator(item, callback)` - A truth test to apply to each item in `arr`.
407 The `iterator` is passed a `callback(truthValue)`, which must be called with a
408 boolean argument once it has completed.
409 * `callback(results)` - *Optional* A callback which is called after all the `iterator`
410 functions have finished.
415 async.filter(['file1','file2','file3'], fs.exists, function(results){
416 // results now equals an array of the existing files
422 * filterSeries(arr, iterator, [callback])
423 * filterLimit(arr, limit, iterator, [callback])
425 ---------------------------------------
428 ### reject(arr, iterator, [callback])
430 The opposite of [`filter`](#filter). Removes values that pass an `async` truth test.
434 * rejectSeries(arr, iterator, [callback])
435 * rejectLimit(arr, limit, iterator, [callback])
437 ---------------------------------------
440 ### reduce(arr, memo, iterator, [callback])
442 __Aliases:__ `inject`, `foldl`
444 Reduces `arr` into a single value using an async `iterator` to return
445 each successive step. `memo` is the initial state of the reduction.
446 This function only operates in series.
448 For performance reasons, it may make sense to split a call to this function into
449 a parallel map, and then use the normal `Array.prototype.reduce` on the results.
450 This function is for situations where each step in the reduction needs to be async;
451 if you can get the data before reducing it, then it's probably a good idea to do so.
455 * `arr` - An array to iterate over.
456 * `memo` - The initial state of the reduction.
457 * `iterator(memo, item, callback)` - A function applied to each item in the
458 array to produce the next step in the reduction. The `iterator` is passed a
459 `callback(err, reduction)` which accepts an optional error as its first
460 argument, and the state of the reduction as the second. If an error is
461 passed to the callback, the reduction is stopped and the main `callback` is
462 immediately called with the error.
463 * `callback(err, result)` - *Optional* A callback which is called after all the `iterator`
464 functions have finished. Result is the reduced value.
469 async.reduce([1,2,3], 0, function(memo, item, callback){
471 process.nextTick(function(){
472 callback(null, memo + item)
474 }, function(err, result){
475 // result is now equal to the last value of memo, which is 6
479 ---------------------------------------
481 <a name="reduceRight" />
482 ### reduceRight(arr, memo, iterator, [callback])
486 Same as [`reduce`](#reduce), only operates on `arr` in reverse order.
489 ---------------------------------------
492 ### detect(arr, iterator, [callback])
494 Returns the first value in `arr` that passes an async truth test. The
495 `iterator` is applied in parallel, meaning the first iterator to return `true` will
496 fire the detect `callback` with that result. That means the result might not be
497 the first item in the original `arr` (in terms of order) that passes the test.
499 If order within the original `arr` is important, then look at [`detectSeries`](#detectSeries).
503 * `arr` - An array to iterate over.
504 * `iterator(item, callback)` - A truth test to apply to each item in `arr`.
505 The iterator is passed a `callback(truthValue)` which must be called with a
506 boolean argument once it has completed. **Note: this callback does not take an error as its first argument.**
507 * `callback(result)` - *Optional* A callback which is called as soon as any iterator returns
508 `true`, or after all the `iterator` functions have finished. Result will be
509 the first item in the array that passes the truth test (iterator) or the
510 value `undefined` if none passed. **Note: this callback does not take an error as its first argument.**
515 async.detect(['file1','file2','file3'], fs.exists, function(result){
516 // result now equals the first file in the list that exists
522 * detectSeries(arr, iterator, [callback])
523 * detectLimit(arr, limit, iterator, [callback])
525 ---------------------------------------
528 ### sortBy(arr, iterator, [callback])
530 Sorts a list by the results of running each `arr` value through an async `iterator`.
534 * `arr` - An array to iterate over.
535 * `iterator(item, callback)` - A function to apply to each item in `arr`.
536 The iterator is passed a `callback(err, sortValue)` which must be called once it
537 has completed with an error (which can be `null`) and a value to use as the sort
539 * `callback(err, results)` - *Optional* A callback which is called after all the `iterator`
540 functions have finished, or an error occurs. Results is the items from
541 the original `arr` sorted by the values returned by the `iterator` calls.
546 async.sortBy(['file1','file2','file3'], function(file, callback){
547 fs.stat(file, function(err, stats){
548 callback(err, stats.mtime);
550 }, function(err, results){
551 // results is now the original array of files sorted by
558 By modifying the callback parameter the sorting order can be influenced:
562 async.sortBy([1,9,3,5], function(x, callback){
564 }, function(err,result){
569 async.sortBy([1,9,3,5], function(x, callback){
570 callback(null, x*-1); //<- x*-1 instead of x, turns the order around
571 }, function(err,result){
576 ---------------------------------------
579 ### some(arr, iterator, [callback])
583 Returns `true` if at least one element in the `arr` satisfies an async test.
584 _The callback for each iterator call only accepts a single argument of `true` or
585 `false`; it does not accept an error argument first!_ This is in-line with the
586 way node libraries work with truth tests like `fs.exists`. Once any iterator
587 call returns `true`, the main `callback` is immediately called.
591 * `arr` - An array to iterate over.
592 * `iterator(item, callback)` - A truth test to apply to each item in the array
593 in parallel. The iterator is passed a `callback(truthValue)`` which must be
594 called with a boolean argument once it has completed.
595 * `callback(result)` - *Optional* A callback which is called as soon as any iterator returns
596 `true`, or after all the iterator functions have finished. Result will be
597 either `true` or `false` depending on the values of the async tests.
599 **Note: the callbacks do not take an error as their first argument.**
603 async.some(['file1','file2','file3'], fs.exists, function(result){
604 // if result is true then at least one of the files exists
610 * someLimit(arr, limit, iterator, callback)
612 ---------------------------------------
615 ### every(arr, iterator, [callback])
619 Returns `true` if every element in `arr` satisfies an async test.
620 _The callback for each `iterator` call only accepts a single argument of `true` or
621 `false`; it does not accept an error argument first!_ This is in-line with the
622 way node libraries work with truth tests like `fs.exists`.
626 * `arr` - An array to iterate over.
627 * `iterator(item, callback)` - A truth test to apply to each item in the array
628 in parallel. The iterator is passed a `callback(truthValue)` which must be
629 called with a boolean argument once it has completed.
630 * `callback(result)` - *Optional* A callback which is called as soon as any iterator returns
631 `false`, or after all the iterator functions have finished. Result will be
632 either `true` or `false` depending on the values of the async tests.
634 **Note: the callbacks do not take an error as their first argument.**
639 async.every(['file1','file2','file3'], fs.exists, function(result){
640 // if result is true then every file exists
646 * everyLimit(arr, limit, iterator, callback)
648 ---------------------------------------
651 ### concat(arr, iterator, [callback])
653 Applies `iterator` to each item in `arr`, concatenating the results. Returns the
654 concatenated list. The `iterator`s are called in parallel, and the results are
655 concatenated as they return. There is no guarantee that the results array will
656 be returned in the original order of `arr` passed to the `iterator` function.
660 * `arr` - An array to iterate over.
661 * `iterator(item, callback)` - A function to apply to each item in `arr`.
662 The iterator is passed a `callback(err, results)` which must be called once it
663 has completed with an error (which can be `null`) and an array of results.
664 * `callback(err, results)` - *Optional* A callback which is called after all the `iterator`
665 functions have finished, or an error occurs. Results is an array containing
666 the concatenated results of the `iterator` function.
671 async.concat(['dir1','dir2','dir3'], fs.readdir, function(err, files){
672 // files is now a list of filenames that exist in the 3 directories
678 * concatSeries(arr, iterator, [callback])
684 ### series(tasks, [callback])
686 Run the functions in the `tasks` array in series, each one running once the previous
687 function has completed. If any functions in the series pass an error to its
688 callback, no more functions are run, and `callback` is immediately called with the value of the error.
689 Otherwise, `callback` receives an array of results when `tasks` have completed.
691 It is also possible to use an object instead of an array. Each property will be
692 run as a function, and the results will be passed to the final `callback` as an object
693 instead of an array. This can be a more readable way of handling results from
696 **Note** that while many implementations preserve the order of object properties, the
697 [ECMAScript Language Specification](http://www.ecma-international.org/ecma-262/5.1/#sec-8.6)
698 explicitly states that
700 > The mechanics and order of enumerating the properties is not specified.
702 So if you rely on the order in which your series of functions are executed, and want
703 this to work on all platforms, consider using an array.
707 * `tasks` - An array or object containing functions to run, each function is passed
708 a `callback(err, result)` it must call on completion with an error `err` (which can
709 be `null`) and an optional `result` value.
710 * `callback(err, results)` - An optional callback to run once all the functions
711 have completed. This function gets a results array (or object) containing all
712 the result arguments passed to the `task` callbacks.
720 callback(null, 'one');
723 // do some more stuff ...
724 callback(null, 'two');
728 function(err, results){
729 // results is now equal to ['one', 'two']
733 // an example using an object instead of an array
735 one: function(callback){
736 setTimeout(function(){
740 two: function(callback){
741 setTimeout(function(){
746 function(err, results) {
747 // results is now equal to: {one: 1, two: 2}
751 ---------------------------------------
753 <a name="parallel" />
754 ### parallel(tasks, [callback])
756 Run the `tasks` array of functions in parallel, without waiting until the previous
757 function has completed. If any of the functions pass an error to its
758 callback, the main `callback` is immediately called with the value of the error.
759 Once the `tasks` have completed, the results are passed to the final `callback` as an
762 **Note:** `parallel` is about kicking-off I/O tasks in parallel, not about parallel execution of code. If your tasks do not use any timers or perform any I/O, they will actually be executed in series. Any synchronous setup sections for each task will happen one after the other. JavaScript remains single-threaded.
764 It is also possible to use an object instead of an array. Each property will be
765 run as a function and the results will be passed to the final `callback` as an object
766 instead of an array. This can be a more readable way of handling results from
767 [`parallel`](#parallel).
772 * `tasks` - An array or object containing functions to run. Each function is passed
773 a `callback(err, result)` which it must call on completion with an error `err`
774 (which can be `null`) and an optional `result` value.
775 * `callback(err, results)` - An optional callback to run once all the functions
776 have completed successfully. This function gets a results array (or object) containing all
777 the result arguments passed to the task callbacks.
784 setTimeout(function(){
785 callback(null, 'one');
789 setTimeout(function(){
790 callback(null, 'two');
795 function(err, results){
796 // the results array will equal ['one','two'] even though
797 // the second function had a shorter timeout.
801 // an example using an object instead of an array
803 one: function(callback){
804 setTimeout(function(){
808 two: function(callback){
809 setTimeout(function(){
814 function(err, results) {
815 // results is now equals to: {one: 1, two: 2}
821 * parallelLimit(tasks, limit, [callback])
823 ---------------------------------------
826 ### whilst(test, fn, callback)
828 Repeatedly call `fn`, while `test` returns `true`. Calls `callback` when stopped,
833 * `test()` - synchronous truth test to perform before each execution of `fn`.
834 * `fn(callback)` - A function which is called each time `test` passes. The function is
835 passed a `callback(err)`, which must be called once it has completed with an
836 optional `err` argument.
837 * `callback(err, [results])` - A callback which is called after the test
838 function has failed and repeated execution of `fn` has stopped. `callback`
839 will be passed an error and any arguments passed to the final `fn`'s callback.
847 function () { return count < 5; },
848 function (callback) {
850 setTimeout(function () {
851 callback(null, count);
855 // 5 seconds have passed, n = 5
860 ---------------------------------------
862 <a name="doWhilst" />
863 ### doWhilst(fn, test, callback)
865 The post-check version of [`whilst`](#whilst). To reflect the difference in
866 the order of operations, the arguments `test` and `fn` are switched.
868 `doWhilst` is to `whilst` as `do while` is to `while` in plain JavaScript.
870 ---------------------------------------
873 ### until(test, fn, callback)
875 Repeatedly call `fn` until `test` returns `true`. Calls `callback` when stopped,
876 or an error occurs. `callback` will be passed an error and any arguments passed
877 to the final `fn`'s callback.
879 The inverse of [`whilst`](#whilst).
881 ---------------------------------------
884 ### doUntil(fn, test, callback)
886 Like [`doWhilst`](#doWhilst), except the `test` is inverted. Note the argument ordering differs from `until`.
888 ---------------------------------------
891 ### during(test, fn, callback)
893 Like [`whilst`](#whilst), except the `test` is an asynchronous function that is passed a callback in the form of `function (err, truth)`. If error is passed to `test` or `fn`, the main callback is immediately called with the value of the error.
901 function (callback) {
902 return callback(null, count < 5);
904 function (callback) {
906 setTimeout(callback, 1000);
909 // 5 seconds have passed
914 ---------------------------------------
916 <a name="doDuring" />
917 ### doDuring(fn, test, callback)
919 The post-check version of [`during`](#during). To reflect the difference in
920 the order of operations, the arguments `test` and `fn` are switched.
922 Also a version of [`doWhilst`](#doWhilst) with asynchronous `test` function.
924 ---------------------------------------
927 ### forever(fn, [errback])
929 Calls the asynchronous function `fn` with a callback parameter that allows it to
930 call itself again, in series, indefinitely.
932 If an error is passed to the callback then `errback` is called with the
933 error, and execution stops, otherwise it will never be called.
938 // next is suitable for passing to things that need a callback(err [, whatever]);
939 // it will result in this function being called again.
942 // if next is called with a value in its first parameter, it will appear
943 // in here as 'err', and execution will stop.
948 ---------------------------------------
950 <a name="waterfall" />
951 ### waterfall(tasks, [callback])
953 Runs the `tasks` array of functions in series, each passing their results to the next in
954 the array. However, if any of the `tasks` pass an error to their own callback, the
955 next function is not executed, and the main `callback` is immediately called with
960 * `tasks` - An array of functions to run, each function is passed a
961 `callback(err, result1, result2, ...)` it must call on completion. The first
962 argument is an error (which can be `null`) and any further arguments will be
963 passed as arguments in order to the next task.
964 * `callback(err, [results])` - An optional callback to run once all the functions
965 have completed. This will be passed the results of the last task's callback.
974 callback(null, 'one', 'two');
976 function(arg1, arg2, callback) {
977 // arg1 now equals 'one' and arg2 now equals 'two'
978 callback(null, 'three');
980 function(arg1, callback) {
981 // arg1 now equals 'three'
982 callback(null, 'done');
984 ], function (err, result) {
985 // result now equals 'done'
988 Or, with named functions:
995 ], function (err, result) {
996 // result now equals 'done'
998 function myFirstFunction(callback) {
999 callback(null, 'one', 'two');
1001 function mySecondFunction(arg1, arg2, callback) {
1002 // arg1 now equals 'one' and arg2 now equals 'two'
1003 callback(null, 'three');
1005 function myLastFunction(arg1, callback) {
1006 // arg1 now equals 'three'
1007 callback(null, 'done');
1011 Or, if you need to pass any argument to the first function:
1015 async.apply(myFirstFunction, 'zero'),
1018 ], function (err, result) {
1019 // result now equals 'done'
1021 function myFirstFunction(arg1, callback) {
1022 // arg1 now equals 'zero'
1023 callback(null, 'one', 'two');
1025 function mySecondFunction(arg1, arg2, callback) {
1026 // arg1 now equals 'one' and arg2 now equals 'two'
1027 callback(null, 'three');
1029 function myLastFunction(arg1, callback) {
1030 // arg1 now equals 'three'
1031 callback(null, 'done');
1035 ---------------------------------------
1036 <a name="compose" />
1037 ### compose(fn1, fn2...)
1039 Creates a function which is a composition of the passed asynchronous
1040 functions. Each function consumes the return value of the function that
1041 follows. Composing functions `f()`, `g()`, and `h()` would produce the result of
1042 `f(g(h()))`, only this version uses callbacks to obtain the return values.
1044 Each function is executed with the `this` binding of the composed function.
1048 * `functions...` - the asynchronous functions to compose
1054 function add1(n, callback) {
1055 setTimeout(function () {
1056 callback(null, n + 1);
1060 function mul3(n, callback) {
1061 setTimeout(function () {
1062 callback(null, n * 3);
1066 var add1mul3 = async.compose(mul3, add1);
1068 add1mul3(4, function (err, result) {
1069 // result now equals 15
1073 ---------------------------------------
1075 ### seq(fn1, fn2...)
1077 Version of the compose function that is more natural to read.
1078 Each function consumes the return value of the previous function.
1079 It is the equivalent of [`compose`](#compose) with the arguments reversed.
1081 Each function is executed with the `this` binding of the composed function.
1085 * `functions...` - the asynchronous functions to compose
1091 // Requires lodash (or underscore), express3 and dresende's orm2.
1092 // Part of an app, that fetches cats of the logged user.
1093 // This example uses `seq` function to avoid overnesting and error
1094 // handling clutter.
1095 app.get('/cats', function(request, response) {
1096 var User = request.models.User;
1098 _.bind(User.get, User), // 'User.get' has signature (id, callback(err, data))
1099 function(user, fn) {
1100 user.getCats(fn); // 'getCats' has signature (callback(err, data))
1102 )(req.session.user_id, function (err, cats) {
1105 response.json({ status: 'error', message: err.message });
1107 response.json({ status: 'ok', message: 'Cats found', data: cats });
1113 ---------------------------------------
1114 <a name="applyEach" />
1115 ### applyEach(fns, args..., callback)
1117 Applies the provided arguments to each function in the array, calling
1118 `callback` after all functions have completed. If you only provide the first
1119 argument, then it will return a function which lets you pass in the
1120 arguments as if it were a single function call.
1124 * `fns` - the asynchronous functions to all call with the same arguments
1125 * `args...` - any number of separate arguments to pass to the function
1126 * `callback` - the final argument should be the callback, called when all
1127 functions have completed processing
1133 async.applyEach([enableSearch, updateSchema], 'bucket', callback);
1135 // partial application example:
1138 async.applyEach([enableSearch, updateSchema]),
1145 * applyEachSeries(tasks, args..., [callback])
1147 ---------------------------------------
1150 ### queue(worker, [concurrency])
1152 Creates a `queue` object with the specified `concurrency`. Tasks added to the
1153 `queue` are processed in parallel (up to the `concurrency` limit). If all
1154 `worker`s are in progress, the task is queued until one becomes available.
1155 Once a `worker` completes a `task`, that `task`'s callback is called.
1159 * `worker(task, callback)` - An asynchronous function for processing a queued
1160 task, which must call its `callback(err)` argument when finished, with an
1161 optional `error` as an argument. If you want to handle errors from an individual task, pass a callback to `q.push()`.
1162 * `concurrency` - An `integer` for determining how many `worker` functions should be
1163 run in parallel. If omitted, the concurrency defaults to `1`. If the concurrency is `0`, an error is thrown.
1167 The `queue` object returned by this function has the following properties and
1170 * `length()` - a function returning the number of items waiting to be processed.
1171 * `started` - a function returning whether or not any items have been pushed and processed by the queue
1172 * `running()` - a function returning the number of items currently being processed.
1173 * `workersList()` - a function returning the array of items currently being processed.
1174 * `idle()` - a function returning false if there are items waiting or being processed, or true if not.
1175 * `concurrency` - an integer for determining how many `worker` functions should be
1176 run in parallel. This property can be changed after a `queue` is created to
1177 alter the concurrency on-the-fly.
1178 * `push(task, [callback])` - add a new task to the `queue`. Calls `callback` once
1179 the `worker` has finished processing the task. Instead of a single task, a `tasks` array
1180 can be submitted. The respective callback is used for every task in the list.
1181 * `unshift(task, [callback])` - add a new task to the front of the `queue`.
1182 * `saturated` - a callback that is called when the `queue` length hits the `concurrency` limit,
1183 and further tasks will be queued.
1184 * `empty` - a callback that is called when the last item from the `queue` is given to a `worker`.
1185 * `drain` - a callback that is called when the last item from the `queue` has returned from the `worker`.
1186 * `paused` - a boolean for determining whether the queue is in a paused state
1187 * `pause()` - a function that pauses the processing of tasks until `resume()` is called.
1188 * `resume()` - a function that resumes the processing of queued tasks when the queue is paused.
1189 * `kill()` - a function that removes the `drain` callback and empties remaining tasks from the queue forcing it to go idle.
1194 // create a queue object with concurrency 2
1196 var q = async.queue(function (task, callback) {
1197 console.log('hello ' + task.name);
1202 // assign a callback
1203 q.drain = function() {
1204 console.log('all items have been processed');
1207 // add some items to the queue
1209 q.push({name: 'foo'}, function (err) {
1210 console.log('finished processing foo');
1212 q.push({name: 'bar'}, function (err) {
1213 console.log('finished processing bar');
1216 // add some items to the queue (batch-wise)
1218 q.push([{name: 'baz'},{name: 'bay'},{name: 'bax'}], function (err) {
1219 console.log('finished processing item');
1222 // add some items to the front of the queue
1224 q.unshift({name: 'bar'}, function (err) {
1225 console.log('finished processing bar');
1230 ---------------------------------------
1232 <a name="priorityQueue" />
1233 ### priorityQueue(worker, concurrency)
1235 The same as [`queue`](#queue) only tasks are assigned a priority and completed in ascending priority order. There are two differences between `queue` and `priorityQueue` objects:
1237 * `push(task, priority, [callback])` - `priority` should be a number. If an array of
1238 `tasks` is given, all tasks will be assigned the same priority.
1239 * The `unshift` method was removed.
1241 ---------------------------------------
1244 ### cargo(worker, [payload])
1246 Creates a `cargo` object with the specified payload. Tasks added to the
1247 cargo will be processed altogether (up to the `payload` limit). If the
1248 `worker` is in progress, the task is queued until it becomes available. Once
1249 the `worker` has completed some tasks, each callback of those tasks is called.
1250 Check out [these](https://camo.githubusercontent.com/6bbd36f4cf5b35a0f11a96dcd2e97711ffc2fb37/68747470733a2f2f662e636c6f75642e6769746875622e636f6d2f6173736574732f313637363837312f36383130382f62626330636662302d356632392d313165322d393734662d3333393763363464633835382e676966) [animations](https://camo.githubusercontent.com/f4810e00e1c5f5f8addbe3e9f49064fd5d102699/68747470733a2f2f662e636c6f75642e6769746875622e636f6d2f6173736574732f313637363837312f36383130312f38346339323036362d356632392d313165322d383134662d3964336430323431336266642e676966) for how `cargo` and `queue` work.
1252 While [queue](#queue) passes only one task to one of a group of workers
1253 at a time, cargo passes an array of tasks to a single worker, repeating
1254 when the worker is finished.
1258 * `worker(tasks, callback)` - An asynchronous function for processing an array of
1259 queued tasks, which must call its `callback(err)` argument when finished, with
1260 an optional `err` argument.
1261 * `payload` - An optional `integer` for determining how many tasks should be
1262 processed per round; if omitted, the default is unlimited.
1266 The `cargo` object returned by this function has the following properties and
1269 * `length()` - A function returning the number of items waiting to be processed.
1270 * `payload` - An `integer` for determining how many tasks should be
1271 process per round. This property can be changed after a `cargo` is created to
1272 alter the payload on-the-fly.
1273 * `push(task, [callback])` - Adds `task` to the `queue`. The callback is called
1274 once the `worker` has finished processing the task. Instead of a single task, an array of `tasks`
1275 can be submitted. The respective callback is used for every task in the list.
1276 * `saturated` - A callback that is called when the `queue.length()` hits the concurrency and further tasks will be queued.
1277 * `empty` - A callback that is called when the last item from the `queue` is given to a `worker`.
1278 * `drain` - A callback that is called when the last item from the `queue` has returned from the `worker`.
1279 * `idle()`, `pause()`, `resume()`, `kill()` - cargo inherits all of the same methods and event calbacks as [`queue`](#queue)
1284 // create a cargo object with payload 2
1286 var cargo = async.cargo(function (tasks, callback) {
1287 for(var i=0; i<tasks.length; i++){
1288 console.log('hello ' + tasks[i].name);
1296 cargo.push({name: 'foo'}, function (err) {
1297 console.log('finished processing foo');
1299 cargo.push({name: 'bar'}, function (err) {
1300 console.log('finished processing bar');
1302 cargo.push({name: 'baz'}, function (err) {
1303 console.log('finished processing baz');
1307 ---------------------------------------
1310 ### auto(tasks, [concurrency], [callback])
1312 Determines the best order for running the functions in `tasks`, based on their requirements. Each function can optionally depend on other functions being completed first, and each function is run as soon as its requirements are satisfied.
1314 If any of the functions pass an error to their callback, the `auto` sequence will stop. Further tasks will not execute (so any other functions depending on it will not run), and the main `callback` is immediately called with the error. Functions also receive an object containing the results of functions which have completed so far.
1316 Note, all functions are called with a `results` object as a second argument,
1317 so it is unsafe to pass functions in the `tasks` object which cannot handle the
1320 For example, this snippet of code:
1324 readData: async.apply(fs.readFile, 'data.txt', 'utf-8')
1328 will have the effect of calling `readFile` with the results object as the last
1329 argument, which will fail:
1332 fs.readFile('data.txt', 'utf-8', cb, {});
1335 Instead, wrap the call to `readFile` in a function which does not forward the
1340 readData: function(cb, results){
1341 fs.readFile('data.txt', 'utf-8', cb);
1348 * `tasks` - An object. Each of its properties is either a function or an array of
1349 requirements, with the function itself the last item in the array. The object's key
1350 of a property serves as the name of the task defined by that property,
1351 i.e. can be used when specifying requirements for other tasks.
1352 The function receives two arguments: (1) a `callback(err, result)` which must be
1353 called when finished, passing an `error` (which can be `null`) and the result of
1354 the function's execution, and (2) a `results` object, containing the results of
1355 the previously executed functions.
1356 * `concurrency` - An optional `integer` for determining the maximum number of tasks that can be run in parallel. By default, as many as possible.
1357 * `callback(err, results)` - An optional callback which is called when all the
1358 tasks have been completed. It receives the `err` argument if any `tasks`
1359 pass an error to their callback. Results are always returned; however, if
1360 an error occurs, no further `tasks` will be performed, and the results
1361 object will only contain partial results.
1368 get_data: function(callback){
1369 console.log('in get_data');
1370 // async code to get some data
1371 callback(null, 'data', 'converted to array');
1373 make_folder: function(callback){
1374 console.log('in make_folder');
1375 // async code to create a directory to store a file in
1376 // this is run at the same time as getting the data
1377 callback(null, 'folder');
1379 write_file: ['get_data', 'make_folder', function(callback, results){
1380 console.log('in write_file', JSON.stringify(results));
1381 // once there is some data and the directory exists,
1382 // write the data to a file in the directory
1383 callback(null, 'filename');
1385 email_link: ['write_file', function(callback, results){
1386 console.log('in email_link', JSON.stringify(results));
1387 // once the file is written let's email a link to it...
1388 // results.write_file contains the filename returned by write_file.
1389 callback(null, {'file':results.write_file, 'email':'user@example.com'});
1391 }, function(err, results) {
1392 console.log('err = ', err);
1393 console.log('results = ', results);
1397 This is a fairly trivial example, but to do this using the basic parallel and
1398 series functions would look like this:
1403 console.log('in get_data');
1404 // async code to get some data
1405 callback(null, 'data', 'converted to array');
1408 console.log('in make_folder');
1409 // async code to create a directory to store a file in
1410 // this is run at the same time as getting the data
1411 callback(null, 'folder');
1414 function(err, results){
1417 console.log('in write_file', JSON.stringify(results));
1418 // once there is some data and the directory exists,
1419 // write the data to a file in the directory
1420 results.push('filename');
1424 console.log('in email_link', JSON.stringify(results));
1425 // once the file is written let's email a link to it...
1426 callback(null, {'file':results.pop(), 'email':'user@example.com'});
1432 For a complicated series of `async` tasks, using the [`auto`](#auto) function makes adding
1433 new tasks much easier (and the code more readable).
1436 ---------------------------------------
1439 ### retry([opts = {times: 5, interval: 0}| 5], task, [callback])
1441 Attempts to get a successful response from `task` no more than `times` times before
1442 returning an error. If the task is successful, the `callback` will be passed the result
1443 of the successful task. If all attempts fail, the callback will be passed the error and
1444 result (if any) of the final attempt.
1448 * `opts` - Can be either an object with `times` and `interval` or a number.
1449 * `times` - The number of attempts to make before giving up. The default is `5`.
1450 * `interval` - The time to wait between retries, in milliseconds. The default is `0`.
1451 * If `opts` is a number, the number specifies the number of times to retry, with the default interval of `0`.
1452 * `task(callback, results)` - A function which receives two arguments: (1) a `callback(err, result)`
1453 which must be called when finished, passing `err` (which can be `null`) and the `result` of
1454 the function's execution, and (2) a `results` object, containing the results of
1455 the previously executed functions (if nested inside another control flow).
1456 * `callback(err, results)` - An optional callback which is called when the
1457 task has succeeded, or after the final failed attempt. It receives the `err` and `result` arguments of the last attempt at completing the `task`.
1459 The [`retry`](#retry) function can be used as a stand-alone control flow by passing a callback, as shown below:
1462 // try calling apiMethod 3 times
1463 async.retry(3, apiMethod, function(err, result) {
1464 // do something with the result
1469 // try calling apiMethod 3 times, waiting 200 ms between each retry
1470 async.retry({times: 3, interval: 200}, apiMethod, function(err, result) {
1471 // do something with the result
1476 // try calling apiMethod the default 5 times no delay between each retry
1477 async.retry(apiMethod, function(err, result) {
1478 // do something with the result
1482 It can also be embedded within other control flow functions to retry individual methods
1483 that are not as reliable, like this:
1487 users: api.getUsers.bind(api),
1488 payments: async.retry(3, api.getPayments.bind(api))
1489 }, function(err, results) {
1490 // do something with the results
1495 ---------------------------------------
1497 <a name="iterator" />
1500 Creates an iterator function which calls the next function in the `tasks` array,
1501 returning a continuation to call the next one after that. It's also possible to
1502 “peek” at the next iterator with `iterator.next()`.
1504 This function is used internally by the `async` module, but can be useful when
1505 you want to manually control the flow of functions in series.
1509 * `tasks` - An array of functions to run.
1514 var iterator = async.iterator([
1515 function(){ sys.p('one'); },
1516 function(){ sys.p('two'); },
1517 function(){ sys.p('three'); }
1520 node> var iterator2 = iterator();
1522 node> var iterator3 = iterator2();
1526 node> var nextfn = iterator2.next();
1531 ---------------------------------------
1534 ### apply(function, arguments..)
1536 Creates a continuation function with some arguments already applied.
1538 Useful as a shorthand when combined with other control flow functions. Any arguments
1539 passed to the returned function are added to the arguments originally passed
1544 * `function` - The function you want to eventually apply all arguments to.
1545 * `arguments...` - Any number of arguments to automatically apply when the
1546 continuation is called.
1554 async.apply(fs.writeFile, 'testfile1', 'test1'),
1555 async.apply(fs.writeFile, 'testfile2', 'test2'),
1559 // the same process without using apply
1563 fs.writeFile('testfile1', 'test1', callback);
1566 fs.writeFile('testfile2', 'test2', callback);
1571 It's possible to pass any number of additional arguments when calling the
1575 node> var fn = async.apply(sys.puts, 'one');
1576 node> fn('two', 'three');
1582 ---------------------------------------
1584 <a name="nextTick" />
1585 ### nextTick(callback), setImmediate(callback)
1587 Calls `callback` on a later loop around the event loop. In Node.js this just
1588 calls `process.nextTick`; in the browser it falls back to `setImmediate(callback)`
1589 if available, otherwise `setTimeout(callback, 0)`, which means other higher priority
1590 events may precede the execution of `callback`.
1592 This is used internally for browser-compatibility purposes.
1596 * `callback` - The function to call on a later loop around the event loop.
1601 var call_order = [];
1602 async.nextTick(function(){
1603 call_order.push('two');
1604 // call_order now equals ['one','two']
1606 call_order.push('one')
1610 ### times(n, iterator, [callback])
1612 Calls the `iterator` function `n` times, and accumulates results in the same manner
1613 you would use with [`map`](#map).
1617 * `n` - The number of times to run the function.
1618 * `iterator` - The function to call `n` times.
1619 * `callback` - see [`map`](#map)
1624 // Pretend this is some complicated async factory
1625 var createUser = function(id, callback) {
1631 async.times(5, function(n, next){
1632 createUser(n, function(err, user) {
1635 }, function(err, users) {
1636 // we should now have 5 users
1642 * timesSeries(n, iterator, [callback])
1643 * timesLimit(n, limit, iterator, [callback])
1648 <a name="memoize" />
1649 ### memoize(fn, [hasher])
1651 Caches the results of an `async` function. When creating a hash to store function
1652 results against, the callback is omitted from the hash and an optional hash
1653 function can be used.
1655 If no hash function is specified, the first argument is used as a hash key, which may work reasonably if it is a string or a data type that converts to a distinct string. Note that objects and arrays will not behave reasonably. Neither will cases where the other arguments are significant. In such cases, specify your own hash function.
1657 The cache of results is exposed as the `memo` property of the function returned
1662 * `fn` - The function to proxy and cache results from.
1663 * `hasher` - An optional function for generating a custom hash for storing
1664 results. It has all the arguments applied to it apart from the callback, and
1665 must be synchronous.
1670 var slow_fn = function (name, callback) {
1672 callback(null, result);
1674 var fn = async.memoize(slow_fn);
1676 // fn can now be used as if it were slow_fn
1677 fn('some name', function () {
1682 <a name="unmemoize" />
1685 Undoes a [`memoize`](#memoize)d function, reverting it to the original, unmemoized
1686 form. Handy for testing.
1690 * `fn` - the memoized function
1692 ---------------------------------------
1694 <a name="ensureAsync" />
1697 Wrap an async function and ensure it calls its callback on a later tick of the event loop. If the function already calls its callback on a next tick, no extra deferral is added. This is useful for preventing stack overflows (`RangeError: Maximum call stack size exceeded`) and generally keeping [Zalgo](http://blog.izs.me/post/59142742143/designing-apis-for-asynchrony) contained.
1701 * `fn` - an async function, one that expects a node-style callback as its last argument
1703 Returns a wrapped function with the exact same call signature as the function passed in.
1708 function sometimesAsync(arg, callback) {
1710 return callback(null, cache[arg]); // this would be synchronous!!
1712 doSomeIO(arg, callback); // this IO would be asynchronous
1716 // this has a risk of stack overflows if many results are cached in a row
1717 async.mapSeries(args, sometimesAsync, done);
1719 // this will defer sometimesAsync's callback if necessary,
1720 // preventing stack overflows
1721 async.mapSeries(args, async.ensureAsync(sometimesAsync), done);
1725 ---------------------------------------
1728 ### constant(values...)
1730 Returns a function that when called, calls-back with the values provided. Useful as the first function in a `waterfall`, or for plugging values in to `auto`.
1737 function (value, next) {
1744 async.constant(filename, "utf8"),
1746 function (fileData, next) {
1753 hostname: async.constant("https://server.net/"),
1755 launchServer: ["hostname", "port", function (cb, options) {
1756 startServer(options, cb);
1763 ---------------------------------------
1769 __Alias:__ `wrapSync`
1771 Take a sync function and make it async, passing its return value to a callback. This is useful for plugging sync functions into a waterfall, series, or other async functions. Any arguments passed to the generated function will be passed to the wrapped function (except for the final callback argument). Errors thrown will be passed to the callback.
1777 async.apply(fs.readFile, filename, "utf8"),
1778 async.asyncify(JSON.parse),
1779 function (data, next) {
1780 // data is the result of parsing the text.
1781 // If there was a parsing error, it would have been caught.
1786 If the function passed to `asyncify` returns a Promise, that promises's resolved/rejected state will be used to call the callback, rather than simply the synchronous return value. Example:
1790 async.apply(fs.readFile, filename, "utf8"),
1791 async.asyncify(function (contents) {
1792 return db.model.create(contents);
1794 function (model, next) {
1795 // `model` is the instantiated model object.
1796 // If there was an error, this function would be skipped.
1801 This also means you can asyncify ES2016 `async` functions.
1804 var q = async.queue(async.asyncify(async function (file) {
1805 var intermediateStep = await processFile(file);
1806 return await somePromise(intermediateStep)
1812 ---------------------------------------
1815 ### log(function, arguments)
1817 Logs the result of an `async` function to the `console`. Only works in Node.js or
1818 in browsers that support `console.log` and `console.error` (such as FF and Chrome).
1819 If multiple arguments are returned from the async function, `console.log` is
1820 called on each argument in order.
1824 * `function` - The function you want to eventually apply all arguments to.
1825 * `arguments...` - Any number of arguments to apply to the function.
1830 var hello = function(name, callback){
1831 setTimeout(function(){
1832 callback(null, 'hello ' + name);
1837 node> async.log(hello, 'world');
1841 ---------------------------------------
1844 ### dir(function, arguments)
1846 Logs the result of an `async` function to the `console` using `console.dir` to
1847 display the properties of the resulting object. Only works in Node.js or
1848 in browsers that support `console.dir` and `console.error` (such as FF and Chrome).
1849 If multiple arguments are returned from the async function, `console.dir` is
1850 called on each argument in order.
1854 * `function` - The function you want to eventually apply all arguments to.
1855 * `arguments...` - Any number of arguments to apply to the function.
1860 var hello = function(name, callback){
1861 setTimeout(function(){
1862 callback(null, {hello: name});
1867 node> async.dir(hello, 'world');
1871 ---------------------------------------
1873 <a name="noConflict" />
1876 Changes the value of `async` back to its original value, returning a reference to the