Weak references & ephemerons

Weak references in the collector

Most JavaScript references are simple: when a reachable object points at another object, the collector keeps both. Weak APIs make a deliberate exception. They let code observe or attach metadata without turning that observation into ownership.

This is an engine lesson, not an API catalogue. The published WeakMap and WeakSet and WeakRef and finalization lessons teach everyday usage. Here we ask what the collector must do so those APIs do not accidentally keep objects alive.

The previous lesson explained how collectors schedule marking work without freezing a page. Weak edges add one more rule to that marking work. The next lesson, Garbage collection across engines & the DOM, compares how real engines join JavaScript objects with browser and host objects.

Weak versus strong edges

A strong edge is an ordinary reference that the marker follows. If a reachable cart has a user property, that property makes the user reachable too. The edge is part of the normal object graph.

1const cart = { price: 3 };2const strong = { cart };3const weak = new WeakRef(cart);4 5console.log(strong.cart.price);6console.log(weak.deref()?.price);

Line 1 creates a cart. Line 2 creates an ordinary object that strongly points at it. Line 3 creates a WeakRef that can observe the same cart. Lines 5 and 6 both print 3 while the strong edge still keeps the cart alive.

Weak does not mean broken or hidden. It means “do not use this edge as a reason to preserve the target.” That distinction lets a cache attach optional information without silently changing the lifetime of every object it sees.

A WeakMap entry is conditional

Start with the small, ordinary part of WeakMap. Its key is an object, and while another strong path reaches that key, code can ask for the associated value. The map is useful for metadata that belongs beside an object rather than inside it.

1const user = { name: "Asha" };2const notes = new WeakMap();3notes.set(user, "likes tea");4console.log(notes.get(user));

Line 1 creates user. Line 2 creates the map. Line 3 attaches the string "likes tea" to that user, and line 4 prints likes tea. The variable user is an ordinary strong path, so this example says nothing surprising yet.

The crucial part is the value. A normal map would strongly preserve both key and value through the map. A WeakMap must instead wait for a separate proof that the key is live before it treats the value as live.

Ephemerons and a marking fixpoint

An ephemeron is the collector's name for the conditional rule behind a WeakMap entry. It is not simply a weak pointer from the map to a key. The collector must first mark ordinary strong paths, then revisit entries whose keys have become marked.

1const roots = ["user"];2const entry = { key: "user", value: "notes" };3console.log(roots.includes(entry.key) ? entry.value : "nothing");

Line 1 makes user live in this tiny model. Line 2 describes an entry, and line 3 prints notes because the key appears in roots. A real collector repeats this idea through a graph, rather than checking one entry with includes.

1const roots = ["user"];2const graph = { user: [] };3const entries = [{ key: "user", value: "notes" }];4 5function markEphemerons(roots, graph, entries) {6  const marked = new Set(roots);7  let changed = true;8  while (changed) {9    changed = false;10    for (const name of [...marked]) {11      for (const child of graph[name] ?? []) {12        if (!marked.has(child)) { marked.add(child); changed = true; }13      }14    }15    for (const entry of entries) {16      if (marked.has(entry.key) && !marked.has(entry.value)) {17        marked.add(entry.value); changed = true;18      }19    }20  }21  return [...marked].sort();22}23 24console.log(markEphemerons(roots, graph, entries).join(","));

Line 5 starts the model with the roots. Lines 8 through 14 follow ordinary strong edges. Lines 16 through 20 apply the special rule: only a marked key unlocks its value. The loop repeats until a full pass changes nothing, which is called a fixpoint.

1const roots = ["user"];Run2const graph = { user: [] };3const entries = [{ key: "user", value: "notes" }];4 5const result = markEphemeronsForReplay(roots, graph, entries);6console.log(result.marked.join(","));

The replay calls the same model function used by the playground. It is intentionally small: real engines optimize this work with queues and internal metadata, but the conditional “key first, then value” rule is the important part to keep.

1const roots = ["user"];2const graph = { user: [] };3const entries = [{ key: "user", value: "notes" }];4 5function markEphemerons(roots, graph, entries) {6  const marked = new Set(roots);7  let changed = true;8  while (changed) {9    changed = false;10    for (const name of [...marked]) {11      for (const child of graph[name] ?? []) {12        if (!marked.has(child)) { marked.add(child); changed = true; }13      }14    }15    for (const entry of entries) {16      if (marked.has(entry.key) && !marked.has(entry.value)) {17        marked.add(entry.value); changed = true;18      }19    }20  }21  return [...marked].sort();22}23 24console.log(markEphemerons(roots, graph, entries).join(","));

Why a value cannot rescue its key

The rule matters most in a shape that feels circular. Imagine a WeakMap value that points back to its own key. If the collector followed the value first, the value could mark the key, and a dead entry would incorrectly keep itself alive forever.

1const roots = [];2const graph = { user: [], notes: ["user"] };3const entries = [{ key: "user", value: "notes" }];4console.log(markEphemerons(roots, graph, entries).join(",") || "nothing");

Line 1 gives the model no roots. Line 2 says notes points back to user. Line 3 still describes the conditional entry. Line 4 prints nothing, because the key was never marked from elsewhere, so the entry never unlocks notes.

This is why “weak key, strong value” is an incomplete mental model for WeakMap. The value is not simply strong in all circumstances. It is conditionally strong after the collector has proof that the key belongs to the live graph.

WeakRef and finalizer timing

A WeakRef gives an optional read of a target. Calling deref() can return the object, or it can return undefined after a later collection. It is not a lease, lock, or promise that the object will remain around.

1const user = { name: "Asha" };2const ref = new WeakRef(user);3console.log(ref.deref()?.name);4console.log(ref.deref() === undefined ? "gone" : "here");

Line 1 creates an object and line 2 makes a weak observation. Line 3 prints Asha in this immediate job. Line 4 prints here for the same reason. In a later job, after the last strong path disappears, the same expression may print gone.

FinalizationRegistry can schedule a callback after an associated target is collected. The callback may run much later, run in a different environment moment, or not run before shutdown. It is a notification for optional bookkeeping, never the place to close a required file, save a draft, release a lock, or cancel a request.

For required cleanup, write an explicit operation. A resource owner can call its own close(), use the language's using patterns where available, or connect work to an AbortController. Those actions happen because your program requested them.

Keeping a target alive across a job

Weak APIs would be hard to use if a target could vanish between two nearby reads in one piece of code. JavaScript therefore gives a narrow guarantee: creating a WeakRef or getting an object from deref() keeps that target alive through the current job.

1let user = { name: "Asha" };2const ref = new WeakRef(user);3user = null;4 5const first = ref.deref();6const second = ref.deref();7console.log(first === second, second?.name);

Line 1 creates Asha's object. Line 2 creates its WeakRef, and line 3 drops the local strong reference. Lines 5 and 6 read the target twice. Line 7 prints true Asha: both reads see the same object during this synchronous run.

1let user = { name: "Asha" };Run2const ref = new WeakRef(user);3user = null;4 5const first = ref.deref();6const second = ref.deref();7console.log(first === second, second?.name);

A job here means the synchronous code currently running plus promise jobs it queues before the next task. A later timer, browser event, or other task is outside that guarantee. Do not save a weak target and assume it will still exist when a later callback runs.

Cheap Node runtime evidence

Production browser code cannot force collection, and it should not depend on a collection schedule. For a stable lesson check, Node can expose a test hook with --expose-gc. These Node-only probes wait for later tasks, retry collection, and assert simple words instead of heap sizes.

1const laterTask = () => new Promise((resolve) => setTimeout(resolve, 0));2 3function makeWeakOnly() {4  let value = { label: "weak-only", data: new Array(2000).fill("tea") };5  const ref = new WeakRef(value);6  value = null;7  return ref;8}9 10const ref = makeWeakOnly();11let collected = false;12for (let attempt = 0; attempt < 12; attempt += 1) {13  await laterTask();14  globalThis.gc();15  await laterTask();16  if (ref.deref() === undefined) { collected = true; break; }17}18console.log("weak collected", collected);

Line 4 creates an object that is returned only through a WeakRef. Lines 11 through 15 cross later tasks and retry gc(). Line 18 eventually prints weak collected true in the tested Node process. The loop avoids claiming a particular millisecond or attempt.

1const laterTask = () => new Promise((resolve) => setTimeout(resolve, 0));2 3function makeEntry() {4  let key = { name: "Asha" };5  let value = { label: "notes", data: new Array(2000).fill("tea") };6  const valueRef = new WeakRef(value);7  const map = new WeakMap();8  map.set(key, value);9  key = null;10  value = null;11  return valueRef;12}13 14const valueRef = makeEntry();15let collected = false;16for (let attempt = 0; attempt < 12; attempt += 1) {17  await laterTask();18  globalThis.gc();19  await laterTask();20  if (valueRef.deref() === undefined) { collected = true; break; }21}22console.log("ephemeron value collected", collected);

The value has a separate WeakRef so the probe can observe it without owning it. Lines 7 and 8 put the key and value into the WeakMap, then drop both locals. With no other key path, a later collection can make the value WeakRef return undefined, and the probe prints ephemeron value collected true.

1let user = { name: "Asha" };2const ref = new WeakRef(user);3user = null;4globalThis.gc();5console.log("same job", ref.deref()?.name);

Even after line 4 requests collection, line 5 prints same job Asha. This is evidence for the job rule, not an invitation to call a test-only hook from application code. The lesson intentionally omits finalizer callback evidence because it is not stable enough to teach as a promise.

Use weak APIs carefully

A good reason for WeakMap is metadata whose lifetime should match an object that somebody else owns. For example, a UI library might associate measured layout details with a user object without adding a public property to that user object.

1const user = { name: "Asha" };2const layoutNotes = new WeakMap();3layoutNotes.set(user, { row: 3 });4console.log(layoutNotes.get(user)?.row);

Line 1 is the object another part of the app owns. Line 2 creates private metadata storage. Line 3 records a row number, and line 4 prints 3. When no ordinary application path reaches the user, the map should not keep its notes alive on its own.

Do not choose a weak collection just to avoid deciding ownership. Weak collections cannot be enumerated, their entries can disappear, and they do not replace a bounded cache. Use an ordinary Map when your program needs reliable iteration, counts, eviction policy, or persistence.

Common weak-reference mistakes

• “WeakMap values are always strong.” They are conditional on their keys being otherwise reachable.
• “WeakRef gives a stable object handle.” It gives an optional observation that may be undefined later.
• “A finalizer closes resources.” Its timing is optional, so required cleanup must be explicit.
• “Calling `gc()` is an application feature.” The Node hook is test-only; browsers do not provide that promise.
• “Two weak reads can randomly disagree in one line of code.” The current job protects the observed target.

The useful discipline is simple: use ordinary strong ownership by default, use a weak association when the object's owner should control its lifetime, and never make correctness depend on the collector choosing a particular later moment.

Practice exercises

const user = { name: "Asha" };
const notes = new WeakMap();
notes.set(user, "likes tea");
console.log(notes.get(user));

const marked = new Set(["user"]);
const entry = { key: "user", value: "notes" };
if (marked.has(entry.key)) marked.add(entry.value);
console.log([...marked].sort().join(","));

const roots = [];
const entry = { key: "user", value: "notes" };
const marked = new Set(roots);
if (marked.has(entry.key)) marked.add(entry.value);
console.log([...marked].join(",") || "nothing");

Check your understanding

For each question, separate ordinary ownership, conditional WeakMap marking, optional timing, and the narrow current-job guarantee.

Key takeaways

• Strong edges preserve targets; weak edges can observe targets without owning them.
• A WeakMap behaves like ephemerons: a marked key unlocks its value during a repeated marking loop.
• A value that points back to a dead key cannot make that entry live by itself.
• WeakRef can return undefined later, and finalizers are never a required cleanup mechanism.
• Creating or reading a WeakRef keeps its target available through the current job and its promise jobs.
• Use weak APIs for optional associations, not to avoid ordinary ownership or cache policy.

Coming next: Garbage collection across engines & the DOM.