# weakermap

> A WeakerMap is an enumerable Map with with weak values rather than keys

Latest version **0.0.13** (published 2026-08-17) · Apache 2.0 license · 0 weekly downloads

## Install

```sh
npm install weakermap
pnpm add weakermap
yarn add weakermap
bun add weakermap
```

## Health

**Score 55/100 (C)** — status: active.

Positive: no vulnerabilities; recently updated; high maintenance score.

Warnings: low downloads; no types; no esm support; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.0.13 |
| Published | 2026-08-17 |
| First published | 2023-03-19 |
| Weekly downloads | 0 |
| License | Apache 2.0 |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 21.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Sean Morris |
| Maintainers | seanmorris |

## Links

- npm: https://www.npmjs.com/package/weakermap
- Repository: https://github.com/seanmorris/Weaker
- Homepage: https://github.com/seanmorris/Weaker#readme
- Issues: https://github.com/seanmorris/Weaker/issues
- npm.io page: https://npm.io/package/weakermap

## Recent versions

- 0.0.13 (latest) — 2026-08-17
- 0.0.4 (alpha) — 2024-08-22
- 0.0.12 — 2026-08-17
- 0.0.11 — 2025-10-14
- 0.0.10 — 2024-09-20
- 0.0.9 — 2024-09-18
- 0.0.8 — 2024-08-25
- 0.0.7 — 2024-08-25
- 0.0.6 — 2024-08-22
- 0.0.5 — 2024-08-22
- 0.0.3 — 2023-03-20
- 0.0.2 — 2023-03-20
- 0.0.1 — 2023-03-20
- 0.0.0 — 2023-03-19

## README

# WeakerMap

[![CI test status](https://github.com/seanmorris/weaker/actions/workflows/test.yaml/badge.svg)](https://github.com/seanmorris/Weaker/actions)

*A WeakerMap is an enumerable Map with weak values rather than keys.*

This class implements a pattern similar to the 'WeakMap', however its *values* are weakly referenced, rather than the keys. This allows for enumeration, clearing and arbitrarily valued keys, with the limitation that the *values* must be objects. Note that elements may not be garbage collected immediately upon leaving a given scope, however this should not have an impact on memory, since the memory will not be freed until the garbage collector runs, with or without the `WeakerMap`. See [MDN's notes on WeakRefs](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WeakRef#notes_on_weakrefs) for more info.

<!-- ### I am giving up my bed for one night.
> My Sleep Out helps youth facing homelessness find safe shelter and loving care at Covenant House. That care includes essential services like education, job training, medical care, mental health and substance use counseling, and legal aid — everything they need to build independent, sustainable futures.
>
> By supporting my Sleep Out, you are supporting the dreams of young people overcoming homelessness.
>
> <a href = "https://www.sleepout.org/participants/62915"><img width = "50%" alt="Donate to Covenant House" src="https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fwww.sleepout.org%2Fapi%2F1.3%2Fparticipants%2F62915%3F_%3D1760039017428&query=%24.sumDonations&prefix=%24&suffix=%20Raised&style=for-the-badge&label=Sleep%20Out%3A%20NYC&link=https%3A%2F%2Fwww.sleepout.org%2Fparticipants%2F62915"></a>
>
> Click here to help out: https://www.sleepout.org/participants/62915
>
> More info: https://www.sleepout.org/ | https://www.covenanthouse.org/ | https://www.charitynavigator.org/ein/132725416
>
> Together, we are working towards a future where every young person has a safe place to sleep.
>
> Thank you.
>
> and now back to your documentation... -->

## Install
```bash
npm install weakermap
```

```javascript
import { WeakerMap } from 'weakermap';
```

## Methods

### WeakerMap.construct(entries)
Create a new `WeakerMap` object, optionally prepopulated by `entries`, similar to the [standard Map constructor](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map/Map#examples).

#### Parameters
* `entries` - An iterable list of `[key, value]` pairs to add to the map.

#### Returns
A newly constructed `WeakerMap` object.

```javascript
const values = [
    ['x', {a: 1}],
    ['y', {b: 2}],
    ['z', {c: 3}],
];

const wm = new WeakerMap(values);
```

You can call `Object.entries()` to get such a list, given an object:

```javascript
const wm = new WeakerMap(Object.entries({
    x: {a: 1},
    y: {b: 2},
    z: {c: 3},
}));
```

### \[Symbol.iterator]()
Traverse the entries.

#### Parameters
*none*

#### Returns
A new Iterator that traverses the `WeakerMap`.

```javascript
const wm = new WeakerMap(Object.entries({
    x: {a: 1},
    y: {b: 2},
    z: {c: 3},
}));

for(const [key, value] of wm)
{
    console.log({key, value});
}
// { key: 'x', value: { a: 1 } }
// { key: 'y', value: { b: 2 } }
// { key: 'z', value: { c: 3 } }
```

```javascript
const wm = new WeakerMap(Object.entries({x: {a: 1}, y: {b: 2}, z: {c: 3}}));
const ar = [...wm];
console.log(ar);
// [
//    [ 'x', { a: 1 } ],
//    [ 'y', { b: 2 } ],
//    [ 'z', { c: 3 } ]
// ]
```

```javascript
const wm = new WeakerMap(Object.entries({x: {a: 1}, y: {b: 2}, z: {c: 3}}));

[...wm].map( ( [key, value] ) => console.log( {key, value} ));

// { key: 'x', value: { a: 1 } }
// { key: 'y', value: { b: 2 } }
// { key: 'z', value: { c: 3 } }
```

### WeakerMap.clear()
Clear all entries.

#### Parameters
*none*

#### Returns
*none*

```javascript
const wm = new WeakerMap(Object.entries({x: {a: 1}, y: {b: 2}, z: {c: 3}}));

wm.clear();

console.log(wm.size) // 0
```

### WeakerMap.delete(key)
Delete a key.

#### Parameters
* `key` - The key to delete from the map.

#### Returns
*none*

```javascript
const wm = new WeakerMap(Object.entries({x: {a: 1}, y: {b: 2}, z: {c: 3}}));

wm.delete('y');
```

### WeakerMap.entries()
Traverse all entries.

#### Parameters
*none*

#### Returns
A new Iterator that traverses the `WeakerMap`.

```javascript
const wm = new WeakerMap(Object.entries({x: {a: 1}, y: {b: 2}, z: {c: 3}}));

for(const [key, value] of wm.entries())
{
    console.log({key, value});
}
// { key: 'x', value: { a: 1 } }
// { key: 'y', value: { b: 2 } }
// { key: 'z', value: { c: 3 } }
```

### WeakerMap.forEach(callback)
Traverse all entries with a callback.

#### Parameters
* `callback` - a function to run on each entry. Parameters are `(value, key, map)`.

#### Returns
*none*

```javascript
const wm = new WeakerMap(Object.entries({x: {a: 1}, y: {b: 2}, z: {c: 3}}));

wm.forEach((value, key, map) => {
    console.log({value, key});
});
// { value: { a: 1 }, key: 'x' }
// { value: { b: 2 }, key: 'y' }
// { value: { c: 3 }, key: 'z' }
```

### WeakerMap.get(key)
Get the value for a key.

#### Parameters
* `key` - The key to look up in the map.

#### Returns
The object found at `key`, or `undefined` if not found.

```javascript
const wm = new WeakerMap(Object.entries({x: {a: 1}, y: {b: 2}, z: {c: 3}}));

console.log( wm.get('x') ); // {a:1}
```

### WeakerMap.has(key)
Check for the presence of a key.

#### Parameters
* `key` - The key to look up in the map.

#### Returns
`true` if the object at `key` is present, or `false` if not found.

```javascript
const wm = new WeakerMap(Object.entries({x: {a: 1}, y: {b: 2}, z: {c: 3}}));

console.log( wm.has('x') ); // true
console.log( wm.has('g') ); // false
```

### WeakerMap.keys()
Traverse all keys.

#### Parameters
*none*

#### Returns
A new Iterator that traverses the keys of the `WeakerMap`.

```javascript
const wm = new WeakerMap(Object.entries({x: {a: 1}, y: {b: 2}, z: {c: 3}}));

for(const key of wm.keys())
{
    console.log(key);
}
// x
// y
// z
```

### WeakerMap.set(key, value)
Set a key.

#### Parameters
* `key` - The key to set in the map.
* `value` - The value to set in the map.

#### Returns
*none*

```javascript
const wm = new WeakerMap;

wm.set('x', {a:1});
```

### WeakerMap.values()
Traverse all values.

#### Parameters
*none*

#### Returns
A new Iterator that traverses the values of the `WeakerMap`.

```javascript
const wm = new WeakerMap(Object.entries({x: {a: 1}, y: {b: 2}, z: {c: 3}}));

for(const value of wm.values())
{
    console.log(value);
}
// {a:1}
// {b:2}
// {c:3}
```

## Example
A `WeakerMap` will only hold onto its values as long as they aren't garbage collected. Once that happens, they will be removed without any further intervention from the programmer.

⚠️ *NOTE* ⚠️: The following example makes use of `global.gc()` to force garbage collection to run regardless of existing heuristics. This requires node to be run with the `--expose-gc` flag. This is not necessary except to demonstrate the behavior in a short script, where the garbage collector would not normally run until the program exits.

```javascript
import { WeakerMap } from 'weakermap';

const wm = new WeakerMap;
const retain = []; // This will hold refs in-scope and prevent garbage collection.

{
    let a = {a:1}, b = {b:2}, c = {c:3};

    [['a', a], ['b', b], ['c', c]].forEach(e => wm.set(...e));

    retain.push(b, c);
};

const printRemaining = () => {
    retain;       // keep some refs in this-scope as well.
    global.gc();  // force the garbage collector
    console.log([...wm.values()])
};

printRemaining();
// The garbage collector hasn't run yet,
// so we still have all three refs
// [ { a: 1 }, { b: 2 }, { c: 3 } ]

setTimeout(printRemaining, 500);
// Once we swap to a new 'job', it can run
// and we only have two objects now
// [ { b: 2 }, { c: 3 } ]
```

# 🍻 Licensed under the Apache License, Version 2.0

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

[http://www.apache.org/licenses/LICENSE-2.0](http://www.apache.org/licenses/LICENSE-2.0)

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

---
_Source: https://npm.io/package/weakermap · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._