FinalizationRegistry.prototype.unregister()

Baseline Widely available *

This feature is well established and works across many devices and browser versions. It’s been available across browsers since April 2021.

* Some parts of this feature may have varying levels of support.

The unregister() method of FinalizationRegistry instances unregisters a target value from this FinalizationRegistry.

Syntax

js
unregister(unregisterToken)

Parameters

unregisterToken

The token used with the register() method when registering the target value. Multiple cells registered with the same unregisterToken will be unregistered together.

Return value

A boolean value that is true if at least one cell was unregistered and false if no cell was unregistered.

Exceptions

TypeError

Thrown if unregisterToken is not an object or a non-registered symbol.

Description

When a target value has been reclaimed, it is no longer registered in the registry. There is no need to call unregister in your cleanup callback. Only call unregister if you haven't received a cleanup callback and no longer need to receive one.

Examples

Using unregister

This example shows registering a target object using that same object as the unregister token, then later unregistering it via unregister:

js
class Thingy {
  static #cleanup = (label) => {
    //               ^^^^^−−−−− held value
    console.error(
      `The "release" method was never called for the object with the label "${label}"`,
    );
  };
  #registry = new FinalizationRegistry(Thingy.#cleanup);

  /**
   * Constructs a `Thingy` instance.
   * Be sure to call `release` when you're done with it.
   *
   * @param label A label for the `Thingy`.
   */
  constructor(label) {
    //                            vvvvv−−−−− held value
    this.#registry.register(this, label, this);
    //          target −−−−−^^^^         ^^^^−−−−− unregister token
  }

  /**
   * Releases resources held by this `Thingy` instance.
   */
  release() {
    this.#registry.unregister(this);
    //                        ^^^^−−−−− unregister token
  }
}

This example shows registering a target object using a different object as its unregister token:

js
class Thingy {
  static #cleanup = (file) => {
    //               ^^^^−−−−− held value
    console.error(
      `The "release" method was never called for the "Thingy" for the file "${file.name}"`,
    );
  };
  #registry = new FinalizationRegistry(Thingy.#cleanup);
  #file;

  /**
   * Constructs a `Thingy` instance for the given file.
   * Be sure to call `release` when you're done with it.
   *
   * @param filename The name of the file.
   */
  constructor(filename) {
    this.#file = File.open(filename);
    //                            vvvvv−−−−− held value
    this.#registry.register(this, label, this.#file);
    //          target −−−−−^^^^         ^^^^^^^^^^−−−−− unregister token
  }

  /**
   * Releases resources held by this `Thingy` instance.
   */
  release() {
    if (this.#file) {
      this.#registry.unregister(this.#file);
      //                        ^^^^^^^^^^−−−−− unregister token
      File.close(this.#file);
      this.#file = null;
    }
  }
}

Specifications

Specification
ECMAScript® 2027 Language Specification
# sec-finalization-registry.prototype.unregister

Browser compatibility

desktop mobile server
Chrome
Edge
Firefox
Opera
Safari
Chrome Android
Firefox for Android
Opera Android
Safari on iOS
Samsung Internet
WebView Android
WebView on iOS
Bun
Deno
Node.js
unregister
Chrome – Full support
Chrome 84 (Release date: 2020-07-27)
footnote Full support
Edge – Full support
Edge 84 (Release date: 2020-07-16)
footnote Full support
Firefox – Full support
Firefox 79 (Release date: 2020-07-28)
footnote Full support
Opera – Full support
Opera 70 (Release date: 2020-07-27)
footnote Full support
Safari – Full support
Safari 14.1 (Release date: 2021-04-26)
footnote Full support
Chrome Android – Full support
Chrome Android 84 (Release date: 2020-07-27)
footnote Full support
Firefox for Android – Full support
Firefox for Android 79 (Release date: 2020-07-28)
footnote Full support
Opera Android – Full support
Opera Android 60 (Release date: 2020-09-23)
footnote Full support
Safari on iOS – Full support
Safari on iOS 14.5 (Release date: 2021-04-26)
footnote Full support
Samsung Internet – Full support
Samsung Internet 14 (Release date: 2021-04-17)
footnote Full support
WebView Android – Full support
WebView Android 84 (Release date: 2020-07-27)
footnote Full support
WebView on iOS – Full support
WebView on iOS 14.5 (Release date: 2021-04-26)
footnote Full support
Bun – Full support
Bun 1 (Release date: 2023-09-08)
footnote Full support
Deno – Full support
Deno 1 (Release date: 2020-05-13)
footnote Full support
Node.js – Full support
Node.js 14.6 (Release date: 2020-07-21)
footnote Full support
Non-registered symbol as target
Chrome – Full support
Chrome 109 (Release date: 2023-01-10)
footnote Full support
Edge – Full support
Edge 109 (Release date: 2023-01-12)
footnote Full support
Firefox – No support
Firefox
footnote
footnote See bug 1863140
Opera – Full support
Opera 95 (Release date: 2023-02-01)
footnote Full support
Safari – Full support
Safari 16.4 (Release date: 2023-03-27)
footnote Full support
Chrome Android – Full support
Chrome Android 109 (Release date: 2023-01-10)
footnote Full support
Firefox for Android – No support
Firefox for Android
footnote
footnote See bug 1863140
Opera Android – Full support
Opera Android 74 (Release date: 2023-03-13)
footnote Full support
Safari on iOS – Full support
Safari on iOS 16.4 (Release date: 2023-03-27)
footnote Full support
Samsung Internet – Full support
Samsung Internet 21 (Release date: 2023-05-19)
footnote Full support
WebView Android – Full support
WebView Android 109 (Release date: 2023-01-10)
footnote Full support
WebView on iOS – Full support
WebView on iOS 16.4 (Release date: 2023-03-27)
footnote Full support
Bun – Full support
Bun 1 (Release date: 2023-09-08)
footnote Full support
Deno – Full support
Deno 1.28 (Release date: 2022-11-13)
footnote Full support
Node.js – Full support
Node.js 20 (Release date: 2023-04-18)
footnote Full support

Legend

Tip: you can click/tap on a cell for more information.

Full support
Full support
No support
No support
See implementation notes.

See also