register() tells a FinalizationRegistry to watch one object. Later, when the JavaScript engine deletes that object from memory (this is called garbage collection), the registry can call its cleanup function and hand it the held value you chose.
The registry does not keep the watched object alive. You can still use the object as usual, and it is only removed from memory once nothing else uses it. register() returns undefined, and the cleanup call is never guaranteed, so treat it as a bonus.
Remember
registry.register(target, heldValue);
registry.register(target, heldValue, token);
target → the object to watch (not kept alive)
heldValue → given to the callback later
(never the target itself)
token → optional; lets you cancel later
returns → undefined
The callback may run late, or never.
Syntax
First create a registry with a cleanup function. Then call register() on it for each object you want to watch.
JavaScript
const registry = new FinalizationRegistry(callback);
registry.register(target, heldValue);
registry.register(target, heldValue, unregisterToken);
Call
What it does
registry.register(obj, "id")
Watch obj. After it is garbage collected, the callback may receive "id".
registry.register(obj, "id", token)
Same, and remember token so that unregister(token) can cancel it later.
registry.register(obj, "id", obj)
The target can also be its own token. This is a common, easy choice.
A standard JavaScript method (ES2021) on every FinalizationRegistry; no import required. Siblings: unregister().
Library declarations
JavaScript
// ECMAScript 2021
FinalizationRegistry.prototype.register(target, heldValue)
FinalizationRegistry.prototype.register(target, heldValue, unregisterToken)
// returns undefined
// the callback is given to: new FinalizationRegistry(callback)
Parameters
Parameter
Description
target
Required. The object to watch. It must be an object (an array, a function, or an object from your own class all count). A string, a number or null throws a TypeError. The registry holds it weakly, so it does not stop the object from being collected.
heldValue
The value the cleanup callback receives later. It can be any type, and a short string such as an ID or a name works best. It must not be the same as target (that throws a TypeError), and it should not point to the target either, because the registry keeps the held value alive and the target could then never be collected.
unregisterToken
Optional. An object that you can pass to unregister() later to cancel this registration. Leave it out (or pass undefined) if you never plan to cancel. Other types, such as a string or null, throw a TypeError.
Return Value
Return Value
Description
undefined
Nothing is returned. The method only records the registration inside the registry.
TypeError (thrown)
The target is not an object, the held value is the same as the target, or the token has the wrong type.
JavaScript Examples
Example 1 — Watch an Object
Create a registry, register one object, and look at what register() returns.
register() returned: undefined
Callbacks so far: 0
Still using: photo.png
How It Works
Create the registry. The function you pass to new FinalizationRegistry() is the cleanup callback. It receives the held value, which here is a file name.
Register the object.registry.register(photo, "photo.png") starts watching photo and stores "photo.png" for later. The method returns undefined.
Nothing happens yet. The callback only runs after photo has been garbage collected, and never while your code is still running, so cleanedUp is still 0 and photo works as usual.
Example 2 — Check the Rules for target and heldValue
Five registrations, some valid and some not. The catch block prints the error type only, because the message text differs between browsers.
JavaScript
const registry = new FinalizationRegistry(() => {});
const user = { id: 7 };
const tests = [
["object target, string held value", () => registry.register({}, "temp-file")],
["array target, number held value", () => registry.register([1, 2, 3], 42)],
["string target", () => registry.register("hello", "label")],
["null target", () => registry.register(null, "label")],
["target is also the held value", () => registry.register(user, user)]
];
for (const [label, test] of tests) {
try {
test();
console.log(label + " -> ok");
} catch (err) {
console.log(label + " -> " + err.name);
}
}
object target, string held value -> ok
array target, number held value -> ok
string target -> TypeError
null target -> TypeError
target is also the held value -> TypeError
How It Works
Objects are fine. A plain object and an array are both objects, so they can be targets. The held value can be any type: a string, a number, and so on.
Primitives are rejected. A string or null is not an object that can be garbage collected on its own, so register() throws a TypeError.
Target and held value must differ. If the held value were the target, the registry would hold on to the object forever and it could never be collected. JavaScript stops you with a TypeError.
Example 3 — Register Every New Object in a Constructor
A Connection class registers each new object by itself. The third argument is a token, so the registration can be cancelled.
JavaScript
const finished = [];
const registry = new FinalizationRegistry((id) => {
finished.push(id);
});
class Connection {
constructor(id) {
this.id = id;
registry.register(this, id, this);
}
}
const first = new Connection("db-1");
const second = new Connection("db-2");
console.log("Created: " + first.id + ", " + second.id);
console.log("Cleanup calls so far: " + finished.length);
try {
registry.register({}, "temp", "my-token");
} catch (err) {
console.log("A string token gives: " + err.name);
}
console.log("Cancel with the token: " + registry.unregister(first));
Created: db-1, db-2
Cleanup calls so far: 0
A string token gives: TypeError
Cancel with the token: true
How It Works
Register inside the constructor.registry.register(this, id, this) watches the new object, uses the ID as the held value, and uses the object itself as the token. Every Connection is registered automatically.
Keep the callback small. It only stores the ID in an array. The callback never gets the object itself, only the held value, because the object is already gone by then.
Tokens must be objects. The string "my-token" is rejected with a TypeError. The last line shows why a token is useful: unregister(first) finds the registration and removes it, so it returns true.
Compatibility
Browser & Runtime Support
FinalizationRegistry is part of ES2021. Current versions of all major browsers and Node.js have it.
✓ ES2021 · Widely supported
registry.register()
Supported in Chrome 84+, Edge 84+, Firefox 79+, Safari 14.1+ and Node.js 14.6+. Internet Explorer never got it.
ES2021Standard since
Google Chrome84+ · Desktop & Mobile
Full support
Microsoft Edge84+ · Chromium
Full support
Mozilla Firefox79+ · Desktop & Mobile
Full support
Apple Safari14.1+ · macOS & iOS
Full support
Opera70+ · Chromium based
Full support
Samsung InternetRecent versions · Android
Supported
Android WebView84+ · Chromium based
Supported
Node.js14.6+ · Server runtime
Supported
DenoSupported · JavaScript runtime
Supported
BunSupported · JavaScript runtime
Supported
Internet ExplorerNo native support
Not supported
registry.register()Excellent
Bottom line: Safe to use in every current browser and in Node.js. Remember that support for the method does not make the callback predictable, because garbage collection timing depends on the engine.
Frequently Asked Questions
It makes the registry watch one object. When the JavaScript engine later removes that object from memory, the registry may call its cleanup function with the held value you passed. The method itself returns undefined and does not keep the object alive.
The registry keeps the held value in memory until the callback runs. If the held value were the target, the object would stay in memory forever and could never be collected, so JavaScript throws a TypeError. Use a string, a number or a small object that does not point back to the target.
No. The callback runs only after the engine has collected the object, and the engine chooses when. It can be late, and it may never happen, for example when the page closes or the program exits first. Never put work in it that must happen.
Any object: a plain object, an array, a function or an instance of your own class. Strings, numbers, booleans, null and undefined are not allowed and throw a TypeError. Newer engines also accept a symbol that was not created with Symbol.for().
Yes. JavaScript allows it, and each call is tracked as a separate registration. The cleanup callback can then be called once for each of them, with the held value of that registration.