WeakRef & FinalizationRegistry

Pointing at an object without keeping it

JavaScript frees memory for you. A part of the engine called the garbage collector finds objects your code can no longer get to, and removes them. An object is reachable while your code can still get to it, for example through a variable, a property, an array, a map, or a closure.

Most links to an object are strong references. A strong reference keeps the object alive: the garbage collector must not remove it. A weak reference is different. It points at an object, but it does not keep the object alive. The thing a weak reference points at is called its target.

Don't mix these up with WeakMap and WeakSet:

• A WeakMap holds its keys weakly. An object used as a key can be removed, and the map doesn't stop that.
• A WeakRef holds one target weakly. You read the target with deref().

Both follow the reachability rules from the memory management lesson.

The table below compares four tools that are easy to mix up. Read each row as: "this tool holds this weakly, and here is a good first use for it."

This lesson also uses ideas from two earlier lessons. From closures: a closure can keep a value alive by accident. From symbols: some symbols can be weak targets. The next lesson, resource management, shows cleanup you control, such as using.

To make a weak reference, write new WeakRef(target). To read it, call ref.deref(). Then check what you got:

• If it is the object, use it right away.
• If it is undefined, the object is gone. Build it again, or treat it as missing.

The examples use two small tools for this check. ?. reads a property, but gives undefined instead of an error when the left side is undefined. ?? gives the value on its right when the left side is undefined or null.

const user = { name: "Asha" };
const ref = new WeakRef(user);
console.log(ref.deref()?.name ?? "missing");

Line 1 makes an object and keeps it in the variable user. That is a strong reference. Line 2 makes a weak reference to the same object. Line 3 prints Asha, because user still keeps the object alive. The ?? "missing" part is for a later read, when the object might be gone. It doesn't mean the object is removed now.

function readName(ref) {
  const user = ref.deref();
  return user?.name ?? "reload";
}
console.log(readName({ deref: () => undefined }));

Line 2 calls deref() once and keeps the answer in user. Line 3 returns the name, or reload if there is no user. Line 5 prints reload.

Why? Line 5 doesn't pass a real WeakRef. It passes a small stand-in object whose deref() always returns undefined. That shows you the missing case. It does not make the garbage collector remove anything.

function readLater(ref) {
  setTimeout(() => {
    const user = ref.deref();
    console.log(user?.name ?? "reload");
  }, 0);
}
readLater({ deref: () => undefined });

A job is one piece of code that runs from start to finish without a break. Code inside a timer runs later, in a new job.

Line 2 uses setTimeout to run some code later, in a new job. Line 3 calls deref() again. Line 4 prints reload, because this stand-in returns undefined. With a real WeakRef, the object might still be there, or it might be gone. A read that worked earlier tells you nothing about a later job.

The next experiment shows a promise from the specification (the spec), the official rulebook for JavaScript. When you create a WeakRef or call deref(), the spec keeps the target alive until the current job ends. The spec calls this rule KeepDuringJob. It does not keep the object forever.

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");

Line 1 makes the object. Line 2 makes the weak reference. Line 3 sets target to null, which removes the strong reference. Lines 5 and 6 call deref() in the same job, so both get the same object. That is why line 7 prints true. In a later job, either call could give undefined.

A weak target must be something the garbage collector can remove on its own. These work:

• Objects.
• Symbols made with Symbol(). These are called non-registered symbols. They work since ES2023, the 2023 edition of JavaScript.

These don't work. new WeakRef() throws a TypeError for them:

• Registered symbols from Symbol.for(). JavaScript keeps them in one shared list, and Symbol.for() with the same name always gives back the same symbol.
• Primitives: numbers, strings, booleans, null, and undefined.

Older engines may not accept symbols as targets. If your code needs symbol targets, check once when the program starts. If the check fails, use an object target instead.

const local = Symbol("local");
let supported = false;
try { supported = new WeakRef(local).deref() === local; }
catch { supported = false; }
console.log(supported ? "symbol target supported" : "use an object target");

Line 3 tries a symbol as a target, inside a try block. It checks that deref() gives the same symbol back. If an older engine throws, the catch on line 4 runs instead. On current Node 22, line 5 prints symbol target supported. An older engine that rejects symbols prints use an object target instead.

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);

Line 1 makes an object. Line 2 makes a non-registered symbol. Lines 4 and 5 make a weak reference to each one. Both print true, because deref() gives back the same target.

The next two examples fail on purpose. They are marked as expected errors, so the editor shows the TypeError and doesn't treat the example as broken.

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

1new WeakRef(42);

FinalizationRegistry lets you ask for a note after an object is removed. You register two things with it:

• The target: the object to watch.
• A held value: a small value, such as a string, that the registry keeps for you.

If the target is removed, the engine may later call your callback with the held value. This callback is also called a finalizer. You can't control when the target is removed, or when the finalizer runs.

The table lists each part of FinalizationRegistry and what it does.

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));

Lines 1 to 3 make the registry. Its callback prints the held value. Line 5 makes an empty object called token. A token is a key you can use later to cancel a registration.

Line 7 registers widget, with the held value "preview card" and the token. Line 8 cancels that registration and prints true. Line 9 prints false, because nothing is left for that token. The callback never runs here.

A token is optional. If several registrations share one token, a single unregister(token) cancels them all. Cancelling never runs the callback.

const registry = new FinalizationRegistry(() => {});
const token = {};
const first = { name: "Asha" };
const second = { name: "Mira" };
registry.register(first, "first", token);
registry.register(second, "second", token);
console.log(registry.unregister(token));
console.log(registry.unregister(token));

Lines 5 and 6 register two users with the same token. Line 7 cancels both and prints true. Line 8 prints false, because none are left. The garbage collector didn't remove either user here.

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

const registry = new FinalizationRegistry(() => {});
let user = { name: "Asha" };
registry.register(user, { savedUser: user });
user = null;
console.log("registered, but user is still strongly held");

Line 3 works, because the held value is a new object, not user itself. Line 4 removes the variable's strong reference. Line 5 prints registered, but user is still strongly held.

Here is why. The registry keeps the held value, and the held value points back at the user. While that path exists, the user can't be removed, so the callback can never run.

A cache keeps results you made before, so you don't have to make them again. A weak cache usually has two parts:

• A normal Map. Its keys are simple values that don't change, such as URLs or file paths.
• WeakRef values that point at big objects, such as decoded images or ASTs. An AST (abstract syntax tree) is a program turned into a tree of objects.

A FinalizationRegistry can remove old keys later. But it must check the current map entry first. You'll see why below.

const records = new Map();
console.log(records.get("tea")?.deref() ?? "not cached");

Line 1 starts with an empty map. Line 2 prints not cached, because there is no entry to call deref() on. Your code needs a fallback both for a missing key and for a weak reference that finds nothing.

const records = new Map([["tea", { deref: () => undefined }]]);
const cached = records.get("tea")?.deref();
console.log(cached?.label ?? "cache miss");

This time the key exists, but the stand-in on line 1 returns undefined. Line 3 prints cache miss. A cache miss means the cache didn't have the value. This shows what a removed object looks like, without making the garbage collector run.

const records = new Map([["tea", { deref: () => undefined }]]);
function getTea() {
  const cached = records.get("tea")?.deref();
  if (cached !== undefined) return cached;
  const tea = { label: "fresh tea" };
  records.set("tea", new WeakRef(tea));
  return tea;
}
console.log(getTea().label);

Line 3 checks the old entry. It finds nothing, so line 4 doesn't return. Lines 5 and 6 make a new value and store a new WeakRef to it. Line 9 prints fresh tea. If a later read also misses, build the value again. The map alone doesn't promise that a value stays cached.

Now, why must the cleanup check first? Because a callback can arrive late:

1. The old object for app.js is removed.
2. Before its callback runs, your code stores a fresh value under app.js.
3. The late callback for the old object arrives.

If the callback deletes the key without checking, it deletes the fresh value. So the helper below first checks ref.deref() === undefined. It deletes the key only when that is true.

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);

Lines 26 and 27 store an old value and then a new value under app.js. Line 29 calls the cleanup helper, the way a late finalizer for the old value would. On line 8, deref() finds the new value, so the key stays. Line 30 prints NewProgram.

In a real app, remember runs when you decode or parse a value. read runs when the page asks for that value. The registry callback is only a best-effort way to remove old keys: it may happen, but nothing promises it. So normal reads must still handle a miss.

If callbacks never run, old string keys can pile up in the normal Map. Remove them when a read misses. If the number of keys can keep growing, also set a size limit, or clear old keys yourself from time to time. Weak values don't make the map's keys weak.

Your code can't see garbage collection, and it can't control it. An engine may:

• remove an object late,
• never remove it before the program ends, or
• skip the finalizers when a page closes.

TC39, the group that designs JavaScript, advises you to avoid these features when you can. Use them only when a missed callback does no harm.

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 let you try this by hand. In Chrome DevTools, the Memory panel has a Collect garbage button. It is useful for learning and for finding bugs. But your page's code can't press that button. So a demo that says "click here and the object will be removed" teaches the wrong idea.

For cleanup that must happen, use explicit cleanup: cleanup code that you call yourself, at a time you choose.

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

Lines 1 to 5 make a handle object with a close() method. Line 7 starts a try block, and line 8 prints use handle. The finally block on line 9 always runs after the try block. So line 10 closes the handle and prints closed. This also works when the work fails.

const handle = { close: () => console.log("closed") };
try {
  try { throw new Error("failed"); }
  finally { handle.close(); }
} catch (error) {
  console.log(error.message);
}

Line 3 throws an error. The finally on line 4 still runs and closes the handle, which prints closed. Then the outer catch on line 5 catches the error, and line 6 prints failed. Without that outer catch, the error would go on to the calling code, after the cleanup.

Use explicit cleanup for anything important:

• try/finally.
• A close() or dispose() method that you call.
• Your framework's teardown step, which runs when a component is removed.
• In newer JavaScript, using, which the next lesson teaches.

A finalizer can't replace any of these.

These tools fit jobs where losing the value is fine:

• Caches of big things you can make again, such as decoded images, ASTs, or formatted data.
• Code that watches an object but should not keep it alive.
• Tests that look for memory leaks, where a missed note does no harm. A memory leak is memory your program keeps by mistake.

They don't fit cleanup that must happen.

The table lists common situations. For each one, it says whether these tools fit, and why.

Common misconceptions

• "WeakRef makes the object get removed." It only stops your reference from keeping the target alive. The engine decides when to remove it.
• "If deref() worked once, it will work later." In a later job it can give undefined. Check every time.
• "A finalizer is a cleanup hook." A finalizer is a best-effort note: it may come late, or never. Important cleanup belongs in code you call yourself.
• "The held value can be the target." It can't. That would keep the target alive, so register() throws a TypeError.
• "A registry callback can just delete its cache key." It must check the current WeakRef first, because the key may hold a fresh value by then.
• "WeakRef makes code faster." It is a tool for rare cases. A normal cache with a size limit is usually simpler. Use WeakRef only when the object really must stay removable.

The table compares the four tools side by side. Each row asks one question, and each column answers it for one tool.

Key takeaways

• WeakRef doesn't keep its target alive. So deref() can return undefined.
• Creating a WeakRef or calling deref() keeps the target alive only until the current job ends.
• Objects and Symbol() symbols can be weak targets. Primitives and Symbol.for() symbols can't.
• FinalizationRegistry callbacks may run late, or never. Never use them for cleanup that must happen.
• A weak cache deletes an old key only after checking the current WeakRef.

Up next: explicit resource management.