Map.prototype.set()
Adds or overwrites an entry and returns the map, so calls can be chained.
set(key, value)- Added in JavaScript ES2015
Parameters
| Parameter | Type | Description |
|---|---|---|
$key | any | The key of the entry to add or modify. Can be any value; object keys are compared by reference, not by structure. |
$value | any | The value to store under that key. Can be any value, including undefined. |
Return value
MapThe Map object itself, which is what makes chained calls possible.
Errors
Throws a TypeError when called on a value that is not a real Map, such as a plain object borrowing the method.
Changelog
- PHP ES2015Introduced returning the Map itself, enabling chaining.
set() is the only way to put an entry into a Map. If the key already exists the value is replaced in place — the entry keeps its original position in iteration order, it does not move to the end. That is worth knowing when you are updating a counter or a cache and expect "most recently touched" ordering; you would have to delete() then set() to get that.
Chaining
The return value is the map, not the value and not undefined, so map.set(a, 1).set(b, 2) works and you can build a populated map in one expression. Do not accidentally write const v = map.set(k, x) expecting the value back.
Key identity
Keys are compared with SameValueZero. In practice: NaN is a usable key that equals itself, 0 and -0 are the same key, and 1 and "1" are two different keys. Objects and arrays are matched by reference, so building a fresh object at lookup time never finds the entry.
Storing undefined as a value is legal and creates a real entry — use has(), not get(), to check presence afterwards.
Example
When to use it
- Build a lookup table in a single chained expression
- Increment a counter keyed by an arbitrary value
- Memoize results keyed by an argument object
- Register handlers keyed by a function or symbol
Frequently asked questions
What does Map.prototype.set() return?
It returns the Map itself, not the value you stored, which is why set() calls can be chained together.
Does setting an existing key move it to the end of the map?
No. Overwriting a key updates the value in place and the entry keeps its original insertion position. Delete the key first and set it again if you want it moved to the end.
Why can't I retrieve a value I stored under an object key?
Map compares object keys by reference. Looking up with a newly created object that merely looks the same returns undefined; keep the original key object around.
More examples
Counting occurrences
get() returns undefined for a key seen for the first time, so ?? 0 supplies the starting count. The order of the output follows first appearance, not frequency, because overwriting a key never reorders it.
const words = ["fig", "pear", "fig", "plum", "fig"];
const tally = new Map();
for (const w of words) {
tally.set(w, (tally.get(w) ?? 0) + 1);
}
console.log([...tally]);
console.log(tally.get("fig"));Numbers and strings are different keys
A Map keeps 1 and "1" apart because it compares keys without coercion. A plain object coerces every key to a string, so the same two assignments collapse into a single property.
const ids = new Map();
ids.set(1, "number one");
ids.set("1", "string one");
console.log(ids.size); // 2
console.log(ids.get(1));
console.log(ids.get("1"));
const obj = { 1: "only one" };
obj["1"] = "overwritten";
console.log(Object.keys(obj).length); // 1
Discussion