WeakRef und FinalizationRegistry in JavaScript: Speicherverwaltung meistern

1. Wie Garbage Collection in V8 wirklich funktioniert

Javascripts automatische Speicherverwaltung basiert auf einem generationalen Garbage Collector. V8, der JavaScript-Engine in Chrome und Node.js, teilt den Heap in zwei Bereiche: den Young Generation-Bereich (auch Minor Heap) für neu allokierte Objekte und den Old Generation-Bereich (Major Heap) für langlebige Objekte. Die meisten Objekte sterben jung – das ist die generationale Hypothese. Der Minor GC läuft häufig und schnell, der Major GC selten und teuer. Ein WeakRef-Ziel kann nach einem beliebigen GC-Zyklus verschwinden, was der Kern-Kontrakt dieser API ist.

Der GC verwendet den Reachability-Algorithmus: Ein Objekt ist lebendig, wenn es von einem GC-Root aus erreichbar ist. GC-Roots sind globale Variablen, Call-Stack-Variablen, aktive Closures und Event-Listener. Eine starke Referenz hält ein Objekt am Leben, solange die Referenz selbst lebendig ist. Eine WeakRef hält das Zielobjekt nicht am Leben – der GC darf es einsammeln, auch wenn noch eine WeakRef auf es zeigt. Das klingt einfach, hat aber weitreichende Konsequenzen für die Programmierung.

2. Typische Ursachen von Speicherlecks in JavaScript

Die häufigste Ursache für Speicherlecks in JavaScript sind Event-Listener, die nicht entfernt werden. Wenn eine Komponente zerstört wird, aber ihre Event-Listener noch auf DOM-Elemente registriert sind, hält das DOM-Element eine Referenz auf das Closure, das Closure hält eine Referenz auf die Komponente, und der GC kann nichts freigeben. Dasselbe gilt für Timer mit setInterval die nie mit clearInterval gestoppt werden und Closures, die auf große Datenmenge zeigen. In Single-Page-Applications, wo Komponenten häufig gemountet und zerstört werden, summieren sich diese Lecks.

Ein zweites klassisches Muster: globale Caches ohne Ablaufstrategie. Ein Map-Objekt als Cache, das Einträge niemals entfernt, wächst unbegrenzt. In Node.js-Servern mit langen Laufzeiten kann das zu erheblichem Speicherwachstum führen. Hier ist WeakRef eine elegante Lösung: Wenn der Cache-Key ein Objekt ist und die schwache Referenz auf den Wert den GC nicht behindert, kann der GC den Wert bei Speicherdruck einsammeln – der Cache schrumpft automatisch. Das ist kein Ersatz für eine explizite LRU-Cache-Strategie, aber ein nützliches Sicherheitsnetz.

// WeakRef-based cache — values can be GC'd when memory is needed
class WeakCache {
  #store = new Map()
  #registry

  constructor() {
    // FinalizationRegistry cleans up dead Map entries after GC
    this.#registry = new FinalizationRegistry((key) => {
      const ref = this.#store.get(key)
      // Only delete if the WeakRef is actually dead (not replaced)
      if (ref !== undefined && ref.deref() === undefined) {
        this.#store.delete(key)
        console.log(`[WeakCache] Entry for key "${key}" was collected by GC`)
      }
    })
  }

  set(key, value) {
    const ref = new WeakRef(value)
    this.#store.set(key, ref)
    // Register the value for cleanup — passes key as held value to callback
    this.#registry.register(value, key, ref)
    return this
  }

  get(key) {
    const ref = this.#store.get(key)
    if (!ref) return undefined
    // deref() returns the object or undefined if GC has collected it
    return ref.deref()
  }

  has(key) {
    return this.get(key) !== undefined
  }

  get size() {
    // Count only live entries
    let count = 0
    for (const ref of this.#store.values()) {
      if (ref.deref() !== undefined) count++
    }
    return count
  }
}

const cache = new WeakCache()
let bigObject = { data: new Array(1000).fill('expensive computation result') }
cache.set('result', bigObject)
console.log(cache.get('result')) // { data: [...] }
bigObject = null  // drop strong reference — GC may now collect it

3. WeakRef: Schwache Referenzen und ihre Grenzen

Ein WeakRef-Objekt wird mit new WeakRef(target) erstellt und gibt über weakRef.deref() entweder das Zielobjekt oder undefined zurück – je nachdem, ob der GC das Objekt bereits eingesammelt hat. Das zentrale Missverständnis bei WeakRef: Es gibt keine Garantie, wann der GC das Zielobjekt einsammelt. In einer synchronen Ausführung zwischen zwei Microtask-Checkpoints bleibt ein Objekt am Leben. Aber zwischen Event-Loop-Iterationen – und insbesondere nach Speicherdruck – kann der GC zuschlagen. Code, der nach einem deref()-Aufruf undefined behandeln muss, ist robuster Pflicht.

Der richtige Umgang mit WeakRef erfordert deshalb immer denselben Aufruf-Pattern: deref() einmal aufrufen, das Ergebnis in einer lokalen Variable speichern und prüfen, bevor man es verwendet. Mehrfaches Aufrufen von deref() ist gefährlich, weil der GC zwischen den Aufrufen agieren könnte. Wichtig: WeakRef-Ziele müssen Objekte sein – Primitive wie Strings, Numbers oder Booleans werden vom GC sowieso nicht verwaltet und können nicht als WeakRef-Ziel dienen.

4. FinalizationRegistry: Aufräumen wenn der GC zuschlägt

FinalizationRegistry ist das Pendant zu WeakRef für aktive Benachrichtigungen. Statt zu pollen, ob ein WeakRef-Ziel noch lebendig ist, registriert man ein Objekt und einen Callback. Wenn der GC das Objekt einsammelt, ruft die JavaScript-Engine den Callback mit einem beliebig gewählten "held value" auf. Typischer Anwendungsfall: externe Ressourcen wie File-Handles, native Objekte oder Datenbankverbindungen freigeben, die nicht durch Javascripts automatische Speicherverwaltung verwaltet werden.

Die wichtigste Einschränkung der FinalizationRegistry: Der Callback wird nicht sofort ausgeführt, wenn das Objekt eingesammelt wird – er wird irgendwann in einem zukünftigen Event-Loop-Tick ausgeführt. Die Spezifikation gibt keine Timing-Garantien. Programme dürfen nicht darauf angewiesen sein, dass der Cleanup-Callback vor einer bestimmten Operation läuft. FinalizationRegistry ist ein Best-Effort-Mechanismus für ergänzendes Cleanup, kein Ersatz für explizites Ressourcenmanagement mit try/finally oder dem using-Keyword (Explicit Resource Management, ES2024).

// FinalizationRegistry for tracking native/external resource cleanup
class NativeResourceManager {
  #registry
  #openHandles = new Map()

  constructor() {
    this.#registry = new FinalizationRegistry(({ id, type }) => {
      // Called when the associated JS object is GC'd
      // WARNING: this is best-effort — not guaranteed timing
      console.warn(`[ResourceManager] Leaked ${type} resource id=${id} — cleaning up`)
      this.#forceClose(id)
    })
  }

  // Register a resource wrapper object for tracking
  track(resourceObject, id, type = 'generic') {
    this.#openHandles.set(id, { type, opened: Date.now() })
    // third arg = unregister token — allows explicit unregistration
    this.#registry.register(resourceObject, { id, type }, resourceObject)
  }

  close(resourceObject, id) {
    // Explicit close: unregister from FinalizationRegistry
    this.#registry.unregister(resourceObject)
    this.#openHandles.delete(id)
  }

  #forceClose(id) {
    const info = this.#openHandles.get(id)
    if (info) {
      // Emit metrics / alert monitoring for leaked resources
      console.error(`Leaked resource: id=${id}, type=${info.type}, age=${Date.now() - info.opened}ms`)
      this.#openHandles.delete(id)
    }
  }

  get leakCount() { return this.#openHandles.size }
}

// Usage pattern with explicit resource management
const manager = new NativeResourceManager()

function openDbConnection(id) {
  const conn = { id, query: async (sql) => { /* ... */ } }
  manager.track(conn, id, 'db-connection')
  return conn
}

5. Praxismuster: WeakRef-basierter Cache

Der häufigste sinnvolle Anwendungsfall für WeakRef ist ein sekundärer Cache, der teure Berechnungen zwischenspeichert, aber den Speicher unter Druck freigibt. Das klassische Beispiel: ein Bild-Dekodierungscache in einer Web-Applikation. Bilder werden beim ersten Laden dekodiert und als ImageBitmap-Objekte im Cache gehalten. Wenn der Browser Speicher benötigt, darf er diese Objekte freigeben – der nächste Zugriff auf dasselbe Bild löst eine neue Dekodierung aus, die etwas langsamer ist, aber korrekt. Das ist ein klassischer Speed-Memory-Tradeoff, den WeakRef elegant implementierbar macht.

Ein wichtiger Praxishinweis für WeakRef-Caches: Der GC kann unter bestimmten Umständen Objekte einsammeln, die vom Entwickler noch als "aktiv" betrachtet werden – insbesondere wenn der einzige Weg zum Objekt über eine WeakRef führt und keine andere starke Referenz existiert. In Debugging-Sessions passiert das seltener, weil der DevTools-Debugger selbst Referenzen hält. Produktionsverhalten und Debugging-Verhalten können sich dadurch unterscheiden. Dieser Unterschied muss in Tests berücksichtigt werden.

6. WeakMap und WeakSet im Vergleich zu WeakRef

WeakMap und WeakSet existieren seit ES2015 und sind für die meisten Anwendungsfälle schwacher Referenzen die bessere Wahl als WeakRef. Der Unterschied: WeakMap und WeakSet halten schwache Referenzen auf ihre Keys (WeakMap) bzw. Members (WeakSet), aber starke Referenzen auf ihre Werte. Sie sind ideal für das Annotieren von Objekten mit zusätzlichen Metadaten, ohne den GC zu behindern. Wenn der Key eines WeakMap-Eintrags eingesammelt wird, verschwindet der Eintrag automatisch.

WeakRef hingegen hält eine schwache Referenz auf ein beliebiges Objekt, unabhängig von einer Map-Struktur. Es ist die flexiblere, aber auch gefährlichere API. Der Hauptunterschied in der Praxis: WeakMap-Einträge können nie explizit iteriert werden (kein .keys(), kein .size), was sie für Caches mit Key-Iteration ungeeignet macht. WeakRef kann in einer regulären Map gespeichert werden, die iterierbar ist – deshalb die WeakCache-Implementierung aus dem vorigen Beispiel. Die FinalizationRegistry kümmert sich dann um das Aufräumen veralteter Map-Einträge.

7. Fallstricke: Wann WeakRef und FinalizationRegistry schaden

Der größte Fallstrick bei WeakRef: Es verleitet dazu, Speicherverwaltungs-Probleme zu lösen, die eigentlich durch saubereres Code-Design lösbar wären. Wenn eine Klasse Objekte als WeakRef speichert, weil sie sich nicht sicher ist, ob die Objekte noch lebendig sind, ist das oft ein Zeichen für ein Ownership-Problem im Code-Design. Explizite Lebenszyklusmethoden wie mount() und destroy() sind meistens die sauberere Lösung als WeakRef-basierte Heuristiken.

Ein weiteres Problem: FinalizationRegistry-Callbacks können in kritischen Momenten ausgeführt werden und Seiteneffekte haben, die den normalen Kontrollfluss stören. In Node.js-Umgebungen mit Worker Threads ist die Ausführungs-Reihenfolge von Registry-Callbacks noch weniger deterministisch. Außerdem: Je mehr WeakRef- und Registry-Objekte in einem Programm existieren, desto mehr Arbeit muss der GC leisten, um die Erreichbarkeit zu bestimmen. Massive Verwendung dieser APIs kann paradoxerweise die GC-Performance verschlechtern.

8. Memory Profiling im Browser und Node.js

Bevor man WeakRef oder FinalizationRegistry einsetzt, sollte das tatsächliche Speicherproblem mit Profiling-Tools verifiziert werden. In Chrome DevTools bietet der Memory-Tab Heap-Snapshots, die zeigen, welche Objekte wie viel Speicher belegen und von wo sie referenziert werden. Der "Retainers"-Graph zeigt die Referenzkette, die ein Objekt am Leben hält. Für Speicherlecks ist der Vergleich von zwei Snapshots (vor und nach einer Benutzeraktion) der effektivste Ansatz: Objekte, die im Delta auftauchen und wachsen, sind die Kandidaten.

In Node.js steht process.memoryUsage() für einfache Messungen zur Verfügung. Für detailliertes Profiling bietet das --inspect-Flag die Chrome DevTools-Verbindung an. Das npm-Package heapdump ermöglicht programmatische Heap-Snapshots. Mit v8.writeHeapSnapshot() (eingebaut seit Node.js 11) kann man Snapshots im Code triggern. Ein wichtiger Hinweis für das Testen von WeakRef-Verhalten: In Node.js kann man mit --expose-gc und dem globalen gc()-Funktionsaufruf eine GC manuell auslösen – nur für Tests, niemals in Produktionscode.

// Memory profiling utilities for WeakRef / FinalizationRegistry debugging

// Node.js: expose GC for testing (run with: node --expose-gc test.js)
async function testWeakRefBehavior() {
  let target = { payload: new Array(1e6).fill(0) } // ~8 MB
  const ref = new WeakRef(target)

  console.log('Before drop:', ref.deref() !== undefined) // true

  target = null // drop strong reference

  // Force GC (only works with --expose-gc flag!)
  if (typeof gc === 'function') {
    gc()
    // Wait for GC to process — it runs async relative to JS
    await new Promise(resolve => setTimeout(resolve, 100))
  }

  console.log('After GC:', ref.deref()) // undefined (or still the object if GC hasn't run)

  // Proper pattern: always check deref() result before use
  const obj = ref.deref()
  if (obj === undefined) {
    console.log('Object was collected — fallback to recomputation')
    return recompute()
  }
  return obj
}

// Browser: track memory with performance.measureUserAgentSpecificMemory()
async function measureMemory() {
  if ('measureUserAgentSpecificMemory' in performance) {
    const result = await performance.measureUserAgentSpecificMemory()
    console.log('JS Heap:', result.bytes / 1024 / 1024, 'MB')
    console.log('Breakdown:', result.breakdown)
  }
}

9. Vergleich: Starke vs. schwache Referenz-Strategien

Die Entscheidung zwischen starken Referenzen, WeakMap, WeakRef und explizitem Lebenszyklusmanagement hängt vom konkreten Anwendungsfall ab. Für das Annotieren von DOM-Elementen mit Event-Handler-Referenzen ist WeakMap ideal: Wenn das Element aus dem DOM entfernt und alle anderen Referenzen darauf verschwinden, verschwindet auch der Cache-Eintrag automatisch. Für sekundäre Caches mit String-Keys ist WeakRef in einer regulären Map die bessere Wahl, weil WeakMap nur Objekte als Keys erlaubt.

Explizites Lebenszyklusmanagement – also component.destroy()-Methoden, die Event-Listener entfernen und Caches leeren – ist in allen Fällen, wo es möglich ist, die zuverlässigste Strategie. WeakRef und FinalizationRegistry sind für die Fälle gedacht, wo explizites Cleanup nicht garantiert werden kann: Third-Party-Code, der Callbacks registriert, Objekte, deren Lebenszyklus extern gesteuert wird, oder Ressourcen, die als Sicherheitsnetz gehalten werden müssen, falls der explizite Cleanup-Pfad versagt.

10. Zusammenfassung

WeakRef und FinalizationRegistry sind mächtige, aber spezifische Werkzeuge in der JavaScript-Werkzeugkiste. WeakRef ermöglicht das Halten einer Referenz auf ein Objekt, ohne dessen GC zu verhindern – ideal für sekundäre Caches und optionale Ressourcen. FinalizationRegistry ermöglicht Cleanup-Callbacks, wenn der GC ein Objekt einsammelt – ideal für natives Ressourcenmanagement und Leak-Erkennung. Beide APIs verlangen, dass der aufrufende Code mit der Nicht-Determinismus der GC-Ausführung umgeht und niemals auf ein bestimmtes Timing angewiesen ist.

Für die meisten Fälle, in denen schwache Referenzen sinnvoll erscheinen, sind WeakMap und WeakSet die einfacheren und sichereren Alternativen. WeakRef und FinalizationRegistry sollten erst dann eingesetzt werden, wenn diese einfacheren Alternativen nicht ausreichen. Speicherverwaltungsprobleme zuerst mit Profiling-Tools diagnostizieren, dann die minimale nötige Abstraktion wählen, und explizites Cleanup immer bevorzugen. WeakRef ist das Sicherheitsnetz, nicht der erste Griff.

11. FAQ: WeakRef und FinalizationRegistry in JavaScript