Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 1010 lines (730 sloc) 31.781 kb
5011005a »
2010-07-11 updated README
1 # Async.js
2
3 Async is a utility module which provides straight-forward, powerful functions
4 for working with asynchronous JavaScript. Although originally designed for
5 use with [node.js](http://nodejs.org), it can also be used directly in the
6 browser.
7
8 Async provides around 20 functions that include the usual 'functional'
9 suspects (map, reduce, filter, forEach…) as well as some common patterns
2810b751 »
2011-05-17 replace 'flow control' with 'control flow' in README to shut marak up
10 for asynchronous control flow (parallel, series, waterfall…). All these
5011005a »
2010-07-11 updated README
11 functions assume you follow the node.js convention of providing a single
12 callback as the last argument of your async function.
13
14
15 ## Quick Examples
353f4416 »
2010-07-07 added browser support
16
17 async.map(['file1','file2','file3'], fs.stat, function(err, results){
18 // results is now an array of stats for each file
19 });
20
21 async.filter(['file1','file2','file3'], path.exists, function(results){
22 // results now equals an array of the existing files
23 });
24
25 async.parallel([
26 function(){ ... },
27 function(){ ... }
28 ], callback);
29
30 async.series([
31 function(){ ... },
32 function(){ ... }
33 ]);
34
5011005a »
2010-07-11 updated README
35 There are many more functions available so take a look at the docs below for a
36 full list. This module aims to be comprehensive, so if you feel anything is
37 missing please create a GitHub issue for it.
38
39
40 ## Download
353f4416 »
2010-07-07 added browser support
41
5011005a »
2010-07-11 updated README
42 Releases are available for download from
43 [GitHub](http://github.com/caolan/async/downloads).
44 Alternatively, you can install using Node Package Manager (npm):
cb11f0d1 »
2010-06-30 added npm install command to README
45
46 npm install async
47
b4d37093 »
2010-11-17 add line break between development and production links in README
48
9fc0c345 »
2010-11-17 add links to async.js and async.min.js in README
49 __Development:__ [async.js](https://github.com/caolan/async/raw/master/lib/async.js) - 17.5kb Uncompressed
b4d37093 »
2010-11-17 add line break between development and production links in README
50
9fc0c345 »
2010-11-17 add links to async.js and async.min.js in README
51 __Production:__ [async.min.js](https://github.com/caolan/async/raw/master/dist/async.min.js) - 1.7kb Packed and Gzipped
52
5011005a »
2010-07-11 updated README
53
54 ## In the Browser
55
353f4416 »
2010-07-07 added browser support
56 So far its been tested in IE6, IE7, IE8, FF3.6 and Chrome 5. Usage:
57
58 <script type="text/javascript" src="async.js"></script>
59 <script type="text/javascript">
60
61 async.map(data, asyncProcess, function(err, results){
62 alert(results);
63 });
64
65 </script>
6171df79 »
2010-06-01 updated README.md
66
5011005a »
2010-07-11 updated README
67
68 ## Documentation
1a09567b »
2010-06-01 minor tweaks to README.md
69
70 ### Collections
6171df79 »
2010-06-01 updated README.md
71
35266eee »
2010-10-15 remove short descriptions from function list in README
72 * [forEach](#forEach)
73 * [map](#map)
74 * [filter](#filter)
75 * [reject](#reject)
76 * [reduce](#reduce)
77 * [detect](#detect)
78 * [sortBy](#sortBy)
79 * [some](#some)
80 * [every](#every)
81 * [concat](#concat)
1a09567b »
2010-06-01 minor tweaks to README.md
82
2810b751 »
2011-05-17 replace 'flow control' with 'control flow' in README to shut marak up
83 ### Control Flow
1a09567b »
2010-06-01 minor tweaks to README.md
84
35266eee »
2010-10-15 remove short descriptions from function list in README
85 * [series](#series)
86 * [parallel](#parallel)
3dd1ad90 »
2010-10-17 move whilst and until into flow control section of README
87 * [whilst](#whilst)
88 * [until](#until)
35266eee »
2010-10-15 remove short descriptions from function list in README
89 * [waterfall](#waterfall)
0d031be8 »
2010-11-16 added async.queue
90 * [queue](#queue)
35266eee »
2010-10-15 remove short descriptions from function list in README
91 * [auto](#auto)
92 * [iterator](#iterator)
93 * [apply](#apply)
94 * [nextTick](#nextTick)
19d57ef5 »
2010-08-02 exposed browser-compatible nextTick function
95
b438b905 »
2010-08-02 added log and dir functions
96 ### Utils
97
8175ac57 »
2010-11-24 added memoize to README
98 * [memoize](#memoize)
f38b89a5 »
2011-10-06 Add unmemoize documentation to README
99 * [unmemoize](#unmemoize)
35266eee »
2010-10-15 remove short descriptions from function list in README
100 * [log](#log)
101 * [dir](#dir)
102 * [noConflict](#noConflict)
84d9d8fe »
2010-08-02 added noConflict to README
103
b9a14fd1 »
2010-05-27 added README.md
104
9e17a8f9 »
2010-10-15 update README to include anchors for each function
105 ## Collections
106
107 <a name="forEach" />
502d47aa »
2010-05-27 added docs to README.md for forEach and forEachSeries
108 ### forEach(arr, iterator, callback)
109
6171df79 »
2010-06-01 updated README.md
110 Applies an iterator function to each item in an array, in parallel.
502d47aa »
2010-05-27 added docs to README.md for forEach and forEachSeries
111 The iterator is called with an item from the list and a callback for when it
112 has finished. If the iterator passes an error to this callback, the main
113 callback for the forEach function is immediately called with the error.
114
115 Note, that since this function applies the iterator to each item in parallel
116 there is no guarantee that the iterator functions will complete in order.
117
118 __Arguments__
119
120 * arr - An array to iterate over.
121 * iterator(item, callback) - A function to apply to each item in the array.
6171df79 »
2010-06-01 updated README.md
122 The iterator is passed a callback which must be called once it has completed.
502d47aa »
2010-05-27 added docs to README.md for forEach and forEachSeries
123 * callback(err) - A callback which is called after all the iterator functions
124 have finished, or an error has occurred.
125
6171df79 »
2010-06-01 updated README.md
126 __Example__
127
128 // assuming openFiles is an array of file names and saveFile is a function
129 // to save the modified contents of that file:
130
131 async.forEach(openFiles, saveFile, function(err){
132 // if any of the saves produced an error, err would equal that error
133 });
134
ed82759b »
2010-10-15 add horizontal rules between function descriptions in README
135 ---------------------------------------
136
9e17a8f9 »
2010-10-15 update README to include anchors for each function
137 <a name="forEachSeries" />
502d47aa »
2010-05-27 added docs to README.md for forEach and forEachSeries
138 ### forEachSeries(arr, iterator, callback)
139
6171df79 »
2010-06-01 updated README.md
140 The same as forEach only the iterator is applied to each item in the array in
141 series. The next iterator is only called once the current one has completed
142 processing. This means the iterator functions will complete in order.
143
144
ed82759b »
2010-10-15 add horizontal rules between function descriptions in README
145 ---------------------------------------
146
dbc70276 »
2011-10-24 Docs for `forEachLimit`
147 <a name="forEachLimit" />
148 ### forEachLimit(arr, limit, iterator, callback)
149
150 The same as forEach only the iterator is applied to batches of items in the
151 array, in series. The next batch of iterators is only called once the current
152 one has completed processing.
153
154 __Arguments__
155
156 * arr - An array to iterate over.
157 * limit - How many items should be in each batch.
158 * iterator(item, callback) - A function to apply to each item in the array.
159 The iterator is passed a callback which must be called once it has completed.
160 * callback(err) - A callback which is called after all the iterator functions
161 have finished, or an error has occurred.
162
163 __Example__
164
165 // Assume documents is an array of JSON objects and requestApi is a
166 // function that interacts with a rate-limited REST api.
167
168 async.forEachLimit(documents, 20, requestApi, function(err){
169 // if any of the saves produced an error, err would equal that error
170 });
171 ---------------------------------------
172
9e17a8f9 »
2010-10-15 update README to include anchors for each function
173 <a name="map" />
6171df79 »
2010-06-01 updated README.md
174 ### map(arr, iterator, callback)
175
176 Produces a new array of values by mapping each value in the given array through
177 the iterator function. The iterator is called with an item from the array and a
178 callback for when it has finished processing. The callback takes 2 arguments,
179 an error and the transformed item from the array. If the iterator passes an
180 error to this callback, the main callback for the map function is immediately
181 called with the error.
182
183 Note, that since this function applies the iterator to each item in parallel
a57d3194 »
2010-06-09 ensure map and filter results stay in the same order when processing …
184 there is no guarantee that the iterator functions will complete in order, however
185 the results array will be in the same order as the original array.
6171df79 »
2010-06-01 updated README.md
186
187 __Arguments__
188
189 * arr - An array to iterate over.
190 * iterator(item, callback) - A function to apply to each item in the array.
191 The iterator is passed a callback which must be called once it has completed
192 with an error (which can be null) and a transformed item.
193 * callback(err, results) - A callback which is called after all the iterator
194 functions have finished, or an error has occurred. Results is an array of the
195 transformed items from the original array.
196
197 __Example__
198
199 async.map(['file1','file2','file3'], fs.stat, function(err, results){
200 // results is now an array of stats for each file
201 });
202
ed82759b »
2010-10-15 add horizontal rules between function descriptions in README
203 ---------------------------------------
204
9e17a8f9 »
2010-10-15 update README to include anchors for each function
205 <a name="mapSeries" />
6171df79 »
2010-06-01 updated README.md
206 ### mapSeries(arr, iterator, callback)
207
208 The same as map only the iterator is applied to each item in the array in
209 series. The next iterator is only called once the current one has completed
a57d3194 »
2010-06-09 ensure map and filter results stay in the same order when processing …
210 processing. The results array will be in the same order as the original.
6171df79 »
2010-06-01 updated README.md
211
212
ed82759b »
2010-10-15 add horizontal rules between function descriptions in README
213 ---------------------------------------
214
9e17a8f9 »
2010-10-15 update README to include anchors for each function
215 <a name="filter" />
6171df79 »
2010-06-01 updated README.md
216 ### filter(arr, iterator, callback)
217
3a69f647 »
2010-06-16 Updated README to include detect, reject, reduceRight and sortBy func…
218 __Alias:__ select
219
6171df79 »
2010-06-01 updated README.md
220 Returns a new array of all the values which pass an async truth test.
221 _The callback for each iterator call only accepts a single argument of true or
5011005a »
2010-07-11 updated README
222 false, it does not accept an error argument first!_ This is in-line with the
6171df79 »
2010-06-01 updated README.md
223 way node libraries work with truth tests like path.exists. This operation is
a57d3194 »
2010-06-09 ensure map and filter results stay in the same order when processing …
224 performed in parallel, but the results array will be in the same order as the
6171df79 »
2010-06-01 updated README.md
225 original.
226
227 __Arguments__
228
229 * arr - An array to iterate over.
230 * iterator(item, callback) - A truth test to apply to each item in the array.
231 The iterator is passed a callback which must be called once it has completed.
232 * callback(results) - A callback which is called after all the iterator
233 functions have finished.
234
235 __Example__
236
237 async.filter(['file1','file2','file3'], path.exists, function(results){
238 // results now equals an array of the existing files
239 });
240
ed82759b »
2010-10-15 add horizontal rules between function descriptions in README
241 ---------------------------------------
242
9e17a8f9 »
2010-10-15 update README to include anchors for each function
243 <a name="filterSeries" />
6171df79 »
2010-06-01 updated README.md
244 ### filterSeries(arr, iterator, callback)
245
3a69f647 »
2010-06-16 Updated README to include detect, reject, reduceRight and sortBy func…
246 __alias:__ selectSeries
247
6171df79 »
2010-06-01 updated README.md
248 The same as filter only the iterator is applied to each item in the array in
249 series. The next iterator is only called once the current one has completed
a57d3194 »
2010-06-09 ensure map and filter results stay in the same order when processing …
250 processing. The results array will be in the same order as the original.
6171df79 »
2010-06-01 updated README.md
251
ed82759b »
2010-10-15 add horizontal rules between function descriptions in README
252 ---------------------------------------
253
9e17a8f9 »
2010-10-15 update README to include anchors for each function
254 <a name="reject" />
3a69f647 »
2010-06-16 Updated README to include detect, reject, reduceRight and sortBy func…
255 ### reject(arr, iterator, callback)
256
257 The opposite of filter. Removes values that pass an async truth test.
258
ed82759b »
2010-10-15 add horizontal rules between function descriptions in README
259 ---------------------------------------
260
9e17a8f9 »
2010-10-15 update README to include anchors for each function
261 <a name="rejectSeries" />
3a69f647 »
2010-06-16 Updated README to include detect, reject, reduceRight and sortBy func…
262 ### rejectSeries(arr, iterator, callback)
263
264 The same as filter, only the iterator is applied to each item in the array
265 in series.
266
6171df79 »
2010-06-01 updated README.md
267
ed82759b »
2010-10-15 add horizontal rules between function descriptions in README
268 ---------------------------------------
269
9e17a8f9 »
2010-10-15 update README to include anchors for each function
270 <a name="reduce" />
6171df79 »
2010-06-01 updated README.md
271 ### reduce(arr, memo, iterator, callback)
272
3a69f647 »
2010-06-16 Updated README to include detect, reject, reduceRight and sortBy func…
273 __aliases:__ inject, foldl
274
6171df79 »
2010-06-01 updated README.md
275 Reduces a list of values into a single value using an async iterator to return
276 each successive step. Memo is the initial state of the reduction. This
277 function only operates in series. For performance reasons, it may make sense to
278 split a call to this function into a parallel map, then use the normal
279 Array.prototype.reduce on the results. This function is for situations where
280 each step in the reduction needs to be async, if you can get the data before
281 reducing it then its probably a good idea to do so.
282
283 __Arguments__
284
263f71f5 »
2010-09-16 added the concat function
285 * arr - An array to iterate over.
6171df79 »
2010-06-01 updated README.md
286 * memo - The initial state of the reduction.
287 * iterator(memo, item, callback) - A function applied to each item in the
288 array to produce the next step in the reduction. The iterator is passed a
289 callback which accepts an optional error as its first argument, and the state
290 of the reduction as the second. If an error is passed to the callback, the
291 reduction is stopped and the main callback is immediately called with the
292 error.
293 * callback(err, result) - A callback which is called after all the iterator
294 functions have finished. Result is the reduced value.
295
296 __Example__
297
298 async.reduce([1,2,3], 0, function(memo, item, callback){
299 // pointless async:
300 process.nextTick(function(){
301 callback(null, memo + item)
302 });
303 }, function(err, result){
304 // result is now equal to the last value of memo, which is 6
305 });
306
ed82759b »
2010-10-15 add horizontal rules between function descriptions in README
307 ---------------------------------------
308
9e17a8f9 »
2010-10-15 update README to include anchors for each function
309 <a name="reduceRight" />
3a69f647 »
2010-06-16 Updated README to include detect, reject, reduceRight and sortBy func…
310 ### reduceRight(arr, memo, iterator, callback)
311
312 __Alias:__ foldr
313
314 Same as reduce, only operates on the items in the array in reverse order.
315
316
ed82759b »
2010-10-15 add horizontal rules between function descriptions in README
317 ---------------------------------------
318
9e17a8f9 »
2010-10-15 update README to include anchors for each function
319 <a name="detect" />
3a69f647 »
2010-06-16 Updated README to include detect, reject, reduceRight and sortBy func…
320 ### detect(arr, iterator, callback)
321
322 Returns the first value in a list that passes an async truth test. The
323 iterator is applied in parallel, meaning the first iterator to return true will
324 fire the detect callback with that result. That means the result might not be
325 the first item in the original array (in terms of order) that passes the test.
326
327 If order within the original array is important then look at detectSeries.
328
329 __Arguments__
330
263f71f5 »
2010-09-16 added the concat function
331 * arr - An array to iterate over.
3a69f647 »
2010-06-16 Updated README to include detect, reject, reduceRight and sortBy func…
332 * iterator(item, callback) - A truth test to apply to each item in the array.
333 The iterator is passed a callback which must be called once it has completed.
334 * callback(result) - A callback which is called as soon as any iterator returns
335 true, or after all the iterator functions have finished. Result will be
336 the first item in the array that passes the truth test (iterator) or the
337 value undefined if none passed.
338
339 __Example__
340
341 async.detect(['file1','file2','file3'], path.exists, function(result){
342 // result now equals the first file in the list that exists
343 });
344
ed82759b »
2010-10-15 add horizontal rules between function descriptions in README
345 ---------------------------------------
346
9e17a8f9 »
2010-10-15 update README to include anchors for each function
347 <a name="detectSeries" />
3a69f647 »
2010-06-16 Updated README to include detect, reject, reduceRight and sortBy func…
348 ### detectSeries(arr, iterator, callback)
349
350 The same as detect, only the iterator is applied to each item in the array
351 in series. This means the result is always the first in the original array (in
352 terms of array order) that passes the truth test.
353
354
ed82759b »
2010-10-15 add horizontal rules between function descriptions in README
355 ---------------------------------------
356
9e17a8f9 »
2010-10-15 update README to include anchors for each function
357 <a name="sortBy" />
3a69f647 »
2010-06-16 Updated README to include detect, reject, reduceRight and sortBy func…
358 ### sortBy(arr, iterator, callback)
359
360 Sorts a list by the results of running each value through an async iterator.
361
362 __Arguments__
363
364 * arr - An array to iterate over.
365 * iterator(item, callback) - A function to apply to each item in the array.
366 The iterator is passed a callback which must be called once it has completed
367 with an error (which can be null) and a value to use as the sort criteria.
368 * callback(err, results) - A callback which is called after all the iterator
369 functions have finished, or an error has occurred. Results is the items from
370 the original array sorted by the values returned by the iterator calls.
371
372 __Example__
373
374 async.sortBy(['file1','file2','file3'], function(file, callback){
375 fs.stat(file, function(err, stats){
376 callback(err, stats.mtime);
377 });
378 }, function(err, results){
379 // results is now the original array of files sorted by
380 // modified date
381 });
382
383
ed82759b »
2010-10-15 add horizontal rules between function descriptions in README
384 ---------------------------------------
385
9e17a8f9 »
2010-10-15 update README to include anchors for each function
386 <a name="some" />
3a69f647 »
2010-06-16 Updated README to include detect, reject, reduceRight and sortBy func…
387 ### some(arr, iterator, callback)
388
389 __Alias:__ any
6171df79 »
2010-06-01 updated README.md
390
391 Returns true if at least one element in the array satisfies an async test.
392 _The callback for each iterator call only accepts a single argument of true or
5011005a »
2010-07-11 updated README
393 false, it does not accept an error argument first!_ This is in-line with the
6171df79 »
2010-06-01 updated README.md
394 way node libraries work with truth tests like path.exists. Once any iterator
395 call returns true, the main callback is immediately called.
396
397 __Arguments__
398
263f71f5 »
2010-09-16 added the concat function
399 * arr - An array to iterate over.
6171df79 »
2010-06-01 updated README.md
400 * iterator(item, callback) - A truth test to apply to each item in the array.
401 The iterator is passed a callback which must be called once it has completed.
402 * callback(result) - A callback which is called as soon as any iterator returns
403 true, or after all the iterator functions have finished. Result will be
404 either true or false depending on the values of the async tests.
405
406 __Example__
407
408 async.some(['file1','file2','file3'], path.exists, function(result){
409 // if result is true then at least one of the files exists
410 });
411
ed82759b »
2010-10-15 add horizontal rules between function descriptions in README
412 ---------------------------------------
413
9e17a8f9 »
2010-10-15 update README to include anchors for each function
414 <a name="every" />
3a69f647 »
2010-06-16 Updated README to include detect, reject, reduceRight and sortBy func…
415 ### every(arr, iterator, callback)
416
417 __Alias:__ all
6171df79 »
2010-06-01 updated README.md
418
3a69f647 »
2010-06-16 Updated README to include detect, reject, reduceRight and sortBy func…
419 Returns true if every element in the array satisfies an async test.
6171df79 »
2010-06-01 updated README.md
420 _The callback for each iterator call only accepts a single argument of true or
5011005a »
2010-07-11 updated README
421 false, it does not accept an error argument first!_ This is in-line with the
6171df79 »
2010-06-01 updated README.md
422 way node libraries work with truth tests like path.exists.
423
424 __Arguments__
425
263f71f5 »
2010-09-16 added the concat function
426 * arr - An array to iterate over.
6171df79 »
2010-06-01 updated README.md
427 * iterator(item, callback) - A truth test to apply to each item in the array.
428 The iterator is passed a callback which must be called once it has completed.
429 * callback(result) - A callback which is called after all the iterator
430 functions have finished. Result will be either true or false depending on
431 the values of the async tests.
432
433 __Example__
434
435 async.every(['file1','file2','file3'], path.exists, function(result){
436 // if result is true then every file exists
437 });
b9a14fd1 »
2010-05-27 added README.md
438
ed82759b »
2010-10-15 add horizontal rules between function descriptions in README
439 ---------------------------------------
440
9e17a8f9 »
2010-10-15 update README to include anchors for each function
441 <a name="concat" />
263f71f5 »
2010-09-16 added the concat function
442 ### concat(arr, iterator, callback)
443
444 Applies an iterator to each item in a list, concatenating the results. Returns the
28fed845 »
2010-09-17 added concatSeries
445 concatenated list. The iterators are called in parallel, and the results are
446 concatenated as they return. There is no guarantee that the results array will
447 be returned in the original order of the arguments passed to the iterator function.
263f71f5 »
2010-09-16 added the concat function
448
449 __Arguments__
450
451 * arr - An array to iterate over
452 * iterator(item, callback) - A function to apply to each item in the array.
453 The iterator is passed a callback which must be called once it has completed
454 with an error (which can be null) and an array of results.
455 * callback(err, results) - A callback which is called after all the iterator
456 functions have finished, or an error has occurred. Results is an array containing
457 the concatenated results of the iterator function.
458
459 __Example__
460
461 async.concat(['dir1','dir2','dir3'], fs.readdir, function(err, files){
462 // files is now a list of filenames that exist in the 3 directories
463 });
464
ed82759b »
2010-10-15 add horizontal rules between function descriptions in README
465 ---------------------------------------
466
9e17a8f9 »
2010-10-15 update README to include anchors for each function
467 <a name="concatSeries" />
28fed845 »
2010-09-17 added concatSeries
468 ### concatSeries(arr, iterator, callback)
469
470 Same as async.concat, but executes in series instead of parallel.
471
b9a14fd1 »
2010-05-27 added README.md
472
2810b751 »
2011-05-17 replace 'flow control' with 'control flow' in README to shut marak up
473 ## Control Flow
9e17a8f9 »
2010-10-15 update README to include anchors for each function
474
475 <a name="series" />
b9a14fd1 »
2010-05-27 added README.md
476 ### series(tasks, [callback])
477
478 Run an array of functions in series, each one running once the previous
479 function has completed. If any functions in the series pass an error to its
480 callback, no more functions are run and the callback for the series is
641cb768 »
2010-10-17 allow parallel and series functions to accept and object instead of a…
481 immediately called with the value of the error. Once the tasks have completed,
482 the results are passed to the final callback as an array.
483
484 It is also possible to use an object instead of an array. Each property will be
485 run as a function and the results will be passed to the final callback as an object
486 instead of an array. This can be a more readable way of handling results from
487 async.series.
488
b9a14fd1 »
2010-05-27 added README.md
489
490 __Arguments__
491
641cb768 »
2010-10-17 allow parallel and series functions to accept and object instead of a…
492 * tasks - An array or object containing functions to run, each function is passed
493 a callback it must call on completion.
b9a14fd1 »
2010-05-27 added README.md
494 * callback(err, results) - An optional callback to run once all the functions
495 have completed. This function gets an array of all the arguments passed to
496 the callbacks used in the array.
497
498 __Example__
499
500 async.series([
501 function(callback){
502 // do some stuff ...
503 callback(null, 'one');
504 },
505 function(callback){
506 // do some more stuff ...
507 callback(null, 'two');
508 },
509 ],
510 // optional callback
511 function(err, results){
512 // results is now equal to ['one', 'two']
513 });
514
515
641cb768 »
2010-10-17 allow parallel and series functions to accept and object instead of a…
516 // an example using an object instead of an array
517 async.series({
518 one: function(callback){
519 setTimeout(function(){
520 callback(null, 1);
521 }, 200);
522 },
523 two: function(callback){
524 setTimeout(function(){
525 callback(null, 2);
526 }, 100);
527 },
528 },
529 function(err, results) {
2cd61deb »
2011-05-17 grammar nazi
530 // results is now equal to: {one: 1, two: 2}
641cb768 »
2010-10-17 allow parallel and series functions to accept and object instead of a…
531 });
532
533
ed82759b »
2010-10-15 add horizontal rules between function descriptions in README
534 ---------------------------------------
535
9e17a8f9 »
2010-10-15 update README to include anchors for each function
536 <a name="parallel" />
b9a14fd1 »
2010-05-27 added README.md
537 ### parallel(tasks, [callback])
538
539 Run an array of functions in parallel, without waiting until the previous
540 function has completed. If any of the functions pass an error to its
541 callback, the main callback is immediately called with the value of the error.
641cb768 »
2010-10-17 allow parallel and series functions to accept and object instead of a…
542 Once the tasks have completed, the results are passed to the final callback as an
543 array.
544
545 It is also possible to use an object instead of an array. Each property will be
546 run as a function and the results will be passed to the final callback as an object
547 instead of an array. This can be a more readable way of handling results from
548 async.parallel.
549
b9a14fd1 »
2010-05-27 added README.md
550
551 __Arguments__
552
641cb768 »
2010-10-17 allow parallel and series functions to accept and object instead of a…
553 * tasks - An array or object containing functions to run, each function is passed a
554 callback it must call on completion.
b9a14fd1 »
2010-05-27 added README.md
555 * callback(err, results) - An optional callback to run once all the functions
556 have completed. This function gets an array of all the arguments passed to
557 the callbacks used in the array.
558
559 __Example__
560
561 async.parallel([
562 function(callback){
563 setTimeout(function(){
564 callback(null, 'one');
565 }, 200);
566 },
567 function(callback){
568 setTimeout(function(){
569 callback(null, 'two');
570 }, 100);
571 },
572 ],
573 // optional callback
574 function(err, results){
575 // in this case, the results array will equal ['two','one']
576 // because the functions were run in parallel and the second
577 // function had a shorter timeout before calling the callback.
578 });
579
580
641cb768 »
2010-10-17 allow parallel and series functions to accept and object instead of a…
581 // an example using an object instead of an array
582 async.parallel({
583 one: function(callback){
584 setTimeout(function(){
585 callback(null, 1);
586 }, 200);
587 },
588 two: function(callback){
589 setTimeout(function(){
590 callback(null, 2);
591 }, 100);
592 },
593 },
594 function(err, results) {
595 // results is now equals to: {one: 1, two: 2}
596 });
597
598
ed82759b »
2010-10-15 add horizontal rules between function descriptions in README
599 ---------------------------------------
600
3dd1ad90 »
2010-10-17 move whilst and until into flow control section of README
601 <a name="whilst" />
602 ### whilst(test, fn, callback)
603
604 Repeatedly call fn, while test returns true. Calls the callback when stopped,
605 or an error occurs.
606
607 __Arguments__
608
609 * test() - synchronous truth test to perform before each execution of fn.
610 * fn(callback) - A function to call each time the test passes. The function is
611 passed a callback which must be called once it has completed with an optional
612 error as the first argument.
613 * callback(err) - A callback which is called after the test fails and repeated
614 execution of fn has stopped.
615
616 __Example__
617
618 var count = 0;
619
620 async.whilst(
621 function () { return count < 5; },
622 function (callback) {
623 count++;
624 setTimeout(callback, 1000);
625 },
626 function (err) {
627 // 5 seconds have passed
628 }
629 });
630
631
632 ---------------------------------------
633
634 <a name="until" />
635 ### until(test, fn, callback)
636
637 Repeatedly call fn, until test returns true. Calls the callback when stopped,
638 or an error occurs.
639
640 The inverse of async.whilst.
641
642
643 ---------------------------------------
644
9e17a8f9 »
2010-10-15 update README to include anchors for each function
645 <a name="waterfall" />
b9a14fd1 »
2010-05-27 added README.md
646 ### waterfall(tasks, [callback])
647
648 Runs an array of functions in series, each passing their results to the next in
649 the array. However, if any of the functions pass an error to the callback, the
650 next function is not executed and the main callback is immediately called with
651 the error.
652
653 __Arguments__
654
655 * tasks - An array of functions to run, each function is passed a callback it
656 must call on completion.
657 * callback(err) - An optional callback to run once all the functions have
658 completed. This function gets passed any error that may have occurred.
659
660 __Example__
661
662 async.waterfall([
663 function(callback){
664 callback(null, 'one', 'two');
eac373da »
2010-12-06 add commas to waterfall example in REAMDE - thanks dbro
665 },
b9a14fd1 »
2010-05-27 added README.md
666 function(arg1, arg2, callback){
667 callback(null, 'three');
eac373da »
2010-12-06 add commas to waterfall example in REAMDE - thanks dbro
668 },
b9a14fd1 »
2010-05-27 added README.md
669 function(arg1, callback){
670 // arg1 now equals 'three'
671 callback(null, 'done');
672 }
673 ]);
674
675
ed82759b »
2010-10-15 add horizontal rules between function descriptions in README
676 ---------------------------------------
677
0d031be8 »
2010-11-16 added async.queue
678 <a name="queue" />
679 ### queue(worker, concurrency)
680
681 Creates a queue object with the specified concurrency. Tasks added to the
682 queue will be processed in parallel (up to the concurrency limit). If all
683 workers are in progress, the task is queued until one is available. Once
684 a worker has completed a task, the task's callback is called.
685
686 __Arguments__
687
688 * worker(task, callback) - An asynchronous function for processing a queued
689 task.
9bdbf715 »
2010-11-16 update async.queue information in README
690 * concurrency - An integer for determining how many worker functions should be
691 run in parallel.
0d031be8 »
2010-11-16 added async.queue
692
693 __Queue objects__
694
695 The queue object returned by this function has the following properties and
696 methods:
697
698 * length() - a function returning the number of items waiting to be processed.
699 * concurrency - an integer for determining how many worker functions should be
700 run in parallel. This property can be changed after a queue is created to
701 alter the concurrency on-the-fly.
d0337393 »
2010-11-17 show queue.push callback as optional in README
702 * push(task, [callback]) - add a new task to the queue, the callback is called
0d031be8 »
2010-11-16 added async.queue
703 once the worker has finished processing the task.
570cf8e1 »
2011-04-17 callback methods w/ test & docs
704 * saturated - a callback that is called when the queue length hits the concurrency and further tasks will be queued
705 * empty - a callback that is called when the last item from the queue is given to a worker
706 * drain - a callback that is called when the last item from the queue has returned from the worker
0d031be8 »
2010-11-16 added async.queue
707
708 __Example__
709
710 // create a queue object with concurrency 2
711
712 var q = async.queue(function (task, callback) {
5804a81f »
2011-08-26 Fixed a typo in the queue sample
713 console.log('hello ' + task.name);
0d031be8 »
2010-11-16 added async.queue
714 callback();
715 }, 2);
716
717
570cf8e1 »
2011-04-17 callback methods w/ test & docs
718 // assign a callback
719 q.drain = function() {
720 console.log('all items have been processed');
721 }
722
0d031be8 »
2010-11-16 added async.queue
723 // add some items to the queue
724
725 q.push({name: 'foo'}, function (err) {
726 console.log('finished processing foo');
727 });
728 q.push({name: 'bar'}, function (err) {
729 console.log('finished processing bar');
730 });
731
732
733 ---------------------------------------
734
9e17a8f9 »
2010-10-15 update README to include anchors for each function
735 <a name="auto" />
b9a14fd1 »
2010-05-27 added README.md
736 ### auto(tasks, [callback])
737
738 Determines the best order for running functions based on their requirements.
739 Each function can optionally depend on other functions being completed first,
740 and each function is run as soon as its requirements are satisfied. If any of
c66881d4 »
2011-05-25 In Auto function, save results from functions and pass them forward t…
741 the functions pass an error to their callback, that function will not complete
b9a14fd1 »
2010-05-27 added README.md
742 (so any other functions depending on it will not run) and the main callback
c66881d4 »
2011-05-25 In Auto function, save results from functions and pass them forward t…
743 will be called immediately with the error. Functions also receive an object
744 containing the results of functions on which they depend.
b9a14fd1 »
2010-05-27 added README.md
745
746 __Arguments__
747
748 * tasks - An object literal containing named functions or an array of
749 requirements, with the function itself the last item in the array. The key
750 used for each function or array is used when specifying requirements. The
5011005a »
2010-07-11 updated README
751 syntax is easier to understand by looking at the example.
b9a14fd1 »
2010-05-27 added README.md
752 * callback(err) - An optional callback which is called when all the tasks have
5011005a »
2010-07-11 updated README
753 been completed. The callback may receive an error as an argument.
b9a14fd1 »
2010-05-27 added README.md
754
755 __Example__
756
757 async.auto({
758 get_data: function(callback){
759 // async code to get some data
760 },
761 make_folder: function(callback){
762 // async code to create a directory to store a file in
763 // this is run at the same time as getting the data
764 },
765 write_file: ['get_data', 'make_folder', function(callback){
766 // once there is some data and the directory exists,
767 // write the data to a file in the directory
c66881d4 »
2011-05-25 In Auto function, save results from functions and pass them forward t…
768 callback(null, filename);
a57d3194 »
2010-06-09 ensure map and filter results stay in the same order when processing …
769 }],
c66881d4 »
2011-05-25 In Auto function, save results from functions and pass them forward t…
770 email_link: ['write_file', function(callback, results){
b9a14fd1 »
2010-05-27 added README.md
771 // once the file is written let's email a link to it...
c66881d4 »
2011-05-25 In Auto function, save results from functions and pass them forward t…
772 // results.write_file contains the filename returned by write_file.
a57d3194 »
2010-06-09 ensure map and filter results stay in the same order when processing …
773 }]
b9a14fd1 »
2010-05-27 added README.md
774 });
775
776 This is a fairly trivial example, but to do this using the basic parallel and
777 series functions would look like this:
778
779 async.parallel([
780 function(callback){
781 // async code to get some data
782 },
783 function(callback){
784 // async code to create a directory to store a file in
785 // this is run at the same time as getting the data
786 }
787 ],
788 function(results){
789 async.series([
790 function(callback){
791 // once there is some data and the directory exists,
792 // write the data to a file in the directory
793 },
794 email_link: ['write_file', function(callback){
795 // once the file is written let's email a link to it...
796 }
797 ]);
798 });
799
800 For a complicated series of async tasks using the auto function makes adding
801 new tasks much easier and makes the code more readable.
802
803
ed82759b »
2010-10-15 add horizontal rules between function descriptions in README
804 ---------------------------------------
805
9e17a8f9 »
2010-10-15 update README to include anchors for each function
806 <a name="iterator" />
b9a14fd1 »
2010-05-27 added README.md
807 ### iterator(tasks)
808
809 Creates an iterator function which calls the next function in the array,
810 returning a continuation to call the next one after that. Its also possible to
811 'peek' the next iterator by doing iterator.next().
812
813 This function is used internally by the async module but can be useful when
814 you want to manually control the flow of functions in series.
815
816 __Arguments__
817
818 * tasks - An array of functions to run, each function is passed a callback it
819 must call on completion.
820
821 __Example__
822
823 var iterator = async.iterator([
824 function(){ sys.p('one'); },
825 function(){ sys.p('two'); },
826 function(){ sys.p('three'); }
827 ]);
828
829 node> var iterator2 = iterator();
830 'one'
831 node> var iterator3 = iterator2();
832 'two'
833 node> iterator3();
834 'three'
835 node> var nextfn = iterator2.next();
836 node> nextfn();
837 'three'
838
839
ed82759b »
2010-10-15 add horizontal rules between function descriptions in README
840 ---------------------------------------
841
9e17a8f9 »
2010-10-15 update README to include anchors for each function
842 <a name="apply" />
4d09ada9 »
2010-07-06 added apply function
843 ### apply(function, arguments..)
844
845 Creates a continuation function with some arguments already applied, a useful
2810b751 »
2011-05-17 replace 'flow control' with 'control flow' in README to shut marak up
846 shorthand when combined with other control flow functions. Any arguments
4d09ada9 »
2010-07-06 added apply function
847 passed to the returned function are added to the arguments originally passed
848 to apply.
849
850 __Arguments__
851
852 * function - The function you want to eventually apply all arguments to.
853 * arguments... - Any number of arguments to automatically apply when the
854 continuation is called.
855
856 __Example__
857
858 // using apply
859
860 async.parallel([
861 async.apply(fs.writeFile, 'testfile1', 'test1'),
862 async.apply(fs.writeFile, 'testfile2', 'test2'),
863 ]);
864
865
866 // the same process without using apply
867
868 async.parallel([
869 function(callback){
870 fs.writeFile('testfile1', 'test1', callback);
871 },
872 function(callback){
873 fs.writeFile('testfile2', 'test2', callback);
874 },
875 ]);
876
877 It's possible to pass any number of additional arguments when calling the
878 continuation:
879
880 node> var fn = async.apply(sys.puts, 'one');
881 node> fn('two', 'three');
882 one
883 two
884 three
b438b905 »
2010-08-02 added log and dir functions
885
ed82759b »
2010-10-15 add horizontal rules between function descriptions in README
886 ---------------------------------------
887
9e17a8f9 »
2010-10-15 update README to include anchors for each function
888 <a name="nextTick" />
19d57ef5 »
2010-08-02 exposed browser-compatible nextTick function
889 ### nextTick(callback)
890
891 Calls the callback on a later loop around the event loop. In node.js this just
892 calls process.nextTick, in the browser it falls back to setTimeout(callback, 0),
893 which means other higher priority events may precede the execution of the callback.
894
895 This is used internally for browser-compatibility purposes.
896
897 __Arguments__
898
899 * callback - The function to call on a later loop around the event loop.
900
901 __Example__
902
903 var call_order = [];
904 async.nextTick(function(){
905 call_order.push('two');
906 // call_order now equals ['one','two]
907 });
908 call_order.push('one')
909
b438b905 »
2010-08-02 added log and dir functions
910
911 ## Utils
912
8175ac57 »
2010-11-24 added memoize to README
913 <a name="memoize" />
914 ### memoize(fn, [hasher])
915
916 Caches the results of an async function. When creating a hash to store function
917 results against, the callback is omitted from the hash and an optional hash
918 function can be used.
919
920 __Arguments__
921
922 * fn - the function you to proxy and cache results from.
923 * hasher - an optional function for generating a custom hash for storing
924 results, it has all the arguments applied to it apart from the callback, and
925 must be synchronous.
926
927 __Example__
928
929 var slow_fn = function (name, callback) {
930 // do something
931 callback(null, result);
932 };
933 var fn = async.memoize(slow_fn);
934
935 // fn can now be used as if it were slow_fn
936 fn('some name', function () {
937 // callback
938 });
939
f38b89a5 »
2011-10-06 Add unmemoize documentation to README
940 <a name="unmemoize" />
941 ### unmemoize(fn)
942
943 Undoes a memoized function, reverting it to the original, unmemoized
944 form. Comes handy in tests.
945
946 __Arguments__
947
948 * fn - the memoized function
8175ac57 »
2010-11-24 added memoize to README
949
9e17a8f9 »
2010-10-15 update README to include anchors for each function
950 <a name="log" />
b438b905 »
2010-08-02 added log and dir functions
951 ### log(function, arguments)
952
953 Logs the result of an async function to the console. Only works in node.js or
954 in browsers that support console.log and console.error (such as FF and Chrome).
955 If multiple arguments are returned from the async function, console.log is
956 called on each argument in order.
957
958 __Arguments__
959
960 * function - The function you want to eventually apply all arguments to.
961 * arguments... - Any number of arguments to apply to the function.
962
963 __Example__
964
965 var hello = function(name, callback){
966 setTimeout(function(){
967 callback(null, 'hello ' + name);
968 }, 1000);
969 };
970
971 node> async.log(hello, 'world');
972 'hello world'
973
974
ed82759b »
2010-10-15 add horizontal rules between function descriptions in README
975 ---------------------------------------
976
9e17a8f9 »
2010-10-15 update README to include anchors for each function
977 <a name="dir" />
b438b905 »
2010-08-02 added log and dir functions
978 ### dir(function, arguments)
979
980 Logs the result of an async function to the console using console.dir to
981 display the properties of the resulting object. Only works in node.js or
982 in browsers that support console.dir and console.error (such as FF and Chrome).
983 If multiple arguments are returned from the async function, console.dir is
984 called on each argument in order.
985
986 __Arguments__
987
988 * function - The function you want to eventually apply all arguments to.
989 * arguments... - Any number of arguments to apply to the function.
990
991 __Example__
992
993 var hello = function(name, callback){
994 setTimeout(function(){
995 callback(null, {hello: name});
996 }, 1000);
997 };
998
999 node> async.dir(hello, 'world');
1000 {hello: 'world'}
84d9d8fe »
2010-08-02 added noConflict to README
1001
1002
ed82759b »
2010-10-15 add horizontal rules between function descriptions in README
1003 ---------------------------------------
1004
9e17a8f9 »
2010-10-15 update README to include anchors for each function
1005 <a name="noConflict" />
84d9d8fe »
2010-08-02 added noConflict to README
1006 ### noConflict()
1007
1008 Changes the value of async back to its original value, returning a reference to the
1009 async object.
Something went wrong with that request. Please try again.