Javascript Weakmap Weakref: The Memory Management Primitives Nobody Teaches

// ❌ Classic memory leak: caching data tied to DOM nodes
const cache = new Map();

function processElement(element) {
 if (!cache.has(element)) {
 cache.set(element, computeExpensiveData(element));
 }
 return cache.get(element);
}

// When element is removed from DOM:
document.body.removeChild(element);
// element is removed from DOM, but cache still holds a reference!
// GC cannot collect element — MEMORY LEAK
// This is why SPAs slowly consume gigabytes over a session

// ✅ Fix: WeakMap — element can be GC'd even while in cache
const cache = new WeakMap();

function processElement(element) {
 if (!cache.has(element)) {
 cache.set(element, computeExpensiveData(element));
 }
 return cache.get(element);
}
// When element is removed from DOM and has no other references,
// GC collects it AND automatically removes the WeakMap entry
// Zero memory leak. Zero cleanup code needed.

const wm = new WeakMap();

// Keys MUST be objects (not primitives)
wm.set({}, 'value'); // ✅ object key
wm.set('string', 'x'); // ❌ TypeError: Invalid value used as weak map key

// WeakMap is NOT iterable (by design)
// You cannot enumerate keys/values — the GC controls key existence
for (const [k, v] of wm) {} // ❌ TypeError: WeakMap is not iterable
wm.size; // undefined — size is unknowable (GC may have collected keys)

// API: only has/get/set/delete
const key = { id: 1 };
wm.set(key, { computed: 'data', timestamp: Date.now() });
wm.has(key); // true
wm.get(key); // { computed: 'data', timestamp: ... }
wm.delete(key); // true

// Real use case: private class data (pre-#private syntax)
const _private = new WeakMap();
class BankAccount {
 constructor(balance) {
 _private.set(this, { balance, transactions: [] });
 }
 deposit(amount) {
 const data = _private.get(this);
 data.balance += amount;
 data.transactions.push({ type: 'deposit', amount });
 }
 get balance() { return _private.get(this).balance; }
}
// When account instance is GC'd, _private entry disappears automatically

// WeakRef holds a reference that doesn't prevent GC
// deref() returns the object OR undefined if it was collected

let expensiveObject = { data: new ArrayBuffer(1024 * 1024) }; // 1MB

const ref = new WeakRef(expensiveObject);

// Later, expensiveObject might be collected...
expensiveObject = null; // Remove the strong reference

// Try to use the object:
const obj = ref.deref();
if (obj) {
 console.log('Object still alive:', obj.data.byteLength);
} else {
 console.log('Object was garbage collected');
}
// You MUST check deref() result — it can be undefined at any time

// IMPORTANT: The GC can collect the object between any two deref() calls
// Never store deref() result across async operations:
const obj1 = ref.deref(); // alive
await someAsyncOperation();
const obj2 = ref.deref(); // might be undefined — obj1 and obj2 can differ!
// ✅ Correct: call deref() once, check result, use it synchronously

// FinalizationRegistry: callback when a WeakRef target is GC'd
const registry = new FinalizationRegistry((heldValue) => {
 console.log('Object collected, held value:', heldValue);
 // Clean up external resources (file handles, network connections, etc.)
});

let resource = { connection: createDbConnection() };
registry.register(resource, 'db-connection-cleanup');
// When resource is GC'd, callback runs with 'db-connection-cleanup'

// Practical use: LRU cache with automatic cleanup
class WeakCache {
 #cache = new Map();
 #registry = new FinalizationRegistry(key => this.#cache.delete(key));

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

 get(key) {
 const ref = this.#cache.get(key);
 if (!ref) return undefined;
 const value = ref.deref();
 if (!value) {
 this.#cache.delete(key); // Clean up stale entry proactively
 return undefined;
 }
 return value;
 }
}

const cache = new WeakCache();
let bigData = { results: new Array(100000).fill(0) };
cache.set('query-results', bigData);
bigData = null; // When collected, cache entry auto-removes

// ❌ Classic event listener leak
class EventEmitter {
 #listeners = new Map();
 on(event, handler) {
 if (!this.#listeners.has(event)) this.#listeners.set(event, new Set());
 this.#listeners.get(event).add(handler);
 }
 // If subscriber is destroyed without calling off(), handler keeps it alive
}

// ✅ WeakRef-based observer — subscribers can be GC'd
class WeakEventEmitter {
 #listeners = new Map();

 on(event, handler) {
 if (!this.#listeners.has(event)) this.#listeners.set(event, new Set());
 this.#listeners.get(event).add(new WeakRef(handler));
 }

 emit(event, data) {
 const handlers = this.#listeners.get(event);
 if (!handlers) return;
 for (const ref of handlers) {
 const handler = ref.deref();
 if (handler) {
 handler(data);
 } else {
 handlers.delete(ref); // Auto-cleanup dead refs
 }
 }
 }
}

// Now subscribers don't need to explicitly unsubscribe
// When component is destroyed and handler function GC'd,
// next emit() call automatically cleans up the dead WeakRef