FinalizationRegistry

FinalizationRegistry is a new feature introduced in ECMAScript 12 (ES2021) that provides a mechanism to manage cleanup logic when objects are garbage-collected. When used in conjunction with WeakRef, it can optimize memory management in certain scenarios, especially when dealing with large objects or external resources that need to be released.

Basic Concepts of FinalizationRegistry

FinalizationRegistry allows developers to register a callback function that will be invoked when a registered object is garbage-collected. Its core purpose is to listen for object lifecycle termination events rather than directly controlling garbage collection. It’s important to note that the timing and frequency of callback execution are not entirely deterministic, as garbage collection behavior depends on the implementation of the JavaScript engine.

const registry = new FinalizationRegistry((heldValue) => {
  console.log(`Object collected, held value: ${heldValue}`);
});

let obj = { data: "example" };
registry.register(obj, "Associated value");

obj = null; // Dereference, potentially triggering garbage collection

Use Cases for FinalizationRegistry

FinalizationRegistry is suitable for scenarios where external resources associated with objects (such as file handles, network connections, or DOM event listeners) need to be released. Here’s a practical example: Suppose a FileHandler class manages file operations, and when an instance is no longer in use, the file should be automatically closed.

class FileHandler {
  constructor(fileName) {
    this.fileName = fileName;
    this.file = openFile(fileName); // Hypothetical file-opening operation
  }

  close() {
    console.log(`Closing file: ${this.fileName}`);
    // Actual file-closing logic
  }
}

const fileRegistry = new FinalizationRegistry((fileName) => {
  console.log(`Auto-cleaning file: ${fileName}`);
});

let fileHandler = new FileHandler("example.txt");
fileRegistry.register(fileHandler, fileHandler.fileName);

// When fileHandler is no longer referenced, the FinalizationRegistry callback may trigger
fileHandler = null;

Considerations for FinalizationRegistry

1. Non-deterministic Callback Execution: The timing of garbage collection is unpredictable, so callbacks may not execute immediately or may not execute at all (e.g., if the program exits prematurely).
2. Avoid Relying on Critical Logic: Due to the unreliability of callbacks, critical resource cleanup logic should not depend entirely on FinalizationRegistry. Instead, explicit cleanup methods (e.g., fileHandler.close()) should be called.
3. Memory Leak Risks: If the callback mistakenly re-references the collected object, it could lead to memory leaks.

Combining with WeakRef

FinalizationRegistry is often used with WeakRef, which allows weak references to objects without preventing their garbage collection. The following example demonstrates how to track an object with WeakRef and perform cleanup via FinalizationRegistry when the object is collected:

const registry = new FinalizationRegistry((id) => {
  console.log(`Resource ${id} has been released`);
});

function createResource(id) {
  const resource = { id, data: new Array(1000).fill("*") };
  const weakRef = new WeakRef(resource);
  registry.register(resource, id);
  return weakRef;
}

let weakResource = createResource("resource-1");
// When weakResource is no longer referenced, the callback may trigger

Practical Application: Cache System

In a cache system, FinalizationRegistry can be used to log or update state when cache items are garbage-collected. For example:

class Cache {
  constructor() {
    this.cache = new Map();
    this.registry = new FinalizationRegistry((key) => {
      console.log(`Cache key ${key} has been collected`);
      this.cache.delete(key);
    });
  }

  set(key, value) {
    this.cache.set(key, new WeakRef(value));
    this.registry.register(value, key);
  }

  get(key) {
    const weakRef = this.cache.get(key);
    return weakRef ? weakRef.deref() : null;
  }
}

const cache = new Cache();
let largeData = { data: new Array(10000).fill("value") };
cache.set("data1", largeData);

// When largeData is dereferenced, the cache will auto-clean
largeData = null;

Differences Between Browsers and Node.js

Different JavaScript engines may implement FinalizationRegistry slightly differently. For example:

• V8 (Chrome, Node.js) and SpiderMonkey (Firefox) have different garbage collection strategies, which may lead to inconsistent callback timing.
• In Node.js, FinalizationRegistry might be more commonly used to manage native resources (e.g., database connections), while in browsers, it’s often used for DOM-related cleanup.

Performance Considerations

Frequent use of FinalizationRegistry may have a slight performance impact, as the engine needs to maintain additional data structures to track registered objects. In performance-sensitive scenarios, use it cautiously and prioritize explicit resource management.