From 01c9794ec1b303c5853f3580bffde96ee4405728 Mon Sep 17 00:00:00 2001
From: Denis Pushkarev <zloirock@zloirock.ru>
Date: Mon, 8 Nov 2021 23:53:08 +0700
Subject: [PATCH] update docs

---
 CHANGELOG.md |  5 ++++-
 README.md    | 40 +++++++++++++++++++++++-----------------
 2 files changed, 27 insertions(+), 18 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 3b1fc38b8b7e..8a39dc95546f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,6 +1,9 @@
 ## Changelog
 ##### Unreleased
-- Nothing
+- [`Array` grouping proposal](https://github.com/tc39/proposal-array-grouping):
+  - Moved to the stage 2
+  - Added `Array.prototype.groupByMap` method
+  - Removed `@@species` support
 
 ##### 3.19.1 - 2021.11.03
 - Added a workaround for FF26- bug where `ArrayBuffer`s are non-extensible, but `Object.isExtensible` does not report it:
diff --git a/README.md b/README.md
index db3ea6a652fc..c7516a5f1e96 100644
--- a/README.md
+++ b/README.md
@@ -101,6 +101,7 @@ Promise.resolve(32).then(x => console.log(x)); // => 32
       - [`Iterator` helpers](#iterator-helpers)
       - [New `Set` methods](#new-set-methods)
       - [`Map.prototype.emplace`](#mapprototypeemplace)
+      - [`Array` grouping](#array-grouping)
       - [`Array.isTemplateObject`](#arrayistemplateobject)
       - [`Symbol.{ asyncDispose, dispose }` for `using` statement](#symbol-asyncdispose-dispose--for-using-statement)
       - [`Symbol.metadata` for decorators proposal](#symbolmetadata-for-decorators-proposal)
@@ -111,7 +112,6 @@ Promise.resolve(32).then(x => console.log(x)); // => 32
       - [`compositeKey` and `compositeSymbol`](#compositekey-and-compositesymbol)
       - [`Array.fromAsync`](#arrayfromasync)
       - [`Array` filtering](#array-filtering)
-      - [`Array` grouping](#array-grouping)
       - [`Array` deduplication](#array-deduplication)
       - [Getting last item from `Array`](#getting-last-item-from-array)
       - [`Number.range`](#numberrange)
@@ -2081,6 +2081,28 @@ map.emplace('b', { update: it => it ** 2, insert: () => 3}); // => 3
 
 console.log(map); // => Map { 'a': 4, 'b': 3 }
 ```
+##### [`Array` grouping](#https://github.com/tc39/proposal-array-grouping)[⬆](#index)
+Modules [`esnext.array.group-by`](https://github.com/zloirock/core-js/blob/master/packages/core-js/modules/esnext.array.group-by.js), [`esnext.array.group-by-map`](https://github.com/zloirock/core-js/blob/master/packages/core-js/modules/esnext.array.group-by-map.js).
+```js
+class Array {
+  groupBy(callbackfn: (value: any, index: number, target: any) => key, thisArg?: any): { [key]: Array<mixed> };
+  groupByMap(callbackfn: (value: any, index: number, target: any) => key, thisArg?: any): Map<key, Array<mixed>>;
+}
+```
+[*CommonJS entry points:*](#commonjs-api)
+```
+core-js/proposals/array-grouping
+core-js(-pure)/features/array(/virtual)/group-by
+core-js(-pure)/features/array(/virtual)/group-by-map
+```
+[*Examples*](t.ly/xEqc):
+```js
+[1, 2, 3, 4, 5].groupBy(it => it % 2); // => { 1: [1, 3, 5], 0: [2, 4] }
+
+const map = [1, 2, 3, 4, 5].groupByMap(it => it % 2);
+map.get(1); // => [1, 3, 5]
+map.get(0); // => [2, 4]
+````
 ##### [`Array.isTemplateObject`](https://github.com/tc39/proposal-array-is-template-object)[⬆](#index)
 Module [`esnext.array.is-template-object`](https://github.com/zloirock/core-js/blob/master/packages/core-js/modules/esnext.array.is-template-object.js)
 ```js
@@ -2335,22 +2357,6 @@ core-js/features/typed-array/filter-reject
 ```js
 [1, 2, 3, 4, 5].filterReject(it => it % 2); // => [2, 4]
 ````
-##### [`Array` grouping](#https://github.com/tc39/proposal-array-grouping)[⬆](#index)
-Modules [`esnext.array.group-by`](https://github.com/zloirock/core-js/blob/master/packages/core-js/modules/esnext.array.group-by.js).
-```js
-class Array {
-  groupBy(callbackfn: (value: any, index: number, target: any) => key, thisArg?: any): { [key]: Array<mixed> };
-}
-```
-[*CommonJS entry points:*](#commonjs-api)
-```
-core-js/proposals/array-grouping
-core-js(-pure)/features/array(/virtual)/group-by
-```
-[*Examples*](t.ly/VggI):
-```js
-[1, 2, 3, 4, 5].groupBy(it => it % 2); // => { 1: [1, 3, 5], 0: [2, 4] }
-````
 ##### [Array deduplication](https://github.com/tc39/proposal-array-unique)[⬆](#index)
 Modules [`esnext.array.unique-by`](https://github.com/zloirock/core-js/blob/master/packages/core-js/modules/esnext.array.unique-by.js) and [`esnext.typed-array.unique-by`](https://github.com/zloirock/core-js/blob/master/packages/core-js/modules/esnext.typed-array.unique-by.js)
 ```js