move Map upsert proposal to stable ES

Author: zloirock

CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 ### Unreleased
+- [`Map` upsert proposal](https://github.com/tc39/proposal-upsert):
+  - Built-ins:
+    - `Map.prototype.getOrInsert`
+    - `Map.prototype.getOrInsertComputed`
+    - `WeakMap.prototype.getOrInsert`
+    - `WeakMap.prototype.getOrInsertComputed`
+  - Moved to stable ES, January 2026 TC39 meeting
+  - Added `es.` namespace modules, `/es/` and `/stable/` namespaces entries
 - Use `CreateDataProperty` / `CreateDataPropertyOrThrow` in some missed cases, [#1497](https://github.com/zloirock/core-js/issues/1497)
 - Minor fix / optimization in the `RegExp` constructor (NCG and `dotAll`) polyfill
 - Compat data improvements:
@@ -12,7 +20,7 @@
 
 ### [3.47.0 - 2025.11.18](https://github.com/zloirock/core-js/releases/tag/v3.47.0)
 - Changes [v3.46.0...v3.47.0](https://github.com/zloirock/core-js/compare/v3.46.0...v3.47.0) (117 commits)
-- [`JSON.parse` source text access proposal](https://github.com/tc39/proposal-json-parse-with-source) :
+- [`JSON.parse` source text access proposal](https://github.com/tc39/proposal-json-parse-with-source):
   - Built-ins:
     - `JSON.isRawJSON`
     - `JSON.parse`

README.md

@@ -168,10 +168,10 @@ structuredClone(new Set([1, 2, 3])); // => new Set([1, 2, 3])
       - [Well-formed `JSON.stringify`](#well-formed-jsonstringify)
       - [Well-formed unicode strings](#well-formed-unicode-strings)
       - [New `Set` methods](#new-set-methods)
+      - [`Map` upsert](#map-upsert)
       - [`Math.sumPrecise`](#mathsumprecise)
     - [Stage 3 proposals](#stage-3-proposals)
       - [Joint iteration](#joint-iteration)
-      - [`Map` upsert](#map-upsert)
       - [`Symbol.metadata` for decorators metadata proposal](#symbolmetadata-for-decorators-metadata-proposal)
     - [Stage 2.7 proposals](#stage-27-proposals)
       - [`Iterator` chunking](#iterator-chunking)
@@ -1594,14 +1594,16 @@ for (let key in object2) console.log(key); // nothing
 #### ECMAScript: Collections[⬆](#index)
 `core-js` uses native collections in most cases, just fixes methods / constructor, if it's required, and in the old environment uses fast polyfill (O(1) lookup).
 #### Map[⬆](#index)
-Modules [`es.map`](https://github.com/zloirock/core-js/blob/master/packages/core-js/modules/es.map.js) and [`es.map.group-by`](https://github.com/zloirock/core-js/blob/master/packages/core-js/modules/es.map.group-by.js).
+Modules [`es.map`](https://github.com/zloirock/core-js/blob/master/packages/core-js/modules/es.map.js), [`es.map.group-by`](https://github.com/zloirock/core-js/blob/master/packages/core-js/modules/es.map.group-by.js), [`es.map.get-or-insert`](https://github.com/zloirock/core-js/blob/master/packages/core-js/modules/es.map.get-or-insert.js) and [`es.map.get-or-insert-computed`](https://github.com/zloirock/core-js/blob/master/packages/core-js/modules/es.map.get-or-insert-computed.js).
 ```ts
 class Map {
   constructor(iterable?: Iterable<[key, value]>): Map;
   clear(): void;
   delete(key: any): boolean;
   forEach(callbackfn: (value: any, key: any, target: any) => void, thisArg: any): void;
   get(key: any): any;
+  getOrInsert(key: any, value: any): any;
+  getOrInsertComputed(key: any, (key: any) => value: any): any;
   has(key: any): boolean;
   set(key: any, val: any): this;
   values(): Iterator<value>;
@@ -1616,8 +1618,10 @@ class Map {
 ```
 core-js(-pure)/es|stable|actual|full/map
 core-js(-pure)/es|stable|actual|full/map/group-by
+core-js(-pure)/es|stable|actual|full/map/get-or-insert
+core-js(-pure)/es|stable|actual|full/map/get-or-insert-computed
 ```
-[*Examples*](https://tinyurl.com/yn2w5s8v):
+[*Examples*](https://tinyurl.com/298ekxmq):
 ```js
 let array = [1];
 
@@ -1653,7 +1657,20 @@ for (let [key, value] of map.entries()) {
 map = Map.groupBy([1, 2, 3, 4, 5], it => it % 2);
 map.get(1); // => [1, 3, 5]
 map.get(0); // => [2, 4]
+
+map = new Map([['a', 1]]);
+
+map.getOrInsert('a', 2); // => 1
+
+map.getOrInsert('b', 3); // => 3
+
+map.getOrInsertComputed('a', key => key); // => 1
+
+map.getOrInsertComputed('c', key => key); // => 'c'
+
+console.log(map); // => Map { 'a': 1, 'b': 3, 'c': 'c' }
 ```
+
 #### Set[⬆](#index)
 Modules [`es.set`](https://github.com/zloirock/core-js/blob/master/packages/core-js/modules/es.set.js), [`es.set.difference.v2`](https://github.com/zloirock/core-js/blob/master/packages/core-js/modules/es.set.difference.v2.js), [`es.set.intersection.v2`](https://github.com/zloirock/core-js/blob/master/packages/core-js/modules/es.set.intersection.v2.js), [`es.set.is-disjoint-from.v2`](https://github.com/zloirock/core-js/blob/master/packages/core-js/modules/es.set.is-disjoint-from.v2.js), [`es.set.is-subset-of.v2`](https://github.com/zloirock/core-js/blob/master/packages/core-js/modules/es.set.is-subset-of.v2.js), [`es.set.is-superset-of.v2`](https://github.com/zloirock/core-js/blob/master/packages/core-js/modules/es.set.is-superset-of.v2.js), [`es.set.symmetric-difference.v2`](https://github.com/zloirock/core-js/blob/master/packages/core-js/modules/es.set.symmetric-difference.v2.js), [`es.set.union.v2`](https://github.com/zloirock/core-js/blob/master/packages/core-js/modules/es.set.union.v2.js)
 ```ts
@@ -1722,19 +1739,23 @@ new Set([1, 2, 3]).isSubsetOf(new Set([5, 4, 3, 2, 1]));    // => true
 new Set([5, 4, 3, 2, 1]).isSupersetOf(new Set([1, 2, 3]));  // => true
 ```
 #### WeakMap[⬆](#index)
-Module [`es.weak-map`](https://github.com/zloirock/core-js/blob/master/packages/core-js/modules/es.weak-map.js).
+Module [`es.weak-map`](https://github.com/zloirock/core-js/blob/master/packages/core-js/modules/es.weak-map.js), [`es.weak-map.get-or-insert`](https://github.com/zloirock/core-js/blob/master/packages/core-js/modules/es.weak-map.get-or-insert.js) and [`es.weak-map.get-or-insert-computed`](https://github.com/zloirock/core-js/blob/master/packages/core-js/modules/es.weak-map.get-or-insert-computed.js).
 ```ts
 class WeakMap {
   constructor(iterable?: Iterable<[key, value]>): WeakMap;
-  delete(key: Object): boolean;
-  get(key: Object): any;
-  has(key: Object): boolean;
-  set(key: Object, val: any): this;
+  delete(key: object | symbol): boolean;
+  get(key: object | symbol): any;
+  getOrInsert(key: object | symbol, value: any): any;
+  getOrInsertComputed(key: object | symbol, (key: any) => value: any): any;
+  has(key: object | symbol): boolean;
+  set(key: object | symbol, val: any): this;
 }
 ```
 [*CommonJS entry points:*](#commonjs-api)
 ```
 core-js(-pure)/es|stable|actual|full/weak-map
+core-js(-pure)/es|stable|actual|full/weak-map/get-or-insert
+core-js(-pure)/es|stable|actual|full/weak-map/get-or-insert-computed
 ```
 [*Examples*](https://tinyurl.com/2yws9shh):
 ```js
@@ -1772,9 +1793,9 @@ Module [`es.weak-set`](https://github.com/zloirock/core-js/blob/master/packages/
 ```ts
 class WeakSet {
   constructor(iterable?: Iterable<value>): WeakSet;
-  add(key: Object): this;
-  delete(key: Object): boolean;
-  has(key: Object): boolean;
+  add(key: object | symbol): this;
+  delete(key: object | symbol): boolean;
+  has(key: object | symbol): boolean;
 }
 ```
 [*CommonJS entry points:*](#commonjs-api)
@@ -2728,6 +2749,23 @@ class Set {
 core-js/proposals/set-methods-v2
 ```
 
+##### [`Map` upsert](https://github.com/thumbsupep/proposal-upsert)[⬆](#index)
+```ts
+class Map {
+  getOrInsert(key: any, value: any): any;
+  getOrInsertComputed(key: any, (key: any) => value: any): any;
+}
+
+class WeakMap {
+  getOrInsert(key: object | symbol, value: any): any;
+  getOrInsertComputed(key: object | symbol, (key: any) => value: any): any;
+}
+```
+[*CommonJS entry points:*](#commonjs-api)
+```
+core-js/proposals/map-upsert-v4
+```
+
 ##### [`Math.sumPrecise`](https://github.com/tc39/proposal-math-sum)
 ```ts
 namespace Math {
@@ -2797,42 +2835,6 @@ Iterator.zipKeyed({
  */
 ```
 
-##### [`Map` upsert](https://github.com/thumbsupep/proposal-upsert)[⬆](#index)
-Modules [`esnext.map.get-or-insert`](https://github.com/zloirock/core-js/blob/master/packages/core-js/modules/esnext.map.get-or-insert.js), [`esnext.map.get-or-insert-computed`](https://github.com/zloirock/core-js/blob/master/packages/core-js/modules/esnext.map.get-or-insert-computed.js), [`esnext.weak-map.get-or-insert`](https://github.com/zloirock/core-js/blob/master/packages/core-js/modules/esnext.weak-map.get-or-insert.js) and [`esnext.weak-map.get-or-insert-computed`](https://github.com/zloirock/core-js/blob/master/packages/core-js/modules/esnext.weak-map.get-or-insert-computed.js)
-```ts
-class Map {
-  getOrInsert(key: any, value: any): any;
-  getOrInsertComputed(key: any, (key: any) => value: any): any;
-}
-
-class WeakMap {
-  getOrInsert(key: any, value: any): any;
-  getOrInsertComputed(key: any, (key: any) => value: any): any;
-}
-```
-[*CommonJS entry points:*](#commonjs-api)
-```
-core-js/proposals/map-upsert-v4
-core-js(-pure)/actual|full/map/get-or-insert
-core-js(-pure)/actual|full/map/get-or-insert-computed
-core-js(-pure)/actual|full/weak-map/get-or-insert
-core-js(-pure)/actual|full/weak-map/get-or-insert-computed
-```
-[*Examples*](https://tinyurl.com/2a54u5ux):
-```js
-const map = new Map([['a', 1]]);
-
-map.getOrInsert('a', 2); // => 1
-
-map.getOrInsert('b', 3); // => 3
-
-map.getOrInsertComputed('a', key => key); // => 1
-
-map.getOrInsertComputed('c', key => key); // => 'c'
-
-console.log(map); // => Map { 'a': 1, 'b': 3, 'c': 'c' }
-```
-
 ##### [`Symbol.metadata` for decorators metadata proposal](https://github.com/tc39/proposal-decorator-metadata)[⬆](#index)
 Modules [`esnext.symbol.metadata`](https://github.com/zloirock/core-js/blob/master/packages/core-js/modules/esnext.symbol.metadata.js) and [`esnext.function.metadata`](https://github.com/zloirock/core-js/blob/master/packages/core-js/modules/esnext.function.metadata.js).
 ```ts

docs/web/docs/features/ecmascript/collections.md

@@ -3,7 +3,7 @@
 
 ## Map
 ### Modules 
-[`es.map`](https://github.com/zloirock/core-js/blob/master/packages/core-js/modules/es.map.js), [`es.map.group-by`](https://github.com/zloirock/core-js/blob/master/packages/core-js/modules/es.map.group-by.js).
+[`es.map`](https://github.com/zloirock/core-js/blob/master/packages/core-js/modules/es.map.js), [`es.map.group-by`](https://github.com/zloirock/core-js/blob/master/packages/core-js/modules/es.map.group-by.js), [`es.map.get-or-insert`](https://github.com/zloirock/core-js/blob/master/packages/core-js/modules/es.map.get-or-insert.js) and [`es.map.get-or-insert-computed`](https://github.com/zloirock/core-js/blob/master/packages/core-js/modules/es.map.get-or-insert-computed.js).
 
 ### Built-ins signatures
 ```ts
@@ -13,6 +13,8 @@ class Map {
   delete(key: any): boolean;
   forEach(callbackfn: (value: any, key: any, target: any) => void, thisArg: any): void;
   get(key: any): any;
+  getOrInsert(key: any, value: any): any;
+  getOrInsertComputed(key: any, (key: any) => value: any): any;
   has(key: any): boolean;
   set(key: any, val: any): this;
   values(): Iterator<value>;
@@ -28,6 +30,8 @@ class Map {
 ```plaintext
 core-js(-pure)/es|stable|actual|full/map
 core-js(-pure)/es|stable|actual|full/map/group-by
+core-js(-pure)/es|stable|actual|full/map/get-or-insert
+core-js(-pure)/es|stable|actual|full/map/get-or-insert-computed
 ```
 
 ### Examples
@@ -66,6 +70,19 @@ for (let [key, value] of map.entries()) {
 map = Map.groupBy([1, 2, 3, 4, 5], it => it % 2);
 map.get(1); // => [1, 3, 5]
 map.get(0); // => [2, 4]
+
+
+map = new Map([['a', 1]]);
+
+map.getOrInsert('a', 2); // => 1
+
+map.getOrInsert('b', 3); // => 3
+
+map.getOrInsertComputed('a', key => key); // => 1
+
+map.getOrInsertComputed('c', key => key); // => 'c'
+
+console.log(map); // => Map { 'a': 1, 'b': 3, 'c': 'c' }
 ```
 
 ## Set
@@ -144,21 +161,25 @@ new Set([5, 4, 3, 2, 1]).isSupersetOf(new Set([1, 2, 3]));  // => true
 ## WeakMap
 
 ### Modules
-[`es.weak-map`](https://github.com/zloirock/core-js/blob/master/packages/core-js/modules/es.weak-map.js).
+[`es.weak-map`](https://github.com/zloirock/core-js/blob/master/packages/core-js/modules/es.weak-map.js), [`es.weak-map.get-or-insert`](https://github.com/zloirock/core-js/blob/master/packages/core-js/modules/es.weak-map.get-or-insert.js) and [`es.weak-map.get-or-insert-computed`](https://github.com/zloirock/core-js/blob/master/packages/core-js/modules/es.weak-map.get-or-insert-computed.js).
 
 ### Built-ins signatures
 ```ts
 class WeakMap {
   constructor(iterable?: Iterable<[key, value]>): WeakMap;
-  delete(key: Object): boolean;
-  get(key: Object): any;
-  has(key: Object): boolean;
-  set(key: Object, val: any): this;
+  delete(key: object | symbol): boolean;
+  get(key: object | symbol): any;
+  getOrInsert(key: object | symbol, value: any): any;
+  getOrInsertComputed(key: object | symbol, (key: any) => value: any): any;
+  has(key: object | symbol): boolean;
+  set(key: object | symbol, val: any): this;
 }
 ```
 ### [Entry points]({docs-version}/docs/usage#h-entry-points)
 ```plaintext
 core-js(-pure)/es|stable|actual|full/weak-map
+core-js(-pure)/es|stable|actual|full/weak-map/get-or-insert
+core-js(-pure)/es|stable|actual|full/weak-map/get-or-insert-computed
 ```
 
 ### Examples
@@ -201,9 +222,9 @@ for (let key in person) console.log(key); // => only 'getName'
 ```ts
 class WeakSet {
   constructor(iterable?: Iterable<value>): WeakSet;
-  add(key: Object): this;
-  delete(key: Object): boolean;
-  has(key: Object): boolean;
+  add(key: object | symbol): this;
+  delete(key: object | symbol): boolean;
+  has(key: object | symbol): boolean;
 }
 ```
 

docs/web/docs/features/proposals/map-upsert.md

@@ -3,28 +3,28 @@
 [Proposal repo](https://github.com/thumbsupep/proposal-upsert)
 
 ## Modules 
-[`esnext.map.get-or-insert`](https://github.com/zloirock/core-js/blob/master/packages/core-js/modules/esnext.map.get-or-insert.js), [`esnext.map.get-or-insert-computed`](https://github.com/zloirock/core-js/blob/master/packages/core-js/modules/esnext.map.get-or-insert-computed.js), [`esnext.weak-map.get-or-insert`](https://github.com/zloirock/core-js/blob/master/packages/core-js/modules/esnext.weak-map.get-or-insert.js) and [`esnext.weak-map.get-or-insert-computed`](https://github.com/zloirock/core-js/blob/master/packages/core-js/modules/esnext.weak-map.get-or-insert-computed.js)
+[`es.map.get-or-insert`](https://github.com/zloirock/core-js/blob/master/packages/core-js/modules/es.map.get-or-insert.js), [`es.map.get-or-insert-computed`](https://github.com/zloirock/core-js/blob/master/packages/core-js/modules/es.map.get-or-insert-computed.js), [`es.weak-map.get-or-insert`](https://github.com/zloirock/core-js/blob/master/packages/core-js/modules/es.weak-map.get-or-insert.js) and [`es.weak-map.get-or-insert-computed`](https://github.com/zloirock/core-js/blob/master/packages/core-js/modules/es.weak-map.get-or-insert-computed.js).
 
 ## Built-ins signatures
 ```ts
 class Map {
-  getOrInsert(key: any, value: any): any;
-  getOrInsertComputed(key: any, (key: any) => value: any): any;
+  getOrInsert(key: object | symbol, value: any): any;
+  getOrInsertComputed(key: object | symbol, (key: any) => value: any): any;
 }
 
 class WeakMap {
-  getOrInsert(key: any, value: any): any;
-  getOrInsertComputed(key: any, (key: any) => value: any): any;
+  getOrInsert(key: object | symbol, value: any): any;
+  getOrInsertComputed(key: object | symbol, (key: any) => value: any): any;
 }
 ```
 
 ## [Entry points]({docs-version}/docs/usage#h-entry-points)
 ```plaintext
 core-js/proposals/map-upsert-v4
-core-js(-pure)/actual|full/map/get-or-insert
-core-js(-pure)/actual|full/map/get-or-insert-computed
-core-js(-pure)/actual|full/weak-map/get-or-insert
-core-js(-pure)/actual|full/weak-map/get-or-insert-computed
+core-js(-pure)/es|stable|actual|full/map/get-or-insert
+core-js(-pure)/es|stable|actual|full/map/get-or-insert-computed
+core-js(-pure)/es|stable|actual|full/weak-map/get-or-insert
+core-js(-pure)/es|stable|actual|full/weak-map/get-or-insert-computed
 ```
 
 ## Examples

docs/web/docs/menu.json

@@ -237,6 +237,10 @@
                 "title": "New Set methods",
                 "url": "{docs-version}/docs/features/proposals/set-methods"
               },
+              {
+                "title": "Map upsert",
+                "url": "{docs-version}/docs/features/proposals/map-upsert"
+              },
               {
                 "title": "Math.sumPrecise",
                 "url": "{docs-version}/docs/features/proposals/math-sumprecise"
@@ -250,10 +254,6 @@
                 "title": "Joint iteration",
                 "url": "{docs-version}/docs/features/proposals/joint-iteration"
               },
-              {
-                "title": "Map upsert",
-                "url": "{docs-version}/docs/features/proposals/map-upsert"
-              },
               {
                 "title": "Symbol.metadata for decorators metadata proposal",
                 "url": "{docs-version}/docs/features/proposals/symbol-metadata"