Signatur
Beschreibung
FinalizationRegistry ist ein eingebautes Objekt aus dem ECMAScript 2021-Standard, das es erlaubt, auf die Garbage Collection bestimmter Objekte zu reagieren. Beim Erzeugen einer Instanz übergibt man einen sogenannten Cleanup-Callback, der mit einem frei wählbaren Held Value aufgerufen wird, sobald ein registriertes Zielobjekt vom Garbage Collector freigegeben wurde.
Typische Anwendungsfälle sind das Aufräumen von externen Ressourcen (z. B. native Handles, Cache-Einträge oder Abonnements), die mit einem JavaScript-Objekt verbunden sind, das nicht mehr erreichbar ist. Dabei ist zu beachten, dass der Zeitpunkt der Garbage Collection völlig unbestimmt ist — der Callback wird möglicherweise gar nicht, verspätet oder in einem nicht vorhersagbaren Moment aufgerufen.
Zur Registrierung eines Objekts dient die Methode register(target, heldValue, unregisterToken). Mit einem optionalen Unregister Token kann die Registrierung jederzeit über unregister(token) wieder aufgehoben werden. Das Zielobjekt selbst darf nicht als heldValue verwendet werden, da dies verhindern würde, dass es überhaupt garbage-collected wird.
Wichtig: FinalizationRegistry sollte nur als letztes Mittel zur Ressourcenbereinigung eingesetzt werden. Für vorhersagbares Ressourcenmanagement sind explizite Bereinigungsmuster (z. B. mit AbortController, WeakRef oder dem using-Statement aus ES2023) zu bevorzugen.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $cleanupCallback Pflicht | function | Eine Funktion, die aufgerufen wird, wenn ein registriertes Zielobjekt garbage-collected wurde. Sie erhält den Held Value als einziges Argument, der beim register()-Aufruf angegeben wurde. |
Rückgabewert
FinalizationRegistry-Instanz, mit der Zielobjekte registriert und deren Registrierungen aufgehoben werden können.Beispiele
Einfacher Cache mit automatischer Bereinigung
// Cleanup-Callback erhält den heldValue (hier: den Cache-Schlüssel)
const registry = new FinalizationRegistry((key) => {
console.log(`Objekt mit Schlüssel "${key}" wurde garbage-collected.`);
cache.delete(key);
});
const cache = new Map();
function cacheObject(key, value) {
cache.set(key, value);
// Registriere das Objekt; heldValue ist der Schlüssel
registry.register(value, key);
}
{
let temporaryData = { info: 'Temporäre Daten' };
cacheObject('myData', temporaryData);
console.log('Cache-Größe:', cache.size); // Cache-Größe: 1
// temporaryData verlässt den Scope → wird irgendwann GC'd
}
// Nach der Garbage Collection wird der Callback aufgerufen:
// Objekt mit Schlüssel "myData" wurde garbage-collected.Registrierung mit Unregister Token aufheben
const registry = new FinalizationRegistry((heldValue) => {
console.log(`Bereinige Ressource: ${heldValue}`);
});
let resource = { handle: 42 };
const token = {}; // Token zum späteren Abmelden
// Drittes Argument ist das Unregister Token
registry.register(resource, 'handle-42', token);
// Registrierung wieder aufheben (z. B. wenn Ressource manuell freigegeben wird)
const wasUnregistered = registry.unregister(token);
console.log('Abgemeldet:', wasUnregistered); // Abgemeldet: true
// Selbst wenn resource nun GC'd wird, wird der Callback NICHT mehr aufgerufen
resource = null;// Wichtig · Fallstricke
Keine Garantien: Die JavaScript-Spezifikation gibt keine Garantie, dass Finalizer-Callbacks überhaupt aufgerufen werden — zum Beispiel beim Beenden des Prozesses oder in bestimmten Engine-Optimierungsszenarien. Callbacks dürfen daher nicht für sicherheitskritische oder unbedingt notwendige Bereinigungslogik verwendet werden.
Timing: Der Callback wird nicht synchron nach der Garbage Collection ausgeführt, sondern in einer späteren Microtask- oder Macrotask-Runde. Der genaue Zeitpunkt ist engine-abhängig.
Zirkelbezüge vermeiden: Das registrierte Zielobjekt darf nicht als heldValue oder im unregisterToken direkt referenziert werden, da es sonst nicht freigegeben werden kann.
Browser-Kompatibilität: Unterstützt seit Chrome 84, Firefox 79, Safari 14.1, Node.js 14.6. In älteren Umgebungen nicht verfügbar und nicht vollständig polyfillbar.