In JavaScript, a WeakMap stores pairs of a key and a value. The key must be an object. The value can be anything. You create one with new WeakMap(), then use set(), get(), has(), and delete().
The word weak is about memory. A WeakMap does not keep its keys alive. If nothing else in your program uses a key object, JavaScript may throw that object away, and its entry leaves the WeakMap with it. You never see this happen.
That is why a WeakMap has no size, no clear(), and cannot be looped over. A list of entries would change whenever memory is cleaned up. This page teaches the ideas; the WeakMap Methods index lists every method guide (set(), get(), and more).
Key = object, value = anything.
A WeakMap lets you attach extra data to an object without changing the object and without stopping it from being cleaned up.
Syntax
JavaScript Syntax
Common ways to create a WeakMap and use it:
JavaScript
const wm = new WeakMap(); // empty
const key = { id: 1 }; // keys must be objects
wm.set(key, "data"); // store (returns wm)
wm.get(key); // "data"
wm.has(key); // true
wm.delete(key); // true
const filled = new WeakMap([[key, "again"]]); // start with pairs
Memory
What Weak Means
A normal Map holds its keys strongly. After map.set(user, data), the user object stays in memory for as long as the Map lives, even if the rest of your program forgot it. Over time that is a memory leak.
A WeakMap holds its keys weakly. When the key is no longer used anywhere else, the engine may clean up the key. Its value is cleaned up too, unless something else points to it. The value is only kept while the key is alive.
You cannot watch this in a small script, because the engine decides when to clean up. So no example on these pages depends on it. Related tools are FinalizationRegistry, WeakRef, and WeakSet.
Keys
Which Keys Are Allowed
Keys can be objects, including arrays and functions. Since ES2023 they can also be symbols made with Symbol("name"). Strings, numbers, booleans, null, undefined, and registered symbols from Symbol.for() are not allowed.
set() throws a TypeError for a bad key. get(), has(), and delete() never throw: they return undefined, false, and false. A different object with the same shape is a different key, because objects are matched by identity.
Use cases
When to Use a WeakMap
Use
How it works
Why WeakMap fits
Private data
Store hidden fields in a WeakMap keyed by this
The data goes away with the object
Cache by object
Remember an expensive result for each object
The cache never keeps old objects alive
DOM node notes
Attach extra info to elements you do not own
A removed element frees its notes
Memoization
Skip repeated work when called again with the same object
No cleanup code to write
Compare
Map vs WeakMap
Question
Map
WeakMap
Allowed keys
Any value
Objects (and local symbols) only
Keeps keys alive?
Yes, until you delete them
No, keys can be cleaned up
Size
map.size
None
Loop over entries
for...of, forEach(), keys()
Not possible
Empty it
clear()
Create a new WeakMap
Best for
Data you want to list, count, or show
Hidden extra data about objects
Newer
Newer Upsert Methods
getOrInsert() and getOrInsertComputed() read a value, and store one first if the key is missing. They were added to Map and WeakMap together and replace the long if (!wm.has(k)) wm.set(k, v) pattern.
They are not in every engine yet. We tested Node.js 24.15, which does not have them, and Chrome 148, which does. Check before you rely on them: typeof WeakMap.prototype.getOrInsert === "function". Their examples include a tiny fallback so they still run everywhere.
Code
JavaScript Examples
Three short programs that show how a WeakMap works.
Example 1 — Store, Read, Check, and Remove
Use an object as the key and walk through the four classic methods in order.
A Map is a visible list.map.size is 1 and forEach is a function, so you can count and loop over its entries.
A WeakMap hides its contents.size, forEach, and clear all have type "undefined" because the WeakMap does not offer them.
The reason is memory. Entries may disappear whenever their key is cleaned up, so any list or count would be out of date. The only questions you can ask are about keys you hold.
Example 3 — Fill a WeakMap with Pairs
Pass a list of [key, value] pairs to the constructor. Every key in the list must be an object.
JavaScript
const a = { id: "a" };
const b = { id: "b" };
const meta = new WeakMap([[a, "first"], [b, "second"]]);
console.log(meta.get(b)); // second
console.log(meta.get({ id: "a" }) === undefined); // true
try {
new WeakMap([["a", 1]]);
} catch (e) {
console.log(e.name); // TypeError
}
A WeakMap is a collection of key and value pairs where every key must be an object. The keys are held weakly: the WeakMap does not stop the engine from cleaning up a key that nothing else uses. You create one with new WeakMap() and use set(), get(), has(), and delete().
Strings and numbers are plain values that are never cleaned up like objects, so there would be nothing to hold weakly. set() throws a TypeError for them. Objects (including arrays and functions) work, and since ES2023 so do symbols made with Symbol().
Entries can disappear whenever the engine cleans up a key, and that timing is not predictable. A size or a list would be wrong a moment later, so WeakMap only lets you ask about keys you already hold.
A Map accepts any key, keeps keys alive, has size, and can be looped over. A WeakMap accepts only objects as keys, does not keep them alive, and cannot be counted or looped. Choose a Map for data you show or count, and a WeakMap for hidden extra data about objects.
Use it when data belongs to an object and should disappear with it: private fields, a cache keyed by object, notes about DOM elements, or memoized results. If you need to list or count the entries, use a Map instead.