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

$3

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

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

const weakValueMap = new WeakValueMap();
`

$3

Install

`bash
npm install weakref
`

`ts
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

$3

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

`ts
class IterableWeakSet implements WeakSet, Set {
constructor(values?: readonly T[] | null);
constructor(iterable: Iterable);
}
`

Example

`ts
const set = new IterableWeakSet();

// create an object with a weak reference
{
const user = { id: 1, email: "hey@wan2.land" };
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
`

$3

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

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

Example

`ts
const map = new IterableWeakMap();

// create an object with a weak reference
{
const user = { id: 1, email: "hey@wan2.land" };
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
`

$3

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

`ts
class WeakValueMap implements Map {
constructor(entries?: readonly (readonly [K, V])[] | null);
constructor(iterable: Iterable);
}
`

Example

`ts
const map = new WeakValueMap();

// create an object with a weak reference
{
const user = { id: 1, email: "hey@wan2.land" };
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