node-v0.8.23-darwin-x86.tar.gz

# Async.js Async is a utility module which provides straight-forward, powerful functions for working with asynchronous JavaScript. Although originally designed for use with [node.js](http://nodejs.org), it can also be used directly in the browser. Async provides around 20 functions that include the usual 'functional' suspects (map, reduce, filter, forEach…) as well as some common patterns for asynchronous control flow (parallel, series, waterfall…). All these functions assume you follow the node.js convention of providing a single callback as the last argument of your async function. ## Quick Examples async.map(['file1','file2','file3'], fs.stat, function(err, results){ // results is now an array of stats for each file }); async.filter(['file1','file2','file3'], path.exists, function(results){ // results now equals an array of the existing files }); async.parallel([ function(){ ... }, function(){ ... } ], callback); async.series([ function(){ ... }, function(){ ... } ]); There are many more functions available so take a look at the docs below for a full list. This module aims to be comprehensive, so if you feel anything is missing please create a GitHub issue for it. ## Download Releases are available for download from [GitHub](http://github.com/caolan/async/downloads). Alternatively, you can install using Node Package Manager (npm): npm install async __Development:__ [async.js](https://github.com/caolan/async/raw/master/lib/async.js) - 17.5kb Uncompressed __Production:__ [async.min.js](https://github.com/caolan/async/raw/master/dist/async.min.js) - 1.7kb Packed and Gzipped ## In the Browser So far its been tested in IE6, IE7, IE8, FF3.6 and Chrome 5. Usage: <script type="text/javascript" src="async.js"></script> <script type="text/javascript"> async.map(data, asyncProcess, function(err, results){ alert(results); }); </script> ## Documentation ### Collections * [forEach](#forEach) * [map](#map) * [filter](#filter) * [reject](#reject) * [reduce](#reduce) * [detect](#detect) * [sortBy](#sortBy) * [some](#some) * [every](#every) * [concat](#concat) ### Control Flow * [series](#series) * [parallel](#parallel) * [whilst](#whilst) * [until](#until) * [waterfall](#waterfall) * [queue](#queue) * [auto](#auto) * [iterator](#iterator) * [apply](#apply) * [nextTick](#nextTick) ### Utils * [memoize](#memoize) * [unmemoize](#unmemoize) * [log](#log) * [dir](#dir) * [noConflict](#noConflict) ## Collections <a name="forEach" /> ### forEach(arr, iterator, callback) Applies an iterator function to each item in an array, in parallel. The iterator is called with an item from the list and a callback for when it has finished. If the iterator passes an error to this callback, the main callback for the forEach function is immediately called with the error. Note, that since this function applies the iterator to each item in parallel there is no guarantee that the iterator functions will complete in order. __Arguments__ * arr - An array to iterate over. * iterator(item, callback) - A function to apply to each item in the array. The iterator is passed a callback which must be called once it has completed. * callback(err) - A callback which is called after all the iterator functions have finished, or an error has occurred. __Example__ // assuming openFiles is an array of file names and saveFile is a function // to save the modified contents of that file: async.forEach(openFiles, saveFile, function(err){ // if any of the saves produced an error, err would equal that error }); --------------------------------------- <a name="forEachSeries" /> ### forEachSeries(arr, iterator, callback) The same as forEach only the iterator is applied to each item in the array in series. The next iterator is only called once the current one has completed processing. This means the iterator functions will complete in order. --------------------------------------- <a name="forEachLimit" /> ### forEachLimit(arr, limit, iterator, callback) The same as forEach only the iterator is applied to batches of items in the array, in series. The next batch of iterators is only called once the current one has completed processing. __Arguments__ * arr - An array to iterate over. * limit - How many items should be in each batch. * iterator(item, callback) - A function to apply to each item in the array. The iterator is passed a callback which must be called once it has completed. * callback(err) - A callback which is called after all the iterator functions have finished, or an error has occurred. __Example__ // Assume documents is an array of JSON objects and requestApi is a // function that interacts with a rate-limited REST api. async.forEachLimit(documents, 20, requestApi, function(err){ // if any of the saves produced an error, err would equal that error }); --------------------------------------- <a name="map" /> ### map(arr, iterator, callback) Produces a new array of values by mapping each value in the given array through the iterator function. The iterator is called with an item from the array and a callback for when it has finished processing. The callback takes 2 arguments, an error and the transformed item from the array. If the iterator passes an error to this callback, the main callback for the map function is immediately called with the error. Note, that since this function applies the iterator to each item in parallel there is no guarantee that the iterator functions will complete in order, however the results array will be in the same order as the original array. __Arguments__ * arr - An array to iterate over. * iterator(item, callback) - A function to apply to each item in the array. The iterator is passed a callback which must be called once it has completed with an error (which can be null) and a transformed item. * callback(err, results) - A callback which is called after all the iterator functions have finished, or an error has occurred. Results is an array of the transformed items from the original array. __Example__ async.map(['file1','file2','file3'], fs.stat, function(err, results){ // results is now an array of stats for each file }); --------------------------------------- <a name="mapSeries" /> ### mapSeries(arr, iterator, callback) The same as map only the iterator is applied to each item in the array in series. The next iterator is only called once the current one has completed processing. The results array will be in the same order as the original. --------------------------------------- <a name="filter" /> ### filter(arr, iterator, callback) __Alias:__ select Returns a new array of all the values which pass an async truth test. _The callback for each iterator call only accepts a single argument of true or false, it does not accept an error argument first!_ This is in-line with the way node libraries work with truth tests like path.exists. This operation is performed in parallel, but the results array will be in the same order as the original. __Arguments__ * arr - An array to iterate over. * iterator(item, callback) - A truth test to apply to each item in the array. The iterator is passed a callback which must be called once it has completed. * callback(results) - A callback which is called after all the iterator functions have finished. __Example__ async.filter(['file1','file2','file3'], path.exists, function(results){ // results now equals an array of the existing files }); --------------------------------------- <a name="filterSeries" /> ### filterSeries(arr, iterator, callback) __alias:__ selectSeries The same as filter only the iterator is applied to each item in the array in series. The next iterator is only called once the current one has completed processing. The results arra