WeakMap & WeakSet

Notes that belong to an object

You have already met Map. A Map stores pairs: each key leads to one value. You can count its pairs, loop over them, and keep them as long as you like.

A WeakMap also stores pairs, but each key must be an object. It is made for one job: attach extra data to an object without keeping that object alive.

What does "keeping an object alive" mean? JavaScript frees the memory of objects that your code can no longer get to. This cleanup is called garbage collection. A normal Map is one way to get to its keys, so a Map stops its keys from being cleaned up. A WeakMap does not.

You will use this idea in three ways in this lesson:

• Saving a result for each object, so you don't work it out twice. This is called a cache.
• Keeping private data for each object.
• Marking objects you have already handled, with a WeakSet.

This lesson uses ideas from Map and Set, Symbols, Objects & references, and Closures. Two later lessons, Memory management & garbage collection and Weak references & ephemerons, go deeper. Here you need one word. An object is reachable when your code can still get to it through a variable or through another object.

The "weak" in WeakMap does not mean small or slow. It means the WeakMap's link to each key is weak. That link alone does not keep the key alive.

While your code can still reach the key in some other way, a WeakMap works like a Map. get, has, set, and delete all work as usual. The difference only shows when the rest of your code lets go of the key.

Step through one object used as a key in both a Map and a WeakMap:

1const profile = { id: 42 };Run2const strong = new Map();3const weak = new WeakMap();4 5strong.set(profile, "kept by Map");6weak.set(profile, "attached weakly");7 8console.log(strong.get(profile));9console.log(weak.get(profile));

The replay never shows a pair disappearing. That is on purpose. Your code can't see when garbage collection runs. The engine, the program that runs your JavaScript (like the one inside Chrome), picks the time and keeps it private. This lesson can show you the rules, and a model of which objects are reachable. It can't show the engine's real memory.

1const firstUser = { id: 7 };2const secondUser = { id: 7 };3const notes = new WeakMap();4 5notes.set(firstUser, "first");6console.log(notes.get(firstUser));7console.log(notes.has(secondUser));

Lines 1 and 2 make two different objects. Both happen to hold id: 7. Line 5 stores a note for firstUser, and line 6 prints first. Line 7 asks about secondUser and prints false.

A WeakMap finds a key by which object it is, not by what the object holds. Two objects with the same contents are still two different keys.

A WeakMap has only four methods:

• set(key, value) stores a value for a key.
• get(key) reads the value back.
• has(key) answers true or false: is there a pair for this key?
• delete(key) removes the pair.

A WeakSet has three, the same ones a Set uses to add and check items: add, has, and delete.

The rule for keys is strict:

• A WeakMap key must be an object, or a symbol made with Symbol().
• A WeakSet item follows the same rule.
• Anything else, like a string or a number, throws a TypeError.

1const metadata = new WeakMap();2const user = {};3const settings = { theme: "light" };4 5metadata.set(user, settings);6console.log(metadata.get(user).theme);

Line 3 makes a settings object. Line 5 stores it as the value for user. Line 6 prints light. The value is held normally, so it is still there.

Now run all the rules in one program. Watch for two errors at the end:

1const weakMap = new WeakMap();Run2const weakSet = new WeakSet();3const obj = {};4const localSymbol = Symbol("token");5const registered = Symbol.for("token");6 7weakMap.set(obj, "object ok");8weakSet.add(obj);9weakMap.set(localSymbol, "symbol ok");10 11console.log(weakMap.get(obj));12console.log(weakSet.has(obj));13console.log(weakMap.get(localSymbol));14console.log(typeof weakMap.size);15console.log(typeof weakMap.keys);16 17try { weakMap.set("id", 1); } catch (error) { console.log(error.name); }18try { weakMap.set(registered, 1); } catch (error) { console.log(error.name); }

1const notes = new WeakMap();2const user = {};3 4notes.set(user, "saved");5console.log(notes.delete(user));6console.log(notes.has(user));7console.log(notes.delete(user));

Line 5 removes the pair and prints true. Line 6 checks the same object and prints false: the pair is gone. Line 7 tries again. There is nothing left to remove, so it prints false.

Here your own code removed the pair, so you know exactly when it happened. Garbage collection is different: the engine picks the time, and your code can't see it.

1const notes = new WeakMap();2const user = {};3 4console.log(notes.get(user));5console.log(notes.has(user));

Asking about a key that has no pair is safe. Line 4 prints undefined. Line 5 prints false.

1const notes = new WeakMap();2const user = {};3 4notes.set(user, undefined);5console.log(notes.get(user));6console.log(notes.has(user));

Sometimes the stored value is undefined on purpose. Line 4 stores it. Line 5 prints undefined, the same as for a missing key. So get alone can't tell you if the pair exists. Line 6 prints true: has answers that question.

The table lists each weak collection: what it accepts, which methods it has, and which Map or Set features it leaves out.

Think of links as arrows. Many things can point to an object:

• a variable
• a property of another object
• an item in an array
• a function that remembers it (a closure)
• a key in a normal Map

If your running code can follow some chain of these arrows to an object, the object is reachable. When no chain is left, the engine is allowed to clean the object up. A WeakMap's arrow to its key doesn't count.

Try it. Pick Map or WeakMap, then run user = null and see which arrows are left:

1let user = { name: "Ada" };2const notes = new WeakMap();3notes.set(user, "cached stats");4 5user = null; // drop the last variable reference

The model is drawn with cards. It does not look at real memory. "Can be cleaned up" means the engine may free the object at some later time. It does not mean that has happened yet, and your code gets no signal when it does.

A cache saves the result of slow work, so the next call can reuse it. When the input is an object, a WeakMap makes a good cache:

• The saved result belongs to that exact object.
• The cache does not keep old objects alive forever.

Step through a cache that saves stats for a user object:

1const statsCache = new WeakMap();Run2let calculations = 0;3 4function userStats(user) {5  if (statsCache.has(user)) return statsCache.get(user);6  calculations = calculations + 1;7  const stats = { label: user.name, score: user.visits * 10 };8  statsCache.set(user, stats);9  return stats;10}11 12const ada = { name: "Ada", visits: 3 };13console.log(userStats(ada).score);14console.log(userStats(ada).score);15console.log(calculations);

You will find this pattern in real code, for example when you save:

• totals worked out from user records
• facts about the parts of a code tree
• the measured size of elements on a page

While some part of your app still uses the object, the cache works. Once nothing uses the object, its cache pair can be cleaned up with it.

A class can keep its data in a WeakMap instead of on the object. Before JavaScript had #private fields, many libraries did this:

• Put one WeakMap outside the class.
• Use each new object, this, as a key.
• Store the hidden data as the value.

Code outside can't read the WeakMap unless it can reach the variable that holds it.

1const privateData = new WeakMap();2 3class Counter {4  constructor(name) {5    privateData.set(this, { name, count: 0 });6  }7  click() {8    const data = privateData.get(this);9    data.count = data.count + 1;10    return data.name + ": " + data.count;11  }12}13 14const counter = new Counter("save");15console.log(counter.click());16console.log(counter.count);

Line 1 makes the WeakMap. Line 5 stores { name, count: 0 } with the new object as the key. Lines 8 and 9 get that data back and add 1 to the count. Line 15 prints save: 1. Line 16 prints undefined, because count is not a property of counter. It lives in the WeakMap.

The table compares three ways to keep data private. Each row says what the way is good at and what to watch for.

Compare this with the Closures lesson. A closure hides variables because a function remembers the variables around it. The WeakMap way hides a lookup table instead. In modern classes, #private fields are usually easier to read.

Sometimes a library hands you an object. You should not add your own fields to it, because the library owns it. A WeakMap lets you keep your notes beside the object, without changing the object.

1const validation = new WeakMap();2const form = { email: "asha@example.com" };3 4validation.set(form, { valid: true });5console.log(validation.get(form).valid);6console.log(form.valid);

Line 2 is a form object from another part of the app. Line 4 stores a check result for it. Line 5 reads the result from the WeakMap and prints true. Line 6 prints undefined, because the form itself did not change. When the rest of the app lets go of the form, the form can still be cleaned up.

A WeakSet answers one question: "Have I seen this object?" It stores no values. Use it for objects you handle once, like:

• widgets on a page that you have already set up
• points you have already visited while walking through a tree or a graph
• page elements that some other code created

A WeakSet holds its objects weakly, so it is never the reason an object stays alive. To pick the right tool:

• Need a saved result for each object? Use a WeakMap.
• Need to list or count the items? Use a normal Set.

1const seen = new WeakSet();2const card = {};3 4seen.add(card);5console.log(seen.has(card));6 7try { seen.add("card"); }8catch (error) { console.log(error.name); }

Line 4 adds the object from line 2, and line 5 prints true. Line 7 tries to add the string "card". A string is not an object, so it throws, and line 8 prints TypeError. A WeakSet follows the same rule as WeakMap keys: objects, and symbols made with Symbol().

1const seen = new WeakSet();2const card = {};3 4seen.add(card);5console.log(seen.delete(card));6console.log(seen.has(card));

Line 5 removes the card and prints true. Line 6 prints false. So you can take an object out of a WeakSet yourself, even though you can't list what is inside.

1const processed = new WeakSet();2const firstTodo = {};3const secondTodo = {};4 5processed.add(firstTodo);6console.log(processed.has(firstTodo));7console.log(processed.has(secondTodo));

Lines 2 and 3 make two separate todo objects. Line 5 adds only the first one. Line 6 prints true for it. Line 7 prints false for the second. Like a WeakMap, a WeakSet checks which object it is, not what the object holds.

1const processed = new WeakSet();2 3function initialize(card) {4  if (processed.has(card)) return "already initialized";5  processed.add(card);6  return "initialized now";7}8 9const card = { id: "signup" };10initialize(card);11initialize(card);

Since 2023, JavaScript also lets you use some symbols as WeakMap keys. A symbol is a unique value. There are two ways to make one:

• Symbol("local") makes a brand-new symbol. When no code holds it any more, it can be cleaned up. So it can be a WeakMap key.
• Symbol.for("name") gets a symbol from one shared list for the whole program, called the global symbol registry. That list keeps the symbol forever. So this kind, called a registered symbol, can't be a WeakMap key.

1const local = Symbol("local");2const shared = Symbol.for("shared");3const metadata = new WeakMap();4 5metadata.set(local, "ok");6console.log(metadata.get(local));7 8try { metadata.set(shared, "nope"); }9catch (error) { console.log(error.name); }

Line 1 makes a local symbol. Line 5 uses it as a key, and line 6 prints ok. Line 2 makes a registered symbol. Line 8 tries to use it as a key. That throws, and line 9 prints TypeError. The Symbols lesson explains both kinds of symbol in more detail.

Common misconceptions

• "WeakMap is just a Map with fewer methods." The missing methods are on purpose. Without them, your code can't find out when the engine cleans up an object.
• "I can make a WeakMap pair disappear right now by dropping the key." You can let go of every link to the key, but the engine still decides when to clean up. To remove a pair right now, call delete.
• "Any value can be a WeakMap key." Strings, numbers, booleans, null, and undefined throw a TypeError. So does a symbol from Symbol.for().
• "A WeakSet is for unique strings and numbers." That is a Set's job. A WeakSet only holds objects, and symbols made with Symbol().
• "Private data should always use a WeakMap." In modern class code, #private fields are usually the better choice.

Key takeaways

• A WeakMap holds its keys weakly: a pair does not keep its key object alive.
• Use a WeakMap to store a value for each object. Use a WeakSet to mark objects you have seen.
• There is no size, no keys(), and no loop, so your code can't tell when cleanup happens.
• Symbols made with Symbol() can be WeakMap keys. Symbols from Symbol.for() can't.
• For private data in a modern class, use #private fields unless you need the WeakMap way.

Final definition: WeakMap and WeakSet attach information to objects without keeping those objects alive.

Up next: JSON.