diff options
Diffstat (limited to 'node_modules/async/dist/async.js')
| -rw-r--r-- | node_modules/async/dist/async.js | 1581 |
1 files changed, 815 insertions, 766 deletions
diff --git a/node_modules/async/dist/async.js b/node_modules/async/dist/async.js index bb95651b4..4d2aa0882 100644 --- a/node_modules/async/dist/async.js +++ b/node_modules/async/dist/async.js @@ -5,26 +5,6 @@ }(this, (function (exports) { 'use strict'; /** - * This method returns the first argument it receives. - * - * @static - * @since 0.1.0 - * @memberOf _ - * @category Util - * @param {*} value Any value. - * @returns {*} Returns `value`. - * @example - * - * var object = { 'a': 1 }; - * - * console.log(_.identity(object) === object); - * // => true - */ -function identity(value) { - return value; -} - -/** * A faster alternative to `Function#apply`, this function invokes `func` * with the `this` binding of `thisArg` and the arguments of `args`. * @@ -56,7 +36,7 @@ var nativeMax = Math.max; * @param {Function} transform The rest array transform. * @returns {Function} Returns the new function. */ -function overRest(func, start, transform) { +function overRest$1(func, start, transform) { start = nativeMax(start === undefined ? (func.length - 1) : start, 0); return function() { var args = arguments, @@ -78,30 +58,38 @@ function overRest(func, start, transform) { } /** - * Creates a function that returns `value`. + * This method returns the first argument it receives. * * @static + * @since 0.1.0 * @memberOf _ - * @since 2.4.0 * @category Util - * @param {*} value The value to return from the new function. - * @returns {Function} Returns the new constant function. + * @param {*} value Any value. + * @returns {*} Returns `value`. * @example * - * var objects = _.times(2, _.constant({ 'a': 1 })); - * - * console.log(objects); - * // => [{ 'a': 1 }, { 'a': 1 }] + * var object = { 'a': 1 }; * - * console.log(objects[0] === objects[1]); + * console.log(_.identity(object) === object); * // => true */ -function constant(value) { - return function() { - return value; - }; +function identity(value) { + return value; } +// Lodash rest function without function.toString() +// remappings +function rest(func, start) { + return overRest$1(func, start, identity); +} + +var initialParams = function (fn) { + return rest(function (args /*..., callback*/) { + var callback = args.pop(); + fn.call(this, args, callback); + }); +}; + /** * Checks if `value` is the * [language type](http://www.ecma-international.org/ecma-262/7.0/#sec-ecmascript-language-types) @@ -132,269 +120,253 @@ function isObject(value) { return value != null && (type == 'object' || type == 'function'); } -/** `Object#toString` result references. */ -var funcTag = '[object Function]'; -var genTag = '[object GeneratorFunction]'; -var proxyTag = '[object Proxy]'; - -/** Used for built-in method references. */ -var objectProto$1 = Object.prototype; - /** - * Used to resolve the - * [`toStringTag`](http://ecma-international.org/ecma-262/7.0/#sec-object.prototype.tostring) - * of values. - */ -var objectToString = objectProto$1.toString; - -/** - * Checks if `value` is classified as a `Function` object. + * Take a sync function and make it async, passing its return value to a + * callback. This is useful for plugging sync functions into a waterfall, + * series, or other async functions. Any arguments passed to the generated + * function will be passed to the wrapped function (except for the final + * callback argument). Errors thrown will be passed to the callback. + * + * If the function passed to `asyncify` returns a Promise, that promises's + * resolved/rejected state will be used to call the callback, rather than simply + * the synchronous return value. + * + * This also means you can asyncify ES2017 `async` functions. * + * @name asyncify * @static - * @memberOf _ - * @since 0.1.0 - * @category Lang - * @param {*} value The value to check. - * @returns {boolean} Returns `true` if `value` is a function, else `false`. + * @memberOf module:Utils + * @method + * @alias wrapSync + * @category Util + * @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 * - * _.isFunction(_); - * // => true + * // passing a regular synchronous function + * async.waterfall([ + * async.apply(fs.readFile, filename, "utf8"), + * async.asyncify(JSON.parse), + * function (data, next) { + * // data is the result of parsing the text. + * // If there was a parsing error, it would have been caught. + * } + * ], callback); * - * _.isFunction(/abc/); - * // => false + * // passing a function returning a promise + * async.waterfall([ + * async.apply(fs.readFile, filename, "utf8"), + * async.asyncify(function (contents) { + * return db.model.create(contents); + * }), + * function (model, next) { + * // `model` is the instantiated model object. + * // If there was an error, this function would be skipped. + * } + * ], callback); + * + * // es2017 example, though `asyncify` is not needed if your JS environment + * // supports async functions out of the box + * var q = async.queue(async.asyncify(async function(file) { + * var intermediateStep = await processFile(file); + * return await somePromise(intermediateStep) + * })); + * + * q.push(files); */ -function isFunction(value) { - // The use of `Object#toString` avoids issues with the `typeof` operator - // in Safari 9 which returns 'object' for typed array and other constructors. - var tag = isObject(value) ? objectToString.call(value) : ''; - return tag == funcTag || tag == genTag || tag == proxyTag; +function asyncify(func) { + return initialParams(function (args, callback) { + var result; + try { + result = func.apply(this, args); + } catch (e) { + return callback(e); + } + // if result is Promise object + if (isObject(result) && typeof result.then === 'function') { + result.then(function (value) { + callback(null, value); + }, function (err) { + callback(err.message ? err : new Error(err)); + }); + } else { + callback(null, result); + } + }); } -/** Detect free variable `global` from Node.js. */ -var freeGlobal = typeof global == 'object' && global && global.Object === Object && global; +var supportsSymbol = typeof Symbol === 'function'; -/** Detect free variable `self`. */ -var freeSelf = typeof self == 'object' && self && self.Object === Object && self; +function supportsAsync() { + var supported; + try { + /* eslint no-eval: 0 */ + supported = isAsync(eval('(async function () {})')); + } catch (e) { + supported = false; + } + return supported; +} -/** Used as a reference to the global object. */ -var root = freeGlobal || freeSelf || Function('return this')(); +function isAsync(fn) { + return supportsSymbol && fn[Symbol.toStringTag] === 'AsyncFunction'; +} -/** Used to detect overreaching core-js shims. */ -var coreJsData = root['__core-js_shared__']; +function wrapAsync(asyncFn) { + return isAsync(asyncFn) ? asyncify(asyncFn) : asyncFn; +} -/** Used to detect methods masquerading as native. */ -var maskSrcKey = (function() { - var uid = /[^.]+$/.exec(coreJsData && coreJsData.keys && coreJsData.keys.IE_PROTO || ''); - return uid ? ('Symbol(src)_1.' + uid) : ''; -}()); +var wrapAsync$1 = supportsAsync() ? wrapAsync : identity; -/** - * Checks if `func` has its source masked. - * - * @private - * @param {Function} func The function to check. - * @returns {boolean} Returns `true` if `func` is masked, else `false`. - */ -function isMasked(func) { - return !!maskSrcKey && (maskSrcKey in func); +function applyEach$1(eachfn) { + return rest(function (fns, args) { + var go = initialParams(function (args, callback) { + var that = this; + return eachfn(fns, function (fn, cb) { + wrapAsync$1(fn).apply(that, args.concat(cb)); + }, callback); + }); + if (args.length) { + return go.apply(this, args); + } else { + return go; + } + }); } -/** Used for built-in method references. */ -var funcProto$1 = Function.prototype; - -/** Used to resolve the decompiled source of functions. */ -var funcToString$1 = funcProto$1.toString; +/** Detect free variable `global` from Node.js. */ +var freeGlobal = typeof global == 'object' && global && global.Object === Object && global; -/** - * Converts `func` to its source code. - * - * @private - * @param {Function} func The function to process. - * @returns {string} Returns the source code. - */ -function toSource(func) { - if (func != null) { - try { - return funcToString$1.call(func); - } catch (e) {} - try { - return (func + ''); - } catch (e) {} - } - return ''; -} +/** Detect free variable `self`. */ +var freeSelf = typeof self == 'object' && self && self.Object === Object && self; -/** - * Used to match `RegExp` - * [syntax characters](http://ecma-international.org/ecma-262/7.0/#sec-patterns). - */ -var reRegExpChar = /[\\^$.*+?()[\]{}|]/g; +/** Used as a reference to the global object. */ +var root = freeGlobal || freeSelf || Function('return this')(); -/** Used to detect host constructors (Safari). */ -var reIsHostCtor = /^\[object .+?Constructor\]$/; +/** Built-in value references. */ +var Symbol$1 = root.Symbol; /** Used for built-in method references. */ -var funcProto = Function.prototype; var objectProto = Object.prototype; -/** Used to resolve the decompiled source of functions. */ -var funcToString = funcProto.toString; - /** Used to check objects for own properties. */ var hasOwnProperty = objectProto.hasOwnProperty; -/** Used to detect if a method is native. */ -var reIsNative = RegExp('^' + - funcToString.call(hasOwnProperty).replace(reRegExpChar, '\\$&') - .replace(/hasOwnProperty|(function).*?(?=\\\()| for .+?(?=\\\])/g, '$1.*?') + '$' -); - /** - * The base implementation of `_.isNative` without bad shim checks. - * - * @private - * @param {*} value The value to check. - * @returns {boolean} Returns `true` if `value` is a native function, - * else `false`. + * Used to resolve the + * [`toStringTag`](http://ecma-international.org/ecma-262/7.0/#sec-object.prototype.tostring) + * of values. */ -function baseIsNative(value) { - if (!isObject(value) || isMasked(value)) { - return false; - } - var pattern = isFunction(value) ? reIsNative : reIsHostCtor; - return pattern.test(toSource(value)); -} +var nativeObjectToString = objectProto.toString; -/** - * Gets the value at `key` of `object`. - * - * @private - * @param {Object} [object] The object to query. - * @param {string} key The key of the property to get. - * @returns {*} Returns the property value. - */ -function getValue(object, key) { - return object == null ? undefined : object[key]; -} +/** Built-in value references. */ +var symToStringTag$1 = Symbol$1 ? Symbol$1.toStringTag : undefined; /** - * Gets the native function at `key` of `object`. + * A specialized version of `baseGetTag` which ignores `Symbol.toStringTag` values. * * @private - * @param {Object} object The object to query. - * @param {string} key The key of the method to get. - * @returns {*} Returns the function if it's native, else `undefined`. + * @param {*} value The value to query. + * @returns {string} Returns the raw `toStringTag`. */ -function getNative(object, key) { - var value = getValue(object, key); - return baseIsNative(value) ? value : undefined; -} +function getRawTag(value) { + var isOwn = hasOwnProperty.call(value, symToStringTag$1), + tag = value[symToStringTag$1]; -var defineProperty = (function() { try { - var func = getNative(Object, 'defineProperty'); - func({}, '', {}); - return func; + value[symToStringTag$1] = undefined; + var unmasked = true; } catch (e) {} -}()); -/** - * The base implementation of `setToString` without support for hot loop shorting. - * - * @private - * @param {Function} func The function to modify. - * @param {Function} string The `toString` result. - * @returns {Function} Returns `func`. - */ -var baseSetToString = !defineProperty ? identity : function(func, string) { - return defineProperty(func, 'toString', { - 'configurable': true, - 'enumerable': false, - 'value': constant(string), - 'writable': true - }); -}; + var result = nativeObjectToString.call(value); + if (unmasked) { + if (isOwn) { + value[symToStringTag$1] = tag; + } else { + delete value[symToStringTag$1]; + } + } + return result; +} -/** Used to detect hot functions by number of calls within a span of milliseconds. */ -var HOT_COUNT = 500; -var HOT_SPAN = 16; +/** Used for built-in method references. */ +var objectProto$1 = Object.prototype; -/* Built-in method references for those with the same name as other `lodash` methods. */ -var nativeNow = Date.now; +/** + * Used to resolve the + * [`toStringTag`](http://ecma-international.org/ecma-262/7.0/#sec-object.prototype.tostring) + * of values. + */ +var nativeObjectToString$1 = objectProto$1.toString; /** - * Creates a function that'll short out and invoke `identity` instead - * of `func` when it's called `HOT_COUNT` or more times in `HOT_SPAN` - * milliseconds. + * Converts `value` to a string using `Object.prototype.toString`. * * @private - * @param {Function} func The function to restrict. - * @returns {Function} Returns the new shortable function. + * @param {*} value The value to convert. + * @returns {string} Returns the converted string. */ -function shortOut(func) { - var count = 0, - lastCalled = 0; +function objectToString(value) { + return nativeObjectToString$1.call(value); +} - return function() { - var stamp = nativeNow(), - remaining = HOT_SPAN - (stamp - lastCalled); +/** `Object#toString` result references. */ +var nullTag = '[object Null]'; +var undefinedTag = '[object Undefined]'; - lastCalled = stamp; - if (remaining > 0) { - if (++count >= HOT_COUNT) { - return arguments[0]; - } - } else { - count = 0; - } - return func.apply(undefined, arguments); - }; -} +/** Built-in value references. */ +var symToStringTag = Symbol$1 ? Symbol$1.toStringTag : undefined; /** - * Sets the `toString` method of `func` to return `string`. + * The base implementation of `getTag` without fallbacks for buggy environments. * * @private - * @param {Function} func The function to modify. - * @param {Function} string The `toString` result. - * @returns {Function} Returns `func`. + * @param {*} value The value to query. + * @returns {string} Returns the `toStringTag`. */ -var setToString = shortOut(baseSetToString); +function baseGetTag(value) { + if (value == null) { + return value === undefined ? undefinedTag : nullTag; + } + value = Object(value); + return (symToStringTag && symToStringTag in value) + ? getRawTag(value) + : objectToString(value); +} + +/** `Object#toString` result references. */ +var asyncTag = '[object AsyncFunction]'; +var funcTag = '[object Function]'; +var genTag = '[object GeneratorFunction]'; +var proxyTag = '[object Proxy]'; /** - * The base implementation of `_.rest` which doesn't validate or coerce arguments. + * Checks if `value` is classified as a `Function` object. * - * @private - * @param {Function} func The function to apply a rest parameter to. - * @param {number} [start=func.length-1] The start position of the rest parameter. - * @returns {Function} Returns the new function. + * @static + * @memberOf _ + * @since 0.1.0 + * @category Lang + * @param {*} value The value to check. + * @returns {boolean} Returns `true` if `value` is a function, else `false`. + * @example + * + * _.isFunction(_); + * // => true + * + * _.isFunction(/abc/); + * // => false */ -function baseRest$1(func, start) { - return setToString(overRest(func, start, identity), func + ''); -} - -var initialParams = function (fn) { - return baseRest$1(function (args /*..., callback*/) { - var callback = args.pop(); - fn.call(this, args, callback); - }); -}; - -function applyEach$1(eachfn) { - return baseRest$1(function (fns, args) { - var go = initialParams(function (args, callback) { - var that = this; - return eachfn(fns, function (fn, cb) { - fn.apply(that, args.concat([cb])); - }, callback); - }); - if (args.length) { - return go.apply(this, args); - } else { - return go; - } - }); +function isFunction(value) { + if (!isObject(value)) { + return false; + } + // The use of `Object#toString` avoids issues with the `typeof` operator + // in Safari 9 which returns 'object' for typed arrays and other constructors. + var tag = baseGetTag(value); + return tag == funcTag || tag == genTag || tag == asyncTag || tag == proxyTag; } /** Used as references for various `Number` constants. */ @@ -460,6 +432,10 @@ function isArrayLike(value) { return value != null && isLength(value.length) && !isFunction(value); } +// A temporary value used to identify if the loop should be broken. +// See #1064, #1293 +var breakLoop = {}; + /** * This method returns `undefined`. * @@ -541,16 +517,6 @@ function isObjectLike(value) { /** `Object#toString` result references. */ var argsTag = '[object Arguments]'; -/** Used for built-in method references. */ -var objectProto$4 = Object.prototype; - -/** - * Used to resolve the - * [`toStringTag`](http://ecma-international.org/ecma-262/7.0/#sec-object.prototype.tostring) - * of values. - */ -var objectToString$1 = objectProto$4.toString; - /** * The base implementation of `_.isArguments`. * @@ -559,7 +525,7 @@ var objectToString$1 = objectProto$4.toString; * @returns {boolean} Returns `true` if `value` is an `arguments` object, */ function baseIsArguments(value) { - return isObjectLike(value) && objectToString$1.call(value) == argsTag; + return isObjectLike(value) && baseGetTag(value) == argsTag; } /** Used for built-in method references. */ @@ -734,16 +700,6 @@ typedArrayTags[objectTag] = typedArrayTags[regexpTag] = typedArrayTags[setTag] = typedArrayTags[stringTag] = typedArrayTags[weakMapTag] = false; -/** Used for built-in method references. */ -var objectProto$5 = Object.prototype; - -/** - * Used to resolve the - * [`toStringTag`](http://ecma-international.org/ecma-262/7.0/#sec-object.prototype.tostring) - * of values. - */ -var objectToString$2 = objectProto$5.toString; - /** * The base implementation of `_.isTypedArray` without Node.js optimizations. * @@ -753,7 +709,7 @@ var objectToString$2 = objectProto$5.toString; */ function baseIsTypedArray(value) { return isObjectLike(value) && - isLength(value.length) && !!typedArrayTags[objectToString$2.call(value)]; + isLength(value.length) && !!typedArrayTags[baseGetTag(value)]; } /** @@ -852,7 +808,7 @@ function arrayLikeKeys(value, inherited) { } /** Used for built-in method references. */ -var objectProto$7 = Object.prototype; +var objectProto$5 = Object.prototype; /** * Checks if `value` is likely a prototype object. @@ -863,7 +819,7 @@ var objectProto$7 = Object.prototype; */ function isPrototype(value) { var Ctor = value && value.constructor, - proto = (typeof Ctor == 'function' && Ctor.prototype) || objectProto$7; + proto = (typeof Ctor == 'function' && Ctor.prototype) || objectProto$5; return value === proto; } @@ -886,10 +842,10 @@ function overArg(func, transform) { var nativeKeys = overArg(Object.keys, Object); /** Used for built-in method references. */ -var objectProto$6 = Object.prototype; +var objectProto$4 = Object.prototype; /** Used to check objects for own properties. */ -var hasOwnProperty$3 = objectProto$6.hasOwnProperty; +var hasOwnProperty$3 = objectProto$4.hasOwnProperty; /** * The base implementation of `_.keys` which doesn't treat sparse arrays as dense. @@ -989,10 +945,6 @@ function onlyOnce(fn) { }; } -// A temporary value used to identify if the loop should be broken. -// See #1064, #1293 -var breakLoop = {}; - function _eachOfLimit(limit) { return function (obj, iteratee, callback) { callback = once(callback || noop); @@ -1048,17 +1000,15 @@ function _eachOfLimit(limit) { * @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). */ function eachOfLimit(coll, limit, iteratee, callback) { - _eachOfLimit(limit)(coll, iteratee, callback); + _eachOfLimit(limit)(coll, wrapAsync$1(iteratee), callback); } function doLimit(fn, limit) { @@ -1077,10 +1027,10 @@ function eachOfArrayLike(coll, iteratee, callback) { callback(null); } - function iteratorCallback(err) { + function iteratorCallback(err, value) { if (err) { callback(err); - } else if (++completed === length) { + } else if (++completed === length || value === breakLoop) { callback(null); } } @@ -1105,12 +1055,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 @@ -1136,24 +1084,25 @@ var eachOfGeneric = doLimit(eachOfLimit, Infinity); */ var eachOf = function (coll, iteratee, callback) { var eachOfImplementation = isArrayLike(coll) ? eachOfArrayLike : eachOfGeneric; - eachOfImplementation(coll, iteratee, callback); + eachOfImplementation(coll, wrapAsync$1(iteratee), callback); }; function doParallel(fn) { return function (obj, iteratee, callback) { - return fn(eachOf, obj, iteratee, callback); + return fn(eachOf, obj, wrapAsync$1(iteratee), callback); }; } function _asyncMap(eachfn, arr, iteratee, callback) { - callback = once(callback || noop); + callback = callback || noop; arr = arr || []; var results = []; var counter = 0; + var _iteratee = wrapAsync$1(iteratee); eachfn(arr, function (value, _, callback) { var index = counter++; - iteratee(value, function (err, v) { + _iteratee(value, function (err, v) { results[index] = v; callback(err); }); @@ -1177,7 +1126,7 @@ function _asyncMap(eachfn, arr, iteratee, callback) { * * If `map` is passed an Object, the results will be an Array. The results * will roughly be in the order of the original Objects' keys (but this can - * vary across JavaScript engines) + * vary across JavaScript engines). * * @name map * @static @@ -1185,10 +1134,10 @@ function _asyncMap(eachfn, arr, iteratee, callback) { * @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). @@ -1212,7 +1161,7 @@ var map = doParallel(_asyncMap); * @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. @@ -1237,7 +1186,7 @@ var applyEach = applyEach$1(map); function doParallelLimit(fn) { return function (obj, limit, iteratee, callback) { - return fn(_eachOfLimit(limit), obj, iteratee, callback); + return fn(_eachOfLimit(limit), obj, wrapAsync$1(iteratee), callback); }; } @@ -1252,10 +1201,10 @@ function doParallelLimit(fn) { * @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). @@ -1272,10 +1221,10 @@ var mapLimit = doParallelLimit(_asyncMap); * @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). @@ -1291,7 +1240,7 @@ var mapSeries = doLimit(mapLimit, 1); * @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. @@ -1347,89 +1296,13 @@ var applyEachSeries = applyEach$1(mapSeries); * two * three */ -var apply$2 = baseRest$1(function (fn, args) { - return baseRest$1(function (callArgs) { +var apply$2 = rest(function (fn, args) { + return rest(function (callArgs) { return fn.apply(null, args.concat(callArgs)); }); }); /** - * Take a sync function and make it async, passing its return value to a - * callback. This is useful for plugging sync functions into a waterfall, - * series, or other async functions. Any arguments passed to the generated - * function will be passed to the wrapped function (except for the final - * callback argument). Errors thrown will be passed to the callback. - * - * If the function passed to `asyncify` returns a Promise, that promises's - * resolved/rejected state will be used to call the callback, rather than simply - * the synchronous return value. - * - * This also means you can asyncify ES2016 `async` functions. - * - * @name asyncify - * @static - * @memberOf module:Utils - * @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). - * @example - * - * // passing a regular synchronous function - * async.waterfall([ - * async.apply(fs.readFile, filename, "utf8"), - * async.asyncify(JSON.parse), - * function (data, next) { - * // data is the result of parsing the text. - * // If there was a parsing error, it would have been caught. - * } - * ], callback); - * - * // passing a function returning a promise - * async.waterfall([ - * async.apply(fs.readFile, filename, "utf8"), - * async.asyncify(function (contents) { - * return db.model.create(contents); - * }), - * function (model, next) { - * // `model` is the instantiated model object. - * // If there was an error, this function would be skipped. - * } - * ], callback); - * - * // es6 example - * var q = async.queue(async.asyncify(async function(file) { - * var intermediateStep = await processFile(file); - * return await somePromise(intermediateStep) - * })); - * - * q.push(files); - */ -function asyncify(func) { - return initialParams(function (args, callback) { - var result; - try { - result = func.apply(this, args); - } catch (e) { - return callback(e); - } - // if result is Promise object - if (isObject(result) && typeof result.then === 'function') { - result.then(function (value) { - callback(null, value); - }, function (err) { - callback(err.message ? err : new Error(err)); - }); - } else { - callback(null, result); - } - }); -} - -/** * A specialized version of `_.forEach` for arrays without support for * iteratee shorthands. * @@ -1440,7 +1313,7 @@ function asyncify(func) { */ function arrayEach(array, iteratee) { var index = -1, - length = array ? array.length : 0; + length = array == null ? 0 : array.length; while (++index < length) { if (iteratee(array[index], index, array) === false) { @@ -1571,17 +1444,17 @@ function baseIndexOf(array, value, fromIndex) { } /** - * 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. * @@ -1591,7 +1464,7 @@ function baseIndexOf(array, value, fromIndex) { * @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: @@ -1669,7 +1542,7 @@ var auto = function (tasks, concurrency, callback) { var runningTasks = 0; var hasError = false; - var listeners = {}; + var listeners = Object.create(null); var readyTasks = []; @@ -1697,7 +1570,7 @@ var auto = function (tasks, concurrency, callback) { arrayEach(dependencies, function (dependencyName) { if (!tasks[dependencyName]) { - throw new Error('async.auto task `' + key + '` has a non-existent dependency in ' + dependencies.join(', ')); + throw new Error('async.auto task `' + key + '` has a non-existent dependency `' + dependencyName + '` in ' + dependencies.join(', ')); } addListener(dependencyName, function () { remainingDependencies--; @@ -1747,7 +1620,7 @@ var auto = function (tasks, concurrency, callback) { function runTask(key, task) { if (hasError) return; - var taskCallback = onlyOnce(baseRest$1(function (err, args) { + var taskCallback = onlyOnce(rest(function (err, args) { runningTasks--; if (args.length <= 1) { args = args[0]; @@ -1759,7 +1632,7 @@ var auto = function (tasks, concurrency, callback) { }); safeResults[key] = args; hasError = true; - listeners = []; + listeners = Object.create(null); callback(err, safeResults); } else { @@ -1769,7 +1642,7 @@ var auto = function (tasks, concurrency, callback) { })); runningTasks++; - var taskFn = task[task.length - 1]; + var taskFn = wrapAsync$1(task[task.length - 1]); if (task.length > 1) { taskFn(results, taskCallback); } else { @@ -1820,7 +1693,7 @@ var auto = function (tasks, concurrency, callback) { */ function arrayMap(array, iteratee) { var index = -1, - length = array ? array.length : 0, + length = array == null ? 0 : array.length, result = Array(length); while (++index < length) { @@ -1829,41 +1702,9 @@ function arrayMap(array, iteratee) { return result; } -/** - * Copies the values of `source` to `array`. - * - * @private - * @param {Array} source The array to copy values from. - * @param {Array} [array=[]] The array to copy values to. - * @returns {Array} Returns `array`. - */ -function copyArray(source, array) { - var index = -1, - length = source.length; - - array || (array = Array(length)); - while (++index < length) { - array[index] = source[index]; - } - return array; -} - -/** Built-in value references. */ -var Symbol$1 = root.Symbol; - /** `Object#toString` result references. */ var symbolTag = '[object Symbol]'; -/** Used for built-in method references. */ -var objectProto$8 = Object.prototype; - -/** - * Used to resolve the - * [`toStringTag`](http://ecma-international.org/ecma-262/7.0/#sec-object.prototype.tostring) - * of values. - */ -var objectToString$3 = objectProto$8.toString; - /** * Checks if `value` is classified as a `Symbol` primitive or object. * @@ -1883,7 +1724,7 @@ var objectToString$3 = objectProto$8.toString; */ function isSymbol(value) { return typeof value == 'symbol' || - (isObjectLike(value) && objectToString$3.call(value) == symbolTag); + (isObjectLike(value) && baseGetTag(value) == symbolTag); } /** Used as references for various `Number` constants. */ @@ -2145,7 +1986,7 @@ function trim(string, chars, guard) { return castSlice(strSymbols, start, end).join(''); } -var FN_ARGS = /^(function)?\s*[^\(]*\(\s*([^\)]*)\)/m; +var FN_ARGS = /^(?:async\s+)?(function)?\s*[^\(]*\(\s*([^\)]*)\)/m; var FN_ARG_SPLIT = /,/; var FN_ARG = /(=.+)?(\s*)$/; var STRIP_COMMENTS = /((\/\/.*$)|(\/\*[\s\S]*?\*\/))/mg; @@ -2179,7 +2020,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. @@ -2247,22 +2088,25 @@ function autoInject(tasks, callback) { baseForOwn(tasks, function (taskFn, key) { var params; + var fnIsAsync = isAsync(taskFn); + var hasNoDeps = !fnIsAsync && taskFn.length === 1 || fnIsAsync && taskFn.length === 0; if (isArray(taskFn)) { - params = copyArray(taskFn); - taskFn = params.pop(); + params = taskFn.slice(0, -1); + taskFn = taskFn[taskFn.length - 1]; newTasks[key] = params.concat(params.length > 0 ? newTask : taskFn); - } else if (taskFn.length === 1) { + } else if (hasNoDeps) { // no dependencies, use the function as-is newTasks[key] = taskFn; } else { params = parseParams(taskFn); - if (taskFn.length === 0 && params.length === 0) { + if (taskFn.length === 0 && !fnIsAsync && params.length === 0) { throw new Error("autoInject task functions require explicit parameters."); } - params.pop(); + // remove callback param + if (!fnIsAsync) params.pop(); newTasks[key] = params.concat(newTask); } @@ -2272,7 +2116,7 @@ function autoInject(tasks, callback) { return results[name]; }); newArgs.push(taskCb); - taskFn.apply(null, newArgs); + wrapAsync$1(taskFn).apply(null, newArgs); } }); @@ -2287,7 +2131,7 @@ function fallback(fn) { } function wrap(defer) { - return baseRest$1(function (fn, args) { + return rest(function (fn, args) { defer(function () { fn.apply(null, args); }); @@ -2370,6 +2214,10 @@ function queue(worker, concurrency, payload) { throw new Error('Concurrency must not be zero'); } + var _worker = wrapAsync$1(worker); + var numRunning = 0; + var workersList = []; + function _insert(data, insertAtFront, callback) { if (callback != null && typeof callback !== 'function') { throw new Error('task callback must be a function'); @@ -2401,8 +2249,8 @@ function queue(worker, concurrency, payload) { } function _next(tasks) { - return baseRest$1(function (args) { - workers -= 1; + return rest(function (args) { + numRunning -= 1; for (var i = 0, l = tasks.length; i < l; i++) { var task = tasks[i]; @@ -2418,7 +2266,7 @@ function queue(worker, concurrency, payload) { } } - if (workers <= q.concurrency - q.buffer) { + if (numRunning <= q.concurrency - q.buffer) { q.unsaturated(); } @@ -2429,8 +2277,7 @@ function queue(worker, concurrency, payload) { }); } - var workers = 0; - var workersList = []; + var isProcessing = false; var q = { _tasks: new DLL(), concurrency: concurrency, @@ -2454,7 +2301,13 @@ function queue(worker, concurrency, payload) { _insert(data, true, callback); }, process: function () { - while (!q.paused && workers < q.concurrency && q._tasks.length) { + // Avoid trying to start too many processing operations. This can occur + // when callbacks resolve synchronously (#1267). + if (isProcessing) { + return; + } + isProcessing = true; + while (!q.paused && numRunning < q.concurrency && q._tasks.length) { var tasks = [], data = []; var l = q._tasks.length; @@ -2468,28 +2321,29 @@ function queue(worker, concurrency, payload) { if (q._tasks.length === 0) { q.empty(); } - workers += 1; + numRunning += 1; workersList.push(tasks[0]); - if (workers === q.concurrency) { + if (numRunning === q.concurrency) { q.saturated(); } var cb = onlyOnce(_next(tasks)); - worker(data, cb); + _worker(data, cb); } + isProcessing = false; }, length: function () { return q._tasks.length; }, running: function () { - return workers; + return numRunning; }, workersList: function () { return workersList; }, idle: function () { - return q._tasks.length + workers === 0; + return q._tasks.length + numRunning === 0; }, pause: function () { q.paused = true; @@ -2499,12 +2353,7 @@ function queue(worker, concurrency, payload) { return; } q.paused = false; - var resumeCount = Math.min(q.concurrency, q._tasks.length); - // Need to call q.process once per concurrent - // worker to preserve full concurrency after pause - for (var w = 1; w <= resumeCount; w++) { - setImmediate$1(q.process); - } + setImmediate$1(q.process); } }; return q; @@ -2558,9 +2407,8 @@ function queue(worker, concurrency, payload) { * @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. @@ -2603,11 +2451,9 @@ function cargo(worker, payload) { * @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). */ @@ -2633,12 +2479,12 @@ var eachOfSeries = doLimit(eachOfLimit, 1); * @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). @@ -2655,8 +2501,9 @@ var eachOfSeries = doLimit(eachOfLimit, 1); */ function reduce(coll, memo, iteratee, callback) { callback = once(callback || noop); + var _iteratee = wrapAsync$1(iteratee); eachOfSeries(coll, function (x, i, callback) { - iteratee(memo, x, function (err, v) { + _iteratee(memo, x, function (err, v) { memo = v; callback(err); }); @@ -2678,7 +2525,7 @@ function reduce(coll, memo, iteratee, callback) { * @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 * @@ -2703,8 +2550,9 @@ function reduce(coll, memo, iteratee, callback) { * }); * }); */ -var seq$1 = baseRest$1(function seq(functions) { - return baseRest$1(function (args) { +var seq$1 = rest(function seq(functions) { + var _functions = arrayMap(functions, wrapAsync$1); + return rest(function (args) { var that = this; var cb = args[args.length - 1]; @@ -2714,10 +2562,10 @@ var seq$1 = baseRest$1(function seq(functions) { cb = noop; } - reduce(functions, args, function (newargs, fn, cb) { - fn.apply(that, newargs.concat([baseRest$1(function (err, nextargs) { + reduce(_functions, args, function (newargs, fn, cb) { + fn.apply(that, newargs.concat(rest(function (err, nextargs) { cb(err, nextargs); - })])); + }))); }, function (err, results) { cb.apply(that, [err].concat(results)); }); @@ -2737,7 +2585,7 @@ var seq$1 = baseRest$1(function seq(functions) { * @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 @@ -2759,7 +2607,7 @@ var seq$1 = baseRest$1(function seq(functions) { * // result now equals 15 * }); */ -var compose = baseRest$1(function (args) { +var compose = rest(function (args) { return seq$1.apply(null, args.reverse()); }); @@ -2788,10 +2636,8 @@ function concat$1(eachfn, arr, fn, callback) { * @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 @@ -2806,7 +2652,7 @@ var concat = doParallel(concat$1); function doSeries(fn) { return function (obj, iteratee, callback) { - return fn(eachOfSeries, obj, iteratee, callback); + return fn(eachOfSeries, obj, wrapAsync$1(iteratee), callback); }; } @@ -2820,9 +2666,8 @@ function doSeries(fn) { * @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 @@ -2843,7 +2688,7 @@ var concatSeries = doSeries(concat$1); * @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 * @@ -2873,43 +2718,37 @@ var concatSeries = doSeries(concat$1); * //... * }, callback); */ -var constant$2 = baseRest$1(function (values) { +var constant = rest(function (values) { var args = [null].concat(values); return initialParams(function (ignoredArgs, callback) { return callback.apply(this, args); }); }); -function _createTester(eachfn, check, getResult) { - return function (arr, limit, iteratee, cb) { - function done() { - if (cb) { - cb(null, getResult(false)); - } - } - function wrappedIteratee(x, _, callback) { - if (!cb) return callback(); - iteratee(x, function (err, v) { - // Check cb as another iteratee may have resolved with a - // value or error since we started this iteratee - if (cb && (err || check(v))) { - if (err) cb(err);else cb(err, getResult(true, x)); - cb = iteratee = false; - callback(err, breakLoop); +function _createTester(check, getResult) { + return function (eachfn, arr, iteratee, cb) { + cb = cb || noop; + var testPassed = false; + var testResult; + eachfn(arr, function (value, _, callback) { + iteratee(value, function (err, result) { + if (err) { + callback(err); + } else if (check(result) && !testResult) { + testPassed = true; + testResult = getResult(true, value); + callback(null, breakLoop); } else { callback(); } }); - } - if (arguments.length > 3) { - cb = cb || noop; - eachfn(arr, limit, wrappedIteratee, done); - } else { - cb = iteratee; - cb = cb || noop; - iteratee = limit; - eachfn(arr, wrappedIteratee, done); - } + }, function (err) { + if (err) { + cb(err); + } else { + cb(null, testPassed ? testResult : getResult(false)); + } + }); }; } @@ -2934,9 +2773,9 @@ function _findGetResult(v, x) { * @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 @@ -2952,7 +2791,7 @@ function _findGetResult(v, x) { * // result now equals the first file in the list that exists * }); */ -var detect = _createTester(eachOf, identity, _findGetResult); +var detect = doParallel(_createTester(identity, _findGetResult)); /** * The same as [`detect`]{@link module:Collections.detect} but runs a maximum of `limit` async operations at a @@ -2967,16 +2806,16 @@ var detect = _createTester(eachOf, identity, _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 * (iteratee) or the value `undefined` if none passed. Invoked with * (err, result). */ -var detectLimit = _createTester(eachOfLimit, identity, _findGetResult); +var detectLimit = doParallelLimit(_createTester(identity, _findGetResult)); /** * The same as [`detect`]{@link module:Collections.detect} but runs only a single async operation at a time. @@ -2989,20 +2828,20 @@ var detectLimit = _createTester(eachOfLimit, identity, _findGetResult); * @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 * (iteratee) or the value `undefined` if none passed. Invoked with * (err, result). */ -var detectSeries = _createTester(eachOfSeries, identity, _findGetResult); +var detectSeries = doLimit(detectLimit, 1); function consoleFunc(name) { - return baseRest$1(function (fn, args) { - fn.apply(null, args.concat([baseRest$1(function (err, args) { + return rest(function (fn, args) { + wrapAsync$1(fn).apply(null, args.concat(rest(function (err, args) { if (typeof console === 'object') { if (err) { if (console.error) { @@ -3014,15 +2853,16 @@ function consoleFunc(name) { }); } } - })])); + }))); }); } /** - * 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 @@ -3030,8 +2870,8 @@ function consoleFunc(name) { * @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 * @@ -3059,29 +2899,30 @@ var dir = consoleFunc('dir'); * @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 * function has failed and repeated execution of `fn` has stopped. `callback` - * will be passed an error if one occured, otherwise `null`. + * will be passed an error if one occurred, otherwise `null`. */ function doDuring(fn, test, callback) { callback = onlyOnce(callback || noop); + var _fn = wrapAsync$1(fn); + var _test = wrapAsync$1(test); - var next = baseRest$1(function (err, args) { + var next = rest(function (err, args) { if (err) return callback(err); args.push(check); - test.apply(this, args); + _test.apply(this, args); }); function check(err, truth) { if (err) return callback(err); if (!truth) return callback(null); - fn(next); + _fn(next); } check(null, true); @@ -3099,11 +2940,10 @@ function doDuring(fn, test, callback) { * @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. @@ -3112,12 +2952,13 @@ function doDuring(fn, test, callback) { */ function doWhilst(iteratee, test, callback) { callback = onlyOnce(callback || noop); - var next = baseRest$1(function (err, args) { + var _iteratee = wrapAsync$1(iteratee); + var next = rest(function (err, args) { if (err) return callback(err); - if (test.apply(this, args)) return iteratee(next); + if (test.apply(this, args)) return _iteratee(next); callback.apply(null, [null].concat(args)); }); - iteratee(next); + _iteratee(next); } /** @@ -3130,18 +2971,18 @@ function doWhilst(iteratee, test, callback) { * @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]); */ -function doUntil(fn, test, callback) { - doWhilst(fn, function () { +function doUntil(iteratee, test, callback) { + doWhilst(iteratee, function () { return !test.apply(this, arguments); }, callback); } @@ -3158,14 +2999,13 @@ function doUntil(fn, test, callback) { * @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`. + * will be passed an error, if one occurred, otherwise `null`. * @example * * var count = 0; @@ -3185,19 +3025,21 @@ function doUntil(fn, test, callback) { */ function during(test, fn, callback) { callback = onlyOnce(callback || noop); + var _fn = wrapAsync$1(fn); + var _test = wrapAsync$1(test); function next(err) { if (err) return callback(err); - test(check); + _test(check); } function check(err, truth) { if (err) return callback(err); if (!truth) return callback(null); - fn(next); + _fn(next); } - test(check); + _test(check); } function _withoutIndex(iteratee) { @@ -3223,12 +3065,10 @@ function _withoutIndex(iteratee) { * @alias forEach * @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 `eachOf`. + * @param {AsyncFunction} iteratee - An async function to apply to + * each item in `coll`. Invoked with (item, callback). + * The array index is not passed to the iteratee. + * 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 @@ -3266,7 +3106,7 @@ function _withoutIndex(iteratee) { * }); */ function eachLimit(coll, iteratee, callback) { - eachOf(coll, _withoutIndex(iteratee), callback); + eachOf(coll, _withoutIndex(wrapAsync$1(iteratee)), callback); } /** @@ -3281,17 +3121,16 @@ function eachLimit(coll, iteratee, callback) { * @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). */ function eachLimit$1(coll, limit, iteratee, callback) { - _eachOfLimit(limit)(coll, _withoutIndex(iteratee), callback); + _eachOfLimit(limit)(coll, _withoutIndex(wrapAsync$1(iteratee)), callback); } /** @@ -3305,12 +3144,11 @@ function eachLimit$1(coll, limit, iteratee, callback) { * @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). */ @@ -3322,16 +3160,17 @@ var eachSeries = doLimit(eachLimit$1, 1); * 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 * @@ -3351,6 +3190,7 @@ var eachSeries = doLimit(eachLimit$1, 1); * async.mapSeries(args, async.ensureAsync(sometimesAsync), done); */ function ensureAsync(fn) { + if (isAsync(fn)) return fn; return initialParams(function (args, callback) { var sync = true; args.push(function () { @@ -3383,10 +3223,10 @@ function notId(v) { * @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). @@ -3400,7 +3240,7 @@ function notId(v) { * // if result is true then every file exists * }); */ -var every = _createTester(eachOf, notId, notId); +var every = doParallel(_createTester(notId, notId)); /** * The same as [`every`]{@link module:Collections.every} but runs a maximum of `limit` async operations at a time. @@ -3414,15 +3254,15 @@ var every = _createTester(eachOf, notId, 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). */ -var everyLimit = _createTester(eachOfLimit, notId, notId); +var everyLimit = doParallelLimit(_createTester(notId, notId)); /** * The same as [`every`]{@link module:Collections.every} but runs only a single async operation at a time. @@ -3435,10 +3275,10 @@ var everyLimit = _createTester(eachOfLimit, notId, notId); * @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). @@ -3458,11 +3298,27 @@ function baseProperty(key) { }; } -function _filter(eachfn, arr, iteratee, callback) { - callback = once(callback || noop); - var results = []; +function filterArray(eachfn, arr, iteratee, callback) { + var truthValues = new Array(arr.length); eachfn(arr, function (x, index, callback) { iteratee(x, function (err, v) { + truthValues[index] = !!v; + callback(err); + }); + }, function (err) { + if (err) return callback(err); + var results = []; + for (var i = 0; i < arr.length; i++) { + if (truthValues[i]) results.push(arr[i]); + } + callback(null, results); + }); +} + +function filterGeneric(eachfn, coll, iteratee, callback) { + var results = []; + eachfn(coll, function (x, index, callback) { + iteratee(x, function (err, v) { if (err) { callback(err); } else { @@ -3483,6 +3339,11 @@ function _filter(eachfn, arr, iteratee, callback) { }); } +function _filter(eachfn, coll, iteratee, callback) { + var filter = isArrayLike(coll) ? filterArray : filterGeneric; + filter(eachfn, coll, wrapAsync$1(iteratee), callback || noop); +} + /** * 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 @@ -3556,16 +3417,16 @@ var filterSeries = doLimit(filterLimit, 1); * Calls the asynchronous function `fn` with a callback parameter that allows it * to call itself again, in series, indefinitely. - * If an error is passed to the - * callback then `errback` is called with the error, and execution stops, - * otherwise it will never be called. + * 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 @@ -3583,7 +3444,7 @@ var filterSeries = doLimit(filterLimit, 1); */ function forever(fn, errback) { var done = onlyOnce(errback || noop); - var task = ensureAsync(fn); + var task = wrapAsync$1(ensureAsync(fn)); function next(err) { if (err) return done(err); @@ -3593,6 +3454,114 @@ function forever(fn, errback) { } /** + * The same as [`groupBy`]{@link module:Collections.groupBy} but runs a maximum of `limit` async operations at a time. + * + * @name groupByLimit + * @static + * @memberOf module:Collections + * @method + * @see [async.groupBy]{@link module:Collections.groupBy} + * @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 {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. + */ +var groupByLimit = function (coll, limit, iteratee, callback) { + callback = callback || noop; + var _iteratee = wrapAsync$1(iteratee); + mapLimit(coll, limit, function (val, callback) { + _iteratee(val, function (err, key) { + if (err) return callback(err); + return callback(null, { key: key, val: val }); + }); + }, function (err, mapResults) { + var result = {}; + // from MDN, handle object having an `hasOwnProperty` prop + var hasOwnProperty = Object.prototype.hasOwnProperty; + + for (var i = 0; i < mapResults.length; i++) { + if (mapResults[i]) { + var key = mapResults[i].key; + var val = mapResults[i].val; + + if (hasOwnProperty.call(result, key)) { + result[key].push(val); + } else { + result[key] = [val]; + } + } + } + + return callback(err, result); + }); +}; + +/** + * Returns a new object, where each value corresponds to an array of items, from + * `coll`, that returned the corresponding key. That is, the keys of the object + * correspond to the values passed to the `iteratee` callback. + * + * Note: 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 values for each key in the `result` will be in the same order as + * the original `coll`. For Objects, the values will roughly be in the order of + * the original Objects' keys (but this can vary across JavaScript engines). + * + * @name groupBy + * @static + * @memberOf module:Collections + * @method + * @category Collection + * @param {Array|Iterable|Object} coll - A collection to iterate over. + * @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. + * @example + * + * async.groupBy(['userId1', 'userId2', 'userId3'], function(userId, callback) { + * db.findById(userId, function(err, user) { + * if (err) return callback(err); + * return callback(null, user.age); + * }); + * }, function(err, result) { + * // result is object containing the userIds grouped by age + * // e.g. { 30: ['userId1', 'userId3'], 42: ['userId2']}; + * }); + */ +var groupBy = doLimit(groupByLimit, Infinity); + +/** + * The same as [`groupBy`]{@link module:Collections.groupBy} but runs only a single async operation at a time. + * + * @name groupBySeries + * @static + * @memberOf module:Collections + * @method + * @see [async.groupBy]{@link module:Collections.groupBy} + * @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 {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. + */ +var groupBySeries = doLimit(groupByLimit, 1); + +/** * Logs the result of an `async` function to the `console`. Only works in * Node.js or in browsers that support `console.log` and `console.error` (such * as FF and Chrome). If multiple arguments are returned from the async @@ -3603,8 +3572,8 @@ function forever(fn, errback) { * @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 * @@ -3633,10 +3602,10 @@ var log = consoleFunc('log'); * @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. @@ -3645,8 +3614,9 @@ var log = consoleFunc('log'); function mapValuesLimit(obj, limit, iteratee, callback) { callback = once(callback || noop); var newObj = {}; + var _iteratee = wrapAsync$1(iteratee); eachOfLimit(obj, limit, function (val, key, next) { - iteratee(val, key, function (err, result) { + _iteratee(val, key, function (err, result) { if (err) return next(err); newObj[key] = result; next(); @@ -3675,10 +3645,10 @@ function mapValuesLimit(obj, limit, iteratee, callback) { * @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. @@ -3713,10 +3683,10 @@ var mapValues = doLimit(mapValuesLimit, Infinity); * @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. @@ -3729,7 +3699,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. * @@ -3747,11 +3717,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) { @@ -3769,6 +3739,7 @@ function memoize(fn, hasher) { var memo = Object.create(null); var queues = Object.create(null); hasher = hasher || identity; + var _fn = wrapAsync$1(fn); var memoized = initialParams(function memoized(args, callback) { var key = hasher.apply(null, args); if (has(memo, key)) { @@ -3779,14 +3750,14 @@ function memoize(fn, hasher) { queues[key].push(callback); } else { queues[key] = [callback]; - fn.apply(null, args.concat([baseRest$1(function (args) { + _fn.apply(null, args.concat(rest(function (args) { memo[key] = args; var q = queues[key]; delete queues[key]; for (var i = 0, l = q.length; i < l; i++) { q[i].apply(null, args); } - })])); + }))); } }); memoized.memo = memo; @@ -3842,7 +3813,7 @@ function _parallel(eachfn, tasks, callback) { var results = isArrayLike(tasks) ? [] : {}; eachfn(tasks, function (task, key, callback) { - task(baseRest$1(function (err, args) { + wrapAsync$1(task)(rest(function (err, args) { if (args.length <= 1) { args = args[0]; } @@ -3867,6 +3838,9 @@ function _parallel(eachfn, tasks, callback) { * 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. + * * It is also possible to use an object instead of an array. Each property will * be run as a function and the results will be passed to the final `callback` * as an object instead of an array. This can be a more readable way of handling @@ -3877,14 +3851,14 @@ function _parallel(eachfn, tasks, callback) { * @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) { @@ -3934,10 +3908,9 @@ function parallelLimit(tasks, callback) { * @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 @@ -4006,11 +3979,9 @@ function parallelLimit$1(tasks, limit, callback) { * @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. @@ -4049,8 +4020,9 @@ function parallelLimit$1(tasks, limit, callback) { * }); */ var queue$1 = function (worker, concurrency) { + var _worker = wrapAsync$1(worker); return queue(function (items, cb) { - worker(items[0], cb); + _worker(items[0], cb); }, concurrency, 1); }; @@ -4064,11 +4036,10 @@ var queue$1 = function (worker, concurrency) { * @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. @@ -4138,9 +4109,8 @@ var priorityQueue = function (worker, concurrency) { * @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). @@ -4169,7 +4139,7 @@ function race(tasks, callback) { if (!isArray(tasks)) return callback(new TypeError('First argument to race must be an array of functions')); if (!tasks.length) return callback(); for (var i = 0, l = tasks.length; i < l; i++) { - tasks[i](callback); + wrapAsync$1(tasks[i])(callback); } } @@ -4187,12 +4157,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). @@ -4203,17 +4173,17 @@ function reduceRight(array, memo, iteratee, callback) { } /** - * 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. @@ -4242,8 +4212,9 @@ function reduceRight(array, memo, iteratee, callback) { * }); */ function reflect(fn) { + var _fn = wrapAsync$1(fn); return initialParams(function reflectOn(args, reflectCallback) { - args.push(baseRest$1(function callback(err, cbArgs) { + args.push(rest(function callback(err, cbArgs) { if (err) { reflectCallback(null, { error: err @@ -4261,18 +4232,14 @@ function reflect(fn) { } })); - return fn.apply(this, args); + return _fn.apply(this, args); }); } function reject$1(eachfn, arr, iteratee, callback) { _filter(eachfn, arr, function (value, cb) { iteratee(value, function (err, v) { - if (err) { - cb(err); - } else { - cb(null, !v); - } + cb(err, !v); }); }, callback); } @@ -4287,9 +4254,10 @@ function reject$1(eachfn, arr, iteratee, callback) { * @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 @@ -4306,7 +4274,7 @@ function reject$1(eachfn, arr, iteratee, callback) { var reject = doParallel(reject$1); /** - * 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 @@ -4314,8 +4282,9 @@ var reject = doParallel(reject$1); * @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 * @@ -4396,9 +4365,10 @@ function reflectAll(tasks) { * @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). */ @@ -4414,15 +4384,41 @@ var rejectLimit = doParallelLimit(reject$1); * @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). */ var rejectSeries = doLimit(rejectLimit, 1); /** + * Creates a function that returns `value`. + * + * @static + * @memberOf _ + * @since 2.4.0 + * @category Util + * @param {*} value The value to return from the new function. + * @returns {Function} Returns the new constant function. + * @example + * + * var objects = _.times(2, _.constant({ 'a': 1 })); + * + * console.log(objects); + * // => [{ 'a': 1 }, { 'a': 1 }] + * + * console.log(objects[0] === objects[1]); + * // => true + */ +function constant$1(value) { + return function() { + return value; + }; +} + +/** * Attempts to get a successful response from `task` no more than `times` times * before returning an error. If the task is successful, the `callback` will be * passed the result of the successful task. If all attempts fail, the callback @@ -4433,6 +4429,7 @@ var rejectSeries = doLimit(rejectLimit, 1); * @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 @@ -4447,16 +4444,13 @@ var rejectSeries = doLimit(rejectLimit, 1); * 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 @@ -4502,7 +4496,7 @@ var rejectSeries = doLimit(rejectLimit, 1); * // 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 * }); @@ -4514,14 +4508,14 @@ function retry(opts, task, callback) { var options = { times: DEFAULT_TIMES, - intervalFunc: constant(DEFAULT_INTERVAL) + intervalFunc: constant$1(DEFAULT_INTERVAL) }; function parseTimes(acc, t) { if (typeof t === 'object') { acc.times = +t.times || DEFAULT_TIMES; - acc.intervalFunc = typeof t.interval === 'function' ? t.interval : constant(+t.interval || DEFAULT_INTERVAL); + acc.intervalFunc = typeof t.interval === 'function' ? t.interval : constant$1(+t.interval || DEFAULT_INTERVAL); acc.errorFilter = t.errorFilter; } else if (typeof t === 'number' || typeof t === 'string') { @@ -4543,9 +4537,11 @@ function retry(opts, task, callback) { throw new Error("Invalid arguments for async.retry"); } + var _task = wrapAsync$1(task); + var attempt = 1; function retryAttempt() { - task(function (err) { + _task(function (err) { if (err && attempt++ < options.times && (typeof options.errorFilter != 'function' || options.errorFilter(err))) { setTimeout(retryAttempt, options.intervalFunc(attempt)); } else { @@ -4558,8 +4554,9 @@ function retry(opts, task, callback) { } /** - * 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 @@ -4569,9 +4566,12 @@ function retry(opts, task, callback) { * @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({ @@ -4586,9 +4586,10 @@ var retryable = function (opts, task) { task = opts; opts = null; } + var _task = wrapAsync$1(task); return initialParams(function (args, callback) { function taskFn(cb) { - task.apply(null, args.concat([cb])); + _task.apply(null, args.concat(cb)); } if (opts) retry(opts, taskFn, callback);else retry(taskFn, callback); @@ -4621,9 +4622,9 @@ var retryable = function (opts, task) { * @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 @@ -4675,10 +4676,10 @@ function series(tasks, callback) { * @alias any * @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 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 @@ -4693,7 +4694,7 @@ function series(tasks, callback) { * // if result is true then at least one of the files exists * }); */ -var some = _createTester(eachOf, Boolean, identity); +var some = doParallel(_createTester(Boolean, identity)); /** * The same as [`some`]{@link module:Collections.some} but runs a maximum of `limit` async operations at a time. @@ -4707,16 +4708,16 @@ var some = _createTester(eachOf, Boolean, 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 * tests. Invoked with (err, result). */ -var someLimit = _createTester(eachOfLimit, Boolean, identity); +var someLimit = doParallelLimit(_createTester(Boolean, identity)); /** * The same as [`some`]{@link module:Collections.some} but runs only a single async operation at a time. @@ -4729,10 +4730,10 @@ var someLimit = _createTester(eachOfLimit, Boolean, identity); * @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 @@ -4750,10 +4751,11 @@ var someSeries = doLimit(someLimit, 1); * @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` @@ -4787,8 +4789,9 @@ var someSeries = doLimit(someLimit, 1); * }); */ function sortBy(coll, iteratee, callback) { + var _iteratee = wrapAsync$1(iteratee); map(coll, function (x, callback) { - iteratee(x, function (err, criteria) { + _iteratee(x, function (err, criteria) { if (err) return callback(err); callback(null, { value: x, criteria: criteria }); }); @@ -4814,14 +4817,13 @@ function sortBy(coll, iteratee, callback) { * @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) { @@ -4868,11 +4870,13 @@ function timeout(asyncFn, milliseconds, info) { originalCallback(error); } + var fn = wrapAsync$1(asyncFn); + return initialParams(function (args, origCallback) { originalCallback = origCallback; // setup timer and call original function timer = setTimeout(timeoutCallback, milliseconds); - asyncFn.apply(null, args.concat(injectedCallback)); + fn.apply(null, args.concat(injectedCallback)); }); } @@ -4915,12 +4919,13 @@ function baseRange(start, end, step, fromRight) { * @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}. */ function timeLimit(count, limit, iteratee, callback) { - mapLimit(baseRange(0, count, 1), limit, iteratee, callback); + var _iteratee = wrapAsync$1(iteratee); + mapLimit(baseRange(0, count, 1), limit, _iteratee, callback); } /** @@ -4934,8 +4939,8 @@ function timeLimit(count, limit, iteratee, callback) { * @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 * @@ -4967,8 +4972,8 @@ var times = doLimit(timeLimit, Infinity); * @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}. */ var timesSeries = doLimit(timeLimit, 1); @@ -4986,11 +4991,8 @@ var timesSeries = doLimit(timeLimit, 1); * @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. @@ -5019,15 +5021,16 @@ var timesSeries = doLimit(timeLimit, 1); * }) */ function transform(coll, accumulator, iteratee, callback) { - if (arguments.length === 3) { + if (arguments.length <= 3) { callback = iteratee; iteratee = accumulator; accumulator = isArray(coll) ? [] : {}; } callback = once(callback || noop); + var _iteratee = wrapAsync$1(iteratee); eachOf(coll, function (v, k, cb) { - iteratee(accumulator, v, k, cb); + _iteratee(accumulator, v, k, cb); }, function (err) { callback(err, accumulator); }); @@ -5043,8 +5046,8 @@ function transform(coll, accumulator, iteratee, callback) { * @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 */ function unmemoize(fn) { return function () { @@ -5063,9 +5066,8 @@ function unmemoize(fn) { * @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} iteratee - 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 @@ -5089,19 +5091,20 @@ function unmemoize(fn) { */ function whilst(test, iteratee, callback) { callback = onlyOnce(callback || noop); + var _iteratee = wrapAsync$1(iteratee); if (!test()) return callback(null); - var next = baseRest$1(function (err, args) { + var next = rest(function (err, args) { if (err) return callback(err); - if (test()) return iteratee(next); + if (test()) return _iteratee(next); callback.apply(null, [null].concat(args)); }); - iteratee(next); + _iteratee(next); } /** - * Repeatedly call `fn` until `test` returns `true`. Calls `callback` when + * Repeatedly call `iteratee` until `test` returns `true`. Calls `callback` when * stopped, or an error occurs. `callback` will be passed an error and any - * arguments passed to the final `fn`'s callback. + * arguments passed to the final `iteratee`'s callback. * * The inverse of [whilst]{@link module:ControlFlow.whilst}. * @@ -5112,19 +5115,18 @@ function whilst(test, iteratee, callback) { * @see [async.whilst]{@link module:ControlFlow.whilst} * @category Control Flow * @param {Function} test - synchronous truth test to perform before each - * execution of `fn`. Invoked with (). - * @param {Function} fn - A function which is called each time `test` fails. - * The function is passed a `callback(err)`, which must be called once it has - * completed with an optional `err` argument. Invoked with (callback). + * execution of `iteratee`. Invoked with (). + * @param {AsyncFunction} iteratee - An async function which is called each time + * `test` fails. Invoked with (callback). * @param {Function} [callback] - A callback which is called after the test - * function has passed and repeated execution of `fn` has stopped. `callback` - * will be passed an error and any arguments passed to the final `fn`'s + * 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]); */ -function until(test, fn, callback) { +function until(test, iteratee, callback) { whilst(function () { return !test.apply(this, arguments); - }, fn, callback); + }, iteratee, callback); } /** @@ -5138,10 +5140,10 @@ function until(test, fn, callback) { * @memberOf module:ControlFlow * @method * @category Control Flow - * @param {Array} tasks - An array of functions to run, each function is passed - * a `callback(err, result1, result2, ...)` it must call on completion. The - * first argument is an error (which can be `null`) and any further arguments - * will be passed as arguments in order to the next task. + * @param {Array} tasks - An array of [async functions]{@link AsyncFunction} + * to run. + * Each function should complete with any number of `result` values. + * The `result` values will be passed as arguments, in order, to the next task. * @param {Function} [callback] - An optional callback to run once all the * functions have completed. This will be passed the results of the last task's * callback. Invoked with (err, [results]). @@ -5195,7 +5197,7 @@ var waterfall = function (tasks, callback) { return callback.apply(null, [null].concat(args)); } - var taskCallback = onlyOnce(baseRest$1(function (err, args) { + var taskCallback = onlyOnce(rest(function (err, args) { if (err) { return callback.apply(null, [err].concat(args)); } @@ -5204,7 +5206,7 @@ var waterfall = function (tasks, callback) { args.push(taskCallback); - var task = tasks[taskIndex++]; + var task = wrapAsync$1(tasks[taskIndex++]); task.apply(null, args); } @@ -5212,11 +5214,51 @@ var waterfall = function (tasks, callback) { }; /** + * An "async function" in the context of Async is an asynchronous function with + * 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 should be called with a + * Error as its first argument to signal that an error occurred. + * 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", + * 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}. + * In this case, the `async` function will not be passed a final callback + * argument, and any thrown error will be used as the `err` argument of the + * implicit callback, and the return value will be used as the `result` value. + * (i.e. a `rejected` of the returned Promise becomes the `err` callback + * argument, and a `resolved` value becomes the `result`.) + * + * Note, due to JavaScript limitations, we can only detect native `async` + * functions and not transpilied implementations. + * Your environment must have `async`/`await` support for this to work. + * (e.g. Node > v7.6, or a recent version of a modern browser). + * If you are using `async` functions through a transpiler (e.g. Babel), you + * must still wrap the function with [asyncify]{@link module:Utils.asyncify}, + * because the `async function` will be compiled to an ordinary function that + * returns a promise. + * + * @typedef {Function} AsyncFunction + * @static + */ + +/** * Async is a utility module which provides straight-forward, powerful functions * for working with asynchronous JavaScript. Although originally designed for * use with [Node.js](http://nodejs.org) and installable via * `npm install --save async`, it can also be used directly in the browser. * @module async + * @see AsyncFunction */ /** @@ -5234,6 +5276,7 @@ var waterfall = function (tasks, callback) { * A collection of `async` utility functions. * @module Utils */ + var index = { applyEach: applyEach, applyEachSeries: applyEachSeries, @@ -5245,7 +5288,7 @@ var index = { compose: compose, concat: concat, concatSeries: concatSeries, - constant: constant$2, + constant: constant, detect: detect, detectLimit: detectLimit, detectSeries: detectSeries, @@ -5268,6 +5311,9 @@ var index = { filterLimit: filterLimit, filterSeries: filterSeries, forever: forever, + groupBy: groupBy, + groupByLimit: groupByLimit, + groupBySeries: groupBySeries, log: log, map: map, mapLimit: mapLimit, @@ -5337,7 +5383,7 @@ exports.cargo = cargo; exports.compose = compose; exports.concat = concat; exports.concatSeries = concatSeries; -exports.constant = constant$2; +exports.constant = constant; exports.detect = detect; exports.detectLimit = detectLimit; exports.detectSeries = detectSeries; @@ -5360,6 +5406,9 @@ exports.filter = filter; exports.filterLimit = filterLimit; exports.filterSeries = filterSeries; exports.forever = forever; +exports.groupBy = groupBy; +exports.groupByLimit = groupByLimit; +exports.groupBySeries = groupBySeries; exports.log = log; exports.map = map; exports.mapLimit = mapLimit; |