Map.prototype.delete()

map.delete(key)

Returns boolean· Updated June 2, 2026· Map and Set

mapdeleteremove

The delete() method removes a single entry from a Map by key. It is the targeted removal tool for Maps — use it when you know exactly which key to remove. For removing all entries at once, use clear(). For removing entries that match a condition, iterate with forEach or for...of and call delete() selectively.

Key matching uses the SameValueZero algorithm: primitive values are compared by value, while object keys are compared by reference. This means you must hold a reference to the original key object to delete it. It returns true when the key existed and the entry was removed, or false when the key was not present. That boolean return value makes Map.prototype.delete() handy for cache invalidation, conditional cleanup, and other code paths where you want to know whether anything actually changed.

Syntax

map.delete(key)

Parameters

Parameter	Type	Description
key	any	The key to remove from the map

Return Value

Returns true if the key existed and was removed. Returns false if the key was not found. The boolean return lets you distinguish between “was present and removed” and “was never there,” which is useful for conditional logic after deletion.

Examples

Basic usage

const roles = new Map([
  ['alice', 'admin'],
  ['bob', 'editor'],
  ['charlie', 'viewer']
]);

console.log(roles.delete('bob'));
// true

console.log(roles.has('bob'));
// false

console.log(roles.size);
// 2

When the key exists, delete() removes the entry, shrinks the Map by one, and returns true. A subsequent has() call confirms the key is gone. When the key is not present, delete() returns false without modifying the Map — it is a safe no-op, not an error that needs try/catch.

Deleting a missing key

const cache = new Map([['theme', 'dark']]);

console.log(cache.delete('language'));
// false

console.log(cache.size);
// 1

Because delete() tells you whether it actually removed anything, the return value doubles as an existence check. You can build conditional logic where removal and the existence test happen in a single method call, avoiding a separate has() check before the delete(). The next example uses this return value directly in an if statement.

Conditional invalidation

const sessions = new Map([
  ['a1', { user: 'alice' }],
  ['b2', { user: 'bob' }]
]);

function invalidateSession(id) {
  if (sessions.delete(id)) {
    return `Session ${id} removed`;
  }

  return `Session ${id} was not active`;
}

console.log(invalidateSession('a1'));
// Session a1 removed

delete() vs clear()

delete(key) removes a single entry by key and returns a boolean: true when the key was found, false otherwise. In contrast, clear() wipes every entry at once and returns undefined. Use delete for targeted removal when you know which key to eliminate; use clear when you want to reset the entire Map, such as emptying a cache between test runs.

const m = new Map([['a', 1], ['b', 2], ['c', 3]]);

m.delete('b');    // removes only 'b'; returns true
console.log(m.size); // 2

m.clear();        // removes everything
console.log(m.size); // 0

Key comparison

delete() uses the SameValueZero algorithm for key lookup — the same rule Map uses when storing entries. Object keys are matched by reference rather than by content. Two objects with identical property structure but different references count as different keys, so you must delete with the exact object you originally used as the key.

const key1 = { id: 1 };
const key2 = { id: 1 };

const m = new Map();
m.set(key1, 'first');

console.log(m.delete(key1)); // true
console.log(m.delete(key2)); // false — different reference

Using delete() in a drain pattern

Because object keys are compared by reference, you must hold the exact object you used as a key when you call delete(). This identity-based matching is what makes the drain pattern reliable — the same reference that stored the entry is the one that removes it, giving you a natural way to detect whether an item has already been consumed.

delete() is commonly used to “consume” an entry from a cache or session map — the boolean return lets you detect double-processing:

const processing = new Map([
  ['job:1', { payload: 'data' }],
  ['job:2', { payload: 'more' }]
]);

function claim(jobId) {
  const job = processing.get(jobId);
  if (!processing.delete(jobId)) {
    return null; // already claimed or never existed
  }
  return job;
}

claim('job:1'); // returns job, removes from map
claim('job:1'); // returns null — already gone

Performance

Map.prototype.delete() runs in O(1) average time, the same as Map.prototype.set() and Map.prototype.get(). Deleting from a large Map does not require shifting elements the way Array.prototype.splice() does, which makes Map a better choice than an array when you need frequent insertions and deletions by key.

After deletion, the Map size decreases by one. In long-running applications that accumulate many short-lived entries, calling delete() (or clear()) regularly avoids memory pressure from entries that are no longer needed.