JavaScript WeakMap and WeakSet Guide

WeakMap and WeakSet hold weak references to objects, enabling garbage collection. Here's how to use them.

WeakMap vs Map#

// Map: Strong references, prevents garbage collection
const map = new Map();
let obj = { name: 'John' };
map.set(obj, 'metadata');
obj = null; // Object still exists in map

// WeakMap: Weak references, allows garbage collection
const weakMap = new WeakMap();
let obj2 = { name: 'Jane' };
weakMap.set(obj2, 'metadata');
obj2 = null; // Object can be garbage collected

// Key differences
const map = new Map();
map.set('string', 'value');     // OK
map.set(123, 'value');          // OK
map.size;                        // Available

const weakMap = new WeakMap();
// weakMap.set('string', 'value'); // Error: Invalid key
weakMap.set({}, 'value');       // Only objects as keys
// weakMap.size;                 // Not available
// weakMap.keys();               // Not iterable

WeakSet vs Set#

// Set: Strong references
const set = new Set();
let obj = { id: 1 };
set.add(obj);
obj = null; // Object still exists in set

// WeakSet: Weak references
const weakSet = new WeakSet();
let obj2 = { id: 2 };
weakSet.add(obj2);
obj2 = null; // Object can be garbage collected

// WeakSet limitations
const weakSet = new WeakSet();
// weakSet.add('string');    // Error: Invalid value
// weakSet.size;             // Not available
// weakSet.values();         // Not iterable
weakSet.add({});             // OK
weakSet.has({});             // false (different object)

Private Data Pattern#

// Store private data without exposing it
const privateData = new WeakMap();

class User {
  constructor(name, password) {
    this.name = name;
    privateData.set(this, { password });
  }

  checkPassword(attempt) {
    const data = privateData.get(this);
    return data.password === attempt;
  }

  // Password is not accessible from outside
  // When User instance is garbage collected,
  // private data is also cleaned up
}

const user = new User('John', 'secret123');
console.log(user.name);             // 'John'
console.log(user.password);         // undefined
console.log(user.checkPassword('secret123')); // true

// With Symbol (alternative but data visible via reflection)
const _password = Symbol('password');
class User2 {
  constructor(name, password) {
    this.name = name;
    this[_password] = password;
  }
}
// Object.getOwnPropertySymbols(user2) exposes the symbol

Caching with WeakMap#

// Cache computation results per object
const cache = new WeakMap();

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

  // Expensive operation
  const result = Object.keys(obj).reduce((sum, key) => {
    return sum + String(obj[key]).length;
  }, 0);

  cache.set(obj, result);
  return result;
}

const data = { a: 'hello', b: 'world' };
expensiveComputation(data); // Computes
expensiveComputation(data); // Returns cached

// When data is no longer referenced,
// cache entry is automatically cleaned up

// Memoization for class instances
const memoCache = new WeakMap();

function memoize(instance, key, fn) {
  if (!memoCache.has(instance)) {
    memoCache.set(instance, new Map());
  }

  const instanceCache = memoCache.get(instance);

  if (!instanceCache.has(key)) {
    instanceCache.set(key, fn());
  }

  return instanceCache.get(key);
}

DOM Element Metadata#

// Associate data with DOM elements
const elementData = new WeakMap();

function setElementData(element, data) {
  elementData.set(element, data);
}

function getElementData(element) {
  return elementData.get(element);
}

// Usage
const button = document.querySelector('#myButton');
setElementData(button, {
  clickCount: 0,
  lastClicked: null,
});

button.addEventListener('click', () => {
  const data = getElementData(button);
  data.clickCount++;
  data.lastClicked = new Date();
});

// When button is removed from DOM and dereferenced,
// metadata is automatically cleaned up

// Event listener tracking
const listeners = new WeakMap();

function addTrackedListener(element, event, handler) {
  if (!listeners.has(element)) {
    listeners.set(element, []);
  }

  element.addEventListener(event, handler);
  listeners.get(element).push({ event, handler });
}

function removeAllListeners(element) {
  const elementListeners = listeners.get(element) || [];
  elementListeners.forEach(({ event, handler }) => {
    element.removeEventListener(event, handler);
  });
  listeners.delete(element);
}

Object Visited Tracking#

// Track visited objects in recursive operations
function deepClone(obj, visited = new WeakSet()) {
  // Handle primitives
  if (obj === null || typeof obj !== 'object') {
    return obj;
  }

  // Handle circular references
  if (visited.has(obj)) {
    return obj; // Or throw error, or return placeholder
  }

  visited.add(obj);

  // Handle arrays
  if (Array.isArray(obj)) {
    return obj.map(item => deepClone(item, visited));
  }

  // Handle objects
  const clone = {};
  for (const key in obj) {
    if (obj.hasOwnProperty(key)) {
      clone[key] = deepClone(obj[key], visited);
    }
  }

  return clone;
}

// Test with circular reference
const obj = { a: 1, b: { c: 2 } };
obj.self = obj;
const cloned = deepClone(obj);

// Compare objects without infinite loop
function deepEqual(a, b, visited = new WeakSet()) {
  if (a === b) return true;
  if (typeof a !== 'object' || typeof b !== 'object') return false;
  if (a === null || b === null) return false;

  if (visited.has(a)) return true; // Assume equal for circular
  visited.add(a);

  const keysA = Object.keys(a);
  const keysB = Object.keys(b);

  if (keysA.length !== keysB.length) return false;

  return keysA.every(key =>
    keysB.includes(key) && deepEqual(a[key], b[key], visited)
  );
}

WeakRef for Optional Caching#

// WeakRef provides weak reference to single object
class Cache {
  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) {
      const value = ref.deref();
      if (value !== undefined) {
        return value;
      }
      // Clean up dead reference
      this.cache.delete(key);
    }
    return undefined;
  }

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

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

function createTrackedObject(id) {
  const obj = { id };
  registry.register(obj, id);
  return obj;
}

let tracked = createTrackedObject(1);
tracked = null; // Eventually logs: "Object with id 1 was garbage collected"

Instance Counting#

// Track active instances without preventing GC
const instances = new WeakSet();
let instanceCount = 0;

const registry = new FinalizationRegistry(() => {
  instanceCount--;
  console.log(`Instance collected. Active: ${instanceCount}`);
});

class TrackedClass {
  constructor() {
    instances.add(this);
    instanceCount++;
    registry.register(this, undefined);
    console.log(`Instance created. Active: ${instanceCount}`);
  }

  static isInstance(obj) {
    return instances.has(obj);
  }
}

let a = new TrackedClass(); // Active: 1
let b = new TrackedClass(); // Active: 2
TrackedClass.isInstance(a); // true

a = null; // Eventually: Active: 1
b = null; // Eventually: Active: 0

React Integration#

// Store component-specific data
const componentData = new WeakMap();

function useComponentData<T>(initialData: T) {
  const ref = useRef<object>({});

  if (!componentData.has(ref.current)) {
    componentData.set(ref.current, initialData);
  }

  return componentData.get(ref.current) as T;
}

// Track mounted components
const mountedComponents = new WeakSet();

function useTrackMounted() {
  const ref = useRef<object>({});

  useEffect(() => {
    mountedComponents.add(ref.current);
    return () => {
      mountedComponents.delete(ref.current);
    };
  }, []);

  return ref;
}

API Response Caching#

// Cache API responses per request config
const responseCache = new WeakMap();

async function cachedFetch(config) {
  // config must be an object (not a string URL)
  if (responseCache.has(config)) {
    return responseCache.get(config);
  }

  const response = await fetch(config.url, config.options);
  const data = await response.json();

  responseCache.set(config, data);
  return data;
}

// Config objects as keys
const userConfig = { url: '/api/users', options: { method: 'GET' } };
await cachedFetch(userConfig); // Fetches
await cachedFetch(userConfig); // Returns cached

// When userConfig is no longer referenced,
// cached response is cleaned up

Best Practices#

Use WeakMap when:
✓ Storing metadata for objects
✓ Implementing private data
✓ Caching computed values
✓ Associating data with DOM elements

Use WeakSet when:
✓ Tracking visited objects
✓ Marking objects as processed
✓ Checking object membership
✓ Preventing duplicate processing

Avoid when:
✗ Need to iterate over entries
✗ Need to know size
✗ Keys are primitives
✗ Need persistent storage

WeakMap and WeakSet enable memory-efficient object associations. Use WeakMap for private data, caching, and metadata. Use WeakSet for tracking processed objects. Both automatically clean up when objects are garbage collected, preventing memory leaks.