diff options
author | Hubert Argasinski <argasinski.hubert@gmail.com> | 2016-04-06 02:10:35 -0700 |
---|---|---|
committer | Graeme Yeates <yeatesgraeme@gmail.com> | 2016-04-12 18:46:28 -0400 |
commit | 8114c90883857d8390add28976f36d0b9bac31ca (patch) | |
tree | fb06f667b0e1fde4627d552a87d194748461a33d | |
parent | 8eb2a7cec2c62edf35d7b812765bd64e6b7d484f (diff) | |
download | async-8114c90883857d8390add28976f36d0b9bac31ca.tar.gz |
jsdoc-style documentation began documenting `Util` methods
remaining `Util` methods to document (10):
- ensureAsync
- constant
- asyncify
- wrapSync
- log
- dir
- noConflict
- timeout
- reflect
- reflectAll
-rw-r--r-- | lib/apply.js | 43 | ||||
-rw-r--r-- | lib/memoize.js | 35 | ||||
-rw-r--r-- | lib/nextTick.js | 30 | ||||
-rw-r--r-- | lib/race.js | 35 | ||||
-rw-r--r-- | lib/times.js | 30 | ||||
-rw-r--r-- | lib/timesLimit.js | 15 | ||||
-rw-r--r-- | lib/timesSeries.js | 13 | ||||
-rw-r--r-- | lib/unmemoize.js | 11 |
8 files changed, 212 insertions, 0 deletions
diff --git a/lib/apply.js b/lib/apply.js index 76b5602..0c3c33d 100644 --- a/lib/apply.js +++ b/lib/apply.js @@ -2,6 +2,49 @@ import rest from 'lodash/rest'; +/** + * Creates a continuation function with some arguments already applied. + * + * Useful as a shorthand when combined with other control flow functions. Any + * arguments passed to the returned function are added to the arguments + * originally passed to apply. + * + * @name apply + * @static + * @memberOf async + * @category Util + * @param {Function} function - The function you want to eventually apply all + * arguments to. Invokes with (arguments...). + * @param {...*} arguments... - Any number of arguments to automatically apply + * when the continuation is called. + * @example + * + * // using apply + * async.parallel([ + * async.apply(fs.writeFile, 'testfile1', 'test1'), + * async.apply(fs.writeFile, 'testfile2', 'test2') + * ]); + * + * + * // the same process without using apply + * async.parallel([ + * function(callback) { + * fs.writeFile('testfile1', 'test1', callback); + * }, + * function(callback) { + * fs.writeFile('testfile2', 'test2', callback); + * } + * ]); + * + * // It's possible to pass any number of additional arguments when calling the + * // continuation: + * + * node> var fn = async.apply(sys.puts, 'one'); + * node> fn('two', 'three'); + * one + * two + * three + */ export default rest(function(fn, args) { return rest(function(callArgs) { return fn.apply(null, args.concat(callArgs)); diff --git a/lib/memoize.js b/lib/memoize.js index d1af636..955f709 100644 --- a/lib/memoize.js +++ b/lib/memoize.js @@ -10,6 +10,41 @@ function has(obj, key) { return key in obj; } +/** + * Caches the results of an `async` function. When creating a hash to store + * function results against, the callback is omitted from the hash and an + * optional hash function can be used. + * + * If no hash function is specified, the first argument is used as a hash key, + * which may work reasonably if it is a string or a data type that converts to a + * distinct string. Note that objects and arrays will not behave reasonably. + * Neither will cases where the other arguments are significant. In such cases, + * specify your own hash function. + * + * The cache of results is exposed as the `memo` property of the function + * returned by `memoize`. + * + * @name memoize + * @static + * @memberOf async + * @category Util + * @param {Function} fn - The function to proxy and cache results from. + * @param {Function} hasher - An optional function for generating a custom hash + * for storing results. It has all the arguments applied to it apart from the + * callback, and must be synchronous. + * @example + * + * var slow_fn = function(name, callback) { + * // do something + * callback(null, result); + * }; + * var fn = async.memoize(slow_fn); + * + * // fn can now be used as if it were slow_fn + * fn('some name', function() { + * // callback + * }); + */ export default function memoize(fn, hasher) { var memo = Object.create(null); var queues = Object.create(null); diff --git a/lib/nextTick.js b/lib/nextTick.js index 05d9555..249bec2 100644 --- a/lib/nextTick.js +++ b/lib/nextTick.js @@ -2,4 +2,34 @@ import setImmediate from './internal/setImmediate'; +/** + * Calls `callback` on a later loop around the event loop. In Node.js this just + * calls `setImmediate`. In the browser it will use `setImmediate` if + * available, otherwise `setTimeout(callback, 0)`, which means other higher + * priority events may precede the execution of `callback`. + * + * This is used internally for browser-compatibility purposes. + * + * @name nextTick + * @static + * @memberOf async + * @alias setImmediate + * @category Util + * @param {Function} callback - The function to call on a later loop around + * the event loop. Invoked with (args...). + * @param {...*} args... - any number of additional arguments to pass to the + * callback on the next tick. + * @example + * + * var call_order = []; + * async.nextTick(function() { + * call_order.push('two'); + * // call_order now equals ['one','two'] + * }); + * call_order.push('one'); + * + * async.setImmediate(function (a, b, c) { + * // a, b, and c equal 1, 2, and 3 + * }, 1, 2, 3); + */ export default setImmediate; diff --git a/lib/race.js b/lib/race.js index b89a5db..b12b2e7 100644 --- a/lib/race.js +++ b/lib/race.js @@ -5,6 +5,41 @@ import each from 'lodash/each'; import noop from 'lodash/noop'; import once from './internal/once'; +/** + * Runs the `tasks` array of functions in parallel, without waiting until the + * previous function has completed. Once any the `tasks` completed or pass an + * error to its callback, the main `callback` is immediately called. It's + * equivalent to `Promise.race()`. + * + * @name race + * @static + * @memberOf async + * @category Util + * @param {Array} tasks - An array containing functions to run. Each function + * is passed a `callback(err, result)` which it must call on completion with an + * error `err` (which can be `null`) and an optional `result` value. + * @param {Function} callback - A callback to run once any of the functions have + * completed. This function gets an error or result from the first function that + * completed. Invoked with (err, result). + * @example + * + * async.race([ + * function(callback) { + * setTimeout(function() { + * callback(null, 'one'); + * }, 200); + * }, + * function(callback) { + * setTimeout(function() { + * callback(null, 'two'); + * }, 100); + * } + * ], + * // main callback + * function(err, result) { + * // the result will be equal to 'two' as it finishes earlier + * }); + */ export default function race(tasks, cb) { cb = once(cb || noop); if (!isArray(tasks)) return cb(new TypeError('First argument to race must be an array of functions')); diff --git a/lib/times.js b/lib/times.js index 2cbd230..a81ba3b 100644 --- a/lib/times.js +++ b/lib/times.js @@ -3,4 +3,34 @@ import timesLimit from './timesLimit'; import doLimit from './internal/doLimit'; +/** + * Calls the `iteratee` function `n` times, and accumulates results in the same + * manner you would use with [`map`](#map). + * + * @name times + * @static + * @memberOf async + * @see `async.map` + * @category Util + * @param {number} n - The number of times to run the function. + * @param {Function} iteratee - The function to call `n` times. Invoked with the + * iteration index and a callback (n, next). + * @param {Function} callback - see [`map`](#map). + * @example + * // Pretend this is some complicated async factory + * var createUser = function(id, callback) { + * callback(null, { + * id: 'user' + id + * }); + * }; + * + * // generate 5 users + * async.times(5, function(n, next) { + * createUser(n, function(err, user) { + * next(err, user); + * }); + * }, function(err, users) { + * // we should now have 5 users + * }); + */ export default doLimit(timesLimit, Infinity); diff --git a/lib/timesLimit.js b/lib/timesLimit.js index dbd9664..73ae4d1 100644 --- a/lib/timesLimit.js +++ b/lib/timesLimit.js @@ -3,6 +3,21 @@ import mapLimit from './mapLimit'; import range from 'lodash/_baseRange'; +/** +* The same as `times` but runs a maximum of `limit` async operations at a +* time. + * + * @name timesLimit + * @static + * @memberOf async + * @see `async.times` + * @category Util + * @param {number} n - The number of times to run the function. + * @param {number} limit - The maximum number of async operations at a time. + * @param {Function} iteratee - The function to call `n` times. Invoked with the + * iteration index and a callback (n, next). + * @param {Function} callback - see [`map`](#map). + */ export default function timeLimit(count, limit, iteratee, cb) { return mapLimit(range(0, count, 1), limit, iteratee, cb); } diff --git a/lib/timesSeries.js b/lib/timesSeries.js index af2219b..dd2ad45 100644 --- a/lib/timesSeries.js +++ b/lib/timesSeries.js @@ -3,4 +3,17 @@ import timesLimit from './timesLimit'; import doLimit from './internal/doLimit'; +/** + * The same as `times` but runs only a single async operation at a time. + * + * @name timesSeries + * @static + * @memberOf async + * @see `async.times` + * @category Util + * @param {number} n - The number of times to run the function. + * @param {Function} iteratee - The function to call `n` times. Invoked with the + * iteration index and a callback (n, next). + * @param {Function} callback - see [`map`](#map). + */ export default doLimit(timesLimit, 1); diff --git a/lib/unmemoize.js b/lib/unmemoize.js index d652e7b..e7f0941 100644 --- a/lib/unmemoize.js +++ b/lib/unmemoize.js @@ -1,5 +1,16 @@ 'use strict'; +/** + * Undoes a [`memoize`](#memoize)d function, reverting it to the original, + * unmemoized form. Handy for testing. + * + * @name unmemoize + * @static + * @memberOf async + * @see `async.memoize` + * @category Util + * @param {Function} fn - the memoized function + */ export default function unmemoize(fn) { return function () { return (fn.unmemoized || fn).apply(null, arguments); |