From 94a8b2d18bf10cca67cf4c308253f642bbb2b160 Mon Sep 17 00:00:00 2001 From: Alexander Early Date: Sat, 1 Apr 2017 15:05:52 -0700 Subject: [PATCH] use the AsyncFunction type in all docs :sweat: --- lib/applyEach.js | 2 +- lib/applyEachSeries.js | 2 +- lib/asyncify.js | 8 ++++---- lib/auto.js | 8 ++++---- lib/autoInject.js | 2 +- lib/cargo.js | 5 ++--- lib/compose.js | 2 +- lib/concat.js | 6 ++---- lib/concatSeries.js | 5 ++--- lib/constant.js | 2 +- lib/detect.js | 6 +++--- lib/detectLimit.js | 6 +++--- lib/detectSeries.js | 6 +++--- lib/dir.js | 13 +++++++------ lib/doDuring.js | 7 +++---- lib/doUntil.js | 16 ++++++++-------- lib/doWhilst.js | 7 +++---- lib/during.js | 7 +++---- lib/eachLimit.js | 11 +++++------ lib/eachOf.js | 10 ++++------ lib/eachOfLimit.js | 8 +++----- lib/eachOfSeries.js | 8 +++----- lib/eachSeries.js | 11 +++++------ lib/ensureAsync.js | 7 ++++--- lib/every.js | 8 ++++---- lib/everyLimit.js | 8 ++++---- lib/everySeries.js | 8 ++++---- lib/forever.js | 8 ++++---- lib/groupBy.js | 8 ++++---- lib/groupByLimit.js | 8 ++++---- lib/groupBySeries.js | 8 ++++---- lib/index.js | 12 ++++++++---- lib/log.js | 4 ++-- lib/map.js | 8 ++++---- lib/mapLimit.js | 8 ++++---- lib/mapSeries.js | 8 ++++---- lib/mapValues.js | 8 ++++---- lib/mapValuesLimit.js | 8 ++++---- lib/mapValuesSeries.js | 8 ++++---- lib/memoize.js | 6 +++--- lib/parallel.js | 9 +++++---- lib/parallelLimit.js | 7 +++---- lib/priorityQueue.js | 9 ++++----- lib/queue.js | 8 +++----- lib/race.js | 5 ++--- lib/reduce.js | 12 ++++++------ lib/reduceRight.js | 12 ++++++------ lib/reflect.js | 8 ++++---- lib/reflectAll.js | 7 ++++--- lib/reject.js | 7 ++++--- lib/rejectLimit.js | 7 ++++--- lib/rejectSeries.js | 7 ++++--- lib/retry.js | 12 +++++------- lib/retryable.js | 14 +++++++++----- lib/seq.js | 2 +- lib/series.js | 6 +++--- lib/someLimit.js | 8 ++++---- lib/someSeries.js | 8 ++++---- lib/sortBy.js | 9 +++++---- lib/timeout.js | 9 ++++----- lib/times.js | 4 ++-- lib/timesLimit.js | 4 ++-- lib/timesSeries.js | 4 ++-- lib/transform.js | 7 ++----- lib/unmemoize.js | 4 ++-- lib/whilst.js | 5 ++--- 66 files changed, 237 insertions(+), 248 deletions(-) diff --git a/lib/applyEach.js b/lib/applyEach.js index d1dfc7889..93d8af3cd 100644 --- a/lib/applyEach.js +++ b/lib/applyEach.js @@ -13,7 +13,7 @@ import map from './map'; * @memberOf module:ControlFlow * @method * @category Control Flow - * @param {Array|Iterable|Object} fns - A collection of asynchronous functions + * @param {Array|Iterable|Object} fns - A collection of {@link AsyncFunction}s * to all call with the same arguments * @param {...*} [args] - any number of separate arguments to pass to the * function. diff --git a/lib/applyEachSeries.js b/lib/applyEachSeries.js index 5a7c257bf..392b1396e 100644 --- a/lib/applyEachSeries.js +++ b/lib/applyEachSeries.js @@ -10,7 +10,7 @@ import mapSeries from './mapSeries'; * @method * @see [async.applyEach]{@link module:ControlFlow.applyEach} * @category Control Flow - * @param {Array|Iterable|Object} fns - A collection of asynchronous functions to all + * @param {Array|Iterable|Object} fns - A collection of {@link AsyncFunction}s to all * call with the same arguments * @param {...*} [args] - any number of separate arguments to pass to the * function. diff --git a/lib/asyncify.js b/lib/asyncify.js index 1f0955e5f..96eea543b 100644 --- a/lib/asyncify.js +++ b/lib/asyncify.js @@ -20,10 +20,10 @@ import initialParams from './internal/initialParams'; * @method * @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). + * @param {Function} func - The synchronous funuction, or Promise-returning + * function to convert to an {@link AsyncFunction}. + * @returns {AsyncFunction} An asynchronous wrapper of the `func`. To be + * invoked with `(args..., callback)`. * @example * * // passing a regular synchronous function diff --git a/lib/auto.js b/lib/auto.js index 4d7bf32d3..ba0fdc337 100644 --- a/lib/auto.js +++ b/lib/auto.js @@ -11,17 +11,17 @@ import onlyOnce from './internal/onlyOnce'; import wrapAsync from './internal/wrapAsync'; /** - * Determines the best order for running the functions in `tasks`, based on + * Determines the best order for running the {@link AsyncFunction}s 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 + * If any of the {@link AsyncFunction}s 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 + * {@link AsyncFunction}s 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. * @@ -31,7 +31,7 @@ import wrapAsync from './internal/wrapAsync'; * @method * @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 + * function or an array of requirements, with the {@link AsyncFunction} 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: diff --git a/lib/autoInject.js b/lib/autoInject.js index 3ba87fcc5..bc8ddd6ef 100644 --- a/lib/autoInject.js +++ b/lib/autoInject.js @@ -40,7 +40,7 @@ function parseParams(func) { * @method * @see [async.auto]{@link module:ControlFlow.auto} * @category Control Flow - * @param {Object} tasks - An object, each of whose properties is a function of + * @param {Object} tasks - An object, each of whose properties is an {@link AsyncFunction} 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. diff --git a/lib/cargo.js b/lib/cargo.js index d86cb67b6..5060223fa 100644 --- a/lib/cargo.js +++ b/lib/cargo.js @@ -48,9 +48,8 @@ import queue from './internal/queue'; * @method * @see [async.queue]{@link module:ControlFlow.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 {AsyncFunction} worker - An asynchronous function for processing an array + * of queued tasks. 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. diff --git a/lib/compose.js b/lib/compose.js index 5c64593f6..96632c05b 100644 --- a/lib/compose.js +++ b/lib/compose.js @@ -14,7 +14,7 @@ import rest from './internal/rest'; * @memberOf module:ControlFlow * @method * @category Control Flow - * @param {...Function} functions - the asynchronous functions to compose + * @param {...AsyncFunction} functions - the asynchronous functions to compose * @returns {Function} an asynchronous function that is the composed * asynchronous `functions` * @example diff --git a/lib/concat.js b/lib/concat.js index ba4ea1314..7edf75937 100644 --- a/lib/concat.js +++ b/lib/concat.js @@ -14,10 +14,8 @@ import doParallel from './internal/doParallel'; * @method * @category Collection * @param {Array|Iterable|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 {AsyncFunction} iteratee - A function to apply to each item in `coll`, + * which should use an array as its result. 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 diff --git a/lib/concatSeries.js b/lib/concatSeries.js index 77b439bc8..f5b3fab9c 100644 --- a/lib/concatSeries.js +++ b/lib/concatSeries.js @@ -11,9 +11,8 @@ import doSeries from './internal/doSeries'; * @see [async.concat]{@link module:Collections.concat} * @category Collection * @param {Array|Iterable|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. + * @param {AsyncFunction} iteratee - A function to apply to each item in `coll`. + * The iteratee should complete with an array 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 diff --git a/lib/constant.js b/lib/constant.js index c9c0c1e72..ae6ffd099 100644 --- a/lib/constant.js +++ b/lib/constant.js @@ -13,7 +13,7 @@ import initialParams from './internal/initialParams'; * @category Util * @param {...*} arguments... - Any number of arguments to automatically invoke * callback with. - * @returns {Function} Returns a function that when invoked, automatically + * @returns {AsyncFunction} Returns a function that when invoked, automatically * invokes the callback with the previous given arguments. * @example * diff --git a/lib/detect.js b/lib/detect.js index 5f5a7ef9f..654a370fa 100644 --- a/lib/detect.js +++ b/lib/detect.js @@ -21,9 +21,9 @@ import findGetResult from './internal/findGetResult'; * @alias find * @category Collections * @param {Array|Iterable|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 {AsyncFunction} iteratee - A truth test to apply to each item in `coll`. + * The iteratee must complete with a boolean value as its result. + * 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 diff --git a/lib/detectLimit.js b/lib/detectLimit.js index d0f2a92af..bba10c839 100644 --- a/lib/detectLimit.js +++ b/lib/detectLimit.js @@ -17,9 +17,9 @@ import findGetResult from './internal/findGetResult'; * @category Collections * @param {Array|Iterable|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 {AsyncFunction} iteratee - A truth test to apply to each item in `coll`. + * The iteratee must complete with a boolean value as its result. + * 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 diff --git a/lib/detectSeries.js b/lib/detectSeries.js index 51413df39..684bdaaab 100644 --- a/lib/detectSeries.js +++ b/lib/detectSeries.js @@ -12,9 +12,9 @@ import doLimit from './internal/doLimit'; * @alias findSeries * @category Collections * @param {Array|Iterable|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 {AsyncFunction} iteratee - A truth test to apply to each item in `coll`. + * The iteratee must complete with a boolean value as its result. + * 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 diff --git a/lib/dir.js b/lib/dir.js index 912b558ae..8a5b5e3ee 100644 --- a/lib/dir.js +++ b/lib/dir.js @@ -1,10 +1,11 @@ import consoleFunc from './internal/consoleFunc'; /** - * 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, + * Logs the result of an [`async` function]{@link AsyncFunction} 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 dir @@ -12,8 +13,8 @@ import consoleFunc from './internal/consoleFunc'; * @memberOf module:Utils * @method * @category Util - * @param {Function} function - The function you want to eventually apply all - * arguments to. + * @param {AsyncFunction} function - The function you want to eventually apply + * all arguments to. * @param {...*} arguments... - Any number of arguments to apply to the function. * @example * diff --git a/lib/doDuring.js b/lib/doDuring.js index e79574b55..7b52c22c2 100644 --- a/lib/doDuring.js +++ b/lib/doDuring.js @@ -14,10 +14,9 @@ import wrapAsync from './internal/wrapAsync'; * @method * @see [async.during]{@link module:ControlFlow.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 + * @param {AsyncFunction} fn - An async function which is called each time + * `test` passes. Invoked with (callback). + * @param {AsyncFunction} test - asynchronous truth test to perform before each * execution of `fn`. Invoked with (...args, callback), where `...args` are the * non-error args from the previous callback of `fn`. * @param {Function} [callback] - A callback which is called after the test diff --git a/lib/doUntil.js b/lib/doUntil.js index 0c5bb7194..06d3af77f 100644 --- a/lib/doUntil.js +++ b/lib/doUntil.js @@ -10,18 +10,18 @@ import doWhilst from './doWhilst'; * @method * @see [async.doWhilst]{@link module:ControlFlow.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 {AsyncFunction} iteratee - An async function which is called each time + * `test` fails. Invoked with (callback). * @param {Function} test - synchronous truth test to perform after each - * execution of `fn`. Invoked with the non-error callback results of `fn`. + * execution of `iteratee`. Invoked with any non-error callback results of + * `iteratee`. * @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 + * function has passed and repeated execution of `iteratee` has stopped. `callback` + * will be passed an error and any arguments passed to the final `iteratee`'s * callback. Invoked with (err, [results]); */ -export default function doUntil(fn, test, callback) { - doWhilst(fn, function() { +export default function doUntil(iteratee, test, callback) { + doWhilst(iteratee, function() { return !test.apply(this, arguments); }, callback); } diff --git a/lib/doWhilst.js b/lib/doWhilst.js index 39f460008..4407305f6 100644 --- a/lib/doWhilst.js +++ b/lib/doWhilst.js @@ -16,11 +16,10 @@ import wrapAsync from './internal/wrapAsync'; * @method * @see [async.whilst]{@link module:ControlFlow.whilst} * @category Control Flow - * @param {Function} iteratee - 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 {AsyncFunction} iteratee - A function which is called each time `test` + * passes. Invoked with (callback). * @param {Function} test - synchronous truth test to perform after each - * execution of `iteratee`. Invoked with the non-error callback results of + * execution of `iteratee`. Invoked with any non-error callback results of * `iteratee`. * @param {Function} [callback] - A callback which is called after the test * function has failed and repeated execution of `iteratee` has stopped. diff --git a/lib/during.js b/lib/during.js index dd9ba997a..2f91dd5a8 100644 --- a/lib/during.js +++ b/lib/during.js @@ -14,11 +14,10 @@ import wrapAsync from './internal/wrapAsync'; * @method * @see [async.whilst]{@link module:ControlFlow.whilst} * @category Control Flow - * @param {Function} test - asynchronous truth test to perform before each + * @param {AsyncFunction} 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 {AsyncFunction} fn - An async function which is called each time + * `test` passes. 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, if one occured, otherwise `null`. diff --git a/lib/eachLimit.js b/lib/eachLimit.js index c3bc595d0..462e329ee 100644 --- a/lib/eachLimit.js +++ b/lib/eachLimit.js @@ -14,12 +14,11 @@ import wrapAsync from './internal/wrapAsync'; * @category Collection * @param {Array|Iterable|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)` 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 {AsyncFunction} iteratee - An async function to apply to each item in + * `coll`. + * The array index is not passed to the iteratee. + * If you need the index, use `eachOfLimit`. + * Invoked with (item, callback). * @param {Function} [callback] - A callback which is called when all * `iteratee` functions have finished, or an error occurs. Invoked with (err). */ diff --git a/lib/eachOf.js b/lib/eachOf.js index 1cfa171dc..9ab3eb6d5 100644 --- a/lib/eachOf.js +++ b/lib/eachOf.js @@ -46,12 +46,10 @@ var eachOfGeneric = doLimit(eachOfLimit, Infinity); * @category Collection * @see [async.each]{@link module:Collections.each} * @param {Array|Iterable|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 {AsyncFunction} 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. + * 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 diff --git a/lib/eachOfLimit.js b/lib/eachOfLimit.js index 17dffc11b..1de28efc6 100644 --- a/lib/eachOfLimit.js +++ b/lib/eachOfLimit.js @@ -14,12 +14,10 @@ import wrapAsync from './internal/wrapAsync'; * @category Collection * @param {Array|Iterable|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 + * @param {AsyncFunction} iteratee - An async 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). + * array. + * 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). */ diff --git a/lib/eachOfSeries.js b/lib/eachOfSeries.js index 21e816d37..fc1a09724 100644 --- a/lib/eachOfSeries.js +++ b/lib/eachOfSeries.js @@ -12,11 +12,9 @@ import doLimit from './internal/doLimit'; * @alias forEachOfSeries * @category Collection * @param {Array|Iterable|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 {AsyncFunction} iteratee - An async function to apply to each item in + * `coll`. + * 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). */ diff --git a/lib/eachSeries.js b/lib/eachSeries.js index 0839d8ca1..9f8d7defd 100644 --- a/lib/eachSeries.js +++ b/lib/eachSeries.js @@ -12,12 +12,11 @@ import doLimit from './internal/doLimit'; * @alias forEachSeries * @category Collection * @param {Array|Iterable|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 {AsyncFunction} iteratee - An async function to apply to each + * item in `coll`. + * The array index is not passed to the iteratee. + * If you need the index, use `eachOfSeries`. + * Invoked with (item, callback). * @param {Function} [callback] - A callback which is called when all * `iteratee` functions have finished, or an error occurs. Invoked with (err). */ diff --git a/lib/ensureAsync.js b/lib/ensureAsync.js index 8582bbabd..a579efca6 100644 --- a/lib/ensureAsync.js +++ b/lib/ensureAsync.js @@ -8,16 +8,17 @@ import { isAsync } from './internal/wrapAsync'; * 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. + * contained. ES2017 `async` functions are returned as-is -- they are immune + * to Zalgo's corrupting influences, as they always resolve on a later tick. * * @name ensureAsync * @static * @memberOf module:Utils * @method * @category Util - * @param {Function} fn - an async function, one that expects a node-style + * @param {AsyncFunction} 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 + * @returns {AsyncFunction} Returns a wrapped function with the exact same call * signature as the function passed in. * @example * diff --git a/lib/every.js b/lib/every.js index b34ad1f93..eb1074807 100644 --- a/lib/every.js +++ b/lib/every.js @@ -13,10 +13,10 @@ import notId from './internal/notId'; * @alias all * @category Collection * @param {Array|Iterable|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 {AsyncFunction} iteratee - An async truth test to apply to each item + * in the collection in parallel. + * The iteratee must complete with a boolean result value. + * 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). diff --git a/lib/everyLimit.js b/lib/everyLimit.js index 4cc709147..89a69fc01 100644 --- a/lib/everyLimit.js +++ b/lib/everyLimit.js @@ -14,10 +14,10 @@ import notId from './internal/notId'; * @category Collection * @param {Array|Iterable|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 {AsyncFunction} iteratee - An async truth test to apply to each item + * in the collection in parallel. + * The iteratee must complete with a boolean result value. + * 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). diff --git a/lib/everySeries.js b/lib/everySeries.js index 743474805..b67368c95 100644 --- a/lib/everySeries.js +++ b/lib/everySeries.js @@ -12,10 +12,10 @@ import doLimit from './internal/doLimit'; * @alias allSeries * @category Collection * @param {Array|Iterable|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 {AsyncFunction} iteratee - An async truth test to apply to each item + * in the collection in series. + * The iteratee must complete with a boolean result value. + * 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). diff --git a/lib/forever.js b/lib/forever.js index 66bc47276..f7be0b257 100644 --- a/lib/forever.js +++ b/lib/forever.js @@ -8,16 +8,16 @@ import wrapAsync from './internal/wrapAsync'; * 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. + * 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 module:ControlFlow * @method * @category Control Flow - * @param {Function} fn - a function to call repeatedly. Invoked with (next). + * @param {AsyncFunction} fn - an async 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 diff --git a/lib/groupBy.js b/lib/groupBy.js index 31e2c0b75..a2f923ff5 100644 --- a/lib/groupBy.js +++ b/lib/groupBy.js @@ -18,10 +18,10 @@ import groupByLimit from './groupByLimit'; * @method * @category Collection * @param {Array|Iterable|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, key)` which must be called once it - * has completed with an error (which can be `null`) and the `key` to group the - * value under. Invoked with (value, callback). + * @param {AsyncFunction} iteratee - An async function to apply to each item in + * `coll`. + * The iteratee should complete with a `key` to group the value under. + * Invoked with (value, callback). * @param {Function} [callback] - A callback which is called when all `iteratee` * functions have finished, or an error occurs. Result is an `Object` whoses * properties are arrays of values which returned the corresponding key. diff --git a/lib/groupByLimit.js b/lib/groupByLimit.js index c14835191..b0a5ef339 100644 --- a/lib/groupByLimit.js +++ b/lib/groupByLimit.js @@ -12,10 +12,10 @@ import wrapAsync from './internal/wrapAsync'; * @category Collection * @param {Array|Iterable|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, key)` which must be called once it - * has completed with an error (which can be `null`) and the `key` to group the - * value under. Invoked with (value, callback). + * @param {AsyncFunction} iteratee - An async function to apply to each item in + * `coll`. + * The iteratee should complete with a `key` to group the value under. + * Invoked with (value, callback). * @param {Function} [callback] - A callback which is called when all `iteratee` * functions have finished, or an error occurs. Result is an `Object` whoses * properties are arrays of values which returned the corresponding key. diff --git a/lib/groupBySeries.js b/lib/groupBySeries.js index 5df9a3cbe..91935c378 100644 --- a/lib/groupBySeries.js +++ b/lib/groupBySeries.js @@ -12,10 +12,10 @@ import groupByLimit from './groupByLimit'; * @category Collection * @param {Array|Iterable|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, key)` which must be called once it - * has completed with an error (which can be `null`) and the `key` to group the - * value under. Invoked with (value, callback). + * @param {AsyncFunction} iteratee - An async function to apply to each item in + * `coll`. + * The iteratee should complete with a `key` to group the value under. + * Invoked with (value, callback). * @param {Function} [callback] - A callback which is called when all `iteratee` * functions have finished, or an error occurs. Result is an `Object` whoses * properties are arrays of values which returned the corresponding key. diff --git a/lib/index.js b/lib/index.js index 0fbeefca8..f1e8e988c 100644 --- a/lib/index.js +++ b/lib/index.js @@ -3,14 +3,18 @@ * a variable number of parameters, with the final parameter being a callback. * (`function (arg1, arg2, ..., callback) {}`) * The final callback is of the form `callback(err, results...)`, which must be - * called once the function is completed. The callback can be called with a + * called once the function is completed. The callback should be called with a * Error as its first argument to signal that an error occurred. - * Otherwise, it can be called with `null` as the first argument, and any - * additional `result` arguments that may apply to signal successful completion. + * Otherwise, if no error occurred, it should be called with `null` as the first + * argument, and any additional `result` arguments that may apply, to signal + * successful completion. * The callback must be called exactly once, ideally on a later tick of the * JavaScript event loop. * - * This type of function is also referred to as a "Node-style async function". + * This type of function is also referred to as a "Node-style async function", + * or a "continuation passing-style function" (CPS). Most of the methods of this + * library are themselves CPS/Node-style async functions, or functions that + * return CPS/Node-style async functions. * * Wherever we accept a Node-style async function, we also directly accept an * [ES2017 `async` function]{@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function}. diff --git a/lib/log.js b/lib/log.js index 848661da5..c39e03352 100644 --- a/lib/log.js +++ b/lib/log.js @@ -11,8 +11,8 @@ import consoleFunc from './internal/consoleFunc'; * @memberOf module:Utils * @method * @category Util - * @param {Function} function - The function you want to eventually apply all - * arguments to. + * @param {AsyncFunction} function - The function you want to eventually apply + * all arguments to. * @param {...*} arguments... - Any number of arguments to apply to the function. * @example * diff --git a/lib/map.js b/lib/map.js index 76d60582b..100ab7a1a 100644 --- a/lib/map.js +++ b/lib/map.js @@ -24,10 +24,10 @@ import map from './internal/map'; * @method * @category Collection * @param {Array|Iterable|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 {AsyncFunction} iteratee - An async function to apply to each item in + * `coll`. + * The iteratee should complete with the 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). diff --git a/lib/mapLimit.js b/lib/mapLimit.js index a54922d3b..0a2fc02c4 100644 --- a/lib/mapLimit.js +++ b/lib/mapLimit.js @@ -12,10 +12,10 @@ import map from './internal/map'; * @category Collection * @param {Array|Iterable|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 {AsyncFunction} iteratee - An async function to apply to each item in + * `coll`. + * The iteratee should complete with the 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). diff --git a/lib/mapSeries.js b/lib/mapSeries.js index e1f3d0d5d..596c75ec7 100644 --- a/lib/mapSeries.js +++ b/lib/mapSeries.js @@ -11,10 +11,10 @@ import doLimit from './internal/doLimit'; * @see [async.map]{@link module:Collections.map} * @category Collection * @param {Array|Iterable|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 {AsyncFunction} iteratee - An async function to apply to each item in + * `coll`. + * The iteratee should complete with the 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). diff --git a/lib/mapValues.js b/lib/mapValues.js index afc43f482..d6a4ad23f 100644 --- a/lib/mapValues.js +++ b/lib/mapValues.js @@ -21,10 +21,10 @@ import doLimit from './internal/doLimit'; * @method * @category Collection * @param {Object} obj - A collection to iterate over. - * @param {Function} iteratee - A function to apply to each value and key 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 value. Invoked with (value, key, callback). + * @param {AsyncFunction} iteratee - A function to apply to each value and key + * in `coll`. + * The iteratee should complete with the transformed value as its result. + * Invoked with (value, key, callback). * @param {Function} [callback] - A callback which is called when all `iteratee` * functions have finished, or an error occurs. `result` is a new object consisting * of each key from `obj`, with each transformed value on the right-hand side. diff --git a/lib/mapValuesLimit.js b/lib/mapValuesLimit.js index 1d5a47a85..c6e020d03 100644 --- a/lib/mapValuesLimit.js +++ b/lib/mapValuesLimit.js @@ -16,10 +16,10 @@ import wrapAsync from './internal/wrapAsync'; * @category Collection * @param {Object} obj - 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 value in `obj`. - * 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 value. Invoked with (value, key, callback). + * @param {AsyncFunction} iteratee - A function to apply to each value and key + * in `coll`. + * The iteratee should complete with the transformed value as its result. + * Invoked with (value, key, callback). * @param {Function} [callback] - A callback which is called when all `iteratee` * functions have finished, or an error occurs. `result` is a new object consisting * of each key from `obj`, with each transformed value on the right-hand side. diff --git a/lib/mapValuesSeries.js b/lib/mapValuesSeries.js index c1530c239..ab0b8f845 100644 --- a/lib/mapValuesSeries.js +++ b/lib/mapValuesSeries.js @@ -11,10 +11,10 @@ import doLimit from './internal/doLimit'; * @see [async.mapValues]{@link module:Collections.mapValues} * @category Collection * @param {Object} obj - A collection to iterate over. - * @param {Function} iteratee - A function to apply to each value in `obj`. - * 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 value. Invoked with (value, key, callback). + * @param {AsyncFunction} iteratee - A function to apply to each value and key + * in `coll`. + * The iteratee should complete with the transformed value as its result. + * Invoked with (value, key, callback). * @param {Function} [callback] - A callback which is called when all `iteratee` * functions have finished, or an error occurs. `result` is a new object consisting * of each key from `obj`, with each transformed value on the right-hand side. diff --git a/lib/memoize.js b/lib/memoize.js index d752d999a..de71c33e7 100644 --- a/lib/memoize.js +++ b/lib/memoize.js @@ -10,7 +10,7 @@ function has(obj, key) { } /** - * Caches the results of an `async` function. When creating a hash to store + * 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. * @@ -28,11 +28,11 @@ function has(obj, key) { * @memberOf module:Utils * @method * @category Util - * @param {Function} fn - The function to proxy and cache results from. + * @param {AsyncFunction} fn - The async 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. - * @returns {Function} a memoized version of `fn` + * @returns {AsyncFunction} a memoized version of `fn` * @example * * var slow_fn = function(name, callback) { diff --git a/lib/parallel.js b/lib/parallel.js index 19d555884..8b6c2ce89 100644 --- a/lib/parallel.js +++ b/lib/parallel.js @@ -13,6 +13,7 @@ import parallel from './internal/parallel'; * 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. + * * **Hint:** Use [`reflect`]{@link module:Utils.reflect} to continue the * execution of other tasks when a task fails. * @@ -26,14 +27,14 @@ import parallel from './internal/parallel'; * @memberOf module:ControlFlow * @method * @category Control Flow - * @param {Array|Iterable|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 {Array|Iterable|Object} tasks - A collection of + * [async functions]{@link AsyncFunction} to run. + * Each async function can complete with any number of optional `result` values. * @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) { diff --git a/lib/parallelLimit.js b/lib/parallelLimit.js index 926fa853a..14e9e5230 100644 --- a/lib/parallelLimit.js +++ b/lib/parallelLimit.js @@ -11,10 +11,9 @@ import parallel from './internal/parallel'; * @method * @see [async.parallel]{@link module:ControlFlow.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 {Array|Iterable|Object} tasks - A collection of + * [async functions]{@link AsyncFunction} to run. + * Each async function can complete with any number of optional `result` values. * @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 diff --git a/lib/priorityQueue.js b/lib/priorityQueue.js index 0af01577c..aff729379 100644 --- a/lib/priorityQueue.js +++ b/lib/priorityQueue.js @@ -15,11 +15,10 @@ import queue from './queue'; * @method * @see [async.queue]{@link module:ControlFlow.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 {AsyncFunction} worker - An async function for processing a queued task. + * 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. diff --git a/lib/queue.js b/lib/queue.js index 0f17cd996..906467c07 100644 --- a/lib/queue.js +++ b/lib/queue.js @@ -59,11 +59,9 @@ import wrapAsync from './internal/wrapAsync'; * @memberOf module:ControlFlow * @method * @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 {AsyncFunction} worker - An async function for processing a queued task. + * 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. diff --git a/lib/race.js b/lib/race.js index ee81b37be..9b4d6c380 100644 --- a/lib/race.js +++ b/lib/race.js @@ -14,9 +14,8 @@ import wrapAsync from './internal/wrapAsync'; * @memberOf module:ControlFlow * @method * @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 {Array} tasks - An array containing [async functions]{@link AsyncFunction} + * to run. Each function can complete with 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). diff --git a/lib/reduce.js b/lib/reduce.js index c5ac2921e..0d58c41e2 100644 --- a/lib/reduce.js +++ b/lib/reduce.js @@ -23,12 +23,12 @@ import wrapAsync from './internal/wrapAsync'; * @category Collection * @param {Array|Iterable|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 {AsyncFunction} iteratee - A function applied to each item in the + * array to produce the next step in the reduction. + * The `iteratee` should complete with the next state of the reduction. + * If the iteratee complete with an error, 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). diff --git a/lib/reduceRight.js b/lib/reduceRight.js index 844c94f93..ca5aa7fb0 100644 --- a/lib/reduceRight.js +++ b/lib/reduceRight.js @@ -14,12 +14,12 @@ var slice = Array.prototype.slice; * @category Collection * @param {Array} array - 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 {AsyncFunction} iteratee - A function applied to each item in the + * array to produce the next step in the reduction. + * The `iteratee` should complete with the next state of the reduction. + * If the iteratee complete with an error, 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). diff --git a/lib/reflect.js b/lib/reflect.js index 0dbd397a6..9e0613b48 100644 --- a/lib/reflect.js +++ b/lib/reflect.js @@ -3,17 +3,17 @@ import rest from './internal/rest'; import wrapAsync from './internal/wrapAsync'; /** - * Wraps the function in another function that always returns data even when it - * errors. + * Wraps the async function in another function that always completes with a + * result object, even when it errors. * - * The object returned has either the property `error` or `value`. + * The result object has either the property `error` or `value`. * * @name reflect * @static * @memberOf module:Utils * @method * @category Util - * @param {Function} fn - The function you want to wrap + * @param {AsyncFunction} fn - The async 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. diff --git a/lib/reflectAll.js b/lib/reflectAll.js index dbeba8d81..0774b9432 100644 --- a/lib/reflectAll.js +++ b/lib/reflectAll.js @@ -4,7 +4,7 @@ import _arrayMap from 'lodash/_arrayMap'; import forOwn from 'lodash/_baseForOwn'; /** - * A helper function that wraps an array or an object of functions with reflect. + * A helper function that wraps an array or an object of functions with `reflect`. * * @name reflectAll * @static @@ -12,8 +12,9 @@ import forOwn from 'lodash/_baseForOwn'; * @method * @see [async.reflect]{@link module:Utils.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 + * @param {Array|Object|Iterable} tasks - The collection of + * [async functions]{@link AsyncFunction} to wrap in `async.reflect`. + * @returns {Array} Returns an array of async functions, each wrapped in * `async.reflect` * @example * diff --git a/lib/reject.js b/lib/reject.js index 0ddbaf0ac..95a627036 100644 --- a/lib/reject.js +++ b/lib/reject.js @@ -11,9 +11,10 @@ import doParallel from './internal/doParallel'; * @see [async.filter]{@link module:Collections.filter} * @category Collection * @param {Array|Iterable|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} iteratee - An async truth test to apply to each item in + * `coll`. + * The should complete with a boolean value as its `result`. + * Invoked with (item, callback). * @param {Function} [callback] - A callback which is called after all the * `iteratee` functions have finished. Invoked with (err, results). * @example diff --git a/lib/rejectLimit.js b/lib/rejectLimit.js index 977bc4c83..814781138 100644 --- a/lib/rejectLimit.js +++ b/lib/rejectLimit.js @@ -13,9 +13,10 @@ import doParallelLimit from './internal/doParallelLimit'; * @category Collection * @param {Array|Iterable|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} iteratee - An async truth test to apply to each item in + * `coll`. + * The should complete with a boolean value as its `result`. + * Invoked with (item, callback). * @param {Function} [callback] - A callback which is called after all the * `iteratee` functions have finished. Invoked with (err, results). */ diff --git a/lib/rejectSeries.js b/lib/rejectSeries.js index 0bb925e97..7eba2f736 100644 --- a/lib/rejectSeries.js +++ b/lib/rejectSeries.js @@ -11,9 +11,10 @@ import doLimit from './internal/doLimit'; * @see [async.reject]{@link module:Collections.reject} * @category Collection * @param {Array|Iterable|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} iteratee - An async truth test to apply to each item in + * `coll`. + * The should complete with a boolean value as its `result`. + * Invoked with (item, callback). * @param {Function} [callback] - A callback which is called after all the * `iteratee` functions have finished. Invoked with (err, results). */ diff --git a/lib/retry.js b/lib/retry.js index e2790160e..bd60644ce 100644 --- a/lib/retry.js +++ b/lib/retry.js @@ -13,6 +13,7 @@ import wrapAsync from './internal/wrapAsync'; * @memberOf module:ControlFlow * @method * @category Control Flow + * @see [async.retryable]{@link module:ControlFlow.retryable} * @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 @@ -27,16 +28,13 @@ import wrapAsync from './internal/wrapAsync'; * Invoked with (err). * * 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 {AsyncFunction} task - An async function to retry. + * Invoked with (callback). * @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 @@ -82,7 +80,7 @@ import wrapAsync from './internal/wrapAsync'; * // individual methods that are not as reliable, like this: * async.auto({ * users: api.getUsers.bind(api), - * payments: async.retry(3, api.getPayments.bind(api)) + * payments: async.retryable(3, api.getPayments.bind(api)) * }, function(err, results) { * // do something with the results * }); diff --git a/lib/retryable.js b/lib/retryable.js index 6fba8e234..57410317a 100644 --- a/lib/retryable.js +++ b/lib/retryable.js @@ -3,8 +3,9 @@ import initialParams from './internal/initialParams'; import wrapAsync from './internal/wrapAsync'; /** - * A close relative of [`retry`]{@link module:ControlFlow.retry}. This method wraps a task and makes it - * retryable, rather than immediately calling it with retries. + * A close relative of [`retry`]{@link module:ControlFlow.retry}. This method + * wraps a task and makes it retryable, rather than immediately calling it + * with retries. * * @name retryable * @static @@ -14,9 +15,12 @@ import wrapAsync from './internal/wrapAsync'; * @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`. + * @param {AsyncFunction} task - the asynchronous function to wrap. + * This function will be passed any arguments passed to the returned wrapper. + * Invoked with (...args, callback). + * @returns {AsyncFunction} The wrapped function, which when invoked, will + * retry on an error, based on the parameters specified in `opts`. + * This function will accept the same parameters as `task`. * @example * * async.auto({ diff --git a/lib/seq.js b/lib/seq.js index 9a3584718..4fceceb60 100644 --- a/lib/seq.js +++ b/lib/seq.js @@ -17,7 +17,7 @@ import arrayMap from 'lodash/_arrayMap'; * @method * @see [async.compose]{@link module:ControlFlow.compose} * @category Control Flow - * @param {...Function} functions - the asynchronous functions to compose + * @param {...AsyncFunction} functions - the asynchronous functions to compose * @returns {Function} a function that composes the `functions` in order * @example * diff --git a/lib/series.js b/lib/series.js index 7955cf251..eef153411 100644 --- a/lib/series.js +++ b/lib/series.js @@ -27,9 +27,9 @@ import eachOfSeries from './eachOfSeries'; * @memberOf module:ControlFlow * @method * @category Control Flow - * @param {Array|Iterable|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 {Array|Iterable|Object} tasks - A collection containing + * [async functions]{@link AsyncFunction} to run in series. + * Each function can complete with any number of optional `result` values. * @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 diff --git a/lib/someLimit.js b/lib/someLimit.js index bf4c601cb..161c3cfe2 100644 --- a/lib/someLimit.js +++ b/lib/someLimit.js @@ -14,10 +14,10 @@ import identity from 'lodash/identity'; * @category Collection * @param {Array|Iterable|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 {AsyncFunction} iteratee - An async truth test to apply to each item + * in the collections in parallel. + * The iteratee should complete with a boolean `result` value. + * 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 diff --git a/lib/someSeries.js b/lib/someSeries.js index 8357a8b16..8e278deb7 100644 --- a/lib/someSeries.js +++ b/lib/someSeries.js @@ -12,10 +12,10 @@ import doLimit from './internal/doLimit'; * @alias anySeries * @category Collection * @param {Array|Iterable|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 {AsyncFunction} iteratee - An async truth test to apply to each item + * in the collections in series. + * The iteratee should complete with a boolean `result` value. + * 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 diff --git a/lib/sortBy.js b/lib/sortBy.js index 812a39ef3..399debd23 100644 --- a/lib/sortBy.js +++ b/lib/sortBy.js @@ -14,10 +14,11 @@ import wrapAsync from './internal/wrapAsync'; * @method * @category Collection * @param {Array|Iterable|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 {AsyncFunction} iteratee - An async function to apply to each item in + * `coll`. + * The iteratee should complete with a value to use as the sort criteria as + * its `result`. + * 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` diff --git a/lib/timeout.js b/lib/timeout.js index ad050e01a..475b20889 100644 --- a/lib/timeout.js +++ b/lib/timeout.js @@ -11,14 +11,13 @@ import wrapAsync from './internal/wrapAsync'; * @memberOf module:Utils * @method * @category Util - * @param {Function} asyncFn - The asynchronous function you want to set the - * time limit. + * @param {AsyncFunction} asyncFn - The async function to limit in time. * @param {number} milliseconds - 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. Invoke this function with the same - * parameters as you would `asyncFunc`. + * @returns {AsyncFunction} Returns a wrapped function that can be used with any + * of the control flow functions. + * Invoke this function with the same parameters as you would `asyncFunc`. * @example * * function myFunction(foo, callback) { diff --git a/lib/times.js b/lib/times.js index bdd2e6b34..ebd336c4c 100644 --- a/lib/times.js +++ b/lib/times.js @@ -12,8 +12,8 @@ import doLimit from './internal/doLimit'; * @see [async.map]{@link module:Collections.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 {AsyncFunction} iteratee - The async function to call `n` times. + * Invoked with the iteration index and a callback: (n, next). * @param {Function} callback - see {@link module:Collections.map}. * @example * diff --git a/lib/timesLimit.js b/lib/timesLimit.js index 7ba91d69c..22be265a1 100644 --- a/lib/timesLimit.js +++ b/lib/timesLimit.js @@ -14,8 +14,8 @@ import wrapAsync from './internal/wrapAsync'; * @category Control Flow * @param {number} count - 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 {AsyncFunction} iteratee - The async function to call `n` times. + * Invoked with the iteration index and a callback: (n, next). * @param {Function} callback - see [async.map]{@link module:Collections.map}. */ export default function timeLimit(count, limit, iteratee, callback) { diff --git a/lib/timesSeries.js b/lib/timesSeries.js index 672428d18..17ec0ca85 100644 --- a/lib/timesSeries.js +++ b/lib/timesSeries.js @@ -11,8 +11,8 @@ import doLimit from './internal/doLimit'; * @see [async.times]{@link module:ControlFlow.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 {AsyncFunction} iteratee - The async function to call `n` times. + * Invoked with the iteration index and a callback: (n, next). * @param {Function} callback - see {@link module:Collections.map}. */ export default doLimit(timesLimit, 1); diff --git a/lib/transform.js b/lib/transform.js index d3c1d6a03..ef254a136 100644 --- a/lib/transform.js +++ b/lib/transform.js @@ -18,11 +18,8 @@ import wrapAsync from './internal/wrapAsync'; * @param {Array|Iterable|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. + * @param {AsyncFunction} iteratee - A function applied to each item in the + * collection that potentially modifies the accumulator. * 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. diff --git a/lib/unmemoize.js b/lib/unmemoize.js index 4b2db4dc8..d89075f5d 100644 --- a/lib/unmemoize.js +++ b/lib/unmemoize.js @@ -8,8 +8,8 @@ * @method * @see [async.memoize]{@link module:Utils.memoize} * @category Util - * @param {Function} fn - the memoized function - * @returns {Function} a function that calls the original unmemoized function + * @param {AsyncFunction} fn - the memoized function + * @returns {AsyncFunction} a function that calls the original unmemoized function */ export default function unmemoize(fn) { return function () { diff --git a/lib/whilst.js b/lib/whilst.js index 8135af7d9..dc56a8a24 100644 --- a/lib/whilst.js +++ b/lib/whilst.js @@ -15,9 +15,8 @@ import wrapAsync from './internal/wrapAsync'; * @category Control Flow * @param {Function} test - synchronous truth test to perform before each * execution of `iteratee`. Invoked with (). - * @param {Function} iteratee - 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 {AsyncFunction} fn - An async function which is called each time + * `test` passes. Invoked with (callback). * @param {Function} [callback] - A callback which is called after the test * function has failed and repeated execution of `iteratee` has stopped. `callback` * will be passed an error and any arguments passed to the final `iteratee`'s