diff options
author | Hubert Argasinski <argasinski.hubert@gmail.com> | 2016-03-29 04:09:31 -0700 |
---|---|---|
committer | Graeme Yeates <yeatesgraeme@gmail.com> | 2016-04-12 18:46:24 -0400 |
commit | 982674c1ac82865c0dbf31ae2ec611ec1cdcd21a (patch) | |
tree | 5424e3dd0884523097218d09bbde36bdf5446cad /lib | |
parent | b40ece78ac5195cd010960ace46833a48d84d3db (diff) | |
download | async-982674c1ac82865c0dbf31ae2ec611ec1cdcd21a.tar.gz |
jsdoc-style documentation for 'collection' methods
Converted documentation from README to jsdoc-style for respective
methods. Currently, only done for 'collection' methods.
jsdoc-style documentation - fixed 'collection' methods documentation
Only the base functions now contain an example, while the `series` and
`limit` versions simply contain a reference to the base function. Fixed
styling issue and misspelled tag.
Diffstat (limited to 'lib')
-rw-r--r-- | lib/concat.js | 26 | ||||
-rw-r--r-- | lib/concatSeries.js | 18 | ||||
-rw-r--r-- | lib/detect.js | 34 | ||||
-rw-r--r-- | lib/detectLimit.js | 21 | ||||
-rw-r--r-- | lib/detectSeries.js | 19 | ||||
-rw-r--r-- | lib/each.js | 58 | ||||
-rw-r--r-- | lib/eachLimit.js | 21 | ||||
-rw-r--r-- | lib/eachOf.js | 39 | ||||
-rw-r--r-- | lib/eachOfLimit.js | 21 | ||||
-rw-r--r-- | lib/eachOfSeries.js | 18 | ||||
-rw-r--r-- | lib/eachSeries.js | 19 | ||||
-rw-r--r-- | lib/every.js | 27 | ||||
-rw-r--r-- | lib/everyLimit.js | 19 | ||||
-rw-r--r-- | lib/everySeries.js | 18 | ||||
-rw-r--r-- | lib/filter.js | 26 | ||||
-rw-r--r-- | lib/filterLimit.js | 18 | ||||
-rw-r--r-- | lib/filterSeries.js | 16 | ||||
-rw-r--r-- | lib/map.js | 31 | ||||
-rw-r--r-- | lib/mapLimit.js | 18 | ||||
-rw-r--r-- | lib/mapSeries.js | 17 | ||||
-rw-r--r-- | lib/reduce.js | 38 | ||||
-rw-r--r-- | lib/reduceRight.js | 21 | ||||
-rw-r--r-- | lib/reject.js | 25 | ||||
-rw-r--r-- | lib/rejectLimit.js | 17 | ||||
-rw-r--r-- | lib/rejectSeries.js | 15 | ||||
-rw-r--r-- | lib/some.js | 29 | ||||
-rw-r--r-- | lib/someLimit.js | 20 | ||||
-rw-r--r-- | lib/someSeries.js | 19 | ||||
-rw-r--r-- | lib/sortBy.js | 45 |
29 files changed, 712 insertions, 1 deletions
diff --git a/lib/concat.js b/lib/concat.js index af019a3..176cb97 100644 --- a/lib/concat.js +++ b/lib/concat.js @@ -3,4 +3,30 @@ import concat from './internal/concat'; import doParallel from './internal/doParallel'; +/** + * 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 + * }); + */ export default doParallel(concat); diff --git a/lib/concatSeries.js b/lib/concatSeries.js index 76f4043..73312dc 100644 --- a/lib/concatSeries.js +++ b/lib/concatSeries.js @@ -3,4 +3,22 @@ import concat from './internal/concat'; import doSeries from './internal/doSeries'; +/** + * 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). + */ export default doSeries(concat); diff --git a/lib/detect.js b/lib/detect.js index b2c4778..0b06374 100644 --- a/lib/detect.js +++ b/lib/detect.js @@ -6,4 +6,38 @@ import createTester from './internal/createTester'; import eachOf from './eachOf'; import findGetResult from './internal/findGetResult'; +/** + * 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 + * }); + */ export default createTester(eachOf, identity, findGetResult); diff --git a/lib/detectLimit.js b/lib/detectLimit.js index 357786d..20c8040 100644 --- a/lib/detectLimit.js +++ b/lib/detectLimit.js @@ -6,4 +6,25 @@ import createTester from './internal/createTester'; import eachOfLimit from './eachOfLimit'; import findGetResult from './internal/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). + */ export default createTester(eachOfLimit, identity, findGetResult); diff --git a/lib/detectSeries.js b/lib/detectSeries.js index 325a500..659d820 100644 --- a/lib/detectSeries.js +++ b/lib/detectSeries.js @@ -6,4 +6,23 @@ import createTester from './internal/createTester'; import eachOfSeries from './eachOfSeries'; import findGetResult from './internal/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). + */ export default createTester(eachOfSeries, identity, findGetResult); diff --git a/lib/each.js b/lib/each.js index d81763a..f2c9929 100644 --- a/lib/each.js +++ b/lib/each.js @@ -3,4 +3,62 @@ import eachLimit from './eachLimit'; import doLimit from './internal/doLimit'; +/** + * 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'); + * } + * }); + */ export default doLimit(eachLimit, Infinity); diff --git a/lib/eachLimit.js b/lib/eachLimit.js index 74965a8..415e6e8 100644 --- a/lib/eachLimit.js +++ b/lib/eachLimit.js @@ -3,7 +3,26 @@ import eachOfLimit from './internal/eachOfLimit'; import withoutIndex from './internal/withoutIndex'; - +/** + * 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). + */ export default function eachLimit(arr, limit, iteratee, cb) { return eachOfLimit(limit)(arr, withoutIndex(iteratee), cb); } diff --git a/lib/eachOf.js b/lib/eachOf.js index d16e1b3..5bb82e4 100644 --- a/lib/eachOf.js +++ b/lib/eachOf.js @@ -3,4 +3,43 @@ import eachOfLimit from './eachOfLimit'; import doLimit from './internal/doLimit'; +/** + * 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); + * }); + */ export default doLimit(eachOfLimit, Infinity); diff --git a/lib/eachOfLimit.js b/lib/eachOfLimit.js index b6ca139..753dbc0 100644 --- a/lib/eachOfLimit.js +++ b/lib/eachOfLimit.js @@ -2,6 +2,27 @@ import _eachOfLimit from './internal/eachOfLimit'; +/** + * 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). + */ export default function eachOfLimit(obj, limit, iteratee, cb) { _eachOfLimit(limit)(obj, iteratee, cb); } diff --git a/lib/eachOfSeries.js b/lib/eachOfSeries.js index 47787bb..0718805 100644 --- a/lib/eachOfSeries.js +++ b/lib/eachOfSeries.js @@ -3,4 +3,22 @@ import eachOfLimit from './eachOfLimit'; import doLimit from './internal/doLimit'; +/** + * 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). + */ export default doLimit(eachOfLimit, 1); diff --git a/lib/eachSeries.js b/lib/eachSeries.js index 39dc81f..470c34c 100644 --- a/lib/eachSeries.js +++ b/lib/eachSeries.js @@ -3,4 +3,23 @@ import eachLimit from './eachLimit'; import doLimit from './internal/doLimit'; +/** + * 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). + */ export default doLimit(eachLimit, 1); diff --git a/lib/every.js b/lib/every.js index b2d2abd..df28b00 100644 --- a/lib/every.js +++ b/lib/every.js @@ -3,4 +3,31 @@ import everyLimit from './everyLimit'; import doLimit from './internal/doLimit'; +/** + * 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 + * }); + */ export default doLimit(everyLimit, Infinity); diff --git a/lib/everyLimit.js b/lib/everyLimit.js index 4b3fc5f..1c3511c 100644 --- a/lib/everyLimit.js +++ b/lib/everyLimit.js @@ -4,4 +4,23 @@ import createTester from './internal/createTester'; import eachOfLimit from './eachOfLimit'; import notId from './internal/notId'; +/** + * The same as `every` but runs a maximum of `limit` async operations at a time. + * + * @name everyLimit + * @static + * @memberOf async + * @see 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). + */ export default createTester(eachOfLimit, notId, notId); diff --git a/lib/everySeries.js b/lib/everySeries.js index 0b3db2c..aca6cec 100644 --- a/lib/everySeries.js +++ b/lib/everySeries.js @@ -3,4 +3,22 @@ import everyLimit from './everyLimit'; import doLimit from './internal/doLimit'; +/** + * 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). + */ export default doLimit(everyLimit, 1); diff --git a/lib/filter.js b/lib/filter.js index f3813d4..f350938 100644 --- a/lib/filter.js +++ b/lib/filter.js @@ -3,4 +3,30 @@ import filterLimit from './filterLimit'; import doLimit from './internal/doLimit'; +/** + * 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 + * }); + */ export default doLimit(filterLimit, Infinity); diff --git a/lib/filterLimit.js b/lib/filterLimit.js index 8fe237f..414ea4d 100644 --- a/lib/filterLimit.js +++ b/lib/filterLimit.js @@ -3,4 +3,22 @@ import filter from './internal/filter'; import doParallelLimit from './internal/doParallelLimit'; +/** + * 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). + */ export default doParallelLimit(filter); diff --git a/lib/filterSeries.js b/lib/filterSeries.js index d3995c9..97c3907 100644 --- a/lib/filterSeries.js +++ b/lib/filterSeries.js @@ -3,4 +3,20 @@ import filterLimit from './filterLimit'; import doLimit from './internal/doLimit'; +/** + * 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) + */ export default doLimit(filterLimit, 1); @@ -3,4 +3,35 @@ import mapLimit from './mapLimit'; import doLimit from './internal/doLimit'; +/** + * 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 + * }); + */ export default doLimit(mapLimit, Infinity); diff --git a/lib/mapLimit.js b/lib/mapLimit.js index 642b4c6..916b206 100644 --- a/lib/mapLimit.js +++ b/lib/mapLimit.js @@ -3,4 +3,22 @@ import doParallelLimit from './internal/doParallelLimit'; import map from './internal/map'; +/** + * 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). + */ export default doParallelLimit(map); diff --git a/lib/mapSeries.js b/lib/mapSeries.js index 9a6bd11..efa2818 100644 --- a/lib/mapSeries.js +++ b/lib/mapSeries.js @@ -3,4 +3,21 @@ import mapLimit from './mapLimit'; import doLimit from './internal/doLimit'; +/** + * 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). + */ export default doLimit(mapLimit, 1); diff --git a/lib/reduce.js b/lib/reduce.js index 675ed8f..2aa516b 100644 --- a/lib/reduce.js +++ b/lib/reduce.js @@ -2,6 +2,44 @@ import eachOfSeries from './eachOfSeries'; +/** + * 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 + * }); + */ export default function reduce(arr, memo, iteratee, cb) { eachOfSeries(arr, function(x, i, cb) { iteratee(memo, x, function(err, v) { diff --git a/lib/reduceRight.js b/lib/reduceRight.js index f79f18f..033b9da 100644 --- a/lib/reduceRight.js +++ b/lib/reduceRight.js @@ -4,6 +4,27 @@ import reduce from './reduce'; 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). + */ export default function reduceRight (arr, memo, iteratee, cb) { var reversed = slice.call(arr).reverse(); reduce(reversed, memo, iteratee, cb); diff --git a/lib/reject.js b/lib/reject.js index 970a0ec..f7f6f10 100644 --- a/lib/reject.js +++ b/lib/reject.js @@ -3,4 +3,29 @@ import rejectLimit from './rejectLimit'; import doLimit from './internal/doLimit'; +/** + * 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); + * }); + */ export default doLimit(rejectLimit, Infinity); diff --git a/lib/rejectLimit.js b/lib/rejectLimit.js index 7cefed6..9b3fbd3 100644 --- a/lib/rejectLimit.js +++ b/lib/rejectLimit.js @@ -3,4 +3,21 @@ import reject from './internal/reject'; import doParallelLimit from './internal/doParallelLimit'; +/** + * 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). + */ export default doParallelLimit(reject); diff --git a/lib/rejectSeries.js b/lib/rejectSeries.js index 00c145f..1732eca 100644 --- a/lib/rejectSeries.js +++ b/lib/rejectSeries.js @@ -3,4 +3,19 @@ import rejectLimit from './rejectLimit'; import doLimit from './internal/doLimit'; +/** + * 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). + */ export default doLimit(rejectLimit, 1); diff --git a/lib/some.js b/lib/some.js index 000f2e2..ccae178 100644 --- a/lib/some.js +++ b/lib/some.js @@ -3,4 +3,33 @@ import someLimit from './someLimit'; import doLimit from './internal/doLimit'; +/** + * 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 + * }); + */ export default doLimit(someLimit, Infinity); diff --git a/lib/someLimit.js b/lib/someLimit.js index 498a262..521c116 100644 --- a/lib/someLimit.js +++ b/lib/someLimit.js @@ -4,4 +4,24 @@ import createTester from './internal/createTester'; import eachOfLimit from './eachOfLimit'; import identity from 'lodash/identity'; +/** + * 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). + */ export default createTester(eachOfLimit, Boolean, identity); diff --git a/lib/someSeries.js b/lib/someSeries.js index a5fc97c..41ca733 100644 --- a/lib/someSeries.js +++ b/lib/someSeries.js @@ -3,4 +3,23 @@ import someLimit from './someLimit'; import doLimit from './internal/doLimit'; +/** + * 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). + */ export default doLimit(someLimit, 1); diff --git a/lib/sortBy.js b/lib/sortBy.js index 8b78221..3e98bf0 100644 --- a/lib/sortBy.js +++ b/lib/sortBy.js @@ -5,6 +5,51 @@ import property from 'lodash/_baseProperty'; import map from './map'; +/** + * 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 + * }); + */ export default function sortBy (arr, iteratee, cb) { map(arr, function (x, cb) { iteratee(x, function (err, criteria) { |