# [`@iter/weak-map`]
An iterable alternative to the native `WeakMap` API. High-fidelity, dependency-free, and platform-agnostic.
[![][badge-jsr-pkg]][jsr] [![][badge-jsr-score]][jsr]
---
This package provides the [`IterableWeakMap`] class, which serves as an
**_iterable_** drop-in replacement for the standard [`WeakMap`] class. With an
API that implements both the standard [`Map`] interface **and** the standard
(non-iterable) [`WeakMap`], it provides a familiar surface
for working with weakly-held keys and values.
## Install
The package is distributed on [JSR] as **[`@iter/weak-map`]**.
```sh
deno add jsr:@iter/weak-map
```
[][jsr]
```sh
npx jsr add @iter/weak-map
```
[][bun]
```sh
bunx jsr add @iter/weak-map
```
[][pnpm]
```sh
pnpm dlx jsr add @iter/weak-map
```
[][yarn]
```sh
yarn dlx jsr add @iter/weak-map
```
## Usage
```ts
import { IterableWeakMap } from "@iter/weak-map";
const map = new IterableWeakMap([
[{ k: 1 }, "value1"],
[{ k: 2 }, "value2"],
]);
// oh no, we have no references to the keys!
map.get([...map.keys()][0]); // => "value1"
console.log([...map]); // => [[{ k: 1 }, "value1"], [{ k: 2 }, "value2"]]
// later on, after the keys are garbage-collected...
console.log([...map]); // => []
```
---
## API
Table of Contents
- **[`IterableWeakMap`](#iterableweakmap)**
- [`constructor`](#constructor)
- [`size`](#size)
- [`clear`](#clear)
- [`delete`](#delete)
- [`get`](#get)
- [`has`](#has)
- [`set`](#set)
- [`forEach`](#foreach)
- [`keys`](#keys)
- [`values`](#values)
- [`entries`](#entries)
- [`[Symbol.iterator]`](#symboliterator)
- [`groupBy` (static)](#groupby)
- [Further Reading](#further-reading)
- [Garbage Collection and Predictability](#garbage-collection-and-predictability)
- [What is _"Weak Iteration"_?](#what-is-weak-iteration)
- [How's it all work?](#hows-it-all-work)
## `IterableWeakMap`
> **Implements**: `WeakMap`, `Iterable<[K, V]>`
### Constructor
```ts ignore
new IterableWeakMap(entries?: Iterable<[K, V]> | null);
```
Creates a new `IterableWeakMap` instance, optionally initializing it with
an iterable of `[K, V]` entries.
If provided, every item in the sequence must be a tuple pair of `K` (a
`WeakKey`), and an arbitrary value `V`.
#### Parameters
| Parameter | Info |
| :------------- | :----------------------------------------------------------- |
| **`entries`**† | Iterable of weak keys and values to initialize the map with. |
> **_†_** Optional. If provided, must be an iterable sequence of `[K, V]` pairs.
#### Examples
```ts
import { IterableWeakMap } from "@iter/weak-map";
const map = new IterableWeakMap([
[{ k: 1 }, "value1"],
[{ k: 2 }, "value2"],
]);
const keys = [...map.keys()];
// => [{ k: 1 }, { k: 2 }]
const values = [...map.values()];
// => ['value1', 'value2']
```
---
### `size`
```ts ignore
get size(): number;
```
#### Returns
The number of living values in the map.
---
### `clear`
```ts ignore
clear(): void;
```
Clears all key-value pairs from the map.
#### Examples
```ts
import { IterableWeakMap } from "@iter/weak-map";
const map = new IterableWeakMap([
[{ k: 1 }, "value1"],
[{ k: 2 }, "value2"],
]);
map.size; // => 2
map.clear();
map.size; // => 0
```
---
### `delete`
```ts ignore
delete(key: K | WeakRef): boolean;
```
Deletes the key and its associated value from the map.
#### Parameters
| Name | Info |
| :-------- | :--------------------------------------- |
| **`key`** | The key or WeakRef of the key to delete. |
#### Returns
`true` if key and value were deleted; `false` if not.
#### Examples
```ts
import { IterableWeakMap } from "@iter/weak-map";
const a = { k: 1 }, b = { k: 2 }, c = { k: 3 };
const map = new IterableWeakMap([[a, "v1"], [b, "v2"], [c, "v3"]]);
map.delete(a); // => true
map.delete(b); // => false
```
---
### `get`
```ts ignore
get(key: K | WeakRef): V | undefined;
```
Gets the value associated with the given key (or a key's weakly-held reference,
a WeakRef). Returns `undefined` if the key is not found, or if its value has
been garbage collected and therefore is no longer available.
#### Parameters
| Name | Info |
| :-------- | :------------------------------------------------------------------------------------------------------------------ |
| **`key`** | The key (or WeakRef of the key) to get the value for. The key must be a non-null object or a non-registered symbol. |
#### Returns
The value associated with the key, if found. If the key is not found, or if the
WeakRef has been garbage collected, `undefined` is returned instead.
#### Examples
```ts
import { IterableWeakMap } from "@iter/weak-map";
const obj1 = { k: 1 };
const map = new IterableWeakMap([[obj1, "value1"]]);
const value = map.get(obj1);
console.log(value); // Output: 'value1'
// ... later on, after obj1 is garbage collected ...
const value2 = map.get(obj1); // Output: undefined
```
---
### `has`
```ts ignore
has(key: K | WeakRef): boolean;
```
Checks if the given key or reference exists in the map.
#### Parameters
| Name | Info |
| :-------- | :-------------------------------------- |
| **`key`** | The key or WeakRef of the key to check. |
#### Returns
`true` if the key exists, otherwise `false`.
#### Examples
```ts
import { IterableWeakMap } from "@iter/weak-map";
const obj1 = { k: 1 };
const map = new IterableWeakMap();
map.has(obj1); // => false
map.set(obj1, "value1");
map.has(obj1); // => true
```
---
### `set`
```ts ignore
set(key: K | WeakRef, value: V): IterableWeakMap;
```
Sets the value associated with the given key or reference.
#### Parameters
| Name | Info |
| :---------- | :--------------------------------------- |
| **`key`** | The key or WeakRef to set the value for. |
| **`value`** | The value to associate with the key. |
#### Returns
The IterableWeakMap instance.
#### Examples
```ts
import { IterableWeakMap } from "@iter/weak-map";
const map = new IterableWeakMap();
map.set({ k: 1 }, "value1");
```
---
### `forEach`
```ts ignore
forEach(
callback: (value: V, key: K, map: IterableWeakMap) => void,
thisArg?: unknown,
): void;
```
Iterates over each key-value pair in the map and invokes the callback function
with the key, value, and map as arguments.
#### Parameters
| Name | Info |
| :------------- | :--------------------------------------------------------------- |
| **`callback`** | The callback function to invoke for each key-value pair. |
| **`thisArg`** | The value to use as the contextual `this` binding in `callback`. |
#### Examples
```ts
import { IterableWeakMap } from "@iter/weak-map";
const obj1 = { k: 1 }, obj2 = { k: 2 };
const map = new IterableWeakMap([
[obj1, "value1"],
[obj2, "value2"],
]);
map.forEach((value, key) => {
console.log(`Key: ${key}, Value: ${value}`);
});
```
---
### `keys`
```ts ignore
*keys(): IterableIterator;
```
#### Returns
An iterable iterator for all keys in the map.
#### Examples
```ts
import { IterableWeakMap } from "@iter/weak-map";
const obj1 = { k: 1 }, obj2 = { k: 2 };
const map = new IterableWeakMap([
[obj1, "value1"],
[obj2, "value2"],
]);
for (const key of map.keys()) {
console.log(key);
}
```
---
### `values`
```ts ignore
*values(): IterableIterator;
```
#### Returns
An iterable iterator for all values in the map.
#### Examples
```ts
import { IterableWeakMap } from "@iter/weak-map";
const obj1 = { k: 1 }, obj2 = { k: 2 };
const map = new IterableWeakMap([
[obj1, "value1"],
[obj2, "value2"],
]);
for (const value of map.values()) {
console.log(value);
}
```
---
### `entries`
```ts ignore
*entries(): IterableIterator<[K, V]>;
```
#### Returns
An iterator over all key-value pairs (entries) in the map.
#### Examples
```ts
import { IterableWeakMap } from "@iter/weak-map";
const obj1 = { k: 1 }, obj2 = { k: 2 };
const map = new IterableWeakMap([
[obj1, "value1"],
[obj2, "value2"],
]);
for (const [key, value] of map.entries()) {
console.log(`Key: ${key}, Value: ${value}`);
}
```
---
### `[Symbol.iterator]`
```ts ignore
*[Symbol.iterator](): IterableIterator<[K, V]>;
```
Returns an iterator over key-value pairs in the map.
#### Returns
An iterator over all key-value pairs.
#### Examples
```ts
import { IterableWeakMap } from "@iter/weak-map";
const obj1 = { k: 1 }, obj2 = { k: 2 };
const map = new IterableWeakMap([
[obj1, "value1"],
[obj2, "value2"],
]);
for (const [key, value] of map) {
console.log(`Key: ${key}, Value: ${value}`);
}
const toArray = [...map];
```
---
### `groupBy`
```ts ignore
static groupBy(
items: Iterable,
keySelector: (item: T, index: number) => K,
): IterableWeakMap;
```
Groups members of an iterable according to the return value of the passed
`keySelector` callback into a new `IterableWeakMap` instance.
#### Parameters
| Parameter | Info |
| :---------------- | :------------------------------------------------------------------------------------------- |
| **`items`** | An iterable of items to group into a new `IterableWeakMap`. |
| **`keySelector`** | Invoked once for each item in `items`. Returns the key to group the item by, as a `WeakKey`. |
#### Returns
An `IterableWeakMap` containing the grouped items.
#### Examples
```ts
import { IterableWeakMap } from "@iter/weak-map";
const wm = IterableWeakMap.groupBy(
[
[Object.prototype, ["toString", { type: "method", native: true }]],
[IterableWeakMap, [undefined, { type: "class", static: true }]],
[IterableWeakMap, ["groupBy", { type: "method", static: true }]],
[IterableWeakMap.prototype, ["has", { type: "method" }]],
[IterableWeakMap.prototype, ["set", { type: "method" }]],
],
([target]) => target,
);
console.assert(wm.has(IterableWeakMap));
console.assert(wm.get(IterableWeakMap)!.length === 2);
console.assert(wm.has(Object.prototype));
console.assert(wm.get(Object.prototype)!.length === 1);
console.assert(wm.has(IterableWeakMap.prototype));
console.assert(wm.get(IterableWeakMap.prototype)!.length === 2);
console.log(wm.get(IterableWeakMap));
// [
// [
// [class IterableWeakMap],
// [undefined, { type: "class", static: true }],
// ],
// [
// [class IterableWeakMap],
// ["groupBy", { type: "method", static: true }],
// ],
// ]
console.log(wm.get(Object.prototype));
// [
// [
// [Function: Object],
// ["toString", { type: "method", native: true }],
// ],
// ]
console.log(wm.get(IterableWeakMap.prototype));
// [
// [
// [IterableWeakMap],
// ["has", { type: "method" }],
// ],
// [
// [IterableWeakMap],
// ["set", { type: "method" }],
// ],
// ]
```
---
## Further Reading
⚠️ Important differences between this and WeakMap
It is important to note that this class is _not_ a subclass of a native
`WeakMap` instance, and as such it does not satisfy any `instanceof` checks or
type comparisons against the native `WeakMap` constructor function.
Instead, this is a standalone class that uses several advanced native APIs to
provide an interface that feels and behaves much like a standard Map on the
surface, while maintaining the same [ephemeral] nature of a standard `WeakMap`
underneath. See the section on [weak iteration](#what-is-weak-iteration) and
[how it all works](#hows-it-all-work) for more information on this.
Garbage Collection and Predictability
Garbage Collection (GC) is the process by which the JavaScript runtime reclaims
memory that is no longer in use by the program. This is done automatically by
the runtime, and is not something that can typically be controlled by the
developer.
The GC engine in JavaScript runtimes is designed to be non-deterministic, such
that the timing of an object's lifecycle is not something one can predict. This
is a fundamental design characteristic (and frequent pain point) of the GC
engine in JavaScript runtimes, and not a problem unique to [`IterableWeakMap`].
What is "Weak Iteration"?
I coined the term "weak iteration" _(at least, I think I did)_ to
describe the concept of inspecting, iterating, and/or serializing entries of
[`WeakMap`] and [`WeakSet`] collections.
The concept of _"Weak Iteration"_ is not one that exists natively in the
JavaScript language. The `WeakMap` and `WeakSet` collections are intended to be
**opaque** and **non-introspectable**, which is precisely why they work so well
for storing private metadata, or associating data that only matters as long as a
particular object is still usable, without running the risk of leaks.
However, many developers (including yours truly) have found that a use cas does
exist for having another, iterable version of these weak collections. And so,
drawing inspiration from the example in the [TC39 WeakRef Proposal], I created
this package in an attempt to bridge that gap.
How's it all work?
To attempt to mitigate this unpredictability, this package utilizes these APIs:
- [x] [`WeakMap`]: stores weakly-held keys and their corresponding `WeakRef`
objects, ensuring they are GC'd in a predictable manner.
- [x] [`WeakRef`]: weakly-held references to the original weak key. Stored in
the internal `WeakMap` (along with the original value), as well as an
internal `Set` (that we leverage to allow [weak iteration]).
- [x] [`FinalizationRegistry`]: for tracking individual object's lifecycles and
GC state; allows us to remove stale entries as soon as they're GC'd.
#### Caveats
This concept of weak iteration is inherently non-deterministic. This is
primarily due to the complex and finicky nature of garbage collection as it is
implemented in most JavaScript runtimes.
While this package has shown itself to be stable and quite reliable in testing,
it is important to remember a garbage collector is basically a "black box". It
can behave in unexpected ways, and so it should be treated as if it will.
##### A Word of Caution
I highly recommend reading the [TC39 WeakRef Proposal] README. It contains a
well-written explanation of the garbage collection (GC), the pitfalls involved
in working with it, and also a helpful [word of warning][tc39-proposal-warning]
for users of packages like this.
Footnotes and References
1. Values are considered "living" if they have not been garbage-collected, and
any weak references to them resolve to a non-nullable WeakKey value.
2. `WeakKey` types are object-like values (objects, arrays, and functions), as
well as _non_-registered symbols (a registered symbol is one that is created
with `Symbol.for`). If your runtime is using a version older than ES2023,
this is limited to `object` types, as support for `symbol` keys is a
[more recent addition][tc39-proposal-symbols].
3. Garbage Collection (GC) is the process by which the JavaScript runtime
reclaims memory that is no longer in use by the program. This is done
automatically by the runtime, and is not something that can typically be
controlled by the developer. V8 does provide an `--expose-gc` flag that
exposes a global `gc()` function that manually triggers the GC; but that
should only be used for testing and debugging.
4. While regular Map objects have no restrictions on the values you use for keys
or values, WeakMap objects require that all keys either be objects (which
includes functions, arrays, and other object-like values), or non-registered
symbols (those not created via `Symbol.for`, supported in ES2023+). The same
restrictions apply to the keys in the `IterableWeakMap` class.
5. The performance benefits of using a `WeakMap` over a `Map` are primarily
related to memory management. Since the keys in a `WeakMap` are weakly held,
they can be garbage-collected if there are no other references to them, which
also means their associated values can be garbage-collected as well. This
makes `WeakMap` objects ideal for storing private data or metadata that is
only relevant as long as the related key is still in use.
6. See the [section on weak iteration](#what-is-weak-iteration) for more info.
> [!WARNING]
>
> While this package _can_ be used as a drop-in replacement for `WeakMap`, it's
> important to have discretion when using it. **Do not** use this package for
> any critical or privacy-sensitive data, as its design breaks the fundamental
> principles of the `WeakMap` API.
>
> Unlike its native counterpart, this package is inherently observable (that's
> the whole point of it), and so the data you store in it _can_ be exposed to
> the outside world. Its primary use case is for debugging and testing, not for
> production code or sensitive data.
---
][jsr]
```sh
npx jsr add @iter/weak-map
```
[
][bun]
```sh
bunx jsr add @iter/weak-map
```
[
][pnpm]
```sh
pnpm dlx jsr add @iter/weak-map
```
[
][yarn]
```sh
yarn dlx jsr add @iter/weak-map
```
## Usage
```ts
import { IterableWeakMap } from "@iter/weak-map";
const map = new IterableWeakMap([
[{ k: 1 }, "value1"],
[{ k: 2 }, "value2"],
]);
// oh no, we have no references to the keys!
map.get([...map.keys()][0]); // => "value1"
console.log([...map]); // => [[{ k: 1 }, "value1"], [{ k: 2 }, "value2"]]
// later on, after the keys are garbage-collected...
console.log([...map]); // => []
```
---
## API
> **Implements**: `WeakMap
```ts ignore
get size(): number;
```
#### Returns
The number of living values in the map.
---
### `clear` 
```ts ignore
clear(): void;
```
Clears all key-value pairs from the map.
#### Examples
```ts
import { IterableWeakMap } from "@iter/weak-map";
const map = new IterableWeakMap([
[{ k: 1 }, "value1"],
[{ k: 2 }, "value2"],
]);
map.size; // => 2
map.clear();
map.size; // => 0
```
---
### `delete` 
```ts ignore
*keys(): IterableIterator
```ts ignore
static groupBy