items

An iterable (such as an Array) whose elements will be grouped.

callbackFn

A function to execute for each element in the iterable. It should return a value that can get coerced into a property key (string or symbol) indicating the group of the current element. The function is called with the following arguments:

element

The current element being processed.

index

The index of the current element being processed.

A null-prototype object with properties for all groups, each assigned to an array containing the elements of the associated group.

Object.groupBy() calls a provided callbackFn function once for each element in an iterable. The callback function should return a string or symbol (values that are neither type are coerced to strings) indicating the group of the associated element. The values returned by callbackFn are used as keys for the object returned by Map.groupBy(). Each key has an associated array containing all the elements for which the callback returned the same value.

The elements in the returned object and the original iterable are the same (not deep copies). Changing the internal structure of the elements will be reflected in both the original iterable and the returned object.

First we define an array containing objects representing an inventory of different foodstuffs. Each food has a type and a quantity.

const inventory = [
  { name: "asparagus", type: "vegetables", quantity: 5 },
  { name: "bananas", type: "fruit", quantity: 0 },
  { name: "goat", type: "meat", quantity: 23 },
  { name: "cherries", type: "fruit", quantity: 5 },
  { name: "fish", type: "meat", quantity: 22 },
];

The code below groups the elements by the value of their type property.

const result = Object.groupBy(inventory, ({ type }) => type);

/* Result is:
{
  vegetables: [
    { name: 'asparagus', type: 'vegetables', quantity: 5 },
  ],
  fruit: [
    { name: "bananas", type: "fruit", quantity: 0 },
    { name: "cherries", type: "fruit", quantity: 5 }
  ],
  meat: [
    { name: "goat", type: "meat", quantity: 23 },
    { name: "fish", type: "meat", quantity: 22 }
  ]
}
*/

The arrow function just returns the type of each array element each time it is called. Note that the function argument { type } is a basic example of object destructuring syntax for function arguments. This unpacks the type property of an object passed as a parameter, and assigns it to a variable named type in the body of the function. This is a very succinct way to access the relevant values of elements within a function.

We can also create groups inferred from values in one or more properties of the elements. Below is a very similar example that puts the items into ok or restock groups based on the value of the quantity field.

function myCallback({ quantity }) {
  return quantity > 5 ? "ok" : "restock";
}

const result2 = Object.groupBy(inventory, myCallback);

/* Result is:
{
  restock: [
    { name: "asparagus", type: "vegetables", quantity: 5 },
    { name: "bananas", type: "fruit", quantity: 0 },
    { name: "cherries", type: "fruit", quantity: 5 }
  ],
  ok: [
    { name: "goat", type: "meat", quantity: 23 },
    { name: "fish", type: "meat", quantity: 22 }
  ]
}
*/

• Polyfill of Object.groupBy in core-js
• Indexed collections guide
• Array.prototype.reduce()
• Object.fromEntries()
• Map.groupBy()