Syed Aslam ⚡️
WeakMaps in JavaScript

WeakMaps in JavaScript


javascript weakmap
Last updated on

Note (2025): WeakMaps remain relevant in modern JavaScript (ES2025). They are especially useful for private data encapsulation, memory-sensitive caches, and avoiding memory leaks. That said, for private fields in classes, modern JavaScript now provides #privateFields syntax, which is often preferred. WeakMaps shine when you need to attach hidden state to objects you don’t own (e.g., DOM nodes, external objects).

Why WeakMaps?

In JavaScript, object property names must be strings (or symbols). If you try to use an object as a key, it’s coerced into a string:

const obj = {};
const key = {};
obj[key] = 'value';

console.log(Object.keys(obj));
// => ["[object Object]"]

This doesn’t preserve the object identity.

WeakMaps to the rescue

With ES6, JavaScript introduced WeakMaps, which allow objects (but not primitives) as keys.

ObjectWeakMap
object = Object.create(null)weakmap = new WeakMap()
object[key]weakmap.get(key)
object[key] = valueweakmap.set(key, value)
delete object[key]weakmap.delete(key)

Example: storing private data

const secrets = new WeakMap();

function setSecret(obj, secret) {
  secrets.set(obj, secret);
}

function getSecret(obj) {
  return secrets.get(obj);
}

const user = {};
setSecret(user, 'hidden-token');

console.log(getSecret(user)); // "hidden-token"

You must hold both the object and the WeakMap reference to recover the secret.

Garbage collection benefits

A key object’s presence in a WeakMap does not prevent garbage collection. Once an object key is no longer referenced anywhere else, both it and its associated value in the WeakMap are automatically cleared.

✅ Prevents memory leaks in long-lived apps.

✅ Useful for caches tied to object lifetimes.

❌ Not enumerable — you can’t list keys or values.

This makes WeakMaps perfect for “hidden side-channel state” without risk of accidental memory retention.

WeakMap vs Map

  • Map: Keys can be any value (including primitives). Keys and values are enumerable.
  • WeakMap: Keys must be objects. Keys/values are not enumerable, and entries are removed when the object is garbage collected.

Use Map if you need iteration. Use WeakMap for privacy and memory safety.

WeakMap vs Map vs Private Fields (2025)

FeatureWeakMapMap#Private Fields
Key typeObjects onlyAny (objects + primitives)Class instance
Garbage collectionAuto-cleared when object is goneNo (must delete manually)N/A (part of instance)
Enumerability❌ No (not iterable)✅ Yes (keys, values, entries)N/A (not exposed)
EncapsulationHidden if WeakMap ref is privateVisible if Map is exposedBuilt-in privacy enforced
Typical use caseHidden state, caches, DOM metadataGeneral key-value storageClass-private properties

Key Uses (2025)

  • Private data in objects you don’t control (DOM nodes, library objects).
  • Memory-sensitive caches.
  • Encapsulation in libraries without exposing hidden state.
  • When you need object identity as a key, but not iteration.

Wrap-up

WeakMaps give you:

  • Object keys without coercion.
  • Automatic garbage collection of unused keys.
  • A way to associate truly private data with objects.

In 2025, prefer #privateFields for class internals, Map for iterable collections, and WeakMap for garbage-collection–sensitive associations.

© 2025 Syed Aslam