weakref

This library provides three iterable weak data structures for JavaScript, IterableWeakSet, IterableWeakMap, and WeakValueMap. They keep only weak references to their keys or values, so entries disappear automatically once the referenced objects are garbage collected instead of blocking GC.

Usage

with Deno

import {
  IterableWeakMap,
  IterableWeakSet,
  WeakValueMap,
} from "@denostack/weakref";

const set = new IterableWeakSet();
const map = new IterableWeakMap();

const weakValueMap = new WeakValueMap();

with Node.js & Browser

Install

npm install weakref

import { IterableWeakMap, IterableWeakSet, WeakValueMap } from "weakref";

Note

Examples below call globalThis.gc?.() only to symbolize “a GC cycle just finished”. Manual GC is available only when the runtime exposes it (e.g. Node.js started with --expose-gc); otherwise entries disappear the next time the runtime notifies the FinalizationRegistry.

Features

IterableWeakSet

IterableWeakSet implements the semantics of both WeakSet (weak keys) and Set (iteration helpers) so you can keep a deduplicated collection of objects without preventing them from being garbage collected. Once an object is collected, the entry is removed automatically.

Interface

class IterableWeakSet<T extends object> implements WeakSet<T>, Set<T> {
  constructor(values?: readonly T[] | null);
  constructor(iterable: Iterable<T>);
}

Example

const set = new IterableWeakSet();

// create an object with a weak reference
{
  const user = { id: 1, email: "[email protected]" };
  set.add(user);
}
// end of scope, user will be garbage collected

// ...later, after a GC cycle (optional manual trigger shown here)
globalThis.gc?.(); // Node needs --expose-gc

// check the set size
console.log(set.size); // output: 0

IterableWeakMap

IterableWeakMap combines a WeakMap with iterable Map helpers so you can inspect entries without blocking GC. Keys are weakly referenced and disappear once they are no longer referenced elsewhere.

Interface

class IterableWeakMap<K extends object, V> implements WeakMap<K, V>, Map<K, V> {
  constructor(entries?: readonly (readonly [K, V])[] | null);
  constructor(iterable: Iterable<readonly [K, V]>);
}

Example

const map = new IterableWeakMap();

// create an object with a weak reference
{
  const user = { id: 1, email: "[email protected]" };
  const metadata = { created: new Date() };
  map.set(user, metadata);
}
// end of scope, user will be garbage collected

// ...later, after a GC cycle (optional manual trigger shown here)
globalThis.gc?.(); // Node needs --expose-gc

// check the map size
console.log(map.size); // output: 0

WeakValueMap

WeakValueMap is a class that allows you to create a map of non-object keys with weak references to object values. It is useful when primitive identifiers are used to look up objects that should be collected when no longer referenced elsewhere.

Interface

class WeakValueMap<K, V extends object> implements Map<K, V> {
  constructor(entries?: readonly (readonly [K, V])[] | null);
  constructor(iterable: Iterable<readonly [K, V]>);
}

Example

const map = new WeakValueMap();

// create an object with a weak reference
{
  const user = { id: 1, email: "[email protected]" };
  map.set(user.id, user);
}
// end of scope, user will be garbage collected

// ...later, after a GC cycle (optional manual trigger shown here)
globalThis.gc?.(); // Node needs --expose-gc

// check the map size
console.log(map.size); // output: 0

Tip

WeakValueMap relies on the host's FinalizationRegistry, so size/has shrink as soon as the GC notifies the registry. There can be a short delay between the object being collected and the entry disappearing.

See Also

• Python weakref inspired this project.
• MDN - JS WeakMap
• MDN - JS WeakSet
• MDN - JS WeakRef
• MDN - JS FinalizationRegistry