File size: 2,819 Bytes
780c9fe |
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 |
---
title: FinalizationRegistry.prototype.register()
short-title: register()
slug: Web/JavaScript/Reference/Global_Objects/FinalizationRegistry/register
page-type: javascript-instance-method
browser-compat: javascript.builtins.FinalizationRegistry.register
sidebar: jsref
---
The **`register()`** method of {{jsxref("FinalizationRegistry")}} instances registers a value with this `FinalizationRegistry` so that if the value is garbage-collected, the registry's callback may get called.
## Syntax
```js-nolint
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_inline}}
- : 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](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol#shared_symbols_in_the_global_symbol_registry). If not provided, the target cannot be unregistered.
### Return value
None ({{jsxref("undefined")}}).
### Exceptions
- {{jsxref("TypeError")}}
- : Thrown in one of the following cases:
- `target` is not an object or a [non-registered symbol](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol#shared_symbols_in_the_global_symbol_registry) (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](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol#shared_symbols_in_the_global_symbol_registry)
## Description
See the [Avoid where possible](/en-US/docs/Web/JavaScript/Reference/Global_Objects/FinalizationRegistry#avoid_where_possible)
and [Notes on cleanup callbacks](/en-US/docs/Web/JavaScript/Reference/Global_Objects/FinalizationRegistry#notes_on_cleanup_callbacks)
sections of the {{jsxref("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
{{Specifications}}
## Browser compatibility
{{Compat}}
## See also
- {{jsxref("FinalizationRegistry")}}
|