References

Beginner-friendly references for web development, with live, editable examples.

The JavaScript WeakMap object

Object JavaScript All modern browsers Updated
Quick answer

A WeakMap is like a Map but its keys must be objects and are held weakly — if a key object is no longer referenced anywhere else, it can be garbage collected and its entry disappears. That makes it ideal for attaching private data or metadata to objects without causing memory leaks. It isn't iterable and has no size.

Overview

A WeakMap stores key-value pairs where the keys must be objects (not strings or numbers) and are referenced weakly. "Weakly" is the whole point: if the only thing referencing a key object is the WeakMap, the garbage collector is free to remove it, and the entry vanishes automatically. A regular Map holds its keys strongly, so anything you put in it lives until you explicitly delete it — a common source of memory leaks.

The API is a deliberately small subset of Map: set(key, value), get(key), has(key) and delete(key). There's no size, no clear(), and crucially no iteration — you can't loop a WeakMap or list its keys, because which entries still exist depends on garbage collection, which isn't observable.

Its main use is associating private or extra data with an object without modifying the object itself and without preventing it from being cleaned up — caching computed results keyed by an object, storing private fields for a class, or tagging DOM nodes with metadata that disappears when the node is removed. Its set-flavored cousin is WeakSet. When you need iteration, size, or non-object keys, use a regular Map instead.

Syntax

const wm = new WeakMap();
const key = {};

wm.set(key, "data");
wm.get(key);   // "data"
wm.has(key);   // true
// no size, no iteration, keys must be objects

Example

Live example 
<pre id="out" style="font:15px ui-monospace,monospace"></pre>
<script>
  const privateData = new WeakMap();

  function User(name) {
    privateData.set(this, { name }); // private, leak-free
  }
  User.prototype.getName = function () {
    return privateData.get(this).name;
  };

  const u = new User('Ada');
  document.getElementById('out').textContent = 'name: ' + u.getName(); // Ada
</script>

Best practices

  • Use a WeakMap to attach data to objects without preventing their garbage collection.
  • Keys must be objects — use a regular Map for primitive keys.
  • Don't expect iteration or size — they don't exist on a WeakMap.
  • Reach for it to avoid memory leaks when caching or storing metadata keyed by objects/DOM nodes.

Frequently asked questions

What is the difference between a Map and a WeakMap?
A Map holds keys strongly (any type) and is iterable with a size; a WeakMap requires object keys, holds them weakly (so they can be garbage collected), and is not iterable.
Why use a WeakMap?
To attach private data or metadata to objects without leaking memory — entries vanish when the key object is no longer referenced.
Can I loop over a WeakMap?
No. It has no iteration and no size, because garbage collection makes its contents non-deterministic. Use a Map if you need to iterate.
Can WeakMap keys be strings?
No — keys must be objects (or non-registered symbols). Primitives like strings and numbers aren't allowed.
URLSearchParams WeakSet