JavaScript WeakRef deref() Method

Beginner
5 min read
Updated: Nov 2026
3 examples
WeakRef

Definition

ref.deref() returns the target of a WeakRef: the very same object, not a copy, while that object is still alive. If the garbage collector has already removed it, you get undefined. A WeakRef is a weak reference: holding one does not keep the object in memory. deref() asks, “Is my object still there?” It is the only method a WeakRef has.

Remember
const ref = new WeakRef(obj);   // weak: does not keep obj alive
ref.deref()                    // obj, or undefined if collected
ref.deref() === obj            // true while obj is alive
ref.deref()?.name              // safe: undefined when it is gone

never write code that needs the garbage collector to run

Syntax

Create a WeakRef with new, then call deref() when you need the object.

JavaScript
const ref = new WeakRef(target);   // target: an object (or a non-registered symbol)
const obj = ref.deref();           // the target, or undefined
CallWhat it does
ref.deref()Get the target, or undefined if it was collected.
ref.deref()?.nameRead a property safely. The result is undefined when the target is gone.
const obj = ref.deref()Keep the result to reuse it. Check for undefined first.

Built into JavaScript since ES2021. On a real WeakRef it never throws.

Library declarations
JavaScript
weakRef.deref()   // returns the target object (or symbol), or undefined

// weakRef: created with new WeakRef(target)
// target:  an object or a non-registered symbol,
//          otherwise new WeakRef() throws a TypeError

Parameters

ParameterDescription
(none)deref() takes no arguments; anything you pass is ignored. The target is fixed by new WeakRef(target).

Return Value

Return ValueDescription
Object, function, or symbolThe target itself while it is alive, so ref.deref() === target is true.
undefinedThe target has been garbage collected. Once deref() returns undefined, it always will; the object never comes back.

JavaScript Examples

Example 1 — Get the Same Object Back

Wrap an object in a WeakRef and call deref(). Your own variable still holds the object, so it is alive.

JavaScript
const user = { name: "Asha", age: 30 };
const ref = new WeakRef(user);

console.log(ref.deref() === user);   // true
console.log(ref.deref().name);       // Asha

user.age = 31;
console.log(ref.deref().age);        // 31
Try It Yourself

How It Works

  1. A reference, not a copy. deref() hands back the very same object you wrapped, so comparing it to user with === is true.
  2. Your variable keeps it alive. While user is in scope, nothing can collect the object, so deref() always has something to return here.
  3. One shared object. Setting user.age to 31 changes the single object, so the next deref() call reads 31.

Example 2 — Read the Target Safely

In real code the object might be gone, so check the result. Two common patterns: optional chaining and an if check.

JavaScript
const settings = { theme: "dark", fontSize: 16 };
const ref = new WeakRef(settings);

const theme = ref.deref()?.theme;
console.log(theme);                          // dark

const target = ref.deref();
if (target !== undefined) {
  console.log("alive: " + target.fontSize);  // alive: 16
} else {
  console.log("already collected");
}
Try It Yourself

How It Works

  1. Optional chaining is a shortcut. ref.deref()?.theme gives the property when there is an object and undefined when there is none, without throwing.
  2. Save it, then test it. Store the result in target and check target !== undefined to use the object more than once.
  3. Keep the else branch. Here the object is alive, so it prints alive: 16. Real programs must still handle the other branch.

Example 3 — A Small Cache with WeakRef

A Map stores a WeakRef per key. getOrCreate reuses the object if it is alive and builds a new one if not.

JavaScript
const cache = new Map();
let created = 0;

function getOrCreate(key) {
  const cached = cache.get(key)?.deref();
  if (cached !== undefined) {
    return cached;
  }
  created++;
  const value = { key: key };
  cache.set(key, new WeakRef(value));
  return value;
}

const first = getOrCreate("a");
const second = getOrCreate("a");
const other = getOrCreate("b");

console.log(first === second);   // true
console.log(first === other);    // false
console.log(created);            // 2
console.log(cache.size);         // 2
Try It Yourself

How It Works

  1. One check covers two cases. cache.get(key)?.deref() is undefined when the key is missing and when the object was collected, so one if handles both.
  2. Build only when needed. The first "a" call creates an object. The second finds it, so created is 2 after three calls.
  3. The Map holds weakly. The Map keeps the keys and WeakRef wrappers, not the objects. Your variables keep them alive here, so the output never changes.

Browser & Runtime Support

WeakRef and deref() are part of ES2021. Symbols as targets came later, in ES2023.

✓ Baseline · ES2021

WeakRef.prototype.deref()

Chrome 84+, Edge 84+, Firefox 79+, Safari 14.1+, Node.js 14.6+, and current Deno. Not in Internet Explorer.

Wide Supported since 2021
Google Chrome Chrome 84+
Supported
Mozilla Firefox Firefox 79+
Supported
Apple Safari Safari 14.1+
Supported
Microsoft Edge Edge 84+
Supported
Node.js Node.js 14.6+
Supported
Deno All current releases
Supported
Internet Explorer No support
Not supported
deref() Wide support

Bottom line: Feature-detect with typeof WeakRef === "function". If it is missing, keep the object in a normal variable instead.

Frequently Asked Questions

It returns the target object if it is still alive, or undefined if the garbage collector has removed it. The object is the one you passed to new WeakRef(), not a copy.
Only after the target has been garbage collected. You cannot predict when, and it can differ between runs, so always check the result.
For a short time, yes. After deref() returns an object, it stays alive until the current synchronous run ends. A variable that stores the result is a normal strong reference.
On a normal WeakRef, no. It throws a TypeError only with the wrong this value, such as a copy of the method called on its own. Errors usually come from new WeakRef(1).
Only if you are sure you need it. A plain Map or a size limit is simpler. Never let correctness depend on garbage collection, and use a FinalizationRegistry only for optional cleanup.

Back to the WeakRef Method Index

See everything a WeakRef can do on one page.

WeakRef methods →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

11 people found this page helpful