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
Call
What it does
ref.deref()
Get the target, or undefined if it was collected.
ref.deref()?.name
Read 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
Parameter
Description
(none)
deref() takes no arguments; anything you pass is ignored. The target is fixed by new WeakRef(target).
Return Value
Return Value
Description
Object, function, or symbol
The target itself while it is alive, so ref.deref() === target is true.
undefined
The 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.
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.
Build only when needed. The first "a" call creates an object. The second finds it, so created is 2 after three calls.
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.
Compatibility
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.
WideSupported since 2021
Google ChromeChrome 84+
Supported
Mozilla FirefoxFirefox 79+
Supported
Apple SafariSafari 14.1+
Supported
Microsoft EdgeEdge 84+
Supported
Node.jsNode.js 14.6+
Supported
DenoAll current releases
Supported
Internet ExplorerNo 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.