js-map-of-sets

name	js-map-of-sets
description	Use the MapOfSets data structure when you need a Map that stores multiple unique values per key (a Map<K, Set<V>>). Handles adding, removing, querying, and iterating over grouped unique values without manual Set management. Use when the user needs to group items by key without duplicates, implement a multimap, track relationships like tags-to-items or events-to-listeners, or replace a plain Map<K, T[]> where uniqueness matters.
license	MIT
metadata	{"author":"burdiuz","package":"@actualwave/map-of-sets"}

Overview

MapOfSets wraps a Map<K, Set<V>> and manages Set creation/cleanup automatically. Each key maps to a deduplicated set of values. When the last value under a key is removed, the key is also removed.

Installation

npm install @actualwave/map-of-sets

Basic usage

import MapOfSets, { createMapOfSets } from '@actualwave/map-of-sets';

// class instantiation
const map = new MapOfSets<string, number>();

// factory function
const map2 = createMapOfSets<string, number>();

map.add('even', 2);
map.add('even', 4);
map.add('even', 2); // duplicate — ignored

map.has('even');          // true
map.hasValue('even', 4);  // true
map.get('even');          // Set { 2, 4 }
map.list('even');         // [2, 4]

API

has(key: K): boolean
// Returns true if key exists and its Set is non-empty.

hasValue(key: K, value: V): boolean
// Returns true if value exists under key.

get(key: K): Set<V> | undefined
// Returns the raw Set for key, or undefined.

list(key: K): V[]
// Returns values as an array, or [] if key is missing.

add(key: K, value: V): void
// Adds value to key's Set; creates the Set if the key is new.

set(key: K, values: Set<V> | V[]): void
// Replaces all values for key. Removes the key if values is empty.

remove(key: K): void
// Removes the key and all its values.

removeValue(key: K, value: V): void
// Removes one value; removes the key if the Set becomes empty.

forEach(callback: (value: V, key: K, map: MapOfSets<K, V>) => void): void
// Iterates over every value of every key.

eachValue(key: K, callback: (value: V, key: K, map: MapOfSets<K, V>) => void): void
// Iterates over every value of a specific key.

clone(): MapOfSets<K, V>
// Returns a deep, independent copy.

Common patterns

Accumulate items by category:

const byTag = new MapOfSets<string, string>();
items.forEach(item => item.tags.forEach(tag => byTag.add(tag, item.id)));

Remove a relationship and check if the key is still active:

listeners.removeValue(event, handler);
if (!listeners.has(event)) cleanup(event);

Snapshot and restore:

const snapshot = map.clone();
// ... mutate map ...
// snapshot is unaffected

Edge cases

• set(key, []) and set(key, new Set()) both remove the key entirely.
• removeValue on a missing key or missing value is a safe no-op.
• forEach and eachValue do nothing on an empty map or missing key.
• clone produces independent copies — mutations to either side do not affect the other.