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
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 thetarget
itself but can be anything else, including functions and primitives.
- : The value to pass to the finalizer for this
unregisterToken
- : A token that may be used with the
unregister
method later to unregister the target value. If provided (and notundefined
), this must be an object or a non-registered symbol. If not provided, the target cannot be unregistered.
- : A token that may be used with the
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 asheldvalue
(target === heldValue
)unregisterToken
is not an object or a non-registered symbol
- : Thrown in one of the following cases:
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:
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):
registry.register(target, { useful: "info about target" });