diff options
Diffstat (limited to 'dist/async.js')
| -rw-r--r-- | dist/async.js | 2314 |
1 files changed, 2257 insertions, 57 deletions
diff --git a/dist/async.js b/dist/async.js index 2062bea..02b0295 100644 --- a/dist/async.js +++ b/dist/async.js @@ -362,8 +362,9 @@ function once(fn) { return function () { if (fn === null) return; - fn.apply(this, arguments); + var callFn = fn; fn = null; + callFn.apply(this, arguments); }; } @@ -801,8 +802,9 @@ function onlyOnce(fn) { return function () { if (fn === null) throw new Error("Callback was already called."); - fn.apply(this, arguments); + var callFn = fn; fn = null; + callFn.apply(this, arguments); }; } @@ -867,6 +869,24 @@ }); } + /** + * The same as `map` but runs a maximum of `limit` async operations at a time. + * + * @name mapLimit + * @static + * @memberOf async + * @see async.map + * @category Collection + * @param {Array|Object} coll - A collection to iterate over. + * @param {number} limit - The maximum number of async operations at a time. + * @param {Function} iteratee - A function to apply to each item in `coll`. + * The iteratee is passed a `callback(err, transformed)` which must be called + * once it has completed with an error (which can be `null`) and a transformed + * item. Invoked with (item, callback). + * @param {Function} [callback] - A callback which is called when all `iteratee` + * functions have finished, or an error occurs. Results is an array of the + * transformed items from the `coll`. Invoked with (err, results). + */ var mapLimit = doParallelLimit(_asyncMap); function doLimit(fn, limit) { @@ -875,20 +895,213 @@ }; } + /** + * Produces a new collection of values by mapping each value in `coll` through + * the `iteratee` function. The `iteratee` is called with an item from `coll` + * and a callback for when it has finished processing. Each of these callback + * takes 2 arguments: an `error`, and the transformed item from `coll`. If + * `iteratee` passes an error to its callback, the main `callback` (for the + * `map` function) is immediately called with the error. + * + * Note, that since this function applies the `iteratee` to each item in + * parallel, there is no guarantee that the `iteratee` functions will complete + * in order. However, the results array will be in the same order as the + * original `coll`. + * + * @name map + * @static + * @memberOf async + * @category Collection + * @param {Array|Object} coll - A collection to iterate over. + * @param {Function} iteratee - A function to apply to each item in `coll`. + * The iteratee is passed a `callback(err, transformed)` which must be called + * once it has completed with an error (which can be `null`) and a + * transformed item. Invoked with (item, callback). + * @param {Function} [callback] - A callback which is called when all `iteratee` + * functions have finished, or an error occurs. Results is an array of the + * transformed items from the `coll`. Invoked with (err, results). + * @example + * + * async.map(['file1','file2','file3'], fs.stat, function(err, results) { + * // results is now an array of stats for each file + * }); + */ var map = doLimit(mapLimit, Infinity); + /** + * Applies the provided arguments to each function in the array, calling + * `callback` after all functions have completed. If you only provide the first + * argument, then it will return a function which lets you pass in the + * arguments as if it were a single function call. + * + * @name applyEach + * @static + * @memberOf async + * @category Control Flow + * @param {Array|Object} fns - A collection of asynchronous functions to all + * call with the same arguments + * @param {...*} [args] - any number of separate arguments to pass to the + * function. + * @param {Function} [callback] - the final argument should be the callback, + * called when all functions have completed processing. + * @returns {Function} - If only the first argument is provided, it will return + * a function which lets you pass in the arguments as if it were a single + * function call. + * @example + * + * async.applyEach([enableSearch, updateSchema], 'bucket', callback); + * + * // partial application example: + * async.each( + * buckets, + * async.applyEach([enableSearch, updateSchema]), + * callback + * ); + */ var applyEach = applyEach$1(map); + /** + * The same as `map` but runs only a single async operation at a time. + * + * @name mapSeries + * @static + * @memberOf async + * @see async.map + * @category Collection + * @param {Array|Object} coll - A collection to iterate over. + * @param {Function} iteratee - A function to apply to each item in `coll`. + * The iteratee is passed a `callback(err, transformed)` which must be called + * once it has completed with an error (which can be `null`) and a + * transformed item. Invoked with (item, callback). + * @param {Function} [callback] - A callback which is called when all `iteratee` + * functions have finished, or an error occurs. Results is an array of the + * transformed items from the `coll`. Invoked with (err, results). + */ var mapSeries = doLimit(mapLimit, 1); + /** + * The same as `applyEach` but runs only a single async operation at a time. + * + * @name applyEachSeries + * @static + * @memberOf async + * @see async.applyEach + * @category Control Flow + * @param {Array|Object} fns - A collection of asynchronous functions to all + * call with the same arguments + * @param {...*} [args] - any number of separate arguments to pass to the + * function. + * @param {Function} [callback] - the final argument should be the callback, + * called when all functions have completed processing. + * @returns {Function} - If only the first argument is provided, it will return + * a function which lets you pass in the arguments as if it were a single + * function call. + */ var applyEachSeries = applyEach$1(mapSeries); + /** + * Creates a continuation function with some arguments already applied. + * + * Useful as a shorthand when combined with other control flow functions. Any + * arguments passed to the returned function are added to the arguments + * originally passed to apply. + * + * @name apply + * @static + * @memberOf async + * @category Util + * @param {Function} function - The function you want to eventually apply all + * arguments to. Invokes with (arguments...). + * @param {...*} arguments... - Any number of arguments to automatically apply + * when the continuation is called. + * @example + * + * // using apply + * async.parallel([ + * async.apply(fs.writeFile, 'testfile1', 'test1'), + * async.apply(fs.writeFile, 'testfile2', 'test2') + * ]); + * + * + * // the same process without using apply + * async.parallel([ + * function(callback) { + * fs.writeFile('testfile1', 'test1', callback); + * }, + * function(callback) { + * fs.writeFile('testfile2', 'test2', callback); + * } + * ]); + * + * // It's possible to pass any number of additional arguments when calling the + * // continuation: + * + * node> var fn = async.apply(sys.puts, 'one'); + * node> fn('two', 'three'); + * one + * two + * three + */ var apply$1 = rest(function (fn, args) { return rest(function (callArgs) { return fn.apply(null, args.concat(callArgs)); }); }); + /** + * Take a sync function and make it async, passing its return value to a + * callback. This is useful for plugging sync functions into a waterfall, + * series, or other async functions. Any arguments passed to the generated + * function will be passed to the wrapped function (except for the final + * callback argument). Errors thrown will be passed to the callback. + * + * If the function passed to `asyncify` returns a Promise, that promises's + * resolved/rejected state will be used to call the callback, rather than simply + * the synchronous return value. + * + * This also means you can asyncify ES2016 `async` functions. + * + * @name asyncify + * @static + * @memberOf async + * @alias wrapSync + * @category Util + * @param {Function} func - The synchronous function to convert to an + * asynchronous function. + * @returns {Function} An asynchronous wrapper of the `func`. To be invoked with + * (callback). + * @example + * + * // passing a regular synchronous function + * async.waterfall([ + * async.apply(fs.readFile, filename, "utf8"), + * async.asyncify(JSON.parse), + * function (data, next) { + * // data is the result of parsing the text. + * // If there was a parsing error, it would have been caught. + * } + * ], callback); + * + * // passing a function returning a promise + * async.waterfall([ + * async.apply(fs.readFile, filename, "utf8"), + * async.asyncify(function (contents) { + * return db.model.create(contents); + * }), + * function (model, next) { + * // `model` is the instantiated model object. + * // If there was an error, this function would be skipped. + * } + * ], callback); + * + * // es6 example + * var q = async.queue(async.asyncify(async function(file) { + * var intermediateStep = await processFile(file); + * return await somePromise(intermediateStep) + * })); + * + * q.push(files); + */ function asyncify(func) { return initialParams(function (args, callback) { var result; @@ -2766,6 +2979,83 @@ return -1; } + /** + * Determines the best order for running the functions in `tasks`, based on + * their requirements. Each function can optionally depend on other functions + * being completed first, and each function is run as soon as its requirements + * are satisfied. + * + * If any of the functions pass an error to their callback, the `auto` sequence + * will stop. Further tasks will not execute (so any other functions depending + * on it will not run), and the main `callback` is immediately called with the + * error. + * + * Functions also receive an object containing the results of functions which + * have completed so far as the first argument, if they have dependencies. If a + * task function has no dependencies, it will only be passed a callback. + * + * @name auto + * @static + * @memberOf async + * @category Control Flow + * @param {Object} tasks - An object. Each of its properties is either a + * function or an array of requirements, with the function itself the last item + * in the array. The object's key of a property serves as the name of the task + * defined by that property, i.e. can be used when specifying requirements for + * other tasks. The function receives one or two arguments: + * * a `results` object, containing the results of the previously executed + * functions, only passed if the task has any dependencies, + * * a `callback(err, result)` function, which must be called when finished, + * passing an `error` (which can be `null`) and the result of the function's + * execution. + * @param {number} [concurrency=Infinity] - An optional `integer` for + * determining the maximum number of tasks that can be run in parallel. By + * default, as many as possible. + * @param {Function} [callback] - An optional callback which is called when all + * the tasks have been completed. It receives the `err` argument if any `tasks` + * pass an error to their callback. Results are always returned; however, if an + * error occurs, no further `tasks` will be performed, and the results object + * will only contain partial results. Invoked with (err, results). + * @example + * + * async.auto({ + * // this function will just be passed a callback + * readData: async.apply(fs.readFile, 'data.txt', 'utf-8'), + * showData: ['readData', function(results, cb) { + * // results.readData is the file's contents + * // ... + * }] + * }, callback); + * + * async.auto({ + * get_data: function(callback) { + * console.log('in get_data'); + * // async code to get some data + * callback(null, 'data', 'converted to array'); + * }, + * make_folder: function(callback) { + * console.log('in make_folder'); + * // async code to create a directory to store a file in + * // this is run at the same time as getting the data + * callback(null, 'folder'); + * }, + * write_file: ['get_data', 'make_folder', function(results, callback) { + * console.log('in write_file', JSON.stringify(results)); + * // once there is some data and the directory exists, + * // write the data to a file in the directory + * callback(null, 'filename'); + * }], + * email_link: ['write_file', function(results, callback) { + * console.log('in email_link', JSON.stringify(results)); + * // once the file is written let's email a link to it... + * // results.write_file contains the filename returned by write_file. + * callback(null, {'file':results.write_file, 'email':'user@example.com'}); + * }] + * }, function(err, results) { + * console.log('err = ', err); + * console.log('results = ', results); + * }); + */ function auto (tasks, concurrency, callback) { if (typeof concurrency === 'function') { // concurrency is optional, shift the args. @@ -2790,32 +3080,31 @@ var readyTasks = []; + // for cycle detection: + var readyToCheck = []; // tasks that have been identified as reachable + // without the possibility of returning to an ancestor task + var uncheckedDependencies = {}; + forOwn(tasks, function (task, key) { if (!isArray(task)) { // no dependencies enqueueTask(key, [task]); + readyToCheck.push(key); return; } var dependencies = task.slice(0, task.length - 1); var remainingDependencies = dependencies.length; - - checkForDeadlocks(); - - function checkForDeadlocks() { - var len = dependencies.length; - var dep; - while (len--) { - if (!(dep = tasks[dependencies[len]])) { - throw new Error('async.auto task `' + key + '` has non-existent dependency in ' + dependencies.join(', ')); - } - if (isArray(dep) && baseIndexOf(dep, key, 0) >= 0) { - throw new Error('async.auto task `' + key + '`Has cyclic dependencies'); - } - } + if (!remainingDependencies) { + enqueueTask(key, [task]); + readyToCheck.push(key); } + uncheckedDependencies[key] = remainingDependencies; arrayEach(dependencies, function (dependencyName) { + if (!tasks[dependencyName]) { + throw new Error('async.auto task `' + key + '` has a non-existent dependency in ' + dependencies.join(', ')); + } addListener(dependencyName, function () { remainingDependencies--; if (remainingDependencies === 0) { @@ -2825,6 +3114,7 @@ }); }); + checkForDeadlocks(); processQueue(); function enqueueTask(key, task) { @@ -2892,6 +3182,37 @@ taskFn(taskCallback); } } + + function checkForDeadlocks() { + // Kahn's algorithm + // https://en.wikipedia.org/wiki/Topological_sorting#Kahn.27s_algorithm + // http://connalle.blogspot.com/2013/10/topological-sortingkahn-algorithm.html + var currentTask; + var counter = 0; + while (readyToCheck.length) { + currentTask = readyToCheck.pop(); + counter++; + arrayEach(getDependents(currentTask), function (dependent) { + if (! --uncheckedDependencies[dependent]) { + readyToCheck.push(dependent); + } + }); + } + + if (counter !== numTasks) { + throw new Error('async.auto cannot execute tasks due to a recursive dependency'); + } + } + + function getDependents(taskName) { + var result = []; + forOwn(tasks, function (task, key) { + if (isArray(task) && baseIndexOf(task, taskName, 0) >= 0) { + result.push(key); + } + }); + return result; + } } /** @@ -2919,6 +3240,92 @@ return func.toString().match(argsRegex)[1].split(/\s*\,\s*/); } + /** + * A dependency-injected version of the {@link async.auto} function. Dependent + * tasks are specified as parameters to the function, after the usual callback + * parameter, with the parameter names matching the names of the tasks it + * depends on. This can provide even more readable task graphs which can be + * easier to maintain. + * + * If a final callback is specified, the task results are similarly injected, + * specified as named parameters after the initial error parameter. + * + * The autoInject function is purely syntactic sugar and its semantics are + * otherwise equivalent to {@link async.auto}. + * + * @name autoInject + * @static + * @memberOf async + * @see async.auto + * @category Control Flow + * @param {Object} tasks - An object, each of whose properties is a function of + * the form 'func([dependencies...], callback). The object's key of a property + * serves as the name of the task defined by that property, i.e. can be used + * when specifying requirements for other tasks. + * * The `callback` parameter is a `callback(err, result)` which must be called + * when finished, passing an `error` (which can be `null`) and the result of + * the function's execution. The remaining parameters name other tasks on + * which the task is dependent, and the results from those tasks are the + * arguments of those parameters. + * @param {Function} [callback] - An optional callback which is called when all + * the tasks have been completed. It receives the `err` argument if any `tasks` + * pass an error to their callback. The remaining parameters are task names + * whose results you are interested in. This callback will only be called when + * all tasks have finished or an error has occurred, and so do not specify + * dependencies in the same way as `tasks` do. If an error occurs, no further + * `tasks` will be performed, and `results` will only be valid for those tasks + * which managed to complete. Invoked with (err, [results...]). + * @example + * + * // The example from `auto` can be rewritten as follows: + * async.autoInject({ + * get_data: function(callback) { + * // async code to get some data + * callback(null, 'data', 'converted to array'); + * }, + * make_folder: function(callback) { + * // async code to create a directory to store a file in + * // this is run at the same time as getting the data + * callback(null, 'folder'); + * }, + * write_file: function(get_data, make_folder, callback) { + * // once there is some data and the directory exists, + * // write the data to a file in the directory + * callback(null, 'filename'); + * }, + * email_link: function(write_file, callback) { + * // once the file is written let's email a link to it... + * // write_file contains the filename returned by write_file. + * callback(null, {'file':write_file, 'email':'user@example.com'}); + * } + * }, function(err, email_link) { + * console.log('err = ', err); + * console.log('email_link = ', email_link); + * }); + * + * // If you are using a JS minifier that mangles parameter names, `autoInject` + * // will not work with plain functions, since the parameter names will be + * // collapsed to a single letter identifier. To work around this, you can + * // explicitly specify the names of the parameters your task function needs + * // in an array, similar to Angular.js dependency injection. The final + * // results callback can be provided as an array in the same way. + * + * // This still has an advantage over plain `auto`, since the results a task + * // depends on are still spread into arguments. + * async.autoInject({ + * //... + * write_file: ['get_data', 'make_folder', function(get_data, make_folder, callback) { + * callback(null, 'filename'); + * }], + * email_link: ['write_file', function(write_file, callback) { + * callback(null, {'file':write_file, 'email':'user@example.com'}); + * }] + * //... + * }, ['email_link', function(err, email_link) { + * console.log('err = ', err); + * console.log('email_link = ', email_link); + * }]); + */ function autoInject(tasks, callback) { var newTasks = {}; @@ -2951,23 +3358,7 @@ } }); - auto(newTasks, function (err, results) { - var params; - if (isArray(callback)) { - params = copyArray(callback); - callback = params.pop(); - } else { - params = parseParams(callback); - params.shift(); - } - - params = arrayMap(params, function (name) { - return results[name]; - }); - - params.unshift(err); - callback.apply(null, params); - }); + auto(newTasks, callback); } var _setImmediate = typeof setImmediate === 'function' && setImmediate; @@ -3126,16 +3517,169 @@ return q; } + /** + * A cargo of tasks for the worker function to complete. Cargo inherits all of + * the same methods and event callbacks as {@link async.queue}. + * @typedef {Object} cargo + * @property {Function} length - A function returning the number of items + * waiting to be processed. Invoke with (). + * @property {number} payload - An `integer` for determining how many tasks + * should be process per round. This property can be changed after a `cargo` is + * created to alter the payload on-the-fly. + * @property {Function} push - Adds `task` to the `queue`. The callback is + * called once the `worker` has finished processing the task. Instead of a + * single task, an array of `tasks` can be submitted. The respective callback is + * used for every task in the list. Invoke with (task, [callback]). + * @property {Function} saturated - A callback that is called when the + * `queue.length()` hits the concurrency and further tasks will be queued. + * @property {Function} empty - A callback that is called when the last item + * from the `queue` is given to a `worker`. + * @property {Function} drain - A callback that is called when the last item + * from the `queue` has returned from the `worker`. + * @property {Function} idle - a function returning false if there are items + * waiting or being processed, or true if not. Invoke with (). + * @property {Function} pause - a function that pauses the processing of tasks + * until `resume()` is called. Invoke with (). + * @property {Function} resume - a function that resumes the processing of + * queued tasks when the queue is paused. Invoke with (). + * @property {Function} kill - a function that removes the `drain` callback and + * empties remaining tasks from the queue forcing it to go idle. Invoke with (). + */ + + /** + * Creates a `cargo` object with the specified payload. Tasks added to the + * cargo will be processed altogether (up to the `payload` limit). If the + * `worker` is in progress, the task is queued until it becomes available. Once + * the `worker` has completed some tasks, each callback of those tasks is + * called. Check out [these](https://camo.githubusercontent.com/6bbd36f4cf5b35a0f11a96dcd2e97711ffc2fb37/68747470733a2f2f662e636c6f75642e6769746875622e636f6d2f6173736574732f313637363837312f36383130382f62626330636662302d356632392d313165322d393734662d3333393763363464633835382e676966) [animations](https://camo.githubusercontent.com/f4810e00e1c5f5f8addbe3e9f49064fd5d102699/68747470733a2f2f662e636c6f75642e6769746875622e636f6d2f6173736574732f313637363837312f36383130312f38346339323036362d356632392d313165322d383134662d3964336430323431336266642e676966) + * for how `cargo` and `queue` work. + * + * While [queue](#queue) passes only one task to one of a group of workers + * at a time, cargo passes an array of tasks to a single worker, repeating + * when the worker is finished. + * + * @name cargo + * @static + * @memberOf async + * @see async.queue + * @category Control Flow + * @param {Function} worker - An asynchronous function for processing an array + * of queued tasks, which must call its `callback(err)` argument when finished, + * with an optional `err` argument. Invoked with (tasks, callback). + * @param {number} [payload=Infinity] - An optional `integer` for determining + * how many tasks should be processed per round; if omitted, the default is + * unlimited. + * @returns {cargo} A cargo object to manage the tasks. Callbacks can + * attached as certain properties to listen for specific events during the + * lifecycle of the cargo and inner queue. + * @example + * + * // create a cargo object with payload 2 + * var cargo = async.cargo(function(tasks, callback) { + * for (var i=0; i<tasks.length; i++) { + * console.log('hello ' + tasks[i].name); + * } + * callback(); + * }, 2); + * + * // add some items + * cargo.push({name: 'foo'}, function(err) { + * console.log('finished processing foo'); + * }); + * cargo.push({name: 'bar'}, function(err) { + * console.log('finished processing bar'); + * }); + * cargo.push({name: 'baz'}, function(err) { + * console.log('finished processing baz'); + * }); + */ function cargo(worker, payload) { - return queue(worker, 1, payload); + return queue(worker, 1, payload); } + /** + * The same as `eachOf` but runs a maximum of `limit` async operations at a + * time. + * + * @name eachOfLimit + * @static + * @memberOf async + * @see async.eachOf + * @alias forEachOfLimit + * @category Collection + * @param {Array|Object} coll - A collection to iterate over. + * @param {number} limit - The maximum number of async operations at a time. + * @param {Function} iteratee - A function to apply to each + * item in `coll`. The `key` is the item's key, or index in the case of an + * array. The iteratee is passed a `callback(err)` which must be called once it + * has completed. If no error has occurred, the callback should be run without + * arguments or with an explicit `null` argument. Invoked with + * (item, key, callback). + * @param {Function} [callback] - A callback which is called when all + * `iteratee` functions have finished, or an error occurs. Invoked with (err). + */ function eachOfLimit(obj, limit, iteratee, cb) { - _eachOfLimit(limit)(obj, iteratee, cb); + _eachOfLimit(limit)(obj, iteratee, cb); } + /** + * The same as `eachOf` but runs only a single async operation at a time. + * + * @name eachOfSeries + * @static + * @memberOf async + * @see async.eachOf + * @alias forEachOfSeries + * @category Collection + * @param {Array|Object} coll - A collection to iterate over. + * @param {Function} iteratee - A function to apply to each item in `coll`. The + * `key` is the item's key, or index in the case of an array. The iteratee is + * passed a `callback(err)` which must be called once it has completed. If no + * error has occurred, the callback should be run without arguments or with an + * explicit `null` argument. Invoked with (item, key, callback). + * @param {Function} [callback] - A callback which is called when all `iteratee` + * functions have finished, or an error occurs. Invoked with (err). + */ var eachOfSeries = doLimit(eachOfLimit, 1); + /** + * Reduces `coll` into a single value using an async `iteratee` to return each + * successive step. `memo` is the initial state of the reduction. This function + * only operates in series. + * + * For performance reasons, it may make sense to split a call to this function + * into a parallel map, and then use the normal `Array.prototype.reduce` on the + * results. This function is for situations where each step in the reduction + * needs to be async; if you can get the data before reducing it, then it's + * probably a good idea to do so. + * + * @name reduce + * @static + * @memberOf async + * @alias inject, foldl + * @category Collection + * @param {Array|Object} coll - A collection to iterate over. + * @param {*} memo - The initial state of the reduction. + * @param {Function} iteratee - A function applied to each item in the + * array to produce the next step in the reduction. The `iteratee` is passed a + * `callback(err, reduction)` which accepts an optional error as its first + * argument, and the state of the reduction as the second. If an error is + * passed to the callback, the reduction is stopped and the main `callback` is + * immediately called with the error. Invoked with (memo, item, callback). + * @param {Function} [callback] - A callback which is called after all the + * `iteratee` functions have finished. Result is the reduced value. Invoked with + * (err, result). + * @example + * + * async.reduce([1,2,3], 0, function(memo, item, callback) { + * // pointless async: + * process.nextTick(function() { + * callback(null, memo + item) + * }); + * }, function(err, result) { + * // result is now equal to the last value of memo, which is 6 + * }); + */ function reduce(arr, memo, iteratee, cb) { eachOfSeries(arr, function (x, i, cb) { iteratee(memo, x, function (err, v) { @@ -3147,6 +3691,42 @@ }); } + /** + * Version of the compose function that is more natural to read. Each function + * consumes the return value of the previous function. It is the equivalent of + * {@link async.compose} with the arguments reversed. + * + * Each function is executed with the `this` binding of the composed function. + * + * @name seq + * @static + * @memberOf async + * @see async.compose + * @category Control Flow + * @param {...Function} functions - the asynchronous functions to compose + * @example + * + * // Requires lodash (or underscore), express3 and dresende's orm2. + * // Part of an app, that fetches cats of the logged user. + * // This example uses `seq` function to avoid overnesting and error + * // handling clutter. + * app.get('/cats', function(request, response) { + * var User = request.models.User; + * async.seq( + * _.bind(User.get, User), // 'User.get' has signature (id, callback(err, data)) + * function(user, fn) { + * user.getCats(fn); // 'getCats' has signature (callback(err, data)) + * } + * )(req.session.user_id, function (err, cats) { + * if (err) { + * console.error(err); + * response.json({ status: 'error', message: err.message }); + * } else { + * response.json({ status: 'ok', message: 'Cats found', data: cats }); + * } + * }); + * }); + */ function seq() /* functions... */{ var fns = arguments; return rest(function (args) { @@ -3171,8 +3751,40 @@ var reverse = Array.prototype.reverse; + /** + * Creates a function which is a composition of the passed asynchronous + * functions. Each function consumes the return value of the function that + * follows. Composing functions `f()`, `g()`, and `h()` would produce the result + * of `f(g(h()))`, only this version uses callbacks to obtain the return values. + * + * Each function is executed with the `this` binding of the composed function. + * + * @name compose + * @static + * @memberOf async + * @category Control Flow + * @param {...Function} functions - the asynchronous functions to compose + * @example + * + * function add1(n, callback) { + * setTimeout(function () { + * callback(null, n + 1); + * }, 10); + * } + * + * function mul3(n, callback) { + * setTimeout(function () { + * callback(null, n * 3); + * }, 10); + * } + * + * var add1mul3 = async.compose(mul3, add1); + * add1mul3(4, function (err, result) { + * // result now equals 15 + * }); + */ function compose() /* functions... */{ - return seq.apply(null, reverse.call(arguments)); + return seq.apply(null, reverse.call(arguments)); } function concat$1(eachfn, arr, fn, callback) { @@ -3187,6 +3799,45 @@ }); } + /** + * Like `each`, except that it passes the key (or index) as the second argument + * to the iteratee. + * + * @name eachOf + * @static + * @memberOf async + * @alias forEachOf + * @category Collection + * @param {Array|Object} coll - A collection to iterate over. + * @param {Function} iteratee - A function to apply to each + * item in `coll`. The `key` is the item's key, or index in the case of an + * array. The iteratee is passed a `callback(err)` which must be called once it + * has completed. If no error has occurred, the callback should be run without + * arguments or with an explicit `null` argument. Invoked with + * (item, key, callback). + * @param {Function} [callback] - A callback which is called when all + * `iteratee` functions have finished, or an error occurs. Invoked with (err). + * @example + * + * var obj = {dev: "/dev.json", test: "/test.json", prod: "/prod.json"}; + * var configs = {}; + * + * async.forEachOf(obj, function (value, key, callback) { + * fs.readFile(__dirname + value, "utf8", function (err, data) { + * if (err) return callback(err); + * try { + * configs[key] = JSON.parse(data); + * } catch (e) { + * return callback(e); + * } + * callback(); + * }); + * }, function (err) { + * if (err) console.error(err.message); + * // configs is now a map of JSON data + * doSomethingWith(configs); + * }); + */ var eachOf = doLimit(eachOfLimit, Infinity); function doParallel(fn) { @@ -3195,6 +3846,32 @@ }; } + /** + * Applies `iteratee` to each item in `coll`, concatenating the results. Returns + * the concatenated list. The `iteratee`s are called in parallel, and the + * results are concatenated as they return. There is no guarantee that the + * results array will be returned in the original order of `coll` passed to the + * `iteratee` function. + * + * @name concat + * @static + * @memberOf async + * @category Collection + * @param {Array|Object} coll - A collection to iterate over. + * @param {Function} iteratee - A function to apply to each item in `coll`. + * The iteratee is passed a `callback(err, results)` which must be called once + * it has completed with an error (which can be `null`) and an array of results. + * Invoked with (item, callback). + * @param {Function} [callback(err)] - A callback which is called after all the + * `iteratee` functions have finished, or an error occurs. Results is an array + * containing the concatenated results of the `iteratee` function. Invoked with + * (err, results). + * @example + * + * async.concat(['dir1','dir2','dir3'], fs.readdir, function(err, files) { + * // files is now a list of filenames that exist in the 3 directories + * }); + */ var concat = doParallel(concat$1); function doSeries(fn) { @@ -3203,8 +3880,67 @@ }; } + /** + * The same as `concat` but runs only a single async operation at a time. + * + * @name concatSeries + * @static + * @memberOf async + * @see async.concat + * @category Collection + * @param {Array|Object} coll - A collection to iterate over. + * @param {Function} iteratee - A function to apply to each item in `coll`. + * The iteratee is passed a `callback(err, results)` which must be called once + * it has completed with an error (which can be `null`) and an array of results. + * Invoked with (item, callback). + * @param {Function} [callback(err)] - A callback which is called after all the + * `iteratee` functions have finished, or an error occurs. Results is an array + * containing the concatenated results of the `iteratee` function. Invoked with + * (err, results). + */ var concatSeries = doSeries(concat$1); + /** + * Returns a function that when called, calls-back with the values provided. + * Useful as the first function in a `waterfall`, or for plugging values in to + * `auto`. + * + * @name constant + * @static + * @memberOf async + * @category Util + * @param {...*} arguments... - Any number of arguments to automatically invoke + * callback with. + * @returns {Function} Returns a function that when invoked, automatically + * invokes the callback with the previous given arguments. + * @example + * + * async.waterfall([ + * async.constant(42), + * function (value, next) { + * // value === 42 + * }, + * //... + * ], callback); + * + * async.waterfall([ + * async.constant(filename, "utf8"), + * fs.readFile, + * function (fileData, next) { + * //... + * } + * //... + * ], callback); + * + * async.auto({ + * hostname: async.constant("https://server.net/"), + * port: findFreePort, + * launchServer: ["hostname", "port", function (options, cb) { + * startServer(options, cb); + * }], + * //... + * }, callback); + */ var constant = rest(function (values) { var args = [null].concat(values); return initialParams(function (ignoredArgs, callback) { @@ -3254,10 +3990,84 @@ return x; } + /** + * Returns the first value in `coll` that passes an async truth test. The + * `iteratee` is applied in parallel, meaning the first iteratee to return + * `true` will fire the detect `callback` with that result. That means the + * result might not be the first item in the original `coll` (in terms of order) + * that passes the test. + + * If order within the original `coll` is important, then look at + * `detectSeries`. + * + * @name detect + * @static + * @memberOf async + * @alias find + * @category Collection + * @param {Array|Object} coll - A collection to iterate over. + * @param {Function} iteratee - A truth test to apply to each item in `coll`. + * The iteratee is passed a `callback(err, truthValue)` which must be called + * with a boolean argument once it has completed. Invoked with (item, callback). + * @param {Function} [callback] - A callback which is called as soon as any + * iteratee returns `true`, or after all the `iteratee` functions have finished. + * Result will be the first item in the array that passes the truth test + * (iteratee) or the value `undefined` if none passed. Invoked with + * (err, result). + * @example + * + * async.detect(['file1','file2','file3'], function(filePath, callback) { + * fs.access(filePath, function(err) { + * callback(null, !err) + * }); + * }, function(err, result) { + * // result now equals the first file in the list that exists + * }); + */ var detect = _createTester(eachOf, identity, _findGetResult); + /** + * The same as `detect` but runs a maximum of `limit` async operations at a + * time. + * + * @name detectLimit + * @static + * @memberOf async + * @see async.detect + * @alias findLimit + * @category Collection + * @param {Array|Object} coll - A collection to iterate over. + * @param {number} limit - The maximum number of async operations at a time. + * @param {Function} iteratee - A truth test to apply to each item in `coll`. + * The iteratee is passed a `callback(err, truthValue)` which must be called + * with a boolean argument once it has completed. Invoked with (item, callback). + * @param {Function} [callback] - A callback which is called as soon as any + * iteratee returns `true`, or after all the `iteratee` functions have finished. + * Result will be the first item in the array that passes the truth test + * (iteratee) or the value `undefined` if none passed. Invoked with + * (err, result). + */ var detectLimit = _createTester(eachOfLimit, identity, _findGetResult); + /** + * The same as `detect` but runs only a single async operation at a time. + * + * @name detectSeries + * @static + * @memberOf async + * @see async.detect + * @alias findSeries + * @category Collection + * @param {Array|Object} coll - A collection to iterate over. + * @param {Function} iteratee - A truth test to apply to each item in `coll`. + * The iteratee is passed a `callback(err, truthValue)` which must be called + * with a boolean argument once it has completed. Invoked with (item, callback). + * @param {Function} [callback] - A callback which is called as soon as any + * iteratee returns `true`, or after all the `iteratee` functions have finished. + * Result will be the first item in the array that passes the truth test + * (iteratee) or the value `undefined` if none passed. Invoked with + * (err, result). + */ var detectSeries = _createTester(eachOfSeries, identity, _findGetResult); function consoleFunc(name) { @@ -3278,8 +4088,72 @@ }); } + /** + * Logs the result of an `async` function to the `console` using `console.dir` + * to display the properties of the resulting object. Only works in Node.js or + * in browsers that support `console.dir` and `console.error` (such as FF and + * Chrome). If multiple arguments are returned from the async function, + * `console.dir` is called on each argument in order. + * + * @name log + * @static + * @memberOf async + * @category Util + * @param {Function} function - The function you want to eventually apply all + * arguments to. + * @param {...*} arguments... - Any number of arguments to apply to the function. + * @example + * + * // in a module + * var hello = function(name, callback) { + * setTimeout(function() { + * callback(null, {hello: name}); + * }, 1000); + * }; + * + * // in the node repl + * node> async.dir(hello, 'world'); + * {hello: 'world'} + */ var dir = consoleFunc('dir'); + /** + * Like {@link async.whilst}, except the `test` is an asynchronous function that + * is passed a callback in the form of `function (err, truth)`. If error is + * passed to `test` or `fn`, the main callback is immediately called with the + * value of the error. + * + * @name during + * @static + * @memberOf async + * @see async.whilst + * @category Control Flow + * @param {Function} test - asynchronous truth test to perform before each + * execution of `fn`. Invoked with (callback). + * @param {Function} fn - A function which is called each time `test` passes. + * The function is passed a `callback(err)`, which must be called once it has + * completed with an optional `err` argument. Invoked with (callback). + * @param {Function} [callback] - A callback which is called after the test + * function has failed and repeated execution of `fn` has stopped. `callback` + * will be passed an error and any arguments passed to the final `fn`'s + * callback. Invoked with (err, [results]); + * @example + * + * var count = 0; + * + * async.during( + * function (callback) { + * return callback(null, count < 5); + * }, + * function (callback) { + * count++; + * setTimeout(callback, 1000); + * }, + * function (err) { + * // 5 seconds have passed + * } + * ); + */ function during(test, iteratee, cb) { cb = cb || noop; @@ -3301,6 +4175,26 @@ test(check); } + /** + * The post-check version of {@link async.during}. To reflect the difference in + * the order of operations, the arguments `test` and `fn` are switched. + * + * Also a version of {@link async.doWhilst} with asynchronous `test` function. + * @name doDuring + * @static + * @memberOf async + * @see async.during + * @category Control Flow + * @param {Function} fn - A function which is called each time `test` passes. + * The function is passed a `callback(err)`, which must be called once it has + * completed with an optional `err` argument. Invoked with (callback). + * @param {Function} test - asynchronous truth test to perform before each + * execution of `fn`. Invoked with (callback). + * @param {Function} [callback] - A callback which is called after the test + * function has failed and repeated execution of `fn` has stopped. `callback` + * will be passed an error and any arguments passed to the final `fn`'s + * callback. Invoked with (err, [results]); + */ function doDuring(iteratee, test, cb) { var calls = 0; @@ -3310,6 +4204,39 @@ }, iteratee, cb); } + /** + * Repeatedly call `fn`, while `test` returns `true`. Calls `callback` when + * stopped, or an error occurs. + * + * @name whilst + * @static + * @memberOf async + * @category Control Flow + * @param {Function} test - synchronous truth test to perform before each + * execution of `fn`. Invoked with (). + * @param {Function} fn - A function which is called each time `test` passes. + * The function is passed a `callback(err)`, which must be called once it has + * completed with an optional `err` argument. Invoked with (callback). + * @param {Function} [callback] - A callback which is called after the test + * function has failed and repeated execution of `fn` has stopped. `callback` + * will be passed an error and any arguments passed to the final `fn`'s + * callback. Invoked with (err, [results]); + * @example + * + * var count = 0; + * async.whilst( + * function() { return count < 5; }, + * function(callback) { + * count++; + * setTimeout(function() { + * callback(null, count); + * }, 1000); + * }, + * function (err, n) { + * // 5 seconds have passed, n = 5 + * } + * ); + */ function whilst(test, iteratee, cb) { cb = cb || noop; if (!test()) return cb(null); @@ -3321,6 +4248,27 @@ iteratee(next); } + /** + * The post-check version of {@link async.whilst}. To reflect the difference in + * the order of operations, the arguments `test` and `fn` are switched. + * + * `doWhilst` is to `whilst` as `do while` is to `while` in plain JavaScript. + * + * @name doWhilst + * @static + * @memberOf async + * @see async.whilst + * @category Control Flow + * @param {Function} fn - A function which is called each time `test` passes. + * The function is passed a `callback(err)`, which must be called once it has + * completed with an optional `err` argument. Invoked with (callback). + * @param {Function} test - synchronous truth test to perform before each + * execution of `fn`. Invoked with (). + * @param {Function} [callback] - A callback which is called after the test + * function has failed and repeated execution of `fn` has stopped. `callback` + * will be passed an error and any arguments passed to the final `fn`'s + * callback. Invoked with (err, [results]); + */ function doWhilst(iteratee, test, cb) { var calls = 0; return whilst(function () { @@ -3328,6 +4276,25 @@ }, iteratee, cb); } + /** + * Like {@link async.doWhilst}, except the `test` is inverted. Note the + * argument ordering differs from `until`. + * + * @name doUntil + * @static + * @memberOf async + * @see async.doWhilst + * @category Control Flow + * @param {Function} fn - A function which is called each time `test` fails. + * The function is passed a `callback(err)`, which must be called once it has + * completed with an optional `err` argument. Invoked with (callback). + * @param {Function} test - synchronous truth test to perform before each + * execution of `fn`. Invoked with (). + * @param {Function} [callback] - A callback which is called after the test + * function has passed and repeated execution of `fn` has stopped. `callback` + * will be passed an error and any arguments passed to the final `fn`'s + * callback. Invoked with (err, [results]); + */ function doUntil(iteratee, test, cb) { return doWhilst(iteratee, function () { return !test.apply(this, arguments); @@ -3340,14 +4307,144 @@ }; } + /** + * The same as `each` but runs a maximum of `limit` async operations at a time. + * + * @name eachLimit + * @static + * @memberOf async + * @see async.each + * @alias forEachLimit + * @category Collection + * @param {Array|Object} coll - A colleciton to iterate over. + * @param {number} limit - The maximum number of async operations at a time. + * @param {Function} iteratee - A function to apply to each item in `coll`. The + * iteratee is passed a `callback(err)` which must be called once it has + * completed. If no error has occurred, the `callback` should be run without + * arguments or with an explicit `null` argument. The array index is not passed + * to the iteratee. Invoked with (item, callback). If you need the index, use + * `eachOfLimit`. + * @param {Function} [callback] - A callback which is called when all + * `iteratee` functions have finished, or an error occurs. Invoked with (err). + */ function eachLimit(arr, limit, iteratee, cb) { - return _eachOfLimit(limit)(arr, _withoutIndex(iteratee), cb); + return _eachOfLimit(limit)(arr, _withoutIndex(iteratee), cb); } + /** + * Applies the function `iteratee` to each item in `coll`, in parallel. + * The `iteratee` is called with an item from the list, and a callback for when + * it has finished. If the `iteratee` passes an error to its `callback`, the + * main `callback` (for the `each` function) is immediately called with the + * error. + * + * Note, that since this function applies `iteratee` to each item in parallel, + * there is no guarantee that the iteratee functions will complete in order. + * + * @name each + * @static + * @memberOf async + * @alias forEach + * @category Collection + * @param {Array|Object} coll - A collection to iterate over. + * @param {Function} iteratee - A function to apply to each item + * in `coll`. The iteratee is passed a `callback(err)` which must be called once + * it has completed. If no error has occurred, the `callback` should be run + * without arguments or with an explicit `null` argument. The array index is not + * passed to the iteratee. Invoked with (item, callback). If you need the index, + * use `eachOf`. + * @param {Function} [callback] - A callback which is called when all + * `iteratee` functions have finished, or an error occurs. Invoked with (err). + * @example + * + * // assuming openFiles is an array of file names and saveFile is a function + * // to save the modified contents of that file: + * + * async.each(openFiles, saveFile, function(err){ + * // if any of the saves produced an error, err would equal that error + * }); + * + * // assuming openFiles is an array of file names + * async.each(openFiles, function(file, callback) { + * + * // Perform operation on file here. + * console.log('Processing file ' + file); + * + * if( file.length > 32 ) { + * console.log('This file name is too long'); + * callback('File name too long'); + * } else { + * // Do work to process file here + * console.log('File processed'); + * callback(); + * } + * }, function(err) { + * // if any of the file processing produced an error, err would equal that error + * if( err ) { + * // One of the iterations produced an error. + * // All processing will now stop. + * console.log('A file failed to process'); + * } else { + * console.log('All files have been processed successfully'); + * } + * }); + */ var each = doLimit(eachLimit, Infinity); + /** + * The same as `each` but runs only a single async operation at a time. + * + * @name eachSeries + * @static + * @memberOf async + * @see async.each + * @alias forEachSeries + * @category Collection + * @param {Array|Object} coll - A collection to iterate over. + * @param {Function} iteratee - A function to apply to each + * item in `coll`. The iteratee is passed a `callback(err)` which must be called + * once it has completed. If no error has occurred, the `callback` should be run + * without arguments or with an explicit `null` argument. The array index is + * not passed to the iteratee. Invoked with (item, callback). If you need the + * index, use `eachOfSeries`. + * @param {Function} [callback] - A callback which is called when all + * `iteratee` functions have finished, or an error occurs. Invoked with (err). + */ var eachSeries = doLimit(eachLimit, 1); + /** + * Wrap an async function and ensure it calls its callback on a later tick of + * the event loop. If the function already calls its callback on a next tick, + * no extra deferral is added. This is useful for preventing stack overflows + * (`RangeError: Maximum call stack size exceeded`) and generally keeping + * [Zalgo](http://blog.izs.me/post/59142742143/designing-apis-for-asynchrony) + * contained. + * + * @name ensureAsync + * @static + * @memberOf async + * @category Util + * @param {Function} fn - an async function, one that expects a node-style + * callback as its last argument. + * @returns {Function} Returns a wrapped function with the exact same call + * signature as the function passed in. + * @example + * + * function sometimesAsync(arg, callback) { + * if (cache[arg]) { + * return callback(null, cache[arg]); // this would be synchronous!! + * } else { + * doSomeIO(arg, callback); // this IO would be asynchronous + * } + * } + * + * // this has a risk of stack overflows if many results are cached in a row + * async.mapSeries(args, sometimesAsync, done); + * + * // this will defer sometimesAsync's callback if necessary, + * // preventing stack overflows + * async.mapSeries(args, async.ensureAsync(sometimesAsync), done); + */ function ensureAsync(fn) { return initialParams(function (args, callback) { var sync = true; @@ -3370,10 +4467,74 @@ return !v; } + /** + * The same as `every` but runs a maximum of `limit` async operations at a time. + * + * @name everyLimit + * @static + * @memberOf async + * @see async.every + * @alias allLimit + * @category Collection + * @param {Array|Object} coll - A collection to iterate over. + * @param {number} limit - The maximum number of async operations at a time. + * @param {Function} iteratee - A truth test to apply to each item in the + * collection in parallel. The iteratee is passed a `callback(err, truthValue)` + * which must be called with a boolean argument once it has completed. Invoked + * with (item, callback). + * @param {Function} [callback] - A callback which is called after all the + * `iteratee` functions have finished. Result will be either `true` or `false` + * depending on the values of the async tests. Invoked with (err, result). + */ var everyLimit = _createTester(eachOfLimit, notId, notId); + /** + * Returns `true` if every element in `coll` satisfies an async test. If any + * iteratee call returns `false`, the main `callback` is immediately called. + * + * @name every + * @static + * @memberOf async + * @alias all + * @category Collection + * @param {Array|Object} coll - A collection to iterate over. + * @param {Function} iteratee - A truth test to apply to each item in the + * collection in parallel. The iteratee is passed a `callback(err, truthValue)` + * which must be called with a boolean argument once it has completed. Invoked + * with (item, callback). + * @param {Function} [callback] - A callback which is called after all the + * `iteratee` functions have finished. Result will be either `true` or `false` + * depending on the values of the async tests. Invoked with (err, result). + * @example + * + * async.every(['file1','file2','file3'], function(filePath, callback) { + * fs.access(filePath, function(err) { + * callback(null, !err) + * }); + * }, function(err, result) { + * // if result is true then every file exists + * }); + */ var every = doLimit(everyLimit, Infinity); + /** + * The same as `every` but runs only a single async operation at a time. + * + * @name everySeries + * @static + * @memberOf async + * @see async.every + * @alias allSeries + * @category Collection + * @param {Array|Object} coll - A collection to iterate over. + * @param {Function} iteratee - A truth test to apply to each item in the + * collection in parallel. The iteratee is passed a `callback(err, truthValue)` + * which must be called with a boolean argument once it has completed. Invoked + * with (item, callback). + * @param {Function} [callback] - A callback which is called after all the + * `iteratee` functions have finished. Result will be either `true` or `false` + * depending on the values of the async tests. Invoked with (err, result). + */ var everySeries = doLimit(everyLimit, 1); function _filter(eachfn, arr, iteratee, callback) { @@ -3400,12 +4561,100 @@ }); } + /** + * The same as `filter` but runs a maximum of `limit` async operations at a + * time. + * + * @name filterLimit + * @static + * @memberOf async + * @see async.filter + * @alias selectLimit + * @category Collection + * @param {Array|Object} coll - A collection to iterate over. + * @param {number} limit - The maximum number of async operations at a time. + * @param {Function} iteratee - A truth test to apply to each item in `coll`. + * The `iteratee` is passed a `callback(err, truthValue)`, which must be called + * with a boolean argument once it has completed. Invoked with (item, callback). + * @param {Function} [callback] - A callback which is called after all the + * `iteratee` functions have finished. Invoked with (err, results). + */ var filterLimit = doParallelLimit(_filter); + /** + * Returns a new array of all the values in `coll` which pass an async truth + * test. This operation is performed in parallel, but the results array will be + * in the same order as the original. + * + * @name filter + * @static + * @memberOf async + * @alias select + * @category Collection + * @param {Array|Object} coll - A collection to iterate over. + * @param {Function} iteratee - A truth test to apply to each item in `coll`. + * The `iteratee` is passed a `callback(err, truthValue)`, which must be called + * with a boolean argument once it has completed. Invoked with (item, callback). + * @param {Function} [callback] - A callback which is called after all the + * `iteratee` functions have finished. Invoked with (err, results). + * @example + * + * async.filter(['file1','file2','file3'], function(filePath, callback) { + * fs.access(filePath, function(err) { + * callback(null, !err) + * }); + * }, function(err, results) { + * // results now equals an array of the existing files + * }); + */ var filter = doLimit(filterLimit, Infinity); + /** + * The same as `filter` but runs only a single async operation at a time. + * + * @name filterSeries + * @static + * @memberOf async + * @see async.filter + * @alias selectSeries + * @category Collection + * @param {Array|Object} coll - A collection to iterate over. + * @param {Function} iteratee - A truth test to apply to each item in `coll`. + * The `iteratee` is passed a `callback(err, truthValue)`, which must be called + * with a boolean argument once it has completed. Invoked with (item, callback). + * @param {Function} [callback] - A callback which is called after all the + * `iteratee` functions have finished. Invoked with (err, results) + */ var filterSeries = doLimit(filterLimit, 1); + /** + * Calls the asynchronous function `fn` with a callback parameter that allows it + * to call itself again, in series, indefinitely. + + * If an error is passed to the + * callback then `errback` is called with the error, and execution stops, + * otherwise it will never be called. + * + * @name forever + * @static + * @memberOf async + * @category Control Flow + * @param {Function} fn - a function to call repeatedly. Invoked with (next). + * @param {Function} [errback] - when `fn` passes an error to it's callback, + * this function will be called, and execution stops. Invoked with (err). + * @example + * + * async.forever( + * function(next) { + * // next is suitable for passing to things that need a callback(err [, whatever]); + * // it will result in this function being called again. + * }, + * function(err) { + * // if next is called with a value in its first parameter, it will appear + * // in here as 'err', and execution will stop. + * } + * ); + */ function forever(fn, cb) { var done = onlyOnce(cb || noop); var task = ensureAsync(fn); @@ -3417,6 +4666,39 @@ next(); } + /** + * Creates an iterator function which calls the next function in the `tasks` + * array, returning a continuation to call the next one after that. It's also + * possible to “peek” at the next iterator with `iterator.next()`. + * + * This function is used internally by the `async` module, but can be useful + * when you want to manually control the flow of functions in series. + * + * @name iterator + * @static + * @memberOf async + * @category Control Flow + * @param {Array} tasks - An array of functions to run. + * @returns The next function to run in the series. + * @example + * + * var iterator = async.iterator([ + * function() { sys.p('one'); }, + * function() { sys.p('two'); }, + * function() { sys.p('three'); } + * ]); + * + * node> var iterator2 = iterator(); + * 'one' + * node> var iterator3 = iterator2(); + * 'two' + * node> iterator3(); + * 'three' + * node> var nextfn = iterator2.next(); + * node> nextfn(); + * 'three' + */ + function iterator$1 (tasks) { function makeCallback(index) { function fn() { @@ -3433,12 +4715,73 @@ return makeCallback(0); } + /** + * Logs the result of an `async` function to the `console`. Only works in + * Node.js or in browsers that support `console.log` and `console.error` (such + * as FF and Chrome). If multiple arguments are returned from the async + * function, `console.log` is called on each argument in order. + * + * @name log + * @static + * @memberOf async + * @category Util + * @param {Function} function - The function you want to eventually apply all + * arguments to. + * @param {...*} arguments... - Any number of arguments to apply to the function. + * @example + * + * // in a module + * var hello = function(name, callback) { + * setTimeout(function() { + * callback(null, 'hello ' + name); + * }, 1000); + * }; + * + * // in the node repl + * node> async.log(hello, 'world'); + * 'hello world' + */ var log = consoleFunc('log'); function has(obj, key) { return key in obj; } + /** + * Caches the results of an `async` function. When creating a hash to store + * function results against, the callback is omitted from the hash and an + * optional hash function can be used. + * + * If no hash function is specified, the first argument is used as a hash key, + * which may work reasonably if it is a string or a data type that converts to a + * distinct string. Note that objects and arrays will not behave reasonably. + * Neither will cases where the other arguments are significant. In such cases, + * specify your own hash function. + * + * The cache of results is exposed as the `memo` property of the function + * returned by `memoize`. + * + * @name memoize + * @static + * @memberOf async + * @category Util + * @param {Function} fn - The function to proxy and cache results from. + * @param {Function} hasher - An optional function for generating a custom hash + * for storing results. It has all the arguments applied to it apart from the + * callback, and must be synchronous. + * @example + * + * var slow_fn = function(name, callback) { + * // do something + * callback(null, result); + * }; + * var fn = async.memoize(slow_fn); + * + * // fn can now be used as if it were slow_fn + * fn('some name', function() { + * // callback + * }); + */ function memoize$1(fn, hasher) { var memo = Object.create(null); var queues = Object.create(null); @@ -3485,18 +4828,221 @@ }); } + /** + * The same as `parallel` but runs a maximum of `limit` async operations at a + * time. + * + * @name parallel + * @static + * @memberOf async + * @see async.parallel + * @category Control Flow + * @param {Array|Collection} tasks - A collection containing functions to run. + * Each function is passed a `callback(err, result)` which it must call on + * completion with an error `err` (which can be `null`) and an optional `result` + * value. + * @param {number} limit - The maximum number of async operations at a time. + * @param {Function} [callback] - An optional callback to run once all the + * functions have completed successfully. This function gets a results array + * (or object) containing all the result arguments passed to the task callbacks. + * Invoked with (err, results). + */ function parallelLimit(tasks, limit, cb) { - return _parallel(_eachOfLimit(limit), tasks, cb); + return _parallel(_eachOfLimit(limit), tasks, cb); } + /** + * Run the `tasks` collection of functions in parallel, without waiting until + * the previous function has completed. If any of the functions pass an error to + * its callback, the main `callback` is immediately called with the value of the + * error. Once the `tasks` have completed, the results are passed to the final + * `callback` as an array. + * + * **Note:** `parallel` is about kicking-off I/O tasks in parallel, not about + * parallel execution of code. If your tasks do not use any timers or perform + * any I/O, they will actually be executed in series. Any synchronous setup + * sections for each task will happen one after the other. JavaScript remains + * single-threaded. + * + * It is also possible to use an object instead of an array. Each property will + * be run as a function and the results will be passed to the final `callback` + * as an object instead of an array. This can be a more readable way of handling + * results from {@link async.parallel}. + * + * @name parallel + * @static + * @memberOf async + * @category Control Flow + * @param {Array|Object} tasks - A collection containing functions to run. + * Each function is passed a `callback(err, result)` which it must call on + * completion with an error `err` (which can be `null`) and an optional `result` + * value. + * @param {Function} [callback] - An optional callback to run once all the + * functions have completed successfully. This function gets a results array + * (or object) containing all the result arguments passed to the task callbacks. + * Invoked with (err, results). + * @example + * async.parallel([ + * function(callback) { + * setTimeout(function() { + * callback(null, 'one'); + * }, 200); + * }, + * function(callback) { + * setTimeout(function() { + * callback(null, 'two'); + * }, 100); + * } + * ], + * // optional callback + * function(err, results) { + * // the results array will equal ['one','two'] even though + * // the second function had a shorter timeout. + * }); + * + * // an example using an object instead of an array + * async.parallel({ + * one: function(callback) { + * setTimeout(function() { + * callback(null, 1); + * }, 200); + * }, + * two: function(callback) { + * setTimeout(function() { + * callback(null, 2); + * }, 100); + * } + * }, function(err, results) { + * // results is now equals to: {one: 1, two: 2} + * }); + */ var parallel = doLimit(parallelLimit, Infinity); + /** + * A queue of tasks for the worker function to complete. + * @typedef {Object} queue + * @property {Function} length - a function returning the number of items + * waiting to be processed. Invoke with (). + * @property {Function} started - a function returning whether or not any + * items have been pushed and processed by the queue. Invoke with (). + * @property {Function} running - a function returning the number of items + * currently being processed. Invoke with (). + * @property {Function} workersList - a function returning the array of items + * currently being processed. Invoke with (). + * @property {Function} idle - a function returning false if there are items + * waiting or being processed, or true if not. Invoke with (). + * @property {number} concurrency - an integer for determining how many `worker` + * functions should be run in parallel. This property can be changed after a + * `queue` is created to alter the concurrency on-the-fly. + * @property {Function} push - add a new task to the `queue`. Calls `callback` + * once the `worker` has finished processing the task. Instead of a single task, + * a `tasks` array can be submitted. The respective callback is used for every + * task in the list. Invoke with (task, [callback]), + * @property {Function} unshift - add a new task to the front of the `queue`. + * Invoke with (task, [callback]). + * @property {Function} saturated - a callback that is called when the number of + * running workers hits the `concurrency` limit, and further tasks will be + * queued. + * @property {Function} unsaturated - a callback that is called when the number + * of running workers is less than the `concurrency` & `buffer` limits, and + * further tasks will not be queued. + * @property {number} buffer - A minimum threshold buffer in order to say that + * the `queue` is `unsaturated`. + * @property {Function} empty - a callback that is called when the last item + * from the `queue` is given to a `worker`. + * @property {Function} drain - a callback that is called when the last item + * from the `queue` has returned from the `worker`. + * @property {boolean} paused - a boolean for determining whether the queue is + * in a paused state. + * @property {Function} pause - a function that pauses the processing of tasks + * until `resume()` is called. Invoke with (). + * @property {Function} resume - a function that resumes the processing of + * queued tasks when the queue is paused. Invoke with (). + * @property {Function} kill - a function that removes the `drain` callback and + * empties remaining tasks from the queue forcing it to go idle. Invoke with (). + */ + + /** + * Creates a `queue` object with the specified `concurrency`. Tasks added to the + * `queue` are processed in parallel (up to the `concurrency` limit). If all + * `worker`s are in progress, the task is queued until one becomes available. + * Once a `worker` completes a `task`, that `task`'s callback is called. + * + * @name queue + * @static + * @memberOf async + * @category Control Flow + * @param {Function} worker - An asynchronous function for processing a queued + * task, which must call its `callback(err)` argument when finished, with an + * optional `error` as an argument. If you want to handle errors from an + * individual task, pass a callback to `q.push()`. Invoked with + * (task, callback). + * @param {number} [concurrency=1] - An `integer` for determining how many + * `worker` functions should be run in parallel. If omitted, the concurrency + * defaults to `1`. If the concurrency is `0`, an error is thrown. + * @returns {queue} A queue object to manage the tasks. Callbacks can + * attached as certain properties to listen for specific events during the + * lifecycle of the queue. + * @example + * + * // create a queue object with concurrency 2 + * var q = async.queue(function(task, callback) { + * console.log('hello ' + task.name); + * callback(); + * }, 2); + * + * // assign a callback + * q.drain = function() { + * console.log('all items have been processed'); + * }; + * + * // add some items to the queue + * q.push({name: 'foo'}, function(err) { + * console.log('finished processing foo'); + * }); + * q.push({name: 'bar'}, function (err) { + * console.log('finished processing bar'); + * }); + * + * // add some items to the queue (batch-wise) + * q.push([{name: 'baz'},{name: 'bay'},{name: 'bax'}], function(err) { + * console.log('finished processing item'); + * }); + * + * // add some items to the front of the queue + * q.unshift({name: 'bar'}, function (err) { + * console.log('finished processing bar'); + * }); + */ function queue$1 (worker, concurrency) { - return queue(function (items, cb) { - worker(items[0], cb); - }, concurrency, 1); + return queue(function (items, cb) { + worker(items[0], cb); + }, concurrency, 1); } + /** + * The same as {@link async.queue} only tasks are assigned a priority and + * completed in ascending priority order. + * + * @name priorityQueue + * @static + * @memberOf async + * @see async.queue + * @category Control Flow + * @param {Function} worker - An asynchronous function for processing a queued + * task, which must call its `callback(err)` argument when finished, with an + * optional `error` as an argument. If you want to handle errors from an + * individual task, pass a callback to `q.push()`. Invoked with + * (task, callback). + * @param {number} concurrency - An `integer` for determining how many `worker` + * functions should be run in parallel. If omitted, the concurrency defaults to + * `1`. If the concurrency is `0`, an error is thrown. + * @returns {queue} A priorityQueue object to manage the tasks. There are two + * differences between `queue` and `priorityQueue` objects: + * * `push(task, priority, [callback])` - `priority` should be a number. If an + * array of `tasks` is given, all tasks will be assigned the same priority. + * * The `unshift` method was removed. + */ function priorityQueue (worker, concurrency) { function _compareTasks(a, b) { return a.priority - b.priority; @@ -3539,12 +5085,6 @@ q.tasks.splice(_binarySearch(q.tasks, item, _compareTasks) + 1, 0, item); - if (q.tasks.length === q.concurrency) { - q.saturated(); - } - if (q.tasks.length <= q.concurrency - q.buffer) { - q.unsaturated(); - } setImmediate$1(q.process); }); } @@ -3637,6 +5177,41 @@ : baseEach(collection, baseIteratee(iteratee)); } + /** + * Runs the `tasks` array of functions in parallel, without waiting until the + * previous function has completed. Once any the `tasks` completed or pass an + * error to its callback, the main `callback` is immediately called. It's + * equivalent to `Promise.race()`. + * + * @name race + * @static + * @memberOf async + * @category Control Flow + * @param {Array} tasks - An array containing functions to run. Each function + * is passed a `callback(err, result)` which it must call on completion with an + * error `err` (which can be `null`) and an optional `result` value. + * @param {Function} callback - A callback to run once any of the functions have + * completed. This function gets an error or result from the first function that + * completed. Invoked with (err, result). + * @example + * + * async.race([ + * function(callback) { + * setTimeout(function() { + * callback(null, 'one'); + * }, 200); + * }, + * function(callback) { + * setTimeout(function() { + * callback(null, 'two'); + * }, 100); + * } + * ], + * // main callback + * function(err, result) { + * // the result will be equal to 'two' as it finishes earlier + * }); + */ function race(tasks, cb) { cb = once(cb || noop); if (!isArray(tasks)) return cb(new TypeError('First argument to race must be an array of functions')); @@ -3648,11 +5223,70 @@ var slice = Array.prototype.slice; + /** + * Same as `reduce`, only operates on `coll` in reverse order. + * + * @name reduceRight + * @static + * @memberOf async + * @see async.reduce + * @alias foldr + * @category Collection + * @param {Array|Object} coll - A collection to iterate over. + * @param {*} memo - The initial state of the reduction. + * @param {Function} iteratee - A function applied to each item in the + * array to produce the next step in the reduction. The `iteratee` is passed a + * `callback(err, reduction)` which accepts an optional error as its first + * argument, and the state of the reduction as the second. If an error is + * passed to the callback, the reduction is stopped and the main `callback` is + * immediately called with the error. Invoked with (memo, item, callback). + * @param {Function} [callback] - A callback which is called after all the + * `iteratee` functions have finished. Result is the reduced value. Invoked with + * (err, result). + */ function reduceRight(arr, memo, iteratee, cb) { - var reversed = slice.call(arr).reverse(); - reduce(reversed, memo, iteratee, cb); + var reversed = slice.call(arr).reverse(); + reduce(reversed, memo, iteratee, cb); } + /** + * Wraps the function in another function that always returns data even when it + * errors. + * + * The object returned has either the property `error` or `value`. + * + * @name reflect + * @static + * @memberOf async + * @category Util + * @param {Function} function - The function you want to wrap + * @returns {Function} - A function that always passes null to it's callback as + * the error. The second argument to the callback will be an `object` with + * either an `error` or a `value` property. + * @example + * + * async.parallel([ + * async.reflect(function(callback) { + * // do some stuff ... + * callback(null, 'one'); + * }), + * async.reflect(function(callback) { + * // do some more stuff but error ... + * callback('bad stuff happened'); + * }), + * async.reflect(function(callback) { + * // do some more stuff ... + * callback(null, 'two'); + * }) + * ], + * // optional callback + * function(err, results) { + * // values + * // results[0].value = 'one' + * // results[1].error = 'bad stuff happened' + * // results[2].value = 'two' + * }); + */ function reflect(fn) { return initialParams(function reflectOn(args, reflectCallback) { args.push(rest(function callback(err, cbArgs) { @@ -3689,20 +5323,236 @@ }, callback); } + /** + * The same as `reject` but runs a maximum of `limit` async operations at a + * time. + * + * @name rejectLimit + * @static + * @memberOf async + * @see async.reject + * @category Collection + * @param {Array|Object} coll - A collection to iterate over. + * @param {number} limit - The maximum number of async operations at a time. + * @param {Function} iteratee - A truth test to apply to each item in `coll`. + * The `iteratee` is passed a `callback(err, truthValue)`, which must be called + * with a boolean argument once it has completed. Invoked with (item, callback). + * @param {Function} [callback] - A callback which is called after all the + * `iteratee` functions have finished. Invoked with (err, results). + */ var rejectLimit = doParallelLimit(reject$1); + /** + * The opposite of `filter`. Removes values that pass an `async` truth test. + * + * @name reject + * @static + * @memberOf async + * @see async.filter + * @category Collection + * @param {Array|Object} coll - A collection to iterate over. + * @param {Function} iteratee - A truth test to apply to each item in `coll`. + * The `iteratee` is passed a `callback(err, truthValue)`, which must be called + * with a boolean argument once it has completed. Invoked with (item, callback). + * @param {Function} [callback] - A callback which is called after all the + * `iteratee` functions have finished. Invoked with (err, results). + * @example + * + * async.reject(['file1','file2','file3'], function(filePath, callback) { + * fs.access(filePath, function(err) { + * callback(null, !err) + * }); + * }, function(err, results) { + * // results now equals an array of missing files + * createFiles(results); + * }); + */ var reject = doLimit(rejectLimit, Infinity); + /** + * A helper function that wraps an array of functions with reflect. + * + * @name reflectAll + * @static + * @memberOf async + * @see async.reflect + * @category Util + * @param {Array} tasks - The array of functions to wrap in `async.reflect`. + * @returns {Array} Returns an array of functions, each function wrapped in + * `async.reflect` + * @example + * + * let tasks = [ + * function(callback) { + * setTimeout(function() { + * callback(null, 'one'); + * }, 200); + * }, + * function(callback) { + * // do some more stuff but error ... + * callback(new Error('bad stuff happened')); + * }, + * function(callback) { + * setTimeout(function() { + * callback(null, 'two'); + * }, 100); + * } + * ]; + * + * async.parallel(async.reflectAll(tasks), + * // optional callback + * function(err, results) { + * // values + * // results[0].value = 'one' + * // results[1].error = Error('bad stuff happened') + * // results[2].value = 'two' + * }); + */ function reflectAll(tasks) { - return tasks.map(reflect); + return tasks.map(reflect); } + /** + * The same as `reject` but runs only a single async operation at a time. + * + * @name rejectSeries + * @static + * @memberOf async + * @see async.reject + * @category Collection + * @param {Array|Object} coll - A collection to iterate over. + * @param {Function} iteratee - A truth test to apply to each item in `coll`. + * The `iteratee` is passed a `callback(err, truthValue)`, which must be called + * with a boolean argument once it has completed. Invoked with (item, callback). + * @param {Function} [callback] - A callback which is called after all the + * `iteratee` functions have finished. Invoked with (err, results). + */ var rejectSeries = doLimit(rejectLimit, 1); + /** + * Run the functions in the `tasks` collection in series, each one running once + * the previous function has completed. If any functions in the series pass an + * error to its callback, no more functions are run, and `callback` is + * immediately called with the value of the error. Otherwise, `callback` + * receives an array of results when `tasks` have completed. + * + * It is also possible to use an object instead of an array. Each property will + * be run as a function, and the results will be passed to the final `callback` + * as an object instead of an array. This can be a more readable way of handling + * results from {@link async.series}. + * + * **Note** that while many implementations preserve the order of object + * properties, the [ECMAScript Language Specification](http://www.ecma-international.org/ecma-262/5.1/#sec-8.6) + * explicitly states that + * + * > The mechanics and order of enumerating the properties is not specified. + * + * So if you rely on the order in which your series of functions are executed, + * and want this to work on all platforms, consider using an array. + * + * @name series + * @static + * @memberOf async + * @category Control Flow + * @param {Array|Object} tasks - A collection containing functions to run, each + * function is passed a `callback(err, result)` it must call on completion with + * an error `err` (which can be `null`) and an optional `result` value. + * @param {Function} [callback] - An optional callback to run once all the + * functions have completed. This function gets a results array (or object) + * containing all the result arguments passed to the `task` callbacks. Invoked + * with (err, result). + * @example + * async.series([ + * function(callback) { + * // do some stuff ... + * callback(null, 'one'); + * }, + * function(callback) { + * // do some more stuff ... + * callback(null, 'two'); + * } + * ], + * // optional callback + * function(err, results) { + * // results is now equal to ['one', 'two'] + * }); + * + * async.series({ + * one: function(callback) { + * setTimeout(function() { + * callback(null, 1); + * }, 200); + * }, + * two: function(callback){ + * setTimeout(function() { + * callback(null, 2); + * }, 100); + * } + * }, function(err, results) { + * // results is now equal to: {one: 1, two: 2} + * }); + */ function series(tasks, cb) { - return _parallel(eachOfSeries, tasks, cb); + return _parallel(eachOfSeries, tasks, cb); } + /** + * Attempts to get a successful response from `task` no more than `times` times + * before returning an error. If the task is successful, the `callback` will be + * passed the result of the successful task. If all attempts fail, the callback + * will be passed the error and result (if any) of the final attempt. + * + * @name retry + * @static + * @memberOf async + * @category Control Flow + * @param {Object|number} [opts = {times: 5, interval: 0}| 5] - Can be either an + * object with `times` and `interval` or a number. + * * `times` - The number of attempts to make before giving up. The default + * is `5`. + * * `interval` - The time to wait between retries, in milliseconds. The + * default is `0`. + * * If `opts` is a number, the number specifies the number of times to retry, + * with the default interval of `0`. + * @param {Function} task - A function which receives two arguments: (1) a + * `callback(err, result)` which must be called when finished, passing `err` + * (which can be `null`) and the `result` of the function's execution, and (2) + * a `results` object, containing the results of the previously executed + * functions (if nested inside another control flow). Invoked with + * (callback, results). + * @param {Function} [callback] - An optional callback which is called when the + * task has succeeded, or after the final failed attempt. It receives the `err` + * and `result` arguments of the last attempt at completing the `task`. Invoked + * with (err, results). + * @example + * + * // The `retry` function can be used as a stand-alone control flow by passing + * // a callback, as shown below: + * + * // try calling apiMethod 3 times + * async.retry(3, apiMethod, function(err, result) { + * // do something with the result + * }); + * + * // try calling apiMethod 3 times, waiting 200 ms between each retry + * async.retry({times: 3, interval: 200}, apiMethod, function(err, result) { + * // do something with the result + * }); + * + * // try calling apiMethod the default 5 times no delay between each retry + * async.retry(apiMethod, function(err, result) { + * // do something with the result + * }); + * + * // It can also be embedded within other control flow functions to retry + * // individual methods that are not as reliable, like this: + * async.auto({ + * users: api.getUsers.bind(api), + * payments: async.retry(3, api.getPayments.bind(api)) + * }, function(err, results) { + * // do something with the results + * }); + */ function retry(times, task, callback) { var DEFAULT_TIMES = 5; var DEFAULT_INTERVAL = 0; @@ -3769,6 +5619,29 @@ } } + /** + * A close relative of `retry`. This method wraps a task and makes it + * retryable, rather than immediately calling it with retries. + * + * @name retryable + * @static + * @memberOf async + * @see async.retry + * @category Control Flow + * @param {Object|number} [opts = {times: 5, interval: 0}| 5] - optional + * options, exactly the same as from `retry` + * @param {Function} task - the asynchronous function to wrap + * @returns {Functions} The wrapped function, which when invoked, will retry on + * an error, based on the parameters specified in `opts`. + * @example + * + * async.auto({ + * dep1: async.retryable(3, getFromFlakyService), + * process: ["dep1", async.retryable(3, function (results, cb) { + * maybeProcessData(results.dep1, cb); + * })] + * }, callback); + */ function retryable (opts, task) { if (!task) { task = opts; @@ -3783,12 +5656,125 @@ }); } + /** + * The same as `some` but runs a maximum of `limit` async operations at a time. + * + * @name someLimit + * @static + * @memberOf async + * @see async.some + * @alias anyLimit + * @category Collection + * @param {Array|Object} coll - A collection to iterate over. + * @param {number} limit - The maximum number of async operations at a time. + * @param {Function} iteratee - A truth test to apply to each item in the array + * in parallel. The iteratee is passed a `callback(err, truthValue)` which must + * be called with a boolean argument once it has completed. Invoked with + * (item, callback). + * @param {Function} [callback] - A callback which is called as soon as any + * iteratee returns `true`, or after all the iteratee functions have finished. + * Result will be either `true` or `false` depending on the values of the async + * tests. Invoked with (err, result). + */ var someLimit = _createTester(eachOfLimit, Boolean, identity); + /** + * Returns `true` if at least one element in the `coll` satisfies an async test. + * If any iteratee call returns `true`, the main `callback` is immediately + * called. + * + * @name some + * @static + * @memberOf async + * @alias any + * @category Collection + * @param {Array|Object} coll - A collection to iterate over. + * @param {Function} iteratee - A truth test to apply to each item in the array + * in parallel. The iteratee is passed a `callback(err, truthValue)` which must + * be called with a boolean argument once it has completed. Invoked with + * (item, callback). + * @param {Function} [callback] - A callback which is called as soon as any + * iteratee returns `true`, or after all the iteratee functions have finished. + * Result will be either `true` or `false` depending on the values of the async + * tests. Invoked with (err, result). + * @example + * + * async.some(['file1','file2','file3'], function(filePath, callback) { + * fs.access(filePath, function(err) { + * callback(null, !err) + * }); + * }, function(err, result) { + * // if result is true then at least one of the files exists + * }); + */ var some = doLimit(someLimit, Infinity); + /** + * The same as `some` but runs only a single async operation at a time. + * + * @name someSeries + * @static + * @memberOf async + * @see async.some + * @alias anySeries + * @category Collection + * @param {Array|Object} coll - A collection to iterate over. + * @param {Function} iteratee - A truth test to apply to each item in the array + * in parallel. The iteratee is passed a `callback(err, truthValue)` which must + * be called with a boolean argument once it has completed. Invoked with + * (item, callback). + * @param {Function} [callback] - A callback which is called as soon as any + * iteratee returns `true`, or after all the iteratee functions have finished. + * Result will be either `true` or `false` depending on the values of the async + * tests. Invoked with (err, result). + */ var someSeries = doLimit(someLimit, 1); + /** + * Sorts a list by the results of running each `coll` value through an async + * `iteratee`. + * + * @name sortBy + * @static + * @memberOf async + * @category Collection + * @param {Array|Object} coll - A collection to iterate over. + * @param {Function} iteratee - A function to apply to each item in `coll`. + * The iteratee is passed a `callback(err, sortValue)` which must be called once + * it has completed with an error (which can be `null`) and a value to use as + * the sort criteria. Invoked with (item, callback). + * @param {Function} [callback] - A callback which is called after all the + * `iteratee` functions have finished, or an error occurs. Results is the items + * from the original `coll` sorted by the values returned by the `iteratee` + * calls. Invoked with (err, results). + * @example + * + * async.sortBy(['file1','file2','file3'], function(file, callback) { + * fs.stat(file, function(err, stats) { + * callback(err, stats.mtime); + * }); + * }, function(err, results) { + * // results is now the original array of files sorted by + * // modified date + * }); + * + * // By modifying the callback parameter the + * // sorting order can be influenced: + * + * // ascending order + * async.sortBy([1,9,3,5], function(x, callback) { + * callback(null, x); + * }, function(err,result) { + * // result callback + * }); + * + * // descending order + * async.sortBy([1,9,3,5], function(x, callback) { + * callback(null, x*-1); //<- x*-1 instead of x, turns the order around + * }, function(err,result) { + * // result callback + * }); + */ function sortBy(arr, iteratee, cb) { map(arr, function (x, cb) { iteratee(x, function (err, criteria) { @@ -3807,6 +5793,28 @@ } } + /** + * Sets a time limit on an asynchronous function. If the function does not call + * its callback within the specified miliseconds, it will be called with a + * timeout error. The code property for the error object will be `'ETIMEDOUT'`. + * + * @name timeout + * @static + * @memberOf async + * @category Util + * @param {Function} function - The asynchronous function you want to set the + * time limit. + * @param {number} miliseconds - The specified time limit. + * @param {*} [info] - Any variable you want attached (`string`, `object`, etc) + * to timeout Error for more information.. + * @returns {Function} Returns a wrapped function that can be used with any of + * the control flow functions. + * @example + * + * async.timeout(function(callback) { + * doAsyncTask(callback); + * }, 1000); + */ function timeout(asyncFn, miliseconds, info) { var originalCallback, timer; var timedOut = false; @@ -3863,40 +5871,232 @@ return result; } + /** + * The same as {@link times} but runs a maximum of `limit` async operations at a + * time. + * + * @name timesLimit + * @static + * @memberOf async + * @see async.times + * @category Control Flow + * @param {number} n - The number of times to run the function. + * @param {number} limit - The maximum number of async operations at a time. + * @param {Function} iteratee - The function to call `n` times. Invoked with the + * iteration index and a callback (n, next). + * @param {Function} callback - see {@link async.map}. + */ function timeLimit(count, limit, iteratee, cb) { - return mapLimit(baseRange(0, count, 1), limit, iteratee, cb); + return mapLimit(baseRange(0, count, 1), limit, iteratee, cb); } + /** + * Calls the `iteratee` function `n` times, and accumulates results in the same + * manner you would use with {@link async.map}. + * + * @name times + * @static + * @memberOf async + * @see async.map + * @category Control Flow + * @param {number} n - The number of times to run the function. + * @param {Function} iteratee - The function to call `n` times. Invoked with the + * iteration index and a callback (n, next). + * @param {Function} callback - see {@link async.map}. + * @example + * + * // Pretend this is some complicated async factory + * var createUser = function(id, callback) { + * callback(null, { + * id: 'user' + id + * }); + * }; + * + * // generate 5 users + * async.times(5, function(n, next) { + * createUser(n, function(err, user) { + * next(err, user); + * }); + * }, function(err, users) { + * // we should now have 5 users + * }); + */ var times = doLimit(timeLimit, Infinity); + /** + * The same as {@link async.times} but runs only a single async operation at a time. + * + * @name timesSeries + * @static + * @memberOf async + * @see async.times + * @category Control Flow + * @param {number} n - The number of times to run the function. + * @param {Function} iteratee - The function to call `n` times. Invoked with the + * iteration index and a callback (n, next). + * @param {Function} callback - see {@link async.map}. + */ var timesSeries = doLimit(timeLimit, 1); - function transform(arr, memo, iteratee, callback) { + /** + * A relative of `reduce`. Takes an Object or Array, and iterates over each + * element in series, each step potentially mutating an `accumulator` value. + * The type of the accumulator defaults to the type of collection passed in. + * + * @name transform + * @static + * @memberOf async + * @category Collection + * @param {Array|Object} coll - A collection to iterate over. + * @param {*} [accumulator] - The initial state of the transform. If omitted, + * it will default to an empty Object or Array, depending on the type of `coll` + * @param {Function} iteratee - A function applied to each item in the + * collection that potentially modifies the accumulator. The `iteratee` is + * passed a `callback(err)` which accepts an optional error as its first + * argument. If an error is passed to the callback, the transform is stopped + * and the main `callback` is immediately called with the error. + * Invoked with (accumulator, item, key, callback). + * @param {Function} [callback] - A callback which is called after all the + * `iteratee` functions have finished. Result is the transformed accumulator. + * Invoked with (err, result). + * @example + * + * async.transform([1,2,3], function(acc, item, index, callback) { + * // pointless async: + * process.nextTick(function() { + * acc.push(item * 2) + * callback(null) + * }); + * }, function(err, result) { + * // result is now equal to [2, 4, 6] + * }); + * + * @example + * + * async.transform({a: 1, b: 2, c: 3}, function (obj, val, key, callback) { + * setImmediate(function () { + * obj[key] = val * 2; + * callback(); + * }) + * }, function (err, result) { + * // result is equal to {a: 2, b: 4, c: 6} + * }) + */ + function transform(arr, acc, iteratee, callback) { if (arguments.length === 3) { callback = iteratee; - iteratee = memo; - memo = isArray(arr) ? [] : {}; + iteratee = acc; + acc = isArray(arr) ? [] : {}; } eachOf(arr, function (v, k, cb) { - iteratee(memo, v, k, cb); + iteratee(acc, v, k, cb); }, function (err) { - callback(err, memo); + callback(err, acc); }); } + /** + * Undoes a {@link async.memoize}d function, reverting it to the original, + * unmemoized form. Handy for testing. + * + * @name unmemoize + * @static + * @memberOf async + * @see async.memoize + * @category Util + * @param {Function} fn - the memoized function + */ + function unmemoize(fn) { return function () { return (fn.unmemoized || fn).apply(null, arguments); }; } + /** + * Repeatedly call `fn` until `test` returns `true`. Calls `callback` when + * stopped, or an error occurs. `callback` will be passed an error and any + * arguments passed to the final `fn`'s callback. + * + * The inverse of {@link async.whilst}. + * + * @name until + * @static + * @memberOf async + * @see async.whilst + * @category Control Flow + * @param {Function} test - synchronous truth test to perform before each + * execution of `fn`. Invoked with (). + * @param {Function} fn - A function which is called each time `test` fails. + * The function is passed a `callback(err)`, which must be called once it has + * completed with an optional `err` argument. Invoked with (callback). + * @param {Function} [callback] - A callback which is called after the test + * function has passed and repeated execution of `fn` has stopped. `callback` + * will be passed an error and any arguments passed to the final `fn`'s + * callback. Invoked with (err, [results]); + */ function until(test, iteratee, cb) { return whilst(function () { return !test.apply(this, arguments); }, iteratee, cb); } + /** + * Runs the `tasks` array of functions in series, each passing their results to + * the next in the array. However, if any of the `tasks` pass an error to their + * own callback, the next function is not executed, and the main `callback` is + * immediately called with the error. + * + * @name waterfall + * @static + * @memberOf async + * @category Control Flow + * @param {Array} tasks - An array of functions to run, each function is passed + * a `callback(err, result1, result2, ...)` it must call on completion. The + * first argument is an error (which can be `null`) and any further arguments + * will be passed as arguments in order to the next task. + * @param {Function} [callback] - An optional callback to run once all the + * functions have completed. This will be passed the results of the last task's + * callback. Invoked with (err, [results]). + * @example + * + * async.waterfall([ + * function(callback) { + * callback(null, 'one', 'two'); + * }, + * function(arg1, arg2, callback) { + * // arg1 now equals 'one' and arg2 now equals 'two' + * callback(null, 'three'); + * }, + * function(arg1, callback) { + * // arg1 now equals 'three' + * callback(null, 'done'); + * } + * ], function (err, result) { + * // result now equals 'done' + * }); + * + * // Or, with named functions: + * async.waterfall([ + * myFirstFunction, + * mySecondFunction, + * myLastFunction, + * ], function (err, result) { + * // result now equals 'done' + * }); + * function myFirstFunction(callback) { + * callback(null, 'one', 'two'); + * } + * function mySecondFunction(arg1, arg2, callback) { + * // arg1 now equals 'one' and arg2 now equals 'two' + * callback(null, 'three'); + * } + * function myLastFunction(arg1, callback) { + * // arg1 now equals 'three' + * callback(null, 'done'); + * } + */ function waterfall (tasks, cb) { cb = once(cb || noop); if (!isArray(tasks)) return cb(new Error('First argument to waterfall must be an array of functions')); |