groupBy.js

import groupByLimit from './groupByLimit.js'

/**
 * 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|AsyncIterable|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.
 * @returns {Promise} a promise, if no callback is passed
 * @example
 *
 * // dir1 is a directory that contains file1.txt, file2.txt
 * // dir2 is a directory that contains file3.txt, file4.txt
 * // dir3 is a directory that contains file5.txt
 * // dir4 does not exist
 *
 * const files = ['dir1/file1.txt','dir2','dir4']
 *
 * // asynchronous function that detects file type as none, file, or directory
 * function detectFile(file, callback) {
 * fs.stat(file, function(err, stat) {
 * if (err) {
 * return callback(null, 'none');
 * }
 * callback(null, stat.isDirectory() ? 'directory' : 'file');
 * });
 * }
 *
 * //Using callbacks
 * async.groupBy(files, detectFile, function(err, result) {
 * if(err) {
 * console.log(err);
 * } else {
 * console.log(result);
 * // {
 * // file: ['dir1/file1.txt'],
 * // none: ['dir4'],
 * // directory: ['dir2']
 * // }
 * // result is object containing the files grouped by type
 * }
 * });
 *
 * // Using Promises
 * async.groupBy(files, detectFile)
 * .then( result => {
 * console.log(result);
 * // {
 * // file: ['dir1/file1.txt'],
 * // none: ['dir4'],
 * // directory: ['dir2']
 * // }
 * // result is object containing the files grouped by type
 * }).catch( err => {
 * console.log(err);
 * });
 *
 * // Using async/await
 * async () => {
 * try {
 * let result = await async.groupBy(files, detectFile);
 * console.log(result);
 * // {
 * // file: ['dir1/file1.txt'],
 * // none: ['dir4'],
 * // directory: ['dir2']
 * // }
 * // result is object containing the files grouped by type
 * }
 * catch (err) {
 * console.log(err);
 * }
 * }
 *
 */
export default function groupBy (coll, iteratee, callback) {
    return groupByLimit(coll, Infinity, iteratee, callback)
}