FinalizationRegistry : Object

constructor

FinalizationRegistry provides a way to be notified when an object is garbage collected. Note, JavaScript makes no guarantees on if or when an object will be garbage collected. See also WeakRef.

ECMAScript 2021 Spec

Constructors

new FinalizationRegistry(cleanupCallback : Function) : FinalizationRegistry

cleanupCallback(heldValue : Object) : undefined

Returns a new FinalizationRegistry that will call cleanupCallback when objects passed to register() are garbage collected.

Example:

const sleep = (ms) => new Promise(r => setTimeout(r, ms));

let waitingForCleanup = true;
const registry = new FinalizationRegistry((heldValue) => {
  console.log(`cleanup: ${heldValue}`);
  waitingForCleanup = false;
});

let foo = {};
registry.register(foo, 42);
foo = undefined; // Clear strong reference

const startTime = Date.now();
console.log('Allocating a lot of objects to try to force garbage collection');
while (waitingForCleanup) {
  for (let i = 0; i < 100; i++) {
    const x = new Array(100);
  }
  await sleep(10);
}
console.log(`foo was reclaimed after ${((Date.now() - startTime) / 1000).toFixed(1)}s`);

Run

Results:

Spec

Instance Methods

Registers target with this so the cleanupCallback passed to this' constructor will be called when target is garbage collected.

The value passed to cleanupCallback at that time will be heldValue. Note target and heldValue can not be the same object because this will hold a strong reference to heldValue, preventing it from being garbage collected.

If unregisterToken is specified, you can prevent cleanupCallback from being called by calling unregister(unregisterToken).

Example:

const sleep = (ms) => new Promise(r => setTimeout(r, ms));

let waitingForCleanup = true;
const registry = new FinalizationRegistry((heldValue) => {
  console.log(`cleanup: ${heldValue}`);
  waitingForCleanup = false;
});

let foo = {};
registry.register(foo, 42);
foo = undefined; // Clear strong reference

const startTime = Date.now();
console.log('Allocating a lot of objects to try to force garbage collection');
while (waitingForCleanup) {
  for (let i = 0; i < 100; i++) {
    const x = new Array(100);
  }
  await sleep(10);
}
console.log(`foo was reclaimed after ${((Date.now() - startTime) / 1000).toFixed(1)}s`);

Run

Results:

Spec

unregister(unregisterToken : Object) : undefined

Prevents cleanupCallback from being called for an object previously registered with the specified unregisterToken.

Example:

const sleep = (ms) => new Promise(r => setTimeout(r, ms));

let waitingForCleanup = true;
const registry = new FinalizationRegistry((heldValue) => {
  console.log(`cleanup: ${heldValue}`);
  waitingForCleanup = false;
});

let foo = {};
const token1 = {};
const token2 = {};
registry.register(foo, 'registered with token1', token1);
registry.register(foo, 'registered with token2', token2);
foo = undefined; // Clear strong reference

registry.unregister(token1);

const startTime = Date.now();
console.log('Allocating a lot of objects to try to force garbage collection');
while (waitingForCleanup) {
  for (let i = 0; i < 100; i++) {
    const x = new Array(100);
  }
  await sleep(10);
}
console.log(`foo was reclaimed after ${((Date.now() - startTime) / 1000).toFixed(1)}s`);

Run

Results:

Spec

home license contribute feedback toggle light/dark mode