WeakRef & FinalizationRegistry

Weak references that don't prevent garbage collection, and callbacks that fire when objects are collected — when and why to use them.

What it is, in plain English: A WeakRef holds a reference to an object without preventing it from being garbage collected. If no other references to the object exist, the garbage collector can reclaim it, and WeakRef.deref() will return undefined. A FinalizationRegistry lets you register a callback that fires after an object has been collected — useful for cleanup. Both are advanced tools: most code should use WeakMap and WeakSet instead.

Where this bites you

Only objects (and non-registered symbols) can be held weakly. new WeakRef(10000), or a WeakRef to a string, throws TypeError: WeakRef: invalid target. It's an easy crash to ship in a weak cache: the code is tested with objects, then one day a computed value happens to be a number or a string.

const cache = new Map();
function remember(key, value) {
  cache.set(key, new WeakRef(value));
}

remember("report", { rows: 10000 });   // an object: fine
remember("rowCount", 10000);           // a number
// TypeError: WeakRef: invalid target

References that step aside for the garbage collector

Normally, if you have a variable pointing to an object, that object stays in memory forever — as long as your variable exists. This is called a "strong reference." A weak reference is different: it points to an object but doesn't prevent the garbage collector from deleting it if nothing else holds a strong reference.

When do you actually need this? Rarely. WeakMap and WeakSet already cover the most common use cases (associating metadata with objects without memory leaks). WeakRef and FinalizationRegistry are for advanced scenarios: caches, resource tracking, or native bridge cleanup.

WeakRef — check if an object is still alive

// Create a WeakRef to an object:
let server = { host: "localhost", port: 3000 };
const ref  = new WeakRef(server);

// .deref() returns the object if it's still alive, or undefined if GC'd:
const alive = ref.deref();
if (alive) {
  console.log(`Server: ${alive.host}:${alive.port}`);  // "Server: localhost:3000"
} else {
  console.log("Server was collected");
}

// Always use ?. with deref() — never assume it's alive:
console.log(ref.deref()?.host);   // "localhost" (or undefined if collected)

FinalizationRegistry — get notified when an object is collected

// Register a callback to fire when an object is garbage collected:
const registry = new FinalizationRegistry((heldValue) => {
  // 'heldValue' is what you passed when registering — NOT the object itself
  // (the object is already gone when this fires!)
  console.log(`Cleanup for: ${heldValue}`);
});

function createResource(name) {
  const resource = { name, data: new Array(10000).fill(0) };
  registry.register(resource, name);  // second arg = heldValue for the callback
  return resource;
}

let r = createResource("database");
// ... use r ...
r = null;  // release strong reference
// At some future point, GC runs and the callback fires:
// "Cleanup for: database"

The timing problem — why this is tricky

// Garbage collection is non-deterministic.
// You cannot predict WHEN the callback fires.
// You cannot force it to run.
// In some implementations it may never run (e.g. very short programs).

// This means FinalizationRegistry callbacks:
// ✓ Can do logging, metrics, optional cleanup
// ✗ Cannot be relied on for critical cleanup (use try/finally instead)
// ✗ Cannot be used for security-sensitive cleanup
// ✗ Cannot guarantee ordering relative to other code

Try It Yourself

// WeakRef — a reference that doesn't prevent garbage collection
let obj = { name: "Alice", data: new Array(1000).fill("x") };
const ref = new WeakRef(obj);

// While obj is still referenced elsewhere, deref() returns it:
console.log(ref.deref()?.name);  // "Alice"

// If we release our strong reference, the GC can collect obj:
// obj = null;  // (in a real program, GC would then eventually collect it)
// ref.deref()  // → undefined  (after GC runs)

// The safe pattern — always use ?. with deref():
function processIfAlive(weakRef) {
  const target = weakRef.deref();
  if (target === undefined) {
    console.log("Object was collected");
    return;
  }
  console.log("Still alive:", target.name);
}
processIfAlive(ref);  // "Still alive: Alice"

// FinalizationRegistry — run a callback after GC collects an object
const registry = new FinalizationRegistry((heldValue) => {
  console.log(`Object "${heldValue}" was garbage collected`);
});

let resource = { name: "database connection" };
registry.register(resource, "database connection");

// When resource is collected (after resource = null + GC runs),
// the callback fires with "database connection"
console.log("WeakRef and FinalizationRegistry registered.");
console.log("Note: GC timing is not deterministic — callbacks fire eventually.");

// More practical: WeakMap (already built-in — usually prefer this)
const cache = new WeakMap();
function getMetadata(obj) {
  if (!cache.has(obj)) cache.set(obj, { created: Date.now() });
  return cache.get(obj);
}
const item = { id: 1 };
console.log(getMetadata(item));  // { created: ... }
// When 'item' is GC'd, the WeakMap entry is automatically removed

Practical patterns: caches and resource tracking

WeakRef cache — avoid re-computation, allow GC

// A cache that holds objects weakly — they can be GC'd under memory pressure
class WeakCache {
  #map = new Map();  // Map<key, WeakRef>

  get(key) {
    const ref   = this.#map.get(key);
    const value = ref?.deref();
    if (value === undefined) {
      this.#map.delete(key);  // clean up stale entry
      return undefined;
    }
    return value;
  }

  set(key, value) {
    this.#map.set(key, new WeakRef(value));
  }

  getOrCompute(key, compute) {
    const cached = this.get(key);
    if (cached !== undefined) return cached;
    const result = compute();
    this.set(key, result);
    return result;
  }
}

const cache = new WeakCache();
const expensiveData = { processed: true, rows: 10000 };
cache.set("query-results", expensiveData);
console.log(cache.get("query-results")?.processed);  // true

The WeakCache above has the same gap: cache.getOrCompute("count", () => 42) throws. Primitives are small and can't be garbage-collected independently anyway, so there's nothing to gain from holding them weakly. Guard set() so only values that can be held weakly go in, and let getOrCompute return everything else without caching it:

const canHoldWeakly = (v) =>
  (typeof v === "object" && v !== null) || typeof v === "function";

class WeakCache {
  #map = new Map();  // Map<key, WeakRef>
  get(key) {
    const ref   = this.#map.get(key);
    const value = ref?.deref();
    if (value === undefined) {
      this.#map.delete(key);
      return undefined;
    }
    return value;
  }
  set(key, value) {
    if (!canHoldWeakly(value)) return;   // primitives can't be weak targets; skip caching them
    this.#map.set(key, new WeakRef(value));
  }
  getOrCompute(key, compute) {
    const cached = this.get(key);
    if (cached !== undefined) return cached;
    const result = compute();
    this.set(key, result);
    return result;
  }
}

const cache = new WeakCache();
console.log(cache.getOrCompute("report", () => ({ rows: 10000 })).rows);
console.log(cache.getOrCompute("rowCount", () => 10000));
// 10000
// 10000

WeakMap vs WeakRef — when to use which

// WeakMap — associate data with an object (most common need):
const metadata = new WeakMap();
function tag(obj, data) { metadata.set(obj, data); }
function getTag(obj) { return metadata.get(obj); }

const element = document.querySelector("button");
tag(element, { clicks: 0, label: "Submit" });
// When element is removed from DOM and GC'd, the WeakMap entry is automatically gone.
// No WeakRef needed!

// WeakRef — when you need to check if something is still alive:
// Use when you DON'T own the object and need to observe its lifetime.

// FinalizationRegistry — when you have external resources to clean up:
// Example: a native file handle that needs to be closed when the JS object is GC'd.

GC semantics and spec guarantees

What the spec guarantees (and doesn't) — ECMA-262 §9.10

The ECMAScript specification explicitly avoids specifying when garbage collection occurs. It only guarantees:

A WeakRef that has been derefd and returned a non-undefined value within the same job (microtask checkpoint) will continue to return the same object for the duration of that job — the GC cannot collect it mid-execution.
FinalizationRegistry callbacks are called as separate jobs — never synchronously within the current execution context, always after the current job completes.
The order in which multiple FinalizationRegistry callbacks fire is unspecified.
An implementation is not required to call FinalizationRegistry callbacks at all — they are best-effort.

The "avoided values" problem

// Spec §9.10.3: "avoided values" — the spec allows an implementation to keep
// objects alive longer than necessary to avoid observable GC behaviour.
// This means:
// - Testing GC with WeakRef in short scripts is unreliable
// - Node.js --expose-gc allows manual triggering for testing:
//   global.gc()  // force GC (only with --expose-gc flag)
// - In browsers: DevTools memory panel → Force GC button

WeakRef in the spec — §26.1

A WeakRef object has an internal [[WeakRefTarget]] slot which holds either the target object or empty (if collected). The WeakRefDeref abstract operation performs an "in the same job" liveness check — if the target was alive at the start of the current job and WeakRefDeref is called within that same job, it is guaranteed to return the object (the GC cannot run mid-job in the ECMAScript execution model).

Official Sources

The Codex links only to official documentation and the ECMAScript specification. No third-party tutorials.