JavaScript WeakRef and FinalizationRegistry Guide

WeakRef and FinalizationRegistry provide advanced memory management capabilities. Here's how to use them responsibly.

Basic WeakRef#

// Create a weak reference
const target = { data: 'important' };
const weakRef = new WeakRef(target);

// Access the target
const value = weakRef.deref();
if (value) {
  console.log(value.data); // 'important'
} else {
  console.log('Object was garbage collected');
}

// After target goes out of scope and GC runs,
// deref() may return undefined

WeakRef for Caching#

class WeakCache {
  constructor() {
    this.cache = new Map();
  }

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

  get(key) {
    const ref = this.cache.get(key);
    if (!ref) return undefined;

    const value = ref.deref();
    if (!value) {
      // Clean up dead reference
      this.cache.delete(key);
      return undefined;
    }

    return value;
  }

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

// Usage
const cache = new WeakCache();

function processData(id) {
  let data = cache.get(id);

  if (!data) {
    data = fetchExpensiveData(id);
    cache.set(id, data);
  }

  return data;
}

FinalizationRegistry#

// Create registry with cleanup callback
const registry = new FinalizationRegistry((heldValue) => {
  console.log(`Object with id ${heldValue} was garbage collected`);
  // Perform cleanup
});

// Register an object
const obj = { data: 'example' };
registry.register(obj, 'object-123'); // 'object-123' is held value

// Later, when obj is garbage collected,
// the callback will be called with 'object-123'

Resource Cleanup Pattern#

class ResourceManager {
  constructor() {
    this.resources = new Map();
    this.registry = new FinalizationRegistry((resourceId) => {
      this.cleanup(resourceId);
    });
  }

  allocate(owner) {
    const resourceId = crypto.randomUUID();
    const resource = createResource(resourceId);

    this.resources.set(resourceId, resource);
    this.registry.register(owner, resourceId);

    return resource;
  }

  cleanup(resourceId) {
    const resource = this.resources.get(resourceId);
    if (resource) {
      resource.close();
      this.resources.delete(resourceId);
      console.log(`Cleaned up resource ${resourceId}`);
    }
  }
}

// Usage
const manager = new ResourceManager();

function processWithResource() {
  const owner = {};
  const resource = manager.allocate(owner);

  // Use resource...
  return result;

  // When owner is GC'd, resource is automatically cleaned up
}

Unregister Token#

const registry = new FinalizationRegistry((heldValue) => {
  console.log(`Cleanup: ${heldValue}`);
});

const obj = { data: 'test' };
const unregisterToken = {};

// Register with unregister token
registry.register(obj, 'my-object', unregisterToken);

// Later, manually unregister
registry.unregister(unregisterToken);
// Now cleanup won't be called when obj is GC'd

WeakRef + FinalizationRegistry#

class SmartCache {
  constructor() {
    this.cache = new Map();
    this.registry = new FinalizationRegistry((key) => {
      // Clean up the WeakRef entry when object is collected
      this.cache.delete(key);
      console.log(`Cache entry ${key} cleaned up`);
    });
  }

  set(key, value) {
    // If replacing, unregister old value
    const existing = this.cache.get(key);
    if (existing) {
      this.registry.unregister(existing);
    }

    const ref = new WeakRef(value);
    this.cache.set(key, ref);
    this.registry.register(value, key, ref);
  }

  get(key) {
    const ref = this.cache.get(key);
    return ref?.deref();
  }

  // Explicit cleanup
  delete(key) {
    const ref = this.cache.get(key);
    if (ref) {
      this.registry.unregister(ref);
      this.cache.delete(key);
    }
  }
}

DOM Element Tracking#

class ElementTracker {
  constructor() {
    this.elements = new Map();
    this.registry = new FinalizationRegistry((elementId) => {
      console.log(`Element ${elementId} was removed and GC'd`);
      this.elements.delete(elementId);
      this.onElementRemoved?.(elementId);
    });
  }

  track(element, id) {
    this.elements.set(id, new WeakRef(element));
    this.registry.register(element, id);
  }

  getElement(id) {
    return this.elements.get(id)?.deref();
  }

  onElementRemoved = null;
}

// Usage
const tracker = new ElementTracker();
tracker.onElementRemoved = (id) => {
  // Update UI, clear related data, etc.
};

const div = document.createElement('div');
tracker.track(div, 'my-div');

// Later, when div is removed and GC'd,
// onElementRemoved is called

Event Listener Management#

class WeakEventEmitter {
  constructor() {
    this.listeners = new Map();
    this.registry = new FinalizationRegistry(({ event, listenerId }) => {
      this.removeListener(event, listenerId);
    });
  }

  on(event, listener, context) {
    if (!this.listeners.has(event)) {
      this.listeners.set(event, new Map());
    }

    const listenerId = crypto.randomUUID();
    const entry = {
      listener,
      contextRef: context ? new WeakRef(context) : null,
    };

    this.listeners.get(event).set(listenerId, entry);

    if (context) {
      this.registry.register(context, { event, listenerId });
    }

    return listenerId;
  }

  emit(event, ...args) {
    const eventListeners = this.listeners.get(event);
    if (!eventListeners) return;

    for (const [id, { listener, contextRef }] of eventListeners) {
      const context = contextRef?.deref() ?? null;

      // Skip if context was GC'd
      if (contextRef && !context) {
        eventListeners.delete(id);
        continue;
      }

      listener.call(context, ...args);
    }
  }

  removeListener(event, listenerId) {
    this.listeners.get(event)?.delete(listenerId);
  }
}

Image Cache Example#

class ImageCache {
  constructor(maxSize = 100) {
    this.cache = new Map();
    this.maxSize = maxSize;
    this.registry = new FinalizationRegistry((url) => {
      console.log(`Image GC'd: ${url}`);
      this.cache.delete(url);
    });
  }

  async get(url) {
    const cached = this.cache.get(url)?.deref();
    if (cached) {
      return cached;
    }

    // Load image
    const image = await this.loadImage(url);

    // Evict if cache is full
    if (this.cache.size >= this.maxSize) {
      const firstKey = this.cache.keys().next().value;
      this.cache.delete(firstKey);
    }

    this.cache.set(url, new WeakRef(image));
    this.registry.register(image, url);

    return image;
  }

  async loadImage(url) {
    return new Promise((resolve, reject) => {
      const img = new Image();
      img.onload = () => resolve(img);
      img.onerror = reject;
      img.src = url;
    });
  }
}

Object Pool with Cleanup#

class ObjectPool {
  constructor(factory, reset, maxSize = 10) {
    this.factory = factory;
    this.reset = reset;
    this.maxSize = maxSize;
    this.available = [];
    this.inUse = new Set();
    this.registry = new FinalizationRegistry((obj) => {
      // Object was GC'd without being returned
      console.warn('Object not returned to pool, was GC\'d');
      this.inUse.delete(obj);
    });
  }

  acquire() {
    let obj;

    if (this.available.length > 0) {
      obj = this.available.pop();
    } else {
      obj = this.factory();
    }

    this.inUse.add(obj);
    this.registry.register(obj, obj);

    return obj;
  }

  release(obj) {
    if (!this.inUse.has(obj)) {
      return;
    }

    this.registry.unregister(obj);
    this.inUse.delete(obj);
    this.reset(obj);

    if (this.available.length < this.maxSize) {
      this.available.push(obj);
    }
  }
}

// Usage
const bufferPool = new ObjectPool(
  () => new ArrayBuffer(1024),
  (buf) => new Uint8Array(buf).fill(0)
);

Important Caveats#

// ⚠️ WARNING: Timing is unpredictable
// GC timing is not guaranteed, don't rely on it for correctness

// ❌ BAD: Relying on finalization for critical cleanup
class BadExample {
  constructor() {
    this.file = openFile();
    registry.register(this, this.file);
  }
  // File might stay open indefinitely!
}

// ✅ GOOD: Use explicit cleanup with finalization as backup
class GoodExample {
  constructor() {
    this.file = openFile();
    registry.register(this, this.file, this);
  }

  close() {
    if (this.file) {
      this.file.close();
      this.file = null;
      registry.unregister(this);
    }
  }
}

// Always prefer:
// - try/finally
// - using declarations (when available)
// - explicit dispose/close methods

Best Practices#

Valid Use Cases:
✓ Caches that can lose entries
✓ Tracking external resources
✓ Secondary cleanup mechanism
✓ Debugging memory leaks

Requirements:
✓ Must work if cleanup never happens
✓ Must work if cleanup is delayed
✓ Primary cleanup should be explicit
✓ Finalization is a fallback

Performance:
✓ WeakRef.deref() is fast
✓ Don't create many WeakRefs
✓ Clean up dead refs periodically
✓ Avoid in hot paths

Avoid:
✗ Critical resource cleanup
✗ Side effects with timing requirements
✗ Assuming GC timing
✗ Complex finalization logic

WeakRef and FinalizationRegistry enable advanced memory management patterns like weak caches and automatic resource cleanup. WeakRef holds references without preventing garbage collection, while FinalizationRegistry runs callbacks after objects are collected. Always design systems to work correctly without relying on finalization timing, and use these APIs as optimization or fallback mechanisms, not for critical cleanup logic.