W3cubDocs

/JavaScript

FinalizationRegistry.prototype.register()

The register() method of FinalizationRegistry instances registers an value with this FinalizationRegistry so that if the value is garbage-collected, the registry's callback may get called.

Syntax

js
register(target, heldValue)
register(target, heldValue, unregisterToken)

Parameters

target

The target value to register.

heldValue

The value to pass to the finalizer for this target. This cannot be the target itself but can be anything else, including functions and primitives.

unregisterToken Optional

A token that may be used with the unregister method later to unregister the target value. If provided (and not undefined), this must be an object or a non-registered symbol. If not provided, the target cannot be unregistered.

Return value

None (undefined).

Exceptions

TypeError

Thrown in one of the following cases:

  • target is not an object or a non-registered symbol (object as opposed to primitives; functions are objects as well)
  • target is the same as heldvalue (target === heldValue)
  • unregisterToken is not an object or a non-registered symbol

Description

See the Avoid where possible and Notes on cleanup callbacks sections of the FinalizationRegistry page for important caveats.

Examples

Using register

The following registers the value referenced by target, passing in the held value "some value" and passing the target itself as the unregistration token:

js
registry.register(target, "some value", target);

The following registers the value referenced by target, passing in another object as the held value, and not passing in any unregistration token (which means target can't be unregistered):

js
registry.register(target, { useful: "info about target" });

Specifications

Browser compatibility

Desktop Mobile Server
Chrome Edge Firefox Opera Safari Chrome Android Firefox for Android Opera Android Safari on IOS Samsung Internet WebView Android Deno Node.js
register 84 84 79 70 14.1 84 79 60 14.5 14.0 84 1.0 14.6.0

See also

© 2005–2023 MDN contributors.
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/FinalizationRegistry/register