From e426ef31458edc9b78b48a5d89a058818b1286c1 Mon Sep 17 00:00:00 2001 From: Justin Ridgewell Date: Sat, 21 May 2022 18:11:21 -0400 Subject: [PATCH 1/2] Rename to `group` and `groupToMap`. --- README.md | 22 +++++++++++++++++----- index.html | 34 +++++++++++++++++----------------- spec.emu | 32 ++++++++++++++++---------------- 3 files changed, 50 insertions(+), 38 deletions(-) diff --git a/README.md b/README.md index b8b9871..d4de583 100644 --- a/README.md +++ b/README.md @@ -5,19 +5,19 @@ A proposal to make grouping of items in an array easier. ```js const array = [1, 2, 3, 4, 5]; -// groupBy groups items by arbitrary key. +// group groups items by arbitrary key. // In this case, we're grouping by even/odd keys -array.groupBy((num, index, array) => { +array.group((num, index, array) => { return num % 2 === 0 ? 'even': 'odd'; }); // => { odd: [1, 3, 5], even: [2, 4] } -// groupByToMap returns items in a Map, and is useful for grouping using +// groupToMap returns items in a Map, and is useful for grouping using // an object key. const odd = { odd: true }; const even = { even: true }; -array.groupByToMap((num, index, array) => { +array.groupToMap((num, index, array) => { return num % 2 === 0 ? even: odd; }); @@ -40,12 +40,22 @@ 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, `groupBy` and `groupByToMap`. The first returns a +Two methods are offered, `group` and `groupToMap`. 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 `group` and not `groupBy`? + +We've [found][sugar-bug] a web compatibility issue with the name +`groupBy`. The [Sugar][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. + ## Polyfill - A polyfill is available in the [core-js] library. You can find it in the [ECMAScript proposals section][core-js-section]. @@ -60,3 +70,5 @@ a regular `Map` instance, which allows grouping on complex key types [core-js-section]: https://github.com/zloirock/core-js#array-grouping [lodash]: https://lodash.com/docs/4.17.15#groupBy [lodash-npm]: https://www.npmjs.com/package/lodash.groupby +[sugar]: https://sugarjs.com/ +[sugar-bug]: https://github.com/tc39/proposal-array-grouping/issues/37 diff --git a/index.html b/index.html index 274620f..b6313e8 100644 --- a/index.html +++ b/index.html @@ -1149,7 +1149,7 @@ }); let sdoMap = JSON.parse(`{}`); -let biblio = JSON.parse(`{"refsByClause":{"sec-array.prototype.groupby":["_ref_0","_ref_1","_ref_2","_ref_3","_ref_4","_ref_5","_ref_6","_ref_7","_ref_8","_ref_9"],"sec-array.prototype.groupbymap":["_ref_10","_ref_11","_ref_12","_ref_13","_ref_14","_ref_15","_ref_16","_ref_17","_ref_18"],"sec-add-value-to-keyed-group":["_ref_19"],"sec-array.prototype-@@unscopables":["_ref_20","_ref_21","_ref_22","_ref_23","_ref_24","_ref_25","_ref_26","_ref_27","_ref_28","_ref_29","_ref_30","_ref_31","_ref_32"]},"entries":[{"type":"clause","id":"sec-scope","titleHTML":"Scope","number":"1"},{"type":"clause","id":"sec-array.prototype.groupby","title":"Array.prototype.groupBy ( callbackfn [ , thisArg ] )","titleHTML":"Array.prototype.groupBy ( callbackfn [ , thisArg ] )","number":"2.1"},{"type":"clause","id":"sec-array.prototype.groupbymap","title":"Array.prototype.groupByToMap ( callbackfn [ , thisArg ] )","titleHTML":"Array.prototype.groupByToMap ( callbackfn [ , thisArg ] )","number":"2.2"},{"type":"op","aoid":"AddValueToKeyedGroup","refId":"sec-add-value-to-keyed-group"},{"type":"clause","id":"sec-add-value-to-keyed-group","title":"AddValueToKeyedGroup ( groups, key, value )","titleHTML":"AddValueToKeyedGroup ( groups, key, value )","number":"2.3","referencingIds":["_ref_7","_ref_16"]},{"type":"clause","id":"sec-array.prototype-@@unscopables","titleHTML":"Array.prototype [ @@unscopables ]","number":"2.4"},{"type":"clause","id":"sec-properties-of-the-array-prototype-object","titleHTML":"Properties of the Array Prototype Object (22.1.3)","number":"2"},{"type":"clause","id":"sec-copyright-and-software-license","title":"Copyright & Software License","titleHTML":"Copyright & Software License","number":"A"}]}`); +let biblio = JSON.parse(`{"refsByClause":{"sec-array.prototype.groupby":["_ref_0","_ref_1","_ref_2","_ref_3","_ref_4","_ref_5","_ref_6","_ref_7","_ref_8","_ref_9"],"sec-array.prototype.groupbymap":["_ref_10","_ref_11","_ref_12","_ref_13","_ref_14","_ref_15","_ref_16","_ref_17","_ref_18"],"sec-add-value-to-keyed-group":["_ref_19"],"sec-array.prototype-@@unscopables":["_ref_20","_ref_21","_ref_22","_ref_23","_ref_24","_ref_25","_ref_26","_ref_27","_ref_28","_ref_29","_ref_30","_ref_31","_ref_32"]},"entries":[{"type":"clause","id":"sec-scope","titleHTML":"Scope","number":"1"},{"type":"clause","id":"sec-array.prototype.groupby","title":"Array.prototype.group ( callbackfn [ , thisArg ] )","titleHTML":"Array.prototype.group ( callbackfn [ , thisArg ] )","number":"2.1"},{"type":"clause","id":"sec-array.prototype.groupbymap","title":"Array.prototype.groupToMap ( callbackfn [ , thisArg ] )","titleHTML":"Array.prototype.groupToMap ( callbackfn [ , thisArg ] )","number":"2.2"},{"type":"op","aoid":"AddValueToKeyedGroup","refId":"sec-add-value-to-keyed-group"},{"type":"clause","id":"sec-add-value-to-keyed-group","title":"AddValueToKeyedGroup ( groups, key, value )","titleHTML":"AddValueToKeyedGroup ( groups, key, value )","number":"2.3","referencingIds":["_ref_7","_ref_16"]},{"type":"clause","id":"sec-array.prototype-@@unscopables","titleHTML":"Array.prototype [ @@unscopables ]","number":"2.4"},{"type":"clause","id":"sec-properties-of-the-array-prototype-object","titleHTML":"Properties of the Array Prototype Object (22.1.3)","number":"2"},{"type":"clause","id":"sec-copyright-and-software-license","title":"Copyright & Software License","titleHTML":"Copyright & Software License","number":"A"}]}`); ;let usesMultipage = false