WeakRef & FinalizationRegistry

Weak reachability, not weak responsibility

JavaScript normally works with strong references: if a variable, object property, closure, array, or map entry can reach an object, the garbage collector must keep that object. A weak reference is different. It lets your code point at a target without making that target reachable for the future.

Start by separating this from WeakMap and WeakSet. A WeakMap weakens its keys: the object key can disappear without the map keeping it alive. A WeakRef weakens a target you read through deref(), so it is closer to a weak value. Both ideas depend on the reachability rules from memory management.

This lesson also connects back to closures, because closures can accidentally keep values alive, and symbols, because non-registered symbols can be weak targets. We will link forward to resource management for deterministic cleanup patterns such as using.

Creating a weak reference is direct: new WeakRef(target). Reading it is deliberately indirect: call ref.deref(), then branch on the result. If the result is an object, use it immediately. If it is undefined, rebuild the value or treat the cache as a miss.

The first experiment shows a subtle guarantee from the specification. After a target is created as a WeakRef target or returned by deref(), it is kept alive until the end of the current synchronous job. That is sometimes called KeepDuringJob. It does not make the object permanent.

1let target = { label: "decoded image" };Run2const ref = new WeakRef(target);3target = null;4 5const first = ref.deref();6const second = ref.deref();7console.log(first === second);8console.log(first?.label ?? "collected");

Read the code line by line: line 1 creates the object, line 2 creates the weak reference, and line 3 removes the ordinary variable. Lines 5 and 6 call deref() in the same turn, so line 7 prints true. In a later task, both calls must still be treated as possibly undefined.

Weak targets must be values the garbage collector can track independently. Objects work. Since ES2023, non-registered symbols from Symbol() also work. Registered symbols from Symbol.for() and primitives like numbers, strings, booleans, null, and undefined are not valid targets.

1const target = { name: "object target" };2const ref = new WeakRef(target);3console.log(ref.deref() === target);

1const objectTarget = { name: "object target" };2const localSymbol = Symbol("local target");3 4console.log(new WeakRef(objectTarget).deref() === objectTarget);5console.log(new WeakRef(localSymbol).deref() === localSymbol);

The next two examples fail on purpose. The lesson marks them as expected errors so the editor can show the TypeError without treating the example as broken.

1const target = Symbol.for("shared target");2new WeakRef(target);

1new WeakRef(42);

FinalizationRegistry lets you register a target and a separate held value. If the target is collected and the engine later runs finalizers, your callback receives the held value. That wording is careful because collection and callback scheduling are not deterministic.

1const registry = new FinalizationRegistry((heldValue) => {2  console.log("cleanup requested for", heldValue);3});4 5const token = {};6const widget = { id: "preview" };7registry.register(widget, "preview card", token);8console.log(registry.unregister(token));9console.log(registry.unregister(token));

Line 7 registers widget with a string held value and a token object. Line 8 removes that registration and prints true. Line 9 prints false because there is nothing left for the same token.

1const registry = new FinalizationRegistry(() => {});2const target = {};3registry.register(target, target);

A weak cache often uses a normal Map for stable keys such as URLs or file paths, and WeakRef values for large objects such as decoded images or ASTs. A FinalizationRegistry can later remove stale keys, but only after checking the current map entry.

The guard matters because callbacks can be late. A file path might be decoded again before a finalizer for the old object runs. If the callback blindly deletes the key, it can delete fresh work. The helper below calls ref.deref() === undefined before deleting.

1const records = new Map();Run2const registry = new FinalizationRegistry((key) => {3  deleteIfStale(key);4});5 6function deleteIfStale(key) {7  const ref = records.get(key);8  if (ref?.deref() === undefined) {9    records.delete(key);10  }11}12 13function remember(key, value) {14  records.set(key, new WeakRef(value));15  registry.register(value, key, value);16}17 18function read(key) {19  const value = records.get(key)?.deref();20  if (value === undefined) {21    records.delete(key);22  }23  return value;24}25 26remember("app.js", { type: "OldProgram" });27remember("app.js", { type: "NewProgram" });28// A late finalizer for the old object would call this helper.29deleteIfStale("app.js");30console.log(read("app.js").type);

In production, remember would run when you decode or parse a value. read would run when the page asks for the value. The finalizer callback is only a best-effort way to trim stale keys; normal cache reads still need to handle misses.

Garbage collection is intentionally invisible. An engine may collect late, never collect before a process exits, or skip finalizer callbacks before a page unloads. The TC39 weak references guidance says to avoid these features where possible. Use them only when every missed callback is harmless.

1const registry = new FinalizationRegistry((label) => {2  console.log("cleanup for", label);3});4 5let node = { label: "preview" };6registry.register(node, "preview");7node = null;8 9// After this point the callback may run soon, much later, or never.

Browser tools can help you experiment manually. In Chrome DevTools, the Memory panel has a Collect garbage button. That is useful for learning and debugging, but it is not something page code can rely on. A demo that says “click this and the object will be collected” is teaching the wrong mental model.

1const handle = {2  close() {3    console.log("closed");4  },5};6 7try {8  console.log("use handle");9} finally {10  handle.close();11}

The same rule applies to explicit resource management. Use try/finally, a documented close() or dispose() method, framework teardown, and in newer JavaScript the using family taught in the next lesson. A finalizer is not a substitute for those paths.

The best uses are optional: caches of big decoded images, parsed ASTs, or formatted data that can be recreated; observers that should not own what they observe; and leak-detection tests where losing a notification fails safe. The wrong uses are essential cleanup tasks.

Common misconceptions

• “WeakRef makes collection happen.” It only stops your reference from keeping the target alive. The engine chooses when to collect.
• “If deref() worked once, it will work later.” The result can be undefined in a later job. Check every time.
• “Finalizers are a cleanup hook.” They are best-effort notifications. Essential cleanup belongs in explicit code.
• “The held value can be the target.” It cannot; that would keep the target alive, so the API throws.
• “A registry callback can blindly delete a cache key.” It must check the current WeakRef, because the key may have been re-added.
• “WeakRef is a general performance trick.” It is a niche tool. Prefer simpler strong caches with size limits unless weak ownership is the actual requirement.

Key takeaways

• WeakRef does not keep a target alive; deref() may return undefined.
• Creation and deref() keep a target alive only for the current synchronous job.
• Objects and non-registered symbols can be weak targets; primitives and registered symbols cannot.
• FinalizationRegistry callbacks are best-effort and must never be essential cleanup.
• A weak cache deletes stale keys only after checking the current WeakRef.

Up next: explicit resource management.