Weak references & ephemerons

Weak references in the collector

The garbage collector (the collector, for short) is the part of the JavaScript engine that frees memory. It keeps every object your program can still reach and throws the rest away.

An object is reachable when your code can get to it from a starting point, such as a variable that is still in use. These starting points are called roots.

Most references are simple. If a reachable object points at another object, the collector keeps both. A few built-in tools work differently. They let your code look at an object, or attach extra information to it, without keeping that object alive.

This lesson looks at what the collector does with these tools. Two earlier lessons show how to use them in everyday code: WeakMap and WeakSet and WeakRef and finalization.

The previous lesson showed how the collector splits its work into small pieces, so the page does not freeze. Weak references add one more rule to that work. The next lesson, Garbage collection across engines & the DOM, compares how real engines handle JavaScript objects together with the objects of a web page.

Strong and weak references

A strong reference is an ordinary reference, like a property or a variable. The collector follows it. If a reachable object has a property that points at a cart, the cart is reachable too.

People who study collectors often draw objects as dots and references as lines between them. Such a line is called an edge. So a strong reference is also called a strong edge, and a weak reference a weak edge.

A WeakRef is a built-in object that holds a weak reference to one object, its target. Its deref() method gives you the target back. It gives undefined if the target was already thrown away.

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

In plain words, line by line:

1. Line 1 makes a cart with a price of 3.
2. Line 2 makes an ordinary object, strong, that holds the cart. This is a strong reference.
3. Line 3 makes a WeakRef called weak that points at the same cart. This is a weak reference.
4. Line 5 reads the price through strong and prints 3.
5. Line 6 reads the price through weak and prints 3 too. The ?. means "if deref() gave undefined, give undefined instead of an error."

Both reads work because strong still holds the cart.

Weak does not mean broken or hidden. It means: "do not keep the object alive because of this reference." So a cache (a store of saved results) can attach extra information to an object without changing how long that object lives.

A WeakMap entry depends on its key

A WeakMap is a map whose keys must be objects. You store a value with set(key, value) and read it with get(key). It is useful for extra information about an object that you don't want to put inside the object.

Start with the simple case: the key is still in use elsewhere.

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

In plain words, line by line:

1. Line 1 makes a user object.
2. Line 2 makes the map.
3. Line 3 stores the string "likes tea" with user as the key.
4. Line 4 reads it back and prints likes tea.

The variable user is an ordinary strong reference to the key. So nothing surprising happens yet.

The important part is the value. An ordinary Map keeps both its keys and its values alive. A WeakMap does not. It keeps a value alive only after the collector has found that the key is alive for some other reason.

Ephemerons: the key first, then the value

The collector's name for one WeakMap entry is an ephemeron. It is a rule, not an ordinary reference: "keep the value only if the key is already kept."

To find live objects, the collector marks them. Marking means putting a "keep" sign on an object. The collector starts at the roots and follows strong references. Every object it reaches gets marked. At the end, unmarked objects are thrown away.

With ephemerons, the collector works in this order:

• First, it marks everything it can reach through strong references.
• Then it looks at each entry. If the key is marked, it marks the value too.
• A newly marked value may point at more objects, so it goes back to the first step. It stops when a full round marks nothing new.

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

This small program is a model, not the real collector. Line 1 says user is a root. Line 2 describes one entry: the key is user and the value is notes. Line 3 uses includes to check whether the key is in the roots list. The ? : picks entry.value if it is, and "nothing" if it is not. The key is a root, so line 3 prints notes.

The real collector repeats this check for many objects. The next model does that with a loop.

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

Read it in parts:

1. Lines 1 to 3 set up the data: one root, user, and one entry from user to notes. graph lists the strong references of each object; user has none.
2. Line 6 marks the roots. A Set is a list with no repeats.
3. Line 8 repeats the work as long as the last round marked something new.
4. Lines 10 to 14 follow strong references and mark every object they reach.
5. Lines 15 to 19 apply the entry rule: if the key is marked, mark the value.
6. Line 24 prints the marked names in A-to-Z order: notes,user.

When a full round marks nothing new, the result stops changing. That stable result is called a fixpoint (a fixed point).

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 step-through calls the same model function as the playground below. Real engines make this faster with queues and other tricks. The rule stays the same: the key first, then the value.

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 save its own key

The order matters most when a value points back at its own key. Suppose the value notes has a reference to its key, user.

If the collector looked at the value first, notes would mark user. Then user would mark notes. The two would keep each other alive forever, even though your program can't reach either one.

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

In plain words, line by line:

1. Line 1 has no roots at all.
2. Line 2 says notes has a strong reference back to user.
3. Line 3 describes the same entry as before.
4. Line 4 runs the model. The || "nothing" part prints nothing when no name was marked. Nothing marked user, so the entry never marks notes. The reference back to user is never followed.

So "weak key, strong value" is not the full story for WeakMap. The value is kept only after the collector knows the key is alive.

When a WeakRef target can disappear

A WeakRef lets you read its target only while the target still exists. Right now, deref() can return the object. After a later collection, it can return undefined. A WeakRef never promises that the object will stay.

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

In plain words, line by line:

1. Line 1 makes an object for Asha.
2. Line 2 makes a WeakRef to it.
3. Line 3 prints Asha.
4. Line 4 prints here, because the object still exists right now.

Later, after the last strong reference is gone, the same check on line 4 may print gone.

A FinalizationRegistry lets you register a callback (a function the engine calls for you later). The engine may call it some time after a registered object is thrown away. This callback is called a finalizer. It comes with no promises about time:

• It may run much later.
• It may run at a moment your program did not expect.
• It may never run, for example if the page closes first.

So a finalizer is only for optional record keeping. Never use it to close a file, save a draft, release a lock, or cancel a request.

The table compares four similar ideas. Read each row as: "this thing follows this rule, so think of it like this."

For cleanup that must happen, write code that does it yourself:

• Call the object's own close() method.
• Use a using declaration where it is supported. It calls the object's cleanup method for you when the block ends.
• Use an AbortController to cancel work, such as a fetch request.

These actions happen because your program asked for them, at a time you choose.

A target stays alive until the current job ends

A weak reference would be hard to use if its target could vanish between two reads on nearby lines. So JavaScript gives one small promise. When you create a WeakRef, or get an object from deref(), that object stays alive until the current job ends.

Two words matter here:

• A job is the code that is running right now, from start to end without a pause, plus any promise callbacks it queues before the next task.
• A task is a separate piece of work that the engine runs later, such as a timer callback or a click handler.

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

In plain words, line by line:

1. Line 1 makes Asha's object.
2. Line 2 makes a WeakRef to it.
3. Line 3 sets user to null, so the only strong reference is gone.
4. Lines 5 and 6 read the target twice.
5. Line 7 prints true Asha: both reads got the same object.

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 later timer, a browser event, or any other later task is not covered by this promise. Don't save a weak target and expect it to exist when a later callback runs. Call deref() again there, and check for undefined.

Checking it in Node

Browser code cannot make the collector run. It should also never depend on when the collector runs.

For testing, Node can turn on a test-only function, gc(), when you start Node with the --expose-gc flag. Calling gc() asks for a collection right away. The three checks below use it. They print short words, never memory 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);

In plain words:

1. Line 1 defines laterTask. It waits until a later task by using setTimeout.
2. Lines 3 to 8 make an object (line 4), wrap it in a WeakRef (line 5), and drop the strong variable (line 6). Only the WeakRef is returned.
3. Lines 12 to 17 try up to 12 times: wait for a later task, call gc(), wait again, and check whether deref() gives undefined.
4. Line 18 prints weak collected true in the tested Node version.

The loop tries several times because nobody can promise which attempt will work, or how long it takes.

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

In plain words:

1. Line 6 gives the value its own WeakRef. Now the check can watch the value without keeping it alive.
2. Line 8 stores the key and the value in the WeakMap.
3. Lines 9 and 10 drop both variables, so nothing else reaches the key.
4. Lines 16 to 21 try up to 12 times, the same way as before.
5. Line 22 prints ephemeron value collected true. Once the key was gone, the value was thrown away too.

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

Line 3 drops the strong variable, and line 4 even asks for a collection. Line 5 still prints same job Asha, because the job has not ended yet.

This only checks the job promise. Never call a test-only function like gc() in app code. There is no check for finalizers here: their timing is not reliable enough to test.

Using weak tools carefully

A good use for WeakMap is extra information about an object that another part of the app owns. To own an object means to decide how long it lives. For example, a layout helper might store a row number for each user object without adding a property to that object.

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

In plain words, line by line:

1. Line 1 is the user object. Another part of the app owns it.
2. Line 2 makes a private map for layout notes.
3. Line 3 stores row 3 for this user.
4. Line 4 prints 3.

When nothing else in the app reaches the user, the map does not keep its notes alive.

Don't pick a weak tool just to avoid deciding who owns an object. Weak tools have limits:

• You can't loop over the entries of a WeakMap.
• An entry can disappear any time after its key is gone.
• A weak map is not a cache with a size limit.

Use an ordinary Map when you need to loop over entries, count them, remove old ones by your own rule, or save them.

Common mistakes with weak references

• "WeakMap values are always kept." A value is kept only while its key is reached some other way.
• "A WeakRef keeps the object for me." It only looks. deref() may give undefined later.
• "A finalizer can close things." It may run late or never, so cleanup that must happen needs your own code.
• "Apps can call gc()." That function exists only in Node with a test flag. Browsers don't offer it.
• "Two reads on nearby lines can give different answers." Inside one job, the target stays alive, so both reads match.

Read each row as: "this term means this, and it is not that."

A simple habit helps:

• Use ordinary strong references by default.
• Use a weak tool when the object's owner should decide how long it lives.
• Never make your program depend on when the collector runs.

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, first ask which idea it is about: a strong reference, a key that must be marked first, a later read, or the current job.

Key takeaways

• A strong reference keeps its target alive. A weak reference can read its target without keeping it alive.
• A WeakMap entry is an ephemeron: the collector marks the value only after the key is marked, and repeats until nothing changes.
• A value that points back to its key cannot keep the entry alive by itself.
• deref() can return undefined later. A finalizer may run late or never, so never use it for cleanup that must happen.
• Creating a WeakRef or reading it with deref() keeps the target alive until the current job ends.
• Use weak tools for optional extra information, not to avoid deciding who owns an object.

Coming next: Garbage collection across engines & the DOM.