Why Vue 3 Relies on WeakMap for Reactivity and Memory‑Safe Caching

When reading Vue 3's reactivity implementation you’ll notice a WeakMap created as a cache for each object, preventing duplicate proxying and enabling proper garbage collection.

const reactiveMap = new WeakMap();
const mutableHandlers = { get, set };
function reactive(target) {
  return createReactiveObject(target, mutableHandlers, reactiveMap);
}
function createReactiveObject(target, baseHandlers, proxyMap) {
  if (!isObject(target)) return target;
  const existsProxy = proxyMap.get(target);
  if (existsProxy) return existsProxy;
  const proxy = new Proxy(target, baseHandlers);
  proxyMap.set(target, proxy);
  return proxy;
}

The WeakMap cache ensures that an object is proxied only once; subsequent calls return the existing proxy.

What Is WeakMap

A WeakMap is a collection of key‑value pairs where the keys are weak references to objects. Keys must be objects, while values can be any type.

Syntax

new WeakMap([iterable])

The optional iterable is an array of key‑value pairs that are added to the new WeakMap.

Methods

WeakMap

provides four methods: get, set, has, and delete. Example usage:

const wm1 = new WeakMap(), wm2 = new WeakMap(), wm3 = new WeakMap();
const o1 = {}, o2 = function(){}, o3 = window;
wm1.set(o1, 37);
wm1.set(o2, "azerty");
wm2.set(o1, o2);
wm2.set(o3, undefined);
wm2.set(wm1, wm2);
wm1.get(o2); // "azerty"
wm2.has(o2); // false
wm1.delete(o1);
wm1.has(o1); // false

Why Use WeakMap Instead of Map

Using a regular Map stores strong references to keys, preventing the garbage collector from reclaiming those objects even when no other references exist, which can lead to memory leaks. Operations on a naive Map implementation are also O(n) because they require linear scans of internal arrays.

In contrast, WeakMap holds weak references to its keys, allowing the engine to collect the key objects when they become unreachable elsewhere, eliminating the leak risk.

Because WeakMap keys are not enumerable, you cannot obtain a list of all keys; if you need such a list you must use a Map instead.

Weak References

A weak reference does not prevent its target object from being reclaimed by the garbage collector. If an object is referenced only weakly, it may be collected at any time.

In computer programming, a weak reference is a reference that does not prevent its referent from being reclaimed by the garbage collector. An object referenced only by weak references is considered inaccessible and may be collected.

Garbage‑Collection Mechanisms

Modern JavaScript engines use two main strategies: mark‑and‑sweep (based on reachability) and reference counting . Mark‑and‑sweep periodically marks all objects reachable from roots and then frees the unmarked ones. Reference counting tracks the number of references to each object, freeing it when the count drops to zero, but it cannot resolve cyclic references without weak references.

WeakMap Applications

Storing DOM Nodes

Using DOM elements as keys allows associating data with a node without preventing its removal:

const myWeakMap = new WeakMap();
myWeakMap.set(document.getElementById('logo'), { timesClicked: 0 });
document.getElementById('logo').addEventListener('click', () => {
  const data = myWeakMap.get(document.getElementById('logo'));
  data.timesClicked++;
});

When the element is removed from the document, the associated data is automatically garbage‑collected.

Data Caching

Vue 3 uses a WeakMap as a cache for reactive objects, allowing you to associate auxiliary data with an object without altering the original structure.

Private Class Fields

TypeScript’s compiled private fields rely on a WeakMap. Three approaches to implement private data are demonstrated:

Closure (fails because instances share the same private value).

Symbol (works but the symbol can be accessed externally). WeakMap (provides true privacy and per‑instance storage).

const testFn = (function() {
  let data = new WeakMap();
  class Test {
    constructor(val) { data.set(this, val); }
    getData() { return data.get(this); }
  }
  return Test;
})();
let t1 = new testFn(3);
let t2 = new testFn(4);
console.log(t1.getData()); // 3
console.log(t2.getData()); // 4

This pattern cleanly isolates private state per instance.

Conclusion

Because WeakMap holds weak references, it prevents memory leaks when objects become unreachable, making it ideal for Vue 3’s reactivity cache, DOM‑node data storage, and implementing truly private class fields.