Skip to content
This repository has been archived by the owner on Nov 27, 2023. It is now read-only.


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?


Failed to load latest commit information.
Latest commit message
Commit time
July 15, 2021 00:04
July 15, 2021 00:04
July 15, 2021 00:04
July 15, 2021 00:04
November 27, 2023 11:10
November 27, 2023 11:10


Note: this proposal is now at stage 4. See the spec PR here: tc39/ecma262#3176

A proposal to make grouping of items in an array (and iterables) easier.

const array = [1, 2, 3, 4, 5];

// `Object.groupBy` groups items by arbitrary key.
// In this case, we're grouping by even/odd keys
Object.groupBy(array, (num, index) => {
  return num % 2 === 0 ? 'even': 'odd';
// =>  { odd: [1, 3, 5], even: [2, 4] }

// `Map.groupBy` returns items in a Map, and is useful for grouping
// using an object key.
const odd  = { odd: true };
const even = { even: true };
Map.groupBy(array, (num, index) => {
  return num % 2 === 0 ? even: odd;
// =>  Map { {odd: true}: [1, 3, 5], {even: true}: [2, 4] }



Current Stage: 4


Array grouping is an extremely common operation, best exemplified by SQL's GROUP BY clause and MapReduce programming (which is better thought of map-group-reduce). The ability to combine like data into groups allows developers to compute higher order datasets, like the average age of a cohort or daily LCP values for a webpage.

Two methods are offered, Object.groupBy and Map.groupBy. The first returns a null-prototype object, which allows ergonomic destructuring and prevents accidental collisions with global Object properties. The second returns a regular Map instance, which allows grouping on complex key types (imagine a compound key or tuple).

Why static methods?

We've found a web compatibility issue with the name Array.prototype.groupBy. The Sugar library until v1.4.0 conditionally monkey-patches Array.prototype with an incompatible method. By providing a native groupBy, these versions of Sugar would fail to install their implementation, and any sites that depend on their behavior would break. We've found some 660 origins that use these versions of the Sugar library.

We then attempted the name, but this ran into code that uses an array as an arbitrary hashmap. Because these bugs are exceptionally difficult to detect (it requires devs to detect and know how to report the bug to us), the committee didn't want to attempt another prototype method name. Instead we chose to use static method, which we believe is unorthodox enough to not risk a web compatibility issue. This also gives us a nice way to support Records and Tuples in the future.