WeakMap and WeakSet in JavaScript — Memory, Garbage Collection and Real-World Patterns

// Demonstrating that a WeakMap does NOT prevent garbage collection.
// We use FinalizationRegistry (ES2021) to observe when an object is collected.
// Note: GC timing is non-deterministic — this is illustrative, not a guarantee of exact timing.

const collectionLog = new FinalizationRegistry((label) => {
  console.log(`[GC] Object labeled "${label}" has been garbage collected.`);
});

// Create a WeakMap to store metadata about request objects
const requestMetadata = new WeakMap();

// Simulate a request object arriving
let incomingRequest = { id: 'req-001', path: '/api/users' };

// Attach metadata — timing info, headers, etc.
requestMetadata.set(incomingRequest, {
  receivedAt: Date.now(),
  authenticated: true,
  rateLimitRemaining: 99,
});

// Register with FinalizationRegistry so we know when it's collected
collectionLog.register(incomingRequest, 'req-001');

console.log('Metadata while request is alive:');
console.log(requestMetadata.get(incomingRequest));
// { receivedAt: 1718000000000, authenticated: true, rateLimitRemaining: 99 }

console.log('WeakMap has entry for request:', requestMetadata.has(incomingRequest)); // true

// Simulate the request going out of scope — nulling the reference
// After this line, no strong reference to the object remains.
incomingRequest = null;

// The GC is now FREE to collect the old request object.
// The WeakMap entry will vanish when it does.
// We can't force GC from user code, but the engine will do it during idle time.

console.log('\nRequest reference nulled. The WeakMap entry will be freed by the GC automatically.');
console.log('No manual cleanup code needed — this is the entire point.');

// Compare with a regular Map — this WOULD leak memory:
const leakyCache = new Map();
let anotherRequest = { id: 'req-002', path: '/api/posts' };
leakyCache.set(anotherRequest, { receivedAt: Date.now() });
anotherRequest = null;
// The Map STILL holds a strong reference internally.
// The object { id: 'req-002', ... } is NOT eligible for collection.
// leakyCache.size === 1 forever, and that memory never returns.
console.log('\nLeaky Map still has entry count:', leakyCache.size); // 1 — memory leak!

// ─────────────────────────────────────────────
// PATTERN 1: True private class data via WeakMap
// ─────────────────────────────────────────────

// The WeakMap lives in module scope — invisible outside this file
const _bankAccountPrivate = new WeakMap();

class BankAccount {
  constructor(owner, initialBalance) {
    // Store sensitive data in the WeakMap, keyed by the instance itself
    // This data is NOT on `this` — you can't access it from outside
    _bankAccountPrivate.set(this, {
      balance: initialBalance,
      transactionHistory: [],
      pin: null, // set separately
    });

    this.owner = owner; // public
  }

  deposit(amount) {
    const privateData = _bankAccountPrivate.get(this);
    privateData.balance += amount;
    privateData.transactionHistory.push({ type: 'deposit', amount, at: Date.now() });
    console.log(`Deposited $${amount}. New balance: $${privateData.balance}`);
  }

  getBalance() {
    // Only the class itself can read from the WeakMap
    return _bankAccountPrivate.get(this).balance;
  }

  getTransactionCount() {
    return _bankAccountPrivate.get(this).transactionHistory.length;
  }
}

const aliceAccount = new BankAccount('Alice', 1000);
aliceAccount.deposit(250);
console.log('Balance:', aliceAccount.getBalance());        // 1250
console.log('Transactions:', aliceAccount.getTransactionCount()); // 2

// Attempts to read private data directly fail — it's NOT on the object
console.log('Direct access attempt:', aliceAccount.balance);  // undefined — protected!
console.log('Object keys:', Object.keys(aliceAccount));       // ['owner'] — clean!


// ─────────────────────────────────────────────
// PATTERN 2: DOM node metadata without pollution
// (Works in a browser; shown here conceptually for Node.js readers)
// ─────────────────────────────────────────────

const domNodeMetadata = new WeakMap();

function attachComponentData(domNode, componentState) {
  // Safe: when domNode is removed from the DOM and dereferenced, this entry
  // is automatically freed. No manual teardown, no memory leak.
  domNodeMetadata.set(domNode, {
    componentState,
    eventListeners: [],
    mountedAt: Date.now(),
  });
}

function getComponentData(domNode) {
  return domNodeMetadata.get(domNode) ?? null;
}

// Simulate a DOM node (in Node.js context)
let simulatedDomNode = { tagName: 'DIV', id: 'app-root' };
attachComponentData(simulatedDomNode, { count: 0, theme: 'dark' });

console.log('\nComponent data:', getComponentData(simulatedDomNode));
// { componentState: { count: 0, theme: 'dark' }, eventListeners: [], mountedAt: ... }

// Simulate removing the node — memory freed automatically
simulatedDomNode = null;


// ─────────────────────────────────────────────
// PATTERN 3: Self-evicting memoization cache
// ─────────────────────────────────────────────

const computationCache = new WeakMap();

function expensiveAnalysis(dataObject) {
  // Check cache first
  if (computationCache.has(dataObject)) {
    console.log('Cache hit — returning cached result');
    return computationCache.get(dataObject);
  }

  // Simulate expensive work
  const result = {
    itemCount: dataObject.items.length,
    total: dataObject.items.reduce((sum, item) => sum + item.price, 0),
    average: 0,
  };
  result.average = result.total / result.itemCount;

  // Cache the result — when dataObject is GC'd, this entry vanishes too
  computationCache.set(dataObject, result);
  console.log('Cache miss — computed and cached result');
  return result;
}

let orderData = {
  id: 'order-789',
  items: [
    { name: 'Widget', price: 29.99 },
    { name: 'Gadget', price: 49.99 },
    { name: 'Doohickey', price: 14.99 },
  ],
};

console.log('\nFirst call:');
console.log(expensiveAnalysis(orderData));

console.log('\nSecond call (same object):');
console.log(expensiveAnalysis(orderData));

// When orderData goes out of scope, the cache entry is freed automatically
orderData = null;

// ─────────────────────────────────────────────
// PATTERN 1: Cycle detection in object graph traversal
// Without WeakSet, circular references cause infinite loops.
// With a regular Set, every visited node is retained forever.
// WeakSet gives us cycle detection with automatic memory release.
// ─────────────────────────────────────────────

function deepSerialize(rootObject) {
  const visitedNodes = new WeakSet(); // tracks objects we've already processed

  function serialize(currentValue) {
    // Primitives need no cycle check
    if (typeof currentValue !== 'object' || currentValue === null) {
      return currentValue;
    }

    // If we've been here before, we have a circular reference
    if (visitedNodes.has(currentValue)) {
      return '[Circular Reference Detected]';
    }

    // Mark this object as visited BEFORE recursing into its properties
    visitedNodes.add(currentValue);

    if (Array.isArray(currentValue)) {
      return currentValue.map(serialize);
    }

    // Recursively serialize each property
    const serialized = {};
    for (const [key, value] of Object.entries(currentValue)) {
      serialized[key] = serialize(value);
    }
    return serialized;
  }

  return serialize(rootObject);
}

// Build a deliberately circular structure
const nodeA = { name: 'Alpha', children: [] };
const nodeB = { name: 'Beta', children: [] };
const nodeC = { name: 'Gamma', children: [] };

nodeA.children.push(nodeB);
nodeB.children.push(nodeC);
nodeC.children.push(nodeA); // circular! Gamma points back to Alpha

console.log('Serialized circular graph:');
console.log(JSON.stringify(deepSerialize(nodeA), null, 2));


// ─────────────────────────────────────────────
// PATTERN 2: One-time initialization guard
// Prevents a setup function from running twice on the same object
// ─────────────────────────────────────────────

const initializedComponents = new WeakSet();

function initializeComponent(componentInstance) {
  if (initializedComponents.has(componentInstance)) {
    console.log(`\nComponent "${componentInstance.name}" is already initialized — skipping.`);
    return;
  }

  // Perform one-time setup
  componentInstance.isReady = true;
  componentInstance.createdAt = Date.now();
  console.log(`\nComponent "${componentInstance.name}" initialized successfully.`);

  // Mark it so we never run this again for this instance
  initializedComponents.add(componentInstance);
}

const headerComponent = { name: 'HeaderNav', isReady: false };
const footerComponent = { name: 'FooterLinks', isReady: false };

initializeComponent(headerComponent); // runs
initializeComponent(headerComponent); // blocked — already done
initializeComponent(footerComponent); // runs

console.log('\nHeader ready:', headerComponent.isReady); // true
console.log('Footer ready:', footerComponent.isReady); // true

// When a component is destroyed and the reference dropped,
// the WeakSet entry vanishes — no stale entries accumulate over time.


// ─────────────────────────────────────────────
// PATTERN 3: Tracking which elements have listeners attached
// Avoids accidentally adding duplicate event listeners to DOM nodes
// ─────────────────────────────────────────────

const listenersAttached = new WeakSet();

function safeAddClickListener(element, handler) {
  if (listenersAttached.has(element)) {
    console.log(`\nListener already attached to element #${element.id} — not adding again.`);
    return;
  }

  // In a real browser: element.addEventListener('click', handler);
  console.log(`\nAttaching click listener to element #${element.id}`);
  listenersAttached.add(element);
}

const buttonElement = { tagName: 'BUTTON', id: 'submit-btn' };
const clickHandler = () => console.log('Button clicked!');

safeAddClickListener(buttonElement, clickHandler); // attaches
safeAddClickListener(buttonElement, clickHandler); // blocked — already attached
safeAddClickListener(buttonElement, clickHandler); // blocked — already attached

// Demonstrating WeakRef with a cache that gracefully handles collected entries
// This is an advanced pattern — only use WeakRef when WeakMap won't work
// (i.e., when you need to hold the weak reference directly, not as a Map key)

class GracefulCache {
  constructor() {
    // Keys are strings (IDs), values are WeakRefs to the cached objects
    // This is impossible with WeakMap (which needs object keys)
    this._store = new Map();

    // Clean up the Map entry after the object is collected
    this._registry = new FinalizationRegistry((cacheKey) => {
      const existingRef = this._store.get(cacheKey);
      // Only delete if the ref is actually dead (not replaced with a new one)
      if (existingRef && existingRef.deref() === undefined) {
        this._store.delete(cacheKey);
        console.log(`[FinalizationRegistry] Cache entry for key "${cacheKey}" cleaned up.`);
      }
    });
  }

  set(key, value) {
    const weakRef = new WeakRef(value);
    this._store.set(key, weakRef);
    // Register the value with the cleanup callback, passing the key as the token
    this._registry.register(value, key, weakRef);
    console.log(`Cached object under key "${key}"`);
  }

  get(key) {
    const weakRef = this._store.get(key);
    if (!weakRef) return undefined;

    const cachedValue = weakRef.deref();
    if (cachedValue === undefined) {
      // Object was collected — clean up synchronously on access too
      this._store.delete(key);
      console.log(`Cache miss (GC'd) for key "${key}"`);
      return undefined;
    }

    console.log(`Cache hit for key "${key}"`);
    return cachedValue;
  }

  get size() {
    return this._store.size; // Note: may include not-yet-cleaned dead entries
  }
}

const resourceCache = new GracefulCache();

let expensiveResource = {
  id: 'resource-001',
  data: new Array(1000).fill('payload'), // simulate a large object
  computedAt: Date.now(),
};

resourceCache.set('resource-001', expensiveResource);

console.log('\nImmediate retrieval:');
const retrieved = resourceCache.get('resource-001');
console.log('Retrieved id:', retrieved?.id); // resource-001

console.log('\nCache size before release:', resourceCache.size); // 1

// Release the strong reference
expensiveResource = null;

// In a real scenario, the GC would eventually run and the
// FinalizationRegistry callback would fire, printing the cleanup message.
// We can't force this deterministically — it's engine-controlled.

console.log('\nStrong reference released.');
console.log('Cache size (GC may not have run yet):', resourceCache.size);
console.log('WeakRef.deref() returns undefined after GC collects the object.');

// ─────────────────────────────────────────────
// CONTRAST: When to use WeakMap vs WeakRef
// ─────────────────────────────────────────────
console.log('\n--- When to use which ---');
console.log('WeakMap: attach metadata TO an object (object is the key)');
console.log('WeakRef: hold a reference TO an object (string/number as key in outer Map)');
console.log('WeakSet: track WHETHER you have seen an object');
console.log('FinalizationRegistry: run cleanup AFTER an object is collected');