How does a WeakMap differ from a regular Map?

Map objects retain strong references to their keys, preventing garbage collection. WeakMap objects hold weak references, allowing keys to be collected. Keys must be objects, and iteration is prohibited.

Why are WeakMap entries not enumerable?

Garbage collection timing is non-deterministic. Exposing entry lists would reveal when memory recovery occurred. The specification prohibits size and iteration properties to prevent engine leakage.

What is the primary role of a WeakRef?

A WeakRef holds object references without preventing garbage collection. Call .deref() to retrieve targets. This method returns undefined if the object has already been garbage collected.

When should I use a WeakMap instead of private class fields?

Use private fields for instance attributes on classes you write. Reach for WeakMap to store private data on foreign instances or plain objects that do not support private fields.

Is FinalizationRegistry guaranteed to run callbacks?

No, engines may skip callbacks if programs exit early. Treat these execution routines as non-critical optimizations. Always use explicit cleanups or try/finally blocks for essential operations.

Build / Code / JavaScript

JavaScript WeakMap and WeakRef

Store object-keyed data and hold references without blocking garbage collection in JavaScript.

TL;DR

Store object-keyed properties using weak references to support garbage collection.
Hold object references without preventing the engine garbage collection process.
Use FinalizationRegistry objects to configure cleanup callbacks for collected references.

Jump to section

What WeakMap Is
Non-Enumerable design
Private Data Caches
WeakRef
FinalizationRegistry

What WeakMap Is

WeakMap key values

Stores key-value entries where keys are object references.

const cache = new WeakMap();
const user = { id: 1 };
cache.set(user, { clicks: 3 });

Weak references

Allows garbage collection of key objects when references disappear.

let el = document.querySelector("#widget");
cache.set(el, { clicks: 0 });
el = null; // entry can be collected now

Key constraints

Requires object keys, throwing errors when primitives are passed.

// cache.set("key", 1); // TypeError

Non-Enumerable design

No iteration

Prohibits access to size, keys, and values properties.

const wm = new WeakMap();
console.log(wm.size); // undefined
// [...wm]; // TypeError: wm is not iterable

Deterministic safety

Hides garbage collector actions to keep behavior predictable.

// Non-enumerable design prevents observation

Private Data Caches

Property encapsulation

Attaches private attributes to objects without changing structures.

const privateData = new WeakMap();
class Account {
  constructor(b) { privateData.set(this, { b }); }
  getBal() { return privateData.get(this).b; }
}

Metadata attachment

Caches calculated values keyed to specific element instances.

const sizeCache = new WeakMap();
function getBounding(el) {
  if (!sizeCache.has(el)) {
    sizeCache.set(el, el.getBoundingClientRect());
  }
  return sizeCache.get(el);
}

WeakRef

Object wrappers

Wraps object references without blocking garbage collection.

let obj = { data: "large" };
const ref = new WeakRef(obj);
ref.deref(); // { data: "large" }

deref() checks

Queries deref references, verifying presence before accesses.

obj = null;
// after GC executes:
const target = ref.deref();
if (target) console.log(target.data);

FinalizationRegistry

Cleanup callbacks

Registers callbacks to execute after objects are collected.

const reg = new FinalizationRegistry(held => {
  console.log("collected:", held);
});
reg.register(obj, "label");

Tips

Attach metadata records to external object keys safely using self-cleaning WeakMap caches.
Create memory-sensitive caches using WeakRef to let engines collect references under pressure.

Warnings

Avoid setting primitive keys on WeakMap because keys must always be object references.
Do not rely on FinalizationRegistry for critical updates since callback execution timing is unpredictable.

In Practice

Caches DOM bounding rectangles using a WeakMap to automatically purge cache data when nodes are removed.

Create a WeakMap instance to hold the DOM element cache.
Check if the cache contains bounding rects for the query element.
Calculate bounds using the element's bounding rect API.
Store calculated bounds in the cache mapped to the element.
Return cached bounds directly without executing repetitive calculations.

function createBoundingCache() {
  const cache = new WeakMap();

  function getBounds(element) {
    if (!cache.has(element)) {
      const rect =
        element.getBoundingClientRect();
      cache.set(element, rect);
    }
    return cache.get(element);
  }

  return { getBounds };
}