Understanding WeakRef in JavaScript (with examples)

Updated: February 19, 2024 By: Guest Contributor Post a comment


JavaScript, a language known for its dynamic nature, offers several mechanisms to manage memory efficiently. One such feature, introduced in the ECMAScript 2021 specification, is the WeakRef class. This tutorial aims to demystify the concept of WeakRef, guiding you through its practical applications with examples that progress from basic to advanced.

Introduction to WeakRef

In JavaScript, managing memory effectively is crucial for building responsive applications. The WeakRef class provides a way to reference an object weakly, allowing garbage collection (GC) to happen if that’s the only reference to the object. This is particularly useful when dealing with large objects that you don’t need to keep alive strictly but want to access if they still exist.

class MyObject {
    constructor(name) {
        this.name = name;

    greet() {
        return `Hello, ${this.name}!`;

const strongRef = new MyObject('World');
let weakRef = new WeakRef(strongRef);

console.log(weakRef.deref().greet()); // Output: Hello, World!

Note: If the object referred by weakRef gets garbage collected, weakRef.deref() will return undefined.

Why Use WeakRef?

WeakRef can be particularly useful in scenarios where you need to cache large datasets, manage listeners or observers without preventing garbage collection, or hold references to DOM elements that you don’t control the lifecycle of. It offers flexibility by not forcing certain objects to remain in memory indefinitely, thus aiding in memory optimization.

Basic Usage of WeakRef

Let’s dive into a simple use case where we might utilize a WeakRef:

let obj = new Object();
let weakRef = new WeakRef(obj);

console.log(weakRef.deref()); // Outputs the object, or undefined if collected

This example illustrates the most straightforward use of WeakRef: keeping a weak reference to an object. It’s significant to understand that the actual availability of the object through weakRef.deref() is not guaranteed, as the object may have been collected by garbage collection.

Working with FinalizationRegistry

The FinalizationRegistry class works in tandem with WeakRef to execute callbacks once an object is garbage collected. This feature can be valuable in cleaning up resources or performing specific actions after an object is no longer available.

const registry = new FinalizationRegistry((value) => {
    console.log(`Collected: ${value}`);

let obj = { name: 'JavaScript' };
registry.register(obj, 'Resource A');
obj = null; // At some point in the future, logs: Collected: Resource A

This code demonstrates how to use FinalizationRegistry to monitor the collection of an object, allowing you to perform cleanup operations accordingly.

Advanced Use-Cases

WeakRef and FinalizationRegistry can be combined to create powerful patterns in web development, such as caching mechanism without preventing garbage collection of cached objects, or managing subscriptions in event-driven systems with minimal memory leak risks.

Creating a Caching Mechanism

Here’s how you could implement a simple caching mechanism using WeakRef to keep a weak reference to a cached object and FinalizationRegistry to know when the object is collected.

const cache = new Map();

const finalRegistry = new FinalizationRegistry((key) => {
    console.log(`Cache item ${key} collected`);

function cacheObject(key, object) {
    const ref = new WeakRef(object);
    cache.set(key, ref);
    finalRegistry.register(object, key);

function retrieveCachedObject(key) {
    const ref = cache.get(key);
    if (!ref) return null;
    return ref.deref();

// Usage
let obj = { data: 'This is some cached data' };
cacheObject('key1', obj);
console.log(retrieveCachedObject('key1')); // Output: the object or null if collected

This caching example illustrates how to use WeakRef and FinalizationRegistry to build an efficient cache that does not prevent the garbage collector from freeing up memory when needed.


The introduction of WeakRef into JavaScript offers developers a valuable tool for handling memory more proficiently. By understanding and leveraging WeakRef and FinalizationRegistry, you can optimize your applications for better memory management and performance.