Grouper.js

Assign objects into groups by one or more properties, by object value, or by using a comparator function.

API

grouper(arr, props [, opts])

Group by one or more properties.

var arr = [
  { title: 'foo', date: { year: 1999, month: 1 } },
  { title: 'foo', date: { year: 2000, month: 1 } },
  { title: 'bar', date: { year: 2000, month: 1 } },
  { title: 'bar', date: { year: 2000, month: 2 } },
];
 
// group by multiple properties
grouper(arr, ['title', 'date.year']);
/* [
 *   [ arr[0] ],
 *   [ arr[1] ],
 *   [ arr[2], arr[3] ]
 * ]
 */

1. Objects in arr will be grouped together if and only if they are the same for every property specified in props. Comparison is via the deep-equal module with opts.strict set to true.
2. To group on a “nested” property, use a dot-delimited string (eg. date.year above). (See Jaunt.js.)
3. For coercive comparison (==), pass in an opts argument, setting opts.strict to false.

grouper(arr [, opts])

Group by object value.

var arr = [
  { foo: true },
  { foo: 1 },
  { foo: false },
  { foo: 1 }
];
 
// group by object value (with coercive `==`)
grouper(arr, { strict: false });
/* [
 *   [ arr[0], arr[1], arr[3] ],
 *   [ arr[2] ]
 * ]
 */

1. Objects in arr will be grouped together if and only if they are the same value. Comparison is via the deep-equal module with opts.strict set to true.
2. For coercive comparison (==), pass in an opts argument, setting opts.strict to false.

grouper(arr, fn)

Group using a comparator function.

var arr = [
  { foo: true },
  { foo: 1 },
  { foo: false },
  { foo: 1 }
];
 
// group using a comparator function
var fn = function(a, b) {
  return a.foo === b.foo;
};
grouper(arr, fn);
/* [
 *   [ arr[0] ],
 *   [ arr[1], arr[3] ],
 *   [ arr[2] ]
 * ]
 */

The fn comparator function will be passed two elements from arr. The function must return a truthy value if its two arguments are to be placed in the same group.

Installation

Install via npm:

$ npm i --save grouper

Changelog

• 2.1.0
  • Allow grouping using a comparator function
• 2.0.0
  • Use deep-equal for comparing property values, with option to use coercive comparison
  • Allow grouping by object value
  • Allow grouping by nested keys
• 1.0.0
  • Initial release

License

MIT license