socketioMEANseed/www/node_modules/async/README.md
www/node_modules/async/README.mdRaw
1# Async.js
2
3[](https://travis-ci.org/caolan/async)
4
5
6Async is a utility module which provides straight-forward, powerful functions
7for working with asynchronous JavaScript. Although originally designed for
8use with [Node.js](http://nodejs.org), it can also be used directly in the
9browser. Also supports [component](https://github.com/component/component).
10
11Async provides around 20 functions that include the usual 'functional'
12suspects (`map`, `reduce`, `filter`, `each`…) as well as some common patterns
13for asynchronous control flow (`parallel`, `series`, `waterfall`…). All these
14functions assume you follow the Node.js convention of providing a single
15callback as the last argument of your `async` function.
16
17
18## Quick Examples
19
20```javascript
21async.map(['file1','file2','file3'], fs.stat, function(err, results){
22 // results is now an array of stats for each file
23});
24
25async.filter(['file1','file2','file3'], fs.exists, function(results){
26 // results now equals an array of the existing files
27});
28
29async.parallel([
30 function(){ ... },
31 function(){ ... }
32], callback);
33
34async.series([
35 function(){ ... },
36 function(){ ... }
37]);
38```
39
40There are many more functions available so take a look at the docs below for a
41full list. This module aims to be comprehensive, so if you feel anything is
42missing please create a GitHub issue for it.
43
44## Common Pitfalls
45
46### Binding a context to an iterator
47
48This section is really about `bind`, not about `async`. If you are wondering how to
49make `async` execute your iterators in a given context, or are confused as to why
50a method of another library isn't working as an iterator, study this example:
51
52```js
53// Here is a simple object with an (unnecessarily roundabout) squaring method
54var AsyncSquaringLibrary = {
55 squareExponent: 2,
56 square: function(number, callback){
57 var result = Math.pow(number, this.squareExponent);
58 setTimeout(function(){
59 callback(null, result);
60 }, 200);
61 }
62};
63
64async.map([1, 2, 3], AsyncSquaringLibrary.square, function(err, result){
65 // result is [NaN, NaN, NaN]
66 // This fails because the `this.squareExponent` expression in the square
67 // function is not evaluated in the context of AsyncSquaringLibrary, and is
68 // therefore undefined.
69});
70
71async.map([1, 2, 3], AsyncSquaringLibrary.square.bind(AsyncSquaringLibrary), function(err, result){
72 // result is [1, 4, 9]
73 // With the help of bind we can attach a context to the iterator before
74 // passing it to async. Now the square function will be executed in its
75 // 'home' AsyncSquaringLibrary context and the value of `this.squareExponent`
76 // will be as expected.
77});
78```
79
80## Download
81
82The source is available for download from
83[GitHub](http://github.com/caolan/async).
84Alternatively, you can install using Node Package Manager (`npm`):
85
86 npm install async
87
88__Development:__ [async.js](https://github.com/caolan/async/raw/master/lib/async.js) - 29.6kb Uncompressed
89
90## In the Browser
91
92So far it's been tested in IE6, IE7, IE8, FF3.6 and Chrome 5.
93
94Usage:
95
96```html
97<script type="text/javascript" src="async.js"></script>
98<script type="text/javascript">
99
100 async.map(data, asyncProcess, function(err, results){
101 alert(results);
102 });
103
104</script>
105```
106
107## Documentation
108
109### Collections
110
111* [`each`](#each)
112* [`eachSeries`](#eachSeries)
113* [`eachLimit`](#eachLimit)
114* [`map`](#map)
115* [`mapSeries`](#mapSeries)
116* [`mapLimit`](#mapLimit)
117* [`filter`](#filter)
118* [`filterSeries`](#filterSeries)
119* [`reject`](#reject)
120* [`rejectSeries`](#rejectSeries)
121* [`reduce`](#reduce)
122* [`reduceRight`](#reduceRight)
123* [`detect`](#detect)
124* [`detectSeries`](#detectSeries)
125* [`sortBy`](#sortBy)
126* [`some`](#some)
127* [`every`](#every)
128* [`concat`](#concat)
129* [`concatSeries`](#concatSeries)
130
131### Control Flow
132
133* [`series`](#seriestasks-callback)
134* [`parallel`](#parallel)
135* [`parallelLimit`](#parallellimittasks-limit-callback)
136* [`whilst`](#whilst)
137* [`doWhilst`](#doWhilst)
138* [`until`](#until)
139* [`doUntil`](#doUntil)
140* [`forever`](#forever)
141* [`waterfall`](#waterfall)
142* [`compose`](#compose)
143* [`seq`](#seq)
144* [`applyEach`](#applyEach)
145* [`applyEachSeries`](#applyEachSeries)
146* [`queue`](#queue)
147* [`priorityQueue`](#priorityQueue)
148* [`cargo`](#cargo)
149* [`auto`](#auto)
150* [`retry`](#retry)
151* [`iterator`](#iterator)
152* [`apply`](#apply)
153* [`nextTick`](#nextTick)
154* [`times`](#times)
155* [`timesSeries`](#timesSeries)
156
157### Utils
158
159* [`memoize`](#memoize)
160* [`unmemoize`](#unmemoize)
161* [`log`](#log)
162* [`dir`](#dir)
163* [`noConflict`](#noConflict)
164
165
166## Collections
167
168<a name="forEach" />
169<a name="each" />
170### each(arr, iterator, callback)
171
172Applies the function `iterator` to each item in `arr`, in parallel.
173The `iterator` is called with an item from the list, and a callback for when it
174has finished. If the `iterator` passes an error to its `callback`, the main
175`callback` (for the `each` function) is immediately called with the error.
176
177Note, that since this function applies `iterator` to each item in parallel,
178there is no guarantee that the iterator functions will complete in order.
179
180__Arguments__
181
182* `arr` - An array to iterate over.
183* `iterator(item, callback)` - A function to apply to each item in `arr`.
184 The iterator is passed a `callback(err)` which must be called once it has
185 completed. If no error has occured, the `callback` should be run without
186 arguments or with an explicit `null` argument.
187* `callback(err)` - A callback which is called when all `iterator` functions
188 have finished, or an error occurs.
189
190__Examples__
191
192
193```js
194// assuming openFiles is an array of file names and saveFile is a function
195// to save the modified contents of that file:
196
197async.each(openFiles, saveFile, function(err){
198 // if any of the saves produced an error, err would equal that error
199});
200```
201
202```js
203// assuming openFiles is an array of file names
204
205async.each(openFiles, function( file, callback) {
206
207 // Perform operation on file here.
208 console.log('Processing file ' + file);
209
210 if( file.length > 32 ) {
211 console.log('This file name is too long');
212 callback('File name too long');
213 } else {
214 // Do work to process file here
215 console.log('File processed');
216 callback();
217 }
218}, function(err){
219 // if any of the file processing produced an error, err would equal that error
220 if( err ) {
221 // One of the iterations produced an error.
222 // All processing will now stop.
223 console.log('A file failed to process');
224 } else {
225 console.log('All files have been processed successfully');
226 }
227});
228```
229
230---------------------------------------
231
232<a name="forEachSeries" />
233<a name="eachSeries" />
234### eachSeries(arr, iterator, callback)
235
236The same as [`each`](#each), only `iterator` is applied to each item in `arr` in
237series. The next `iterator` is only called once the current one has completed.
238This means the `iterator` functions will complete in order.
239
240
241---------------------------------------
242
243<a name="forEachLimit" />
244<a name="eachLimit" />
245### eachLimit(arr, limit, iterator, callback)
246
247The same as [`each`](#each), only no more than `limit` `iterator`s will be simultaneously
248running at any time.
249
250Note that the items in `arr` are not processed in batches, so there is no guarantee that
251the first `limit` `iterator` functions will complete before any others are started.
252
253__Arguments__
254
255* `arr` - An array to iterate over.
256* `limit` - The maximum number of `iterator`s to run at any time.
257* `iterator(item, callback)` - A function to apply to each item in `arr`.
258 The iterator is passed a `callback(err)` which must be called once it has
259 completed. If no error has occured, the callback should be run without
260 arguments or with an explicit `null` argument.
261* `callback(err)` - A callback which is called when all `iterator` functions
262 have finished, or an error occurs.
263
264__Example__
265
266```js
267// Assume documents is an array of JSON objects and requestApi is a
268// function that interacts with a rate-limited REST api.
269
270async.eachLimit(documents, 20, requestApi, function(err){
271 // if any of the saves produced an error, err would equal that error
272});
273```
274
275---------------------------------------
276
277<a name="map" />
278### map(arr, iterator, callback)
279
280Produces a new array of values by mapping each value in `arr` through
281the `iterator` function. The `iterator` is called with an item from `arr` and a
282callback for when it has finished processing. Each of these callback takes 2 arguments:
283an `error`, and the transformed item from `arr`. If `iterator` passes an error to this
284callback, the main `callback` (for the `map` function) is immediately called with the error.
285
286Note, that since this function applies the `iterator` to each item in parallel,
287there is no guarantee that the `iterator` functions will complete in order.
288However, the results array will be in the same order as the original `arr`.
289
290__Arguments__
291
292* `arr` - An array to iterate over.
293* `iterator(item, callback)` - A function to apply to each item in `arr`.
294 The iterator is passed a `callback(err, transformed)` which must be called once
295 it has completed with an error (which can be `null`) and a transformed item.
296* `callback(err, results)` - A callback which is called when all `iterator`
297 functions have finished, or an error occurs. Results is an array of the
298 transformed items from the `arr`.
299
300__Example__
301
302```js
303async.map(['file1','file2','file3'], fs.stat, function(err, results){
304 // results is now an array of stats for each file
305});
306```
307
308---------------------------------------
309
310<a name="mapSeries" />
311### mapSeries(arr, iterator, callback)
312
313The same as [`map`](#map), only the `iterator` is applied to each item in `arr` in
314series. The next `iterator` is only called once the current one has completed.
315The results array will be in the same order as the original.
316
317
318---------------------------------------
319
320<a name="mapLimit" />
321### mapLimit(arr, limit, iterator, callback)
322
323The same as [`map`](#map), only no more than `limit` `iterator`s will be simultaneously
324running at any time.
325
326Note that the items are not processed in batches, so there is no guarantee that
327the first `limit` `iterator` functions will complete before any others are started.
328
329__Arguments__
330
331* `arr` - An array to iterate over.
332* `limit` - The maximum number of `iterator`s to run at any time.
333* `iterator(item, callback)` - A function to apply to each item in `arr`.
334 The iterator is passed a `callback(err, transformed)` which must be called once
335 it has completed with an error (which can be `null`) and a transformed item.
336* `callback(err, results)` - A callback which is called when all `iterator`
337 calls have finished, or an error occurs. The result is an array of the
338 transformed items from the original `arr`.
339
340__Example__
341
342```js
343async.mapLimit(['file1','file2','file3'], 1, fs.stat, function(err, results){
344 // results is now an array of stats for each file
345});
346```
347
348---------------------------------------
349
350<a name="select" />
351<a name="filter" />
352### filter(arr, iterator, callback)
353
354__Alias:__ `select`
355
356Returns a new array of all the values in `arr` which pass an async truth test.
357_The callback for each `iterator` call only accepts a single argument of `true` or
358`false`; it does not accept an error argument first!_ This is in-line with the
359way node libraries work with truth tests like `fs.exists`. This operation is
360performed in parallel, but the results array will be in the same order as the
361original.
362
363__Arguments__
364
365* `arr` - An array to iterate over.
366* `iterator(item, callback)` - A truth test to apply to each item in `arr`.
367 The `iterator` is passed a `callback(truthValue)`, which must be called with a
368 boolean argument once it has completed.
369* `callback(results)` - A callback which is called after all the `iterator`
370 functions have finished.
371
372__Example__
373
374```js
375async.filter(['file1','file2','file3'], fs.exists, function(results){
376 // results now equals an array of the existing files
377});
378```
379
380---------------------------------------
381
382<a name="selectSeries" />
383<a name="filterSeries" />
384### filterSeries(arr, iterator, callback)
385
386__Alias:__ `selectSeries`
387
388The same as [`filter`](#filter) only the `iterator` is applied to each item in `arr` in
389series. The next `iterator` is only called once the current one has completed.
390The results array will be in the same order as the original.
391
392---------------------------------------
393
394<a name="reject" />
395### reject(arr, iterator, callback)
396
397The opposite of [`filter`](#filter). Removes values that pass an `async` truth test.
398
399---------------------------------------
400
401<a name="rejectSeries" />
402### rejectSeries(arr, iterator, callback)
403
404The same as [`reject`](#reject), only the `iterator` is applied to each item in `arr`
405in series.
406
407
408---------------------------------------
409
410<a name="reduce" />
411### reduce(arr, memo, iterator, callback)
412
413__Aliases:__ `inject`, `foldl`
414
415Reduces `arr` into a single value using an async `iterator` to return
416each successive step. `memo` is the initial state of the reduction.
417This function only operates in series.
418
419For performance reasons, it may make sense to split a call to this function into
420a parallel map, and then use the normal `Array.prototype.reduce` on the results.
421This function is for situations where each step in the reduction needs to be async;
422if you can get the data before reducing it, then it's probably a good idea to do so.
423
424__Arguments__
425
426* `arr` - An array to iterate over.
427* `memo` - The initial state of the reduction.
428* `iterator(memo, item, callback)` - A function applied to each item in the
429 array to produce the next step in the reduction. The `iterator` is passed a
430 `callback(err, reduction)` which accepts an optional error as its first
431 argument, and the state of the reduction as the second. If an error is
432 passed to the callback, the reduction is stopped and the main `callback` is
433 immediately called with the error.
434* `callback(err, result)` - A callback which is called after all the `iterator`
435 functions have finished. Result is the reduced value.
436
437__Example__
438
439```js
440async.reduce([1,2,3], 0, function(memo, item, callback){
441 // pointless async:
442 process.nextTick(function(){
443 callback(null, memo + item)
444 });
445}, function(err, result){
446 // result is now equal to the last value of memo, which is 6
447});
448```
449
450---------------------------------------
451
452<a name="reduceRight" />
453### reduceRight(arr, memo, iterator, callback)
454
455__Alias:__ `foldr`
456
457Same as [`reduce`](#reduce), only operates on `arr` in reverse order.
458
459
460---------------------------------------
461
462<a name="detect" />
463### detect(arr, iterator, callback)
464
465Returns the first value in `arr` that passes an async truth test. The
466`iterator` is applied in parallel, meaning the first iterator to return `true` will
467fire the detect `callback` with that result. That means the result might not be
468the first item in the original `arr` (in terms of order) that passes the test.
469
470If order within the original `arr` is important, then look at [`detectSeries`](#detectSeries).
471
472__Arguments__
473
474* `arr` - An array to iterate over.
475* `iterator(item, callback)` - A truth test to apply to each item in `arr`.
476 The iterator is passed a `callback(truthValue)` which must be called with a
477 boolean argument once it has completed.
478* `callback(result)` - A callback which is called as soon as any iterator returns
479 `true`, or after all the `iterator` functions have finished. Result will be
480 the first item in the array that passes the truth test (iterator) or the
481 value `undefined` if none passed.
482
483__Example__
484
485```js
486async.detect(['file1','file2','file3'], fs.exists, function(result){
487 // result now equals the first file in the list that exists
488});
489```
490
491---------------------------------------
492
493<a name="detectSeries" />
494### detectSeries(arr, iterator, callback)
495
496The same as [`detect`](#detect), only the `iterator` is applied to each item in `arr`
497in series. This means the result is always the first in the original `arr` (in
498terms of array order) that passes the truth test.
499
500
501---------------------------------------
502
503<a name="sortBy" />
504### sortBy(arr, iterator, callback)
505
506Sorts a list by the results of running each `arr` value through an async `iterator`.
507
508__Arguments__
509
510* `arr` - An array to iterate over.
511* `iterator(item, callback)` - A function to apply to each item in `arr`.
512 The iterator is passed a `callback(err, sortValue)` which must be called once it
513 has completed with an error (which can be `null`) and a value to use as the sort
514 criteria.
515* `callback(err, results)` - A callback which is called after all the `iterator`
516 functions have finished, or an error occurs. Results is the items from
517 the original `arr` sorted by the values returned by the `iterator` calls.
518
519__Example__
520
521```js
522async.sortBy(['file1','file2','file3'], function(file, callback){
523 fs.stat(file, function(err, stats){
524 callback(err, stats.mtime);
525 });
526}, function(err, results){
527 // results is now the original array of files sorted by
528 // modified date
529});
530```
531
532__Sort Order__
533
534By modifying the callback parameter the sorting order can be influenced:
535
536```js
537//ascending order
538async.sortBy([1,9,3,5], function(x, callback){
539 callback(err, x);
540}, function(err,result){
541 //result callback
542} );
543
544//descending order
545async.sortBy([1,9,3,5], function(x, callback){
546 callback(err, x*-1); //<- x*-1 instead of x, turns the order around
547}, function(err,result){
548 //result callback
549} );
550```
551
552---------------------------------------
553
554<a name="some" />
555### some(arr, iterator, callback)
556
557__Alias:__ `any`
558
559Returns `true` if at least one element in the `arr` satisfies an async test.
560_The callback for each iterator call only accepts a single argument of `true` or
561`false`; it does not accept an error argument first!_ This is in-line with the
562way node libraries work with truth tests like `fs.exists`. Once any iterator
563call returns `true`, the main `callback` is immediately called.
564
565__Arguments__
566
567* `arr` - An array to iterate over.
568* `iterator(item, callback)` - A truth test to apply to each item in the array
569 in parallel. The iterator is passed a callback(truthValue) which must be
570 called with a boolean argument once it has completed.
571* `callback(result)` - A callback which is called as soon as any iterator returns
572 `true`, or after all the iterator functions have finished. Result will be
573 either `true` or `false` depending on the values of the async tests.
574
575__Example__
576
577```js
578async.some(['file1','file2','file3'], fs.exists, function(result){
579 // if result is true then at least one of the files exists
580});
581```
582
583---------------------------------------
584
585<a name="every" />
586### every(arr, iterator, callback)
587
588__Alias:__ `all`
589
590Returns `true` if every element in `arr` satisfies an async test.
591_The callback for each `iterator` call only accepts a single argument of `true` or
592`false`; it does not accept an error argument first!_ This is in-line with the
593way node libraries work with truth tests like `fs.exists`.
594
595__Arguments__
596
597* `arr` - An array to iterate over.
598* `iterator(item, callback)` - A truth test to apply to each item in the array
599 in parallel. The iterator is passed a callback(truthValue) which must be
600 called with a boolean argument once it has completed.
601* `callback(result)` - A callback which is called after all the `iterator`
602 functions have finished. Result will be either `true` or `false` depending on
603 the values of the async tests.
604
605__Example__
606
607```js
608async.every(['file1','file2','file3'], fs.exists, function(result){
609 // if result is true then every file exists
610});
611```
612
613---------------------------------------
614
615<a name="concat" />
616### concat(arr, iterator, callback)
617
618Applies `iterator` to each item in `arr`, concatenating the results. Returns the
619concatenated list. The `iterator`s are called in parallel, and the results are
620concatenated as they return. There is no guarantee that the results array will
621be returned in the original order of `arr` passed to the `iterator` function.
622
623__Arguments__
624
625* `arr` - An array to iterate over.
626* `iterator(item, callback)` - A function to apply to each item in `arr`.
627 The iterator is passed a `callback(err, results)` which must be called once it
628 has completed with an error (which can be `null`) and an array of results.
629* `callback(err, results)` - A callback which is called after all the `iterator`
630 functions have finished, or an error occurs. Results is an array containing
631 the concatenated results of the `iterator` function.
632
633__Example__
634
635```js
636async.concat(['dir1','dir2','dir3'], fs.readdir, function(err, files){
637 // files is now a list of filenames that exist in the 3 directories
638});
639```
640
641---------------------------------------
642
643<a name="concatSeries" />
644### concatSeries(arr, iterator, callback)
645
646Same as [`concat`](#concat), but executes in series instead of parallel.
647
648
649## Control Flow
650
651<a name="series" />
652### series(tasks, [callback])
653
654Run the functions in the `tasks` array in series, each one running once the previous
655function has completed. If any functions in the series pass an error to its
656callback, no more functions are run, and `callback` is immediately called with the value of the error.
657Otherwise, `callback` receives an array of results when `tasks` have completed.
658
659It is also possible to use an object instead of an array. Each property will be
660run as a function, and the results will be passed to the final `callback` as an object
661instead of an array. This can be a more readable way of handling results from
662[`series`](#series).
663
664**Note** that while many implementations preserve the order of object properties, the
665[ECMAScript Language Specifcation](http://www.ecma-international.org/ecma-262/5.1/#sec-8.6)
666explicitly states that
667
668> The mechanics and order of enumerating the properties is not specified.
669
670So if you rely on the order in which your series of functions are executed, and want
671this to work on all platforms, consider using an array.
672
673__Arguments__
674
675* `tasks` - An array or object containing functions to run, each function is passed
676 a `callback(err, result)` it must call on completion with an error `err` (which can
677 be `null`) and an optional `result` value.
678* `callback(err, results)` - An optional callback to run once all the functions
679 have completed. This function gets a results array (or object) containing all
680 the result arguments passed to the `task` callbacks.
681
682__Example__
683
684```js
685async.series([
686 function(callback){
687 // do some stuff ...
688 callback(null, 'one');
689 },
690 function(callback){
691 // do some more stuff ...
692 callback(null, 'two');
693 }
694],
695// optional callback
696function(err, results){
697 // results is now equal to ['one', 'two']
698});
699
700
701// an example using an object instead of an array
702async.series({
703 one: function(callback){
704 setTimeout(function(){
705 callback(null, 1);
706 }, 200);
707 },
708 two: function(callback){
709 setTimeout(function(){
710 callback(null, 2);
711 }, 100);
712 }
713},
714function(err, results) {
715 // results is now equal to: {one: 1, two: 2}
716});
717```
718
719---------------------------------------
720
721<a name="parallel" />
722### parallel(tasks, [callback])
723
724Run the `tasks` array of functions in parallel, without waiting until the previous
725function has completed. If any of the functions pass an error to its
726callback, the main `callback` is immediately called with the value of the error.
727Once the `tasks` have completed, the results are passed to the final `callback` as an
728array.
729
730It is also possible to use an object instead of an array. Each property will be
731run as a function and the results will be passed to the final `callback` as an object
732instead of an array. This can be a more readable way of handling results from
733[`parallel`](#parallel).
734
735
736__Arguments__
737
738* `tasks` - An array or object containing functions to run. Each function is passed
739 a `callback(err, result)` which it must call on completion with an error `err`
740 (which can be `null`) and an optional `result` value.
741* `callback(err, results)` - An optional callback to run once all the functions
742 have completed. This function gets a results array (or object) containing all
743 the result arguments passed to the task callbacks.
744
745__Example__
746
747```js
748async.parallel([
749 function(callback){
750 setTimeout(function(){
751 callback(null, 'one');
752 }, 200);
753 },
754 function(callback){
755 setTimeout(function(){
756 callback(null, 'two');
757 }, 100);
758 }
759],
760// optional callback
761function(err, results){
762 // the results array will equal ['one','two'] even though
763 // the second function had a shorter timeout.
764});
765
766
767// an example using an object instead of an array
768async.parallel({
769 one: function(callback){
770 setTimeout(function(){
771 callback(null, 1);
772 }, 200);
773 },
774 two: function(callback){
775 setTimeout(function(){
776 callback(null, 2);
777 }, 100);
778 }
779},
780function(err, results) {
781 // results is now equals to: {one: 1, two: 2}
782});
783```
784
785---------------------------------------
786
787<a name="parallelLimit" />
788### parallelLimit(tasks, limit, [callback])
789
790The same as [`parallel`](#parallel), only `tasks` are executed in parallel
791with a maximum of `limit` tasks executing at any time.
792
793Note that the `tasks` are not executed in batches, so there is no guarantee that
794the first `limit` tasks will complete before any others are started.
795
796__Arguments__
797
798* `tasks` - An array or object containing functions to run, each function is passed
799 a `callback(err, result)` it must call on completion with an error `err` (which can
800 be `null`) and an optional `result` value.
801* `limit` - The maximum number of `tasks` to run at any time.
802* `callback(err, results)` - An optional callback to run once all the functions
803 have completed. This function gets a results array (or object) containing all
804 the result arguments passed to the `task` callbacks.
805
806---------------------------------------
807
808<a name="whilst" />
809### whilst(test, fn, callback)
810
811Repeatedly call `fn`, while `test` returns `true`. Calls `callback` when stopped,
812or an error occurs.
813
814__Arguments__
815
816* `test()` - synchronous truth test to perform before each execution of `fn`.
817* `fn(callback)` - A function which is called each time `test` passes. The function is
818 passed a `callback(err)`, which must be called once it has completed with an
819 optional `err` argument.
820* `callback(err)` - A callback which is called after the test fails and repeated
821 execution of `fn` has stopped.
822
823__Example__
824
825```js
826var count = 0;
827
828async.whilst(
829 function () { return count < 5; },
830 function (callback) {
831 count++;
832 setTimeout(callback, 1000);
833 },
834 function (err) {
835 // 5 seconds have passed
836 }
837);
838```
839
840---------------------------------------
841
842<a name="doWhilst" />
843### doWhilst(fn, test, callback)
844
845The post-check version of [`whilst`](#whilst). To reflect the difference in
846the order of operations, the arguments `test` and `fn` are switched.
847
848`doWhilst` is to `whilst` as `do while` is to `while` in plain JavaScript.
849
850---------------------------------------
851
852<a name="until" />
853### until(test, fn, callback)
854
855Repeatedly call `fn` until `test` returns `true`. Calls `callback` when stopped,
856or an error occurs.
857
858The inverse of [`whilst`](#whilst).
859
860---------------------------------------
861
862<a name="doUntil" />
863### doUntil(fn, test, callback)
864
865Like [`doWhilst`](#doWhilst), except the `test` is inverted. Note the argument ordering differs from `until`.
866
867---------------------------------------
868
869<a name="forever" />
870### forever(fn, errback)
871
872Calls the asynchronous function `fn` with a callback parameter that allows it to
873call itself again, in series, indefinitely.
874
875If an error is passed to the callback then `errback` is called with the
876error, and execution stops, otherwise it will never be called.
877
878```js
879async.forever(
880 function(next) {
881 // next is suitable for passing to things that need a callback(err [, whatever]);
882 // it will result in this function being called again.
883 },
884 function(err) {
885 // if next is called with a value in its first parameter, it will appear
886 // in here as 'err', and execution will stop.
887 }
888);
889```
890
891---------------------------------------
892
893<a name="waterfall" />
894### waterfall(tasks, [callback])
895
896Runs the `tasks` array of functions in series, each passing their results to the next in
897the array. However, if any of the `tasks` pass an error to their own callback, the
898next function is not executed, and the main `callback` is immediately called with
899the error.
900
901__Arguments__
902
903* `tasks` - An array of functions to run, each function is passed a
904 `callback(err, result1, result2, ...)` it must call on completion. The first
905 argument is an error (which can be `null`) and any further arguments will be
906 passed as arguments in order to the next task.
907* `callback(err, [results])` - An optional callback to run once all the functions
908 have completed. This will be passed the results of the last task's callback.
909
910
911
912__Example__
913
914```js
915async.waterfall([
916 function(callback){
917 callback(null, 'one', 'two');
918 },
919 function(arg1, arg2, callback){
920 // arg1 now equals 'one' and arg2 now equals 'two'
921 callback(null, 'three');
922 },
923 function(arg1, callback){
924 // arg1 now equals 'three'
925 callback(null, 'done');
926 }
927], function (err, result) {
928 // result now equals 'done'
929});
930```
931
932---------------------------------------
933<a name="compose" />
934### compose(fn1, fn2...)
935
936Creates a function which is a composition of the passed asynchronous
937functions. Each function consumes the return value of the function that
938follows. Composing functions `f()`, `g()`, and `h()` would produce the result of
939`f(g(h()))`, only this version uses callbacks to obtain the return values.
940
941Each function is executed with the `this` binding of the composed function.
942
943__Arguments__
944
945* `functions...` - the asynchronous functions to compose
946
947
948__Example__
949
950```js
951function add1(n, callback) {
952 setTimeout(function () {
953 callback(null, n + 1);
954 }, 10);
955}
956
957function mul3(n, callback) {
958 setTimeout(function () {
959 callback(null, n * 3);
960 }, 10);
961}
962
963var add1mul3 = async.compose(mul3, add1);
964
965add1mul3(4, function (err, result) {
966 // result now equals 15
967});
968```
969
970---------------------------------------
971<a name="seq" />
972### seq(fn1, fn2...)
973
974Version of the compose function that is more natural to read.
975Each following function consumes the return value of the latter function.
976
977Each function is executed with the `this` binding of the composed function.
978
979__Arguments__
980
981* functions... - the asynchronous functions to compose
982
983
984__Example__
985
986```js
987// Requires lodash (or underscore), express3 and dresende's orm2.
988// Part of an app, that fetches cats of the logged user.
989// This example uses `seq` function to avoid overnesting and error
990// handling clutter.
991app.get('/cats', function(request, response) {
992 function handleError(err, data, callback) {
993 if (err) {
994 console.error(err);
995 response.json({ status: 'error', message: err.message });
996 }
997 else {
998 callback(data);
999 }
1000 }
1001 var User = request.models.User;
1002 async.seq(
1003 _.bind(User.get, User), // 'User.get' has signature (id, callback(err, data))
1004 handleError,
1005 function(user, fn) {
1006 user.getCats(fn); // 'getCats' has signature (callback(err, data))
1007 },
1008 handleError,
1009 function(cats) {
1010 response.json({ status: 'ok', message: 'Cats found', data: cats });
1011 }
1012 )(req.session.user_id);
1013 }
1014});
1015```
1016
1017---------------------------------------
1018<a name="applyEach" />
1019### applyEach(fns, args..., callback)
1020
1021Applies the provided arguments to each function in the array, calling
1022`callback` after all functions have completed. If you only provide the first
1023argument, then it will return a function which lets you pass in the
1024arguments as if it were a single function call.
1025
1026__Arguments__
1027
1028* `fns` - the asynchronous functions to all call with the same arguments
1029* `args...` - any number of separate arguments to pass to the function
1030* `callback` - the final argument should be the callback, called when all
1031 functions have completed processing
1032
1033
1034__Example__
1035
1036```js
1037async.applyEach([enableSearch, updateSchema], 'bucket', callback);
1038
1039// partial application example:
1040async.each(
1041 buckets,
1042 async.applyEach([enableSearch, updateSchema]),
1043 callback
1044);
1045```
1046
1047---------------------------------------
1048
1049<a name="applyEachSeries" />
1050### applyEachSeries(arr, iterator, callback)
1051
1052The same as [`applyEach`](#applyEach) only the functions are applied in series.
1053
1054---------------------------------------
1055
1056<a name="queue" />
1057### queue(worker, concurrency)
1058
1059Creates a `queue` object with the specified `concurrency`. Tasks added to the
1060`queue` are processed in parallel (up to the `concurrency` limit). If all
1061`worker`s are in progress, the task is queued until one becomes available.
1062Once a `worker` completes a `task`, that `task`'s callback is called.
1063
1064__Arguments__
1065
1066* `worker(task, callback)` - An asynchronous function for processing a queued
1067 task, which must call its `callback(err)` argument when finished, with an
1068 optional `error` as an argument.
1069* `concurrency` - An `integer` for determining how many `worker` functions should be
1070 run in parallel.
1071
1072__Queue objects__
1073
1074The `queue` object returned by this function has the following properties and
1075methods:
1076
1077* `length()` - a function returning the number of items waiting to be processed.
1078* `started` - a function returning whether or not any items have been pushed and processed by the queue
1079* `running()` - a function returning the number of items currently being processed.
1080* `idle()` - a function returning false if there are items waiting or being processed, or true if not.
1081* `concurrency` - an integer for determining how many `worker` functions should be
1082 run in parallel. This property can be changed after a `queue` is created to
1083 alter the concurrency on-the-fly.
1084* `push(task, [callback])` - add a new task to the `queue`. Calls `callback` once
1085 the `worker` has finished processing the task. Instead of a single task, a `tasks` array
1086 can be submitted. The respective callback is used for every task in the list.
1087* `unshift(task, [callback])` - add a new task to the front of the `queue`.
1088* `saturated` - a callback that is called when the `queue` length hits the `concurrency` limit,
1089 and further tasks will be queued.
1090* `empty` - a callback that is called when the last item from the `queue` is given to a `worker`.
1091* `drain` - a callback that is called when the last item from the `queue` has returned from the `worker`.
1092* `paused` - a boolean for determining whether the queue is in a paused state
1093* `pause()` - a function that pauses the processing of tasks until `resume()` is called.
1094* `resume()` - a function that resumes the processing of queued tasks when the queue is paused.
1095* `kill()` - a function that empties remaining tasks from the queue forcing it to go idle.
1096
1097__Example__
1098
1099```js
1100// create a queue object with concurrency 2
1101
1102var q = async.queue(function (task, callback) {
1103 console.log('hello ' + task.name);
1104 callback();
1105}, 2);
1106
1107
1108// assign a callback
1109q.drain = function() {
1110 console.log('all items have been processed');
1111}
1112
1113// add some items to the queue
1114
1115q.push({name: 'foo'}, function (err) {
1116 console.log('finished processing foo');
1117});
1118q.push({name: 'bar'}, function (err) {
1119 console.log('finished processing bar');
1120});
1121
1122// add some items to the queue (batch-wise)
1123
1124q.push([{name: 'baz'},{name: 'bay'},{name: 'bax'}], function (err) {
1125 console.log('finished processing bar');
1126});
1127
1128// add some items to the front of the queue
1129
1130q.unshift({name: 'bar'}, function (err) {
1131 console.log('finished processing bar');
1132});
1133```
1134
1135
1136---------------------------------------
1137
1138<a name="priorityQueue" />
1139### priorityQueue(worker, concurrency)
1140
1141The 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:
1142
1143* `push(task, priority, [callback])` - `priority` should be a number. If an array of
1144 `tasks` is given, all tasks will be assigned the same priority.
1145* The `unshift` method was removed.
1146
1147---------------------------------------
1148
1149<a name="cargo" />
1150### cargo(worker, [payload])
1151
1152Creates a `cargo` object with the specified payload. Tasks added to the
1153cargo will be processed altogether (up to the `payload` limit). If the
1154`worker` is in progress, the task is queued until it becomes available. Once
1155the `worker` has completed some tasks, each callback of those tasks is called.
1156Check out [this animation](https://camo.githubusercontent.com/6bbd36f4cf5b35a0f11a96dcd2e97711ffc2fb37/68747470733a2f2f662e636c6f75642e6769746875622e636f6d2f6173736574732f313637363837312f36383130382f62626330636662302d356632392d313165322d393734662d3333393763363464633835382e676966) for how `cargo` and `queue` work.
1157
1158While [queue](#queue) passes only one task to one of a group of workers
1159at a time, cargo passes an array of tasks to a single worker, repeating
1160when the worker is finished.
1161
1162__Arguments__
1163
1164* `worker(tasks, callback)` - An asynchronous function for processing an array of
1165 queued tasks, which must call its `callback(err)` argument when finished, with
1166 an optional `err` argument.
1167* `payload` - An optional `integer` for determining how many tasks should be
1168 processed per round; if omitted, the default is unlimited.
1169
1170__Cargo objects__
1171
1172The `cargo` object returned by this function has the following properties and
1173methods:
1174
1175* `length()` - A function returning the number of items waiting to be processed.
1176* `payload` - An `integer` for determining how many tasks should be
1177 process per round. This property can be changed after a `cargo` is created to
1178 alter the payload on-the-fly.
1179* `push(task, [callback])` - Adds `task` to the `queue`. The callback is called
1180 once the `worker` has finished processing the task. Instead of a single task, an array of `tasks`
1181 can be submitted. The respective callback is used for every task in the list.
1182* `saturated` - A callback that is called when the `queue.length()` hits the concurrency and further tasks will be queued.
1183* `empty` - A callback that is called when the last item from the `queue` is given to a `worker`.
1184* `drain` - A callback that is called when the last item from the `queue` has returned from the `worker`.
1185
1186__Example__
1187
1188```js
1189// create a cargo object with payload 2
1190
1191var cargo = async.cargo(function (tasks, callback) {
1192 for(var i=0; i<tasks.length; i++){
1193 console.log('hello ' + tasks[i].name);
1194 }
1195 callback();
1196}, 2);
1197
1198
1199// add some items
1200
1201cargo.push({name: 'foo'}, function (err) {
1202 console.log('finished processing foo');
1203});
1204cargo.push({name: 'bar'}, function (err) {
1205 console.log('finished processing bar');
1206});
1207cargo.push({name: 'baz'}, function (err) {
1208 console.log('finished processing baz');
1209});
1210```
1211
1212---------------------------------------
1213
1214<a name="auto" />
1215### auto(tasks, [callback])
1216
1217Determines the best order for running the functions in `tasks`, based on their
1218requirements. Each function can optionally depend on other functions being completed
1219first, and each function is run as soon as its requirements are satisfied.
1220
1221If any of the functions pass an error to their callback, it will not
1222complete (so any other functions depending on it will not run), and the main
1223`callback` is immediately called with the error. Functions also receive an
1224object containing the results of functions which have completed so far.
1225
1226Note, all functions are called with a `results` object as a second argument,
1227so it is unsafe to pass functions in the `tasks` object which cannot handle the
1228extra argument.
1229
1230For example, this snippet of code:
1231
1232```js
1233async.auto({
1234 readData: async.apply(fs.readFile, 'data.txt', 'utf-8')
1235}, callback);
1236```
1237
1238will have the effect of calling `readFile` with the results object as the last
1239argument, which will fail:
1240
1241```js
1242fs.readFile('data.txt', 'utf-8', cb, {});
1243```
1244
1245Instead, wrap the call to `readFile` in a function which does not forward the
1246`results` object:
1247
1248```js
1249async.auto({
1250 readData: function(cb, results){
1251 fs.readFile('data.txt', 'utf-8', cb);
1252 }
1253}, callback);
1254```
1255
1256__Arguments__
1257
1258* `tasks` - An object. Each of its properties is either a function or an array of
1259 requirements, with the function itself the last item in the array. The object's key
1260 of a property serves as the name of the task defined by that property,
1261 i.e. can be used when specifying requirements for other tasks.
1262 The function receives two arguments: (1) a `callback(err, result)` which must be
1263 called when finished, passing an `error` (which can be `null`) and the result of
1264 the function's execution, and (2) a `results` object, containing the results of
1265 the previously executed functions.
1266* `callback(err, results)` - An optional callback which is called when all the
1267 tasks have been completed. It receives the `err` argument if any `tasks`
1268 pass an error to their callback. Results are always returned; however, if
1269 an error occurs, no further `tasks` will be performed, and the results
1270 object will only contain partial results.
1271
1272
1273__Example__
1274
1275```js
1276async.auto({
1277 get_data: function(callback){
1278 console.log('in get_data');
1279 // async code to get some data
1280 callback(null, 'data', 'converted to array');
1281 },
1282 make_folder: function(callback){
1283 console.log('in make_folder');
1284 // async code to create a directory to store a file in
1285 // this is run at the same time as getting the data
1286 callback(null, 'folder');
1287 },
1288 write_file: ['get_data', 'make_folder', function(callback, results){
1289 console.log('in write_file', JSON.stringify(results));
1290 // once there is some data and the directory exists,
1291 // write the data to a file in the directory
1292 callback(null, 'filename');
1293 }],
1294 email_link: ['write_file', function(callback, results){
1295 console.log('in email_link', JSON.stringify(results));
1296 // once the file is written let's email a link to it...
1297 // results.write_file contains the filename returned by write_file.
1298 callback(null, {'file':results.write_file, 'email':'user@example.com'});
1299 }]
1300}, function(err, results) {
1301 console.log('err = ', err);
1302 console.log('results = ', results);
1303});
1304```
1305
1306This is a fairly trivial example, but to do this using the basic parallel and
1307series functions would look like this:
1308
1309```js
1310async.parallel([
1311 function(callback){
1312 console.log('in get_data');
1313 // async code to get some data
1314 callback(null, 'data', 'converted to array');
1315 },
1316 function(callback){
1317 console.log('in make_folder');
1318 // async code to create a directory to store a file in
1319 // this is run at the same time as getting the data
1320 callback(null, 'folder');
1321 }
1322],
1323function(err, results){
1324 async.series([
1325 function(callback){
1326 console.log('in write_file', JSON.stringify(results));
1327 // once there is some data and the directory exists,
1328 // write the data to a file in the directory
1329 results.push('filename');
1330 callback(null);
1331 },
1332 function(callback){
1333 console.log('in email_link', JSON.stringify(results));
1334 // once the file is written let's email a link to it...
1335 callback(null, {'file':results.pop(), 'email':'user@example.com'});
1336 }
1337 ]);
1338});
1339```
1340
1341For a complicated series of `async` tasks, using the [`auto`](#auto) function makes adding
1342new tasks much easier (and the code more readable).
1343
1344
1345---------------------------------------
1346
1347<a name="retry" />
1348### retry([times = 5], task, [callback])
1349
1350Attempts to get a successful response from `task` no more than `times` times before
1351returning an error. If the task is successful, the `callback` will be passed the result
1352of the successfull task. If all attemps fail, the callback will be passed the error and
1353result (if any) of the final attempt.
1354
1355__Arguments__
1356
1357* `times` - An integer indicating how many times to attempt the `task` before giving up. Defaults to 5.
1358* `task(callback, results)` - A function which receives two arguments: (1) a `callback(err, result)`
1359 which must be called when finished, passing `err` (which can be `null`) and the `result` of
1360 the function's execution, and (2) a `results` object, containing the results of
1361 the previously executed functions (if nested inside another control flow).
1362* `callback(err, results)` - An optional callback which is called when the
1363 task has succeeded, or after the final failed attempt. It receives the `err` and `result` arguments of the last attempt at completing the `task`.
1364
1365The [`retry`](#retry) function can be used as a stand-alone control flow by passing a
1366callback, as shown below:
1367
1368```js
1369async.retry(3, apiMethod, function(err, result) {
1370 // do something with the result
1371});
1372```
1373
1374It can also be embeded within other control flow functions to retry individual methods
1375that are not as reliable, like this:
1376
1377```js
1378async.auto({
1379 users: api.getUsers.bind(api),
1380 payments: async.retry(3, api.getPayments.bind(api))
1381}, function(err, results) {
1382 // do something with the results
1383});
1384```
1385
1386
1387---------------------------------------
1388
1389<a name="iterator" />
1390### iterator(tasks)
1391
1392Creates an iterator function which calls the next function in the `tasks` array,
1393returning a continuation to call the next one after that. It's also possible to
1394“peek” at the next iterator with `iterator.next()`.
1395
1396This function is used internally by the `async` module, but can be useful when
1397you want to manually control the flow of functions in series.
1398
1399__Arguments__
1400
1401* `tasks` - An array of functions to run.
1402
1403__Example__
1404
1405```js
1406var iterator = async.iterator([
1407 function(){ sys.p('one'); },
1408 function(){ sys.p('two'); },
1409 function(){ sys.p('three'); }
1410]);
1411
1412node> var iterator2 = iterator();
1413'one'
1414node> var iterator3 = iterator2();
1415'two'
1416node> iterator3();
1417'three'
1418node> var nextfn = iterator2.next();
1419node> nextfn();
1420'three'
1421```
1422
1423---------------------------------------
1424
1425<a name="apply" />
1426### apply(function, arguments..)
1427
1428Creates a continuation function with some arguments already applied.
1429
1430Useful as a shorthand when combined with other control flow functions. Any arguments
1431passed to the returned function are added to the arguments originally passed
1432to apply.
1433
1434__Arguments__
1435
1436* `function` - The function you want to eventually apply all arguments to.
1437* `arguments...` - Any number of arguments to automatically apply when the
1438 continuation is called.
1439
1440__Example__
1441
1442```js
1443// using apply
1444
1445async.parallel([
1446 async.apply(fs.writeFile, 'testfile1', 'test1'),
1447 async.apply(fs.writeFile, 'testfile2', 'test2'),
1448]);
1449
1450
1451// the same process without using apply
1452
1453async.parallel([
1454 function(callback){
1455 fs.writeFile('testfile1', 'test1', callback);
1456 },
1457 function(callback){
1458 fs.writeFile('testfile2', 'test2', callback);
1459 }
1460]);
1461```
1462
1463It's possible to pass any number of additional arguments when calling the
1464continuation:
1465
1466```js
1467node> var fn = async.apply(sys.puts, 'one');
1468node> fn('two', 'three');
1469one
1470two
1471three
1472```
1473
1474---------------------------------------
1475
1476<a name="nextTick" />
1477### nextTick(callback)
1478
1479Calls `callback` on a later loop around the event loop. In Node.js this just
1480calls `process.nextTick`; in the browser it falls back to `setImmediate(callback)`
1481if available, otherwise `setTimeout(callback, 0)`, which means other higher priority
1482events may precede the execution of `callback`.
1483
1484This is used internally for browser-compatibility purposes.
1485
1486__Arguments__
1487
1488* `callback` - The function to call on a later loop around the event loop.
1489
1490__Example__
1491
1492```js
1493var call_order = [];
1494async.nextTick(function(){
1495 call_order.push('two');
1496 // call_order now equals ['one','two']
1497});
1498call_order.push('one')
1499```
1500
1501<a name="times" />
1502### times(n, callback)
1503
1504Calls the `callback` function `n` times, and accumulates results in the same manner
1505you would use with [`map`](#map).
1506
1507__Arguments__
1508
1509* `n` - The number of times to run the function.
1510* `callback` - The function to call `n` times.
1511
1512__Example__
1513
1514```js
1515// Pretend this is some complicated async factory
1516var createUser = function(id, callback) {
1517 callback(null, {
1518 id: 'user' + id
1519 })
1520}
1521// generate 5 users
1522async.times(5, function(n, next){
1523 createUser(n, function(err, user) {
1524 next(err, user)
1525 })
1526}, function(err, users) {
1527 // we should now have 5 users
1528});
1529```
1530
1531<a name="timesSeries" />
1532### timesSeries(n, callback)
1533
1534The same as [`times`](#times), only the iterator is applied to each item in `arr` in
1535series. The next `iterator` is only called once the current one has completed.
1536The results array will be in the same order as the original.
1537
1538
1539## Utils
1540
1541<a name="memoize" />
1542### memoize(fn, [hasher])
1543
1544Caches the results of an `async` function. When creating a hash to store function
1545results against, the callback is omitted from the hash and an optional hash
1546function can be used.
1547
1548The cache of results is exposed as the `memo` property of the function returned
1549by `memoize`.
1550
1551__Arguments__
1552
1553* `fn` - The function to proxy and cache results from.
1554* `hasher` - Tn optional function for generating a custom hash for storing
1555 results. It has all the arguments applied to it apart from the callback, and
1556 must be synchronous.
1557
1558__Example__
1559
1560```js
1561var slow_fn = function (name, callback) {
1562 // do something
1563 callback(null, result);
1564};
1565var fn = async.memoize(slow_fn);
1566
1567// fn can now be used as if it were slow_fn
1568fn('some name', function () {
1569 // callback
1570});
1571```
1572
1573<a name="unmemoize" />
1574### unmemoize(fn)
1575
1576Undoes a [`memoize`](#memoize)d function, reverting it to the original, unmemoized
1577form. Handy for testing.
1578
1579__Arguments__
1580
1581* `fn` - the memoized function
1582
1583<a name="log" />
1584### log(function, arguments)
1585
1586Logs the result of an `async` function to the `console`. Only works in Node.js or
1587in browsers that support `console.log` and `console.error` (such as FF and Chrome).
1588If multiple arguments are returned from the async function, `console.log` is
1589called on each argument in order.
1590
1591__Arguments__
1592
1593* `function` - The function you want to eventually apply all arguments to.
1594* `arguments...` - Any number of arguments to apply to the function.
1595
1596__Example__
1597
1598```js
1599var hello = function(name, callback){
1600 setTimeout(function(){
1601 callback(null, 'hello ' + name);
1602 }, 1000);
1603};
1604```
1605```js
1606node> async.log(hello, 'world');
1607'hello world'
1608```
1609
1610---------------------------------------
1611
1612<a name="dir" />
1613### dir(function, arguments)
1614
1615Logs the result of an `async` function to the `console` using `console.dir` to
1616display the properties of the resulting object. Only works in Node.js or
1617in browsers that support `console.dir` and `console.error` (such as FF and Chrome).
1618If multiple arguments are returned from the async function, `console.dir` is
1619called on each argument in order.
1620
1621__Arguments__
1622
1623* `function` - The function you want to eventually apply all arguments to.
1624* `arguments...` - Any number of arguments to apply to the function.
1625
1626__Example__
1627
1628```js
1629var hello = function(name, callback){
1630 setTimeout(function(){
1631 callback(null, {hello: name});
1632 }, 1000);
1633};
1634```
1635```js
1636node> async.dir(hello, 'world');
1637{hello: 'world'}
1638```
1639
1640---------------------------------------
1641
1642<a name="noConflict" />
1643### noConflict()
1644
1645Changes the value of `async` back to its original value, returning a reference to the
1646`async` object.