JavaScript FinalizationRegistry: Explained with Examples

Updated: February 14, 2024 By: Guest Contributor Post a comment

In modern JavaScript development, managing memory and ensuring efficient garbage collection is crucial for building high-performance applications. One of the less commonly understood features introduced in recent versions of JavaScript is the FinalizationRegistry. This feature provides a way to register objects for notifications when they are garbage collected, thus offering a unique opportunity for developers to perform cleanup operations. This tutorial aims to demystify the FinalizationRegistry, showcasing its utility with practical examples.

Understanding the FinalizationRegistry

The FinalizationRegistry class allows registered objects to be monitored for garbage collection (GC), triggering a callback function when the object is finally collected. Before delving into examples, let’s establish a foundational understanding of key concepts:

  • Garbage Collection: The process by which the JavaScript engine reclaims memory occupied by objects that are no longer in use by the application, making it available for new objects.
  • Finalization: The act of performing post-cleanup or release of resources (like closing file handles, releasing external resources, etc.) after an object is no longer accessible.

When to Use FinalizationRegistry

Using FinalizationRegistry is best suited for cases where developers need to perform cleanup tasks after an object is garbage collected. It’s particularly useful in scenarios involving resources that are managed outside the JavaScript environment, such as WebAssembly modules or external resource allocations in web applications.

Basic Example

Let’s start by setting up a simple finalization registry:

const registry = new FinalizationRegistry((value) => {
    console.log(`An object was collected: ${value}.`);

This registry will log a message whenever a registered object gets collected. To register an object with the registry, you need a target object and a ‘held value’ which gets passed to the callback upon collection:

let obj = {};
registry.register(obj, 'Resource #1');
obj = null; // Dereference to enable GC

Advanced Use Cases

Let’s consider a more complex scenario where FinalizationRegistry can prove incredibly useful. Imagine managing connections in a web application that interfaces with external databases or file systems.

class ResourceManager {
    private resourceId: string;

    constructor() {
        this.resourceId = ResourceManager.generateId();
        registry.register(this, this.resourceId);

    static generateId() {
        return Math.random().toString(36).substr(2, 9);

    finalize() {
        console.log(`Clearing resources for ${this.resourceId}`);
        // Perform resource cleanup

const registry = new FinalizationRegistry((id) => {
    console.log(`Resource with ID ${id} was collected`);

In this example, the ResourceManager class generates an ID for each resource, registering itself with the FinalizationRegistry. Upon garbage collection, the registry’s callback logs the ID of the resource, signaling an opportunity to perform any necessary cleanup.

Limitations and Considerations

While FinalizationRegistry is a powerful tool, it’s important to understand its limitations:

  • It’s not a substitute for proper memory management. Developers should not rely on finalizers for program logic.
  • The timing of garbage collection is nondeterministic – finalizers may run unpredictably.
  • Overuse of finalizers can lead to performance issues.

In summary, FinalizationRegistry offers a unique opportunity for managing post-garbage collection operations. By understanding its proper use cases and limitations, developers can effectively integrate this feature into their JavaScript applications, ensuring efficient resource management and performance.


This tutorial provided an in-depth look at JavaScript’s FinalizationRegistry, along with examples to demonstrate its usage and potential benefits. As with any advanced feature, it’s crucial to use it judiciously, keeping in mind the nuances of garbage collection and resource management in JavaScript.

Happy coding!