weakref

Build Coverage License Language Typescript
JSR version Deno version NPM Version Downloads

This library provides three iterable weak data structures for JavaScript, IterableWeakSet, IterableWeakMap, and WeakValueMap. These data structures are designed to work with objects as keys or values, and are useful when you need to store a collection of objects that may be garbage collected.

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 } from "weakref";

Features

IterableWeakSet

IterableWeakSet is a class that extends the WeakSet and Set classes in JavaScript, allowing you to create a set of objects that can be iterated over. Objects in the set are stored using weak references, which means that they can be garbage collected if they are no longer referenced elsewhere in the program.

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: "hey@wan2.land" };
  set.add(user);
}
// end of scope, user will be garbage collected

// force garbage collection
if (global.gc) {
  global.gc();
}

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

IterableWeakMap

IterableWeakMap is a class that extends the WeakMap and Map classes in JavaScript, allowing you to create a map of objects that can be iterated over. Keys in the map are stored using weak references, which means that they can be garbage collected if they are no longer referenced elsewhere in the program.

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: "hey@wan2.land" };
  const metadata = { created: new Date() };
  map.set(user, metadata);
}
// end of scope, user will be garbage collected

// force garbage collection
if (global.gc) {
  global.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. This is useful when you have a collection of non-object keys that you want to use to look up objects, and those objects may be garbage collected.

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: "hey@wan2.land" };
  map.set(user.id, user);
}
// end of scope, user will be garbage collected

// force garbage collection
if (global.gc) {
  global.gc();
}

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

See Also