WeakMap, WeakSet, WeakRef, and FinalizationRegistry

The Problem: References That Keep Things Alive Too Long

You've learned that any reachable reference prevents garbage collection. But here's a scenario that comes up constantly: you want to associate data with an object — metadata, cached computations, DOM element state — without preventing the object from being collected when it's no longer needed elsewhere.

// PROBLEM: This map keeps every user object alive forever
const userMetadata = new Map();

function trackUser(user) {
  userMetadata.set(user, {
    firstSeen: Date.now(),
    interactions: 0
  });
}

// Even if the original 'user' object is no longer used anywhere,
// the Map key keeps it reachable: global → userMetadata → key (user) → user object
// The metadata entry AND the user both leak

You need a way to say: "store this association, but if the key object is garbage collected by everyone else, let the entry disappear too." Sounds reasonable, right?

That's exactly what weak references provide.

WeakMap: Metadata Without Ownership

A WeakMap is like a Map, but with critical differences:

const metadata = new WeakMap();

function processElement(element) {
  // Associate data with the element without preventing its collection
  if (!metadata.has(element)) {
    metadata.set(element, {
      processedAt: Date.now(),
      computedLayout: computeExpensiveLayout(element)
    });
  }
  return metadata.get(element);
}

// When 'element' is removed from the DOM and all other references are gone,
// the WeakMap entry is automatically removed — no manual cleanup needed

Why WeakMap Can't Be Iterated

This trips people up. "Why can't I loop over a WeakMap?" It's a deliberate design choice, not a limitation. If you could iterate a WeakMap's keys, you'd hold references to all of them during iteration — which would prevent garbage collection, defeating the entire purpose. The GC must be free to collect any key at any time, so the WeakMap cannot expose its key set.

Real-World WeakMap Patterns

Private data for class instances:

const _private = new WeakMap();

class User {
  constructor(name, email) {
    _private.set(this, { email, passwordHash: null });
    this.name = name;
  }

  getEmail() {
    return _private.get(this).email;
  }
}

const user = new User('Alice', 'alice@example.com');
user.name;       // 'Alice' — public
user.email;      // undefined — not on the instance
user.getEmail(); // 'alice@example.com' — accessible through WeakMap

// When 'user' is GC'd, the private data is automatically cleaned up

Caching computed results per object:

const computeCache = new WeakMap();

function expensiveComputation(obj) {
  if (computeCache.has(obj)) return computeCache.get(obj);

  const result = /* ... heavy computation ... */ obj.data.reduce((a, b) => a + b, 0);
  computeCache.set(obj, result);
  return result;
}

// Cache entries disappear when the input object is GC'd
// No manual cache invalidation needed

WeakSet: Membership Without Ownership

A WeakSet tracks whether objects belong to a group — without preventing their collection.

const visited = new WeakSet();

function processNode(node) {
  if (visited.has(node)) return;  // already processed
  visited.add(node);

  // Process the node...
  node.children.forEach(processNode);
}

// When a node is GC'd, it's automatically removed from the WeakSet
// No risk of the Set growing unboundedly

Branding / type-checking:

const validatedInputs = new WeakSet();

function validate(input) {
  // ... validation logic ...
  if (isValid) {
    validatedInputs.add(input);
  }
  return isValid;
}

function submitForm(formData) {
  if (!validatedInputs.has(formData)) {
    throw new Error('Form data must be validated first');
  }
  // Safe to submit
}

WeakRef: Soft Caches and Nullable References

WeakMap and WeakSet are great when your keys are objects. But what if you want a reference to an object that doesn't prevent garbage collection, period? WeakRef gives you exactly that. You can check if the object is still alive by calling .deref():

let target = { data: 'important', payload: new ArrayBuffer(10_000_000) };
const weakRef = new WeakRef(target);

// Later...
const obj = weakRef.deref();
if (obj) {
  console.log(obj.data);  // object is still alive
} else {
  console.log('Object was garbage collected');
}

Building a WeakRef-Based Cache

class WeakCache {
  #cache = new Map();

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

    const value = ref.deref();
    if (!value) {
      // Object was collected — clean up the stale WeakRef
      this.#cache.delete(key);
      return undefined;
    }
    return value;
  }

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

const imageCache = new WeakCache();

function loadImage(url) {
  const cached = imageCache.get(url);
  if (cached) return cached;

  const img = createLargeImageObject(url);
  imageCache.set(url, img);
  return img;
}

// If memory pressure causes the GC to collect an image,
// the cache gracefully returns undefined and re-fetches

FinalizationRegistry: Cleanup Callbacks

Okay, this is the most exotic tool in the box. FinalizationRegistry lets you register a callback that fires when a registered object is garbage collected. It's the closest JavaScript gets to a destructor — and it comes with major caveats.

const registry = new FinalizationRegistry((heldValue) => {
  console.log(`Object associated with "${heldValue}" was collected`);
  // Perform cleanup: close connections, release external resources, etc.
});

function createResource(name) {
  const resource = { name, handle: openExternalHandle() };

  // When 'resource' is GC'd, the callback fires with 'name' as heldValue
  registry.register(resource, name);

  return resource;
}

let r = createResource('database-connection');
r = null;  // resource becomes eligible for GC
// Eventually: "Object associated with 'database-connection' was collected"

Practical FinalizationRegistry: External Resource Cleanup

const fileHandleRegistry = new FinalizationRegistry((handle) => {
  // Close the file handle when the wrapper object is GC'd
  handle.close();
  console.log(`Auto-closed file handle ${handle.id}`);
});

class ManagedFile {
  #handle;

  constructor(path) {
    this.#handle = openFile(path);
    // Register this instance — when GC'd, close the handle
    fileHandleRegistry.register(this, this.#handle);
  }

  read() {
    return this.#handle.readAll();
  }

  // Explicit close is still preferred — FinalizationRegistry is a safety net
  close() {
    this.#handle.close();
    fileHandleRegistry.unregister(this);  // no need for callback anymore
  }
}

WeakMap vs WeakRef: When to Use Which

With all these tools available, here's how to pick the right one.