Preventing Memory Leaks with JS WeakMaps Guide

A memory leak in JavaScript happens when objects that are no longer needed remain in memory because something still holds a reference to them. The garbage collector cannot free them, so memory usage grows over time.

WeakMap and WeakSet are the built-in tools for preventing this. They let you associate data with an object without keeping that object alive.

The Leak: Regular Map with DOM Elements

This is the most common memory leak pattern that WeakMap fixes. You store data keyed by DOM elements in a regular Map:

javascript

// Memory leak pattern
const elementData = new Map();
 
function trackElement(el) {
  elementData.set(el, { clicks: 0, visible: true });
}
 
const button = document.querySelector("button");
trackElement(button);

Once the button is tracked, removing it from the page does not free it, because the Map still holds a reference to it:

javascript

// Later: button is removed from the DOM
button.remove();
 
// But elementData still holds a reference to button
// The button element and its data cannot be garbage collected

The Map holds a strong reference to button. Even though the button is removed from the page, it stays in memory because elementData still references it.

The Fix: WeakMap

Replace the Map with a WeakMap. The weak reference allows garbage collection:

javascript

// No memory leak
const elementData = new WeakMap();
 
function trackElement(el) {
  elementData.set(el, { clicks: 0, visible: true });
}
 
let button = document.querySelector("button");
trackElement(button);

The setup looks identical to the Map version. The difference shows up once the button is removed and no other references to it remain:

javascript

button.remove();
button = null;
 
// The WeakMap entry for the button is now eligible for garbage collection
// The data object { clicks, visible } is also freed

The key difference: when button has no more strong references, the WeakMap entry is automatically eligible for cleanup. You do not need to manually call delete().

Pattern: Event Listener Metadata

When you attach event listeners to elements that come and go, storing listener metadata in a WeakMap ensures cleanup:

javascript

const listenerMeta = new WeakMap();
 
function addTrackedListener(el, event, handler) {
  el.addEventListener(event, handler);
  listenerMeta.set(el, { event, handler, addedAt: Date.now() });
}

A matching removal function can look up that metadata later without you having to track the event name and handler separately in your own code:

javascript

function removeTrackedListener(el) {
  const meta = listenerMeta.get(el);
  if (meta) {
    el.removeEventListener(meta.event, meta.handler);
    // No need to delete from WeakMap -- if el is garbage collected, entry is freed
  }
}

When the element is deleted and garbage collected, its metadata in listenerMeta is freed. With a regular Map, you would need to remember to delete entries manually.

Pattern: Object-Keyed Cache

Caches that use objects as keys should use WeakMap so entries are freed when the key object is no longer needed:

javascript

const cache = new WeakMap();
 
function getCachedResult(inputObj) {
  if (cache.has(inputObj)) {
    return cache.get(inputObj);
  }
  const result = expensiveTransform(inputObj);
  cache.set(inputObj, result);
  return result;
}

Calling this function looks no different from a Map-backed cache. The benefit is invisible until inputObj stops being referenced anywhere else, at which point its entry disappears on its own instead of sitting in memory forever.

Compare this to a Map-based cache, which would grow forever unless you manually evict entries.

Pattern: Tracking Object State with WeakSet

Use a WeakSet to mark objects as processed without preventing their cleanup:

javascript

const initialized = new WeakSet();
 
class Component {
  mount() {
    if (initialized.has(this)) return;
    initialized.add(this);
    // One-time setup logic
  }
}

When a Component instance is no longer referenced, it is removed from the initialized set. A regular Set would keep it alive.

When Not to Use WeakMap

WeakMap is not the right choice in every situation. Do not use WeakMap when:

• Keys are primitives. WeakMap requires object (or non-registered symbol) keys. Use Map for string or number keys.
• You need to iterate over entries. WeakMap has no keys(), values(), entries(), or forEach().
• You need to know how many entries exist. WeakMap has no size property.
• The data should outlive the key object. If the metadata should persist even after the object is gone, use a regular Map and manage the lifecycle manually.

For the fundamentals of WeakMap and WeakSet, see the article on /javascript/javascript-weakmap-and-weakset-complete-guide.

Quick Decision: Should This Be a WeakMap?

Ask yourself one question: Should this data disappear when the key object is garbage collected?

If the answer is yes, WeakMap gives you automatic cleanup with no manual lifecycle management. The limitation on API (no iteration, no size) is a feature: it enforces the correct pattern of tying data lifetime to object lifetime. Closures are another common source of the same kind of leak; for that pattern, see the article on /javascript/how-to-prevent-memory-leaks-in-javascript-closures.