JavaScript WeakMap and WeakSet Guide

WeakMap and WeakSet hold weak references to objects, allowing garbage collection when no other references exist. Here's how to use them.

WeakMap Basics#

// Create WeakMap
const weakMap = new WeakMap();

// Only objects as keys (no primitives)
const obj = { id: 1 };
const func = () => {};
const arr = [1, 2, 3];

weakMap.set(obj, 'object data');
weakMap.set(func, 'function data');
weakMap.set(arr, 'array data');

console.log(weakMap.get(obj)); // 'object data'
console.log(weakMap.has(func)); // true

weakMap.delete(arr);
console.log(weakMap.has(arr)); // false

// Primitives not allowed
// weakMap.set('string', 'data'); // TypeError

Private Data Pattern#

// Store private data for class instances
const privateData = new WeakMap();

class User {
  constructor(name, password) {
    // Public data
    this.name = name;

    // Private data - not accessible from outside
    privateData.set(this, {
      password,
      loginAttempts: 0,
    });
  }

  checkPassword(attempt) {
    const data = privateData.get(this);
    data.loginAttempts++;

    if (data.loginAttempts > 3) {
      throw new Error('Too many attempts');
    }

    return data.password === attempt;
  }

  getLoginAttempts() {
    return privateData.get(this).loginAttempts;
  }
}

const user = new User('john', 'secret123');
console.log(user.name); // 'john'
console.log(user.password); // undefined
console.log(user.checkPassword('wrong')); // false

Caching with WeakMap#

// Cache computed values without memory leaks
const cache = new WeakMap();

function expensiveOperation(obj) {
  if (cache.has(obj)) {
    console.log('Cache hit');
    return cache.get(obj);
  }

  console.log('Computing...');
  const result = {
    computed: Object.keys(obj).length,
    timestamp: Date.now(),
  };

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

const data = { a: 1, b: 2, c: 3 };

expensiveOperation(data); // Computing...
expensiveOperation(data); // Cache hit

// When data is no longer referenced,
// cache entry is automatically garbage collected

DOM Element Data#

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

function setElementData(element, data) {
  const existing = elementData.get(element) || {};
  elementData.set(element, { ...existing, ...data });
}

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

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

button.addEventListener('click', () => {
  const data = getElementData(button);
  setElementData(button, {
    clicks: data.clicks + 1,
    lastClicked: Date.now(),
  });
});

// When button is removed from DOM and no longer referenced,
// associated data is automatically cleaned up

WeakSet Basics#

// Create WeakSet
const weakSet = new WeakSet();

const obj1 = { id: 1 };
const obj2 = { id: 2 };

weakSet.add(obj1);
weakSet.add(obj2);

console.log(weakSet.has(obj1)); // true
console.log(weakSet.has({ id: 1 })); // false (different object)

weakSet.delete(obj1);
console.log(weakSet.has(obj1)); // false

// No iteration, no size property
// weakSet.forEach() // Error
// weakSet.size // undefined

Object Tracking#

// Track which objects have been processed
const processed = new WeakSet();

function processOnce(obj) {
  if (processed.has(obj)) {
    console.log('Already processed');
    return;
  }

  // Process the object
  console.log('Processing:', obj);
  // ... do work ...

  processed.add(obj);
}

const item = { data: 'test' };
processOnce(item); // Processing: { data: 'test' }
processOnce(item); // Already processed

Circular Reference Detection#

// Detect circular references during traversal
function deepClone(obj, seen = new WeakSet()) {
  if (obj === null || typeof obj !== 'object') {
    return obj;
  }

  if (seen.has(obj)) {
    throw new Error('Circular reference detected');
  }

  seen.add(obj);

  if (Array.isArray(obj)) {
    return obj.map((item) => deepClone(item, seen));
  }

  const clone = {};
  for (const key in obj) {
    if (obj.hasOwnProperty(key)) {
      clone[key] = deepClone(obj[key], seen);
    }
  }

  return clone;
}

// Test
const a = { name: 'a' };
const b = { name: 'b', ref: a };
a.ref = b; // Circular reference

try {
  deepClone(a); // Error: Circular reference detected
} catch (e) {
  console.log(e.message);
}

Instance Validation#

// Track valid instances
const validInstances = new WeakSet();

class SecureToken {
  constructor(value) {
    this.value = value;
    validInstances.add(this);
  }

  static isValid(token) {
    return validInstances.has(token);
  }

  revoke() {
    validInstances.delete(this);
  }
}

function useToken(token) {
  if (!SecureToken.isValid(token)) {
    throw new Error('Invalid or revoked token');
  }
  return token.value;
}

const token = new SecureToken('secret');
console.log(useToken(token)); // 'secret'

token.revoke();
useToken(token); // Error: Invalid or revoked token

Event Listener Tracking#

// Track elements with listeners to prevent duplicates
const hasListener = new WeakSet();

function addClickHandler(element, handler) {
  if (hasListener.has(element)) {
    console.log('Listener already added');
    return;
  }

  element.addEventListener('click', handler);
  hasListener.add(element);
}

function removeClickHandler(element, handler) {
  if (!hasListener.has(element)) {
    return;
  }

  element.removeEventListener('click', handler);
  hasListener.delete(element);
}

Memoization with Object Keys#

// Memoize function calls with object arguments
function memoize(fn) {
  const cache = new WeakMap();

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

    const result = fn(obj);
    cache.set(obj, result);
    return result;
  };
}

// Usage
const getKeys = memoize((obj) => {
  console.log('Computing keys...');
  return Object.keys(obj);
});

const config = { a: 1, b: 2, c: 3 };

getKeys(config); // Computing keys... -> ['a', 'b', 'c']
getKeys(config); // Returns cached ['a', 'b', 'c']

Metadata Association#

// Associate metadata without modifying objects
const metadata = new WeakMap();

function setMeta(obj, key, value) {
  if (!metadata.has(obj)) {
    metadata.set(obj, new Map());
  }
  metadata.get(obj).set(key, value);
}

function getMeta(obj, key) {
  return metadata.get(obj)?.get(key);
}

function getAllMeta(obj) {
  const meta = metadata.get(obj);
  return meta ? Object.fromEntries(meta) : {};
}

// Usage
const user = { name: 'John' };
setMeta(user, 'created', Date.now());
setMeta(user, 'source', 'api');

console.log(getMeta(user, 'created'));
console.log(getAllMeta(user)); // { created: ..., source: 'api' }

Comparison Table#

/*
Feature              | WeakMap        | WeakSet        | Map            | Set
---------------------|----------------|----------------|----------------|----------------
Keys/Values          | object → any   | objects only   | any → any      | any
Garbage Collection   | Yes            | Yes            | No             | No
Iteration            | No             | No             | Yes            | Yes
Size property        | No             | No             | Yes            | Yes
Use case             | Private data   | Object flags   | General cache  | Unique values
*/

When to Use#

// Use WeakMap when:
// 1. Storing private data for objects
// 2. Caching based on object identity
// 3. Associating data with DOM elements
// 4. Preventing memory leaks with object keys

// Use WeakSet when:
// 1. Tracking object state (processed/visited)
// 2. Instance validation
// 3. Preventing duplicate operations
// 4. Circular reference detection

// Use regular Map/Set when:
// 1. Need iteration
// 2. Need size
// 3. Need primitive keys
// 4. Want to prevent garbage collection

Best Practices#

WeakMap:
✓ Private class data
✓ Object-keyed caches
✓ DOM element associations
✓ Metadata storage

WeakSet:
✓ Object tracking flags
✓ Instance validation
✓ Visited/processed tracking
✓ Circular detection

Memory:
✓ Let GC handle cleanup
✓ Don't hold other references
✓ Use for large object graphs
✓ Consider for event systems

Avoid:
✗ Expecting iteration
✗ Using for primitives
✗ Relying on size
✗ Overcomplicating simple cases

WeakMap and WeakSet are specialized collections for object-only keys that don't prevent garbage collection. Use WeakMap for private data, caching, and metadata association. Use WeakSet for tracking object state and validation. They're essential for preventing memory leaks in long-running applications, especially when working with DOM elements or large object graphs.