JavaScript WeakRef Methods

Beginner
3 min read
Updated: Nov 2026
1 method guide
Method index

About This Index

This page is the JavaScript WeakRef Methods index for the tutorial track. A WeakRef has just one method, so there is one guide, with syntax, three runnable examples, browser notes, and FAQs.

Learn what a weak reference is on /js/weakref. Use this page when you want the API: deref() and the constructor facts below.

Weak means “may be gone”.

Always check the result of deref(). It is the object while the object is alive and undefined after it has been garbage collected.

How to Use a WeakRef

Create the WeakRef with new, then call its one method with a dot:

JavaScript
const user = { name: "Asha" };
const ref = new WeakRef(user);   // weak: does not keep user alive

ref.deref();                     // the object, or undefined
ref.deref()?.name;               // safe property read
const obj = ref.deref();         // strong again while obj exists
if (obj !== undefined) {
  // use obj here
}

JavaScript WeakRef Methods Table

The method guide in this JavaScript tutorial series (1 tutorial), grouped by what it does.

Read the target

1 method

The only method on a WeakRef. It returns the object the WeakRef points to, or undefined once the garbage collector has removed it (ES2021).

MethodDescriptionTutorial
deref()Return the object a WeakRef points to, or undefined if the garbage collector has removed it.Open

WeakRef Constructor and Facts

The constructor is used with new. The last row lists things a WeakRef does not have.

MemberWhat it gives youSince
new WeakRef(target)Create a weak reference to an object. Call it with new; without it you get a TypeError.ES2021
new WeakRef(symbol)A symbol from Symbol("x") also works as the target. A symbol from Symbol.for("x") does not.ES2023
ref.deref()Return the target, or undefined if it was garbage collected. This is the only method.ES2021
Object.prototype.toString.call(ref)Gives "[object WeakRef]", because every WeakRef is tagged with Symbol.toStringTag.ES2021
ref.size, ref.target, ref.set()None of these exist. A WeakRef has no other members, and you cannot point it at a new target. Create a new WeakRef instead.-

Frequently Asked Questions

There is only one: deref(). It returns the object a WeakRef points to, or undefined if that object has been garbage collected. Besides the constructor, new WeakRef(target), a WeakRef has nothing else to call.
The WeakRef page explains the idea: strong and weak references, which values are allowed, and why garbage collection timing is never guaranteed. This index lists the method guide and the constructor facts so you can jump straight to the API.
Call it on a WeakRef instance with a dot: ref.deref(). It takes no arguments. Check the result before using it, for example with ref.deref()?.name or with if (obj !== undefined).
No. deref() is the check: an object means it is alive, and undefined means it is gone. There is no property such as alive or size, and you cannot point a WeakRef at a different target later.
Read JavaScript WeakRef first to understand weak references, then open the deref() guide for three runnable examples. Come back to this index when you want to compare the constructor facts or move on to FinalizationRegistry.

Start with WeakRef deref()

Learn how to read a weak reference safely, with three runnable examples.

deref() tutorial →

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.

14 people found this page helpful