[#1348] initial groupBy implementation

lib/groupBy.js

@@ -0,0 +1,37 @@
+import doLimit from './internal/doLimit';
+import groupByLimit from './groupByLimit';
+
+/**
+ * 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 and there is
+ * no guarantee that grouped items will appear in the same order as in `coll`.
+ *
+ * @name groupBy
+ * @static
+ * @memberOf module:Collections
+ * @method
+ * @category Collection
+ * @param {Array|Iterable|Object} coll - A collection to iterate over.
+ * @param {Function} iteratee - A function to apply to each item in `coll`.
+ * The iteratee is passed a `callback(err, key)` which must be called once it
+ * has completed with an error (which can be `null`) and the `key` to group the
+ * value under. Invoked with (value, callback).
+ * @param {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']};
+ * });
+ */
+export default doLimit(groupByLimit, Infinity);

lib/groupByLimit.js

@@ -0,0 +1,44 @@
+import noop from 'lodash/noop';
+import doParallelLimit from './internal/doParallelLimit';
+
+/**
+ * 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 {Function} iteratee - A function to apply to each item in `coll`.
+ * The iteratee is passed a `callback(err, key)` which must be called once it
+ * has completed with an error (which can be `null`) and the `key` to group the
+ * value under. Invoked with (value, callback).
+ * @param {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.
+ */
+export default doParallelLimit(function(eachFn, coll, iteratee, callback) {
+    callback = callback || noop;
+    coll = coll || [];
+    var result = {};
+    // from MDN, handle object having an `hasOwnProperty` prop
+    var hasOwnProperty = Object.prototype.hasOwnProperty;
+
+    eachFn(coll, function(val, _, callback) {
+        iteratee(val, function(err, key) {
+            if (err) return callback(err);
+
+            if (hasOwnProperty.call(result, key)) {
+                result[key].push(val);
+            } else {
+                result[key] = [val];
+            }
+            callback(null);
+        });
+    }, function(err) {
+        callback(err, result);
+    });
+});

lib/groupBySeries.js

@@ -0,0 +1,23 @@
+import doLimit from './internal/doLimit';
+import groupByLimit from './groupByLimit';
+
+/**
+ * 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 {Function} iteratee - A function to apply to each item in `coll`.
+ * The iteratee is passed a `callback(err, key)` which must be called once it
+ * has completed with an error (which can be `null`) and the `key` to group the
+ * value under. Invoked with (value, callback).
+ * @param {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.
+ */
+export default doLimit(groupByLimit, 1);

lib/index.js

@@ -54,6 +54,9 @@ import filter from './filter';
 import filterLimit from './filterLimit';
 import filterSeries from './filterSeries';
 import forever from './forever';
+import groupBy from './groupBy';
+import groupByLimit from './groupByLimit';
+import groupBySeries from './groupBySeries';
 import log from './log';
 import map from './map';
 import mapLimit from './mapLimit';
@@ -128,6 +131,9 @@ export default {
     filterLimit: filterLimit,
     filterSeries: filterSeries,
     forever: forever,
+    groupBy: groupBy,
+    groupByLimit: groupByLimit,
+    groupBySeries: groupBySeries,
     log: log,
     map: map,
     mapLimit: mapLimit,
@@ -220,6 +226,9 @@ export {
     filterLimit as filterLimit,
     filterSeries as filterSeries,
     forever as forever,
+    groupBy as groupBy,
+    groupByLimit as groupByLimit,
+    groupBySeries as groupBySeries,
     log as log,
     map as map,
     mapLimit as mapLimit,