WeakMap and garbage-collected metadata

Understanding WeakMap and garbage-collected metadata

A WeakMap is a lookup table whose keys must be objects and whose entries are not owned by the map. It exposes only get, set, has and delete: no size, no forEach, no iterator, no clear. The mental model is a note pinned to an object from the outside: the note can name the object, but it is not what keeps that object in memory, and once nothing else in the program can reach the object, the whole entry, key and value, becomes garbage.

The missing features follow from that guarantee rather than from an unfinished API. A primitive key is rejected because two occurrences of the string 'id' are one value with no identity and no lifetime, so an entry keyed by it could never be released. Listing entries is forbidden because entries disappear at moments only the collector chooses, so a size or an iterator would let a program detect whether collection had run yet, making memory behaviour observable and results dependent on memory pressure. The rules are coherent enough that a stored value may point back at its own key without keeping the entry alive.

Reach for a WeakMap when the data belongs to an object whose lifetime you do not control: DOM nodes, objects handed to your library by a caller, or instances of your own class that need state no property enumeration reveals. The discipline is that weak means this map adds no reference, not this map removes references; reachability is the union of every reference in the program, so a debugging array of the same keys or a stray listener closing over them pins keys and values alike. The value side is also strong while the key lives, so a WeakMap of large buffers keyed by long-lived objects still grows.

const lastSeen = new WeakMap();

const a = { id: 'a' };
const b = { id: 'b' };

lastSeen.set(a, 100);
lastSeen.set(b, 250);

console.log('a ->', lastSeen.get(a), '| b ->', lastSeen.get(b));
console.log('lookalike key:', lastSeen.has({ id: 'a' }));
console.log('object untouched:', JSON.stringify(a));

lastSeen.delete(a);
console.log('after delete:', lastSeen.has(a), lastSeen.get(a));

try {
  lastSeen.set('a', 1);
} catch (err) {
  console.log('primitive key:', err.constructor.name);
}

console.log('iterable?', Symbol.iterator in lastSeen, '| size?', 'size' in lastSeen);

Worked examples

const balances = new WeakMap();

class Account {
  constructor(owner, start) {
    this.owner = owner;
    balances.set(this, start);
  }
  deposit(amount) {
    balances.set(this, balances.get(this) + amount);
    return this;
  }
  get balance() {
    return balances.get(this);
  }
}

const acct = new Account('Ada', 50);
acct.deposit(25).deposit(25);

console.log(acct.balance);
console.log(JSON.stringify(acct));
console.log(Object.getOwnPropertyNames(acct).join(','));
console.log(balances.get({ owner: 'Ada' }));

const cache = new WeakMap();
let runs = 0;

function summary(order) {
  if (cache.has(order)) return cache.get(order);
  runs++;
  const total = order.items.reduce((sum, i) => sum + i.price * i.qty, 0);
  const result = { total, count: order.items.length };
  cache.set(order, result);
  return result;
}

const order = { items: [{ price: 3, qty: 2 }, { price: 10, qty: 1 }] };

console.log(summary(order).total, summary(order).total, 'runs:', runs);
console.log('same result object:', summary(order) === summary(order));

order.items.push({ price: 5, qty: 1 });
console.log('after mutation:', summary(order).total, 'runs:', runs);

cache.delete(order);
console.log('after invalidation:', summary(order).total, 'runs:', runs);

const strong = new Map();
const weak = new WeakMap();

let n1 = { name: 'n1' };
let n2 = { name: 'n2' };

for (const n of [n1, n2]) {
  strong.set(n, { hits: 0 });
  weak.set(n, { hits: 0 });
}

n1 = null;
n2 = null;

console.log('map size:', strong.size);
console.log('map still returns:', [...strong.keys()].map(k => k.name).join(','));
console.log('weakmap listing methods:', typeof weak.keys, typeof weak.forEach);

Important notes

Common mistakes

Try it yourself