Map.prototype.delete()

A useful return value, which the delete operator on objects does not give you — that one reports whether deletion was ALLOWED, not whether anything was removed.

Map methodES2015Live demo
Common call
map.delete(key)
Returns
boolean — was it actually there?
Replaces
delete obj[key], which cannot tell you
Watch out
a Map holds keys strongly — use WeakMap for object keys
map.delete(keykey — The key to remove, matched by SameValueZero. A missing key is not an error — it simply returns false.type: any · required)
→ boolean

Demo

Live evaluation
Try:
Inputs
jsonstringJSON pairs, e.g. [["a",1]]
kstringkey to delete
Output
(m => [m.delete('a'), m.size])(new Map(JSON.parse('[["a",1],["b",2]]')))
[true, 1]

The pair is [did it delete, how many remain]. A present key gives true and the size drops; an absent key gives false and nothing changes. That boolean is genuinely useful — it lets you act on whether the entry existed without a separate has() call, which the delete operator on plain objects cannot do at all.

Parameters

NameTypeRequiredDescription
keyanyyesThe key to remove, matched by SameValueZero. A missing key is not an error — it simply returns false.

Return value

boolean — True if an entry was removed, false if the key was not there. clear() removes everything and returns undefined.

Common patterns

Delete and react
The return value saves a has() call.
if (cache.delete(key)) log("evicted", key);
Empty the whole Map
clear returns undefined, not a count.
cache.clear();
Let object keys be collected
WeakMap does not hold its keys alive.
const meta = new WeakMap();
meta.set(node, data);

Examples

1. Present
new Map([["a", 1]]).delete("a")
Returns
true
2. Absent
new Map().delete("a")
Returns
false
3. Twice
const m = new Map([["a", 1]]); [m.delete("a"), m.delete("a")]
Returns
[true, false]
4. clear returns undefined
new Map([["a", 1]]).clear()
Returns
undefined
5. Size after clear
const m = new Map([["a", 1]]); m.clear(); m.size
Returns
0
6. The object operator differs
delete {}.missing
Returns
true // always, if configurable

Pitfalls

1. A Map holds its keys strongly
Using DOM nodes or other objects as keys keeps them alive for as long as the Map exists, even after everything else has dropped its reference. A long-lived Map keyed by objects is a classic memory leak — WeakMap exists for exactly this.
Never collected
const m = new Map();
m.set(node, data);   // node stays alive
leak
WeakMap
const m = new WeakMap();
m.set(node, data);
collectable
2. clear returns undefined, not a count
Unlike delete, it tells you nothing. Read size before calling it if you need to know how much was discarded.
No information
const removed = map.clear();
undefined
Count first
const removed = map.size;
map.clear();
the old size
3. Deleting during iteration is allowed but subtle
A Map iterator visits entries in insertion order and honours changes made while iterating — deleting an entry you have not reached yet means it is never visited. Legal, and easy to reason about wrongly.
Skips entries
for (const [k] of m) m.delete(otherKey);
otherKey never visited
Snapshot first
for (const [k] of [...m]) m.delete(k);
iterates a copy
4. The delete operator does not work on entries
delete map[key] removes a property from the Map object, not an entry. It returns true — because there was no such property to fail on — which makes it look as though it worked.
Looks successful
const m = new Map([["a", 1]]);
delete m["a"];
m.size
1
Use the method
m.delete("a");
m.size
0

When to use

Use it
  • Removing one entry, especially when you want to know it existed
  • Cache eviction
  • clear() to reset a Map without reallocating it
Reach for something else
  • Object keys that should be garbage collected → WeakMap
  • Removing many entries by a predicate → rebuild from a filtered spread
  • You want the removed value → get it first, delete returns only a boolean

Notes

Complexity
O(1) average for delete; O(n) for clear
Return
A boolean from delete, undefined from clear
CPython impl
V8: Builtins-map-delete
Memory
Frees the entry; the backing store may not shrink immediately
Thread-safe
Single-threaded; deletion during iteration is defined but easy to misread

FAQ

Because they answer different questions. The delete operator reports whether the property COULD be deleted — it is true even for a property that never existed. Map.delete reports whether an entry was actually removed, which is the useful answer.

delete {}.nope;                 // true
new Map().delete("nope");       // false

History

ES2015
Map added with delete and clear, along with WeakMap for collectable object keys.