shelving/util/mapmodule

Type definitions and helper functions for working with Map instances. Covers type guards, conversions from plain objects or iterables, mutable set/remove operations, and safe key lookups.

Things to know:

Usage

Type guards and conversion

ts
import { isMap, assertMap, getMap } from "shelving/util";

isMap(new Map());           // true
isMap({});                  // false

// Convert a plain object or iterable of entries to a Map.
const m = getMap({ a: 1, b: 2 });
// Map { "a" => 1, "b" => 2 }

getMap(m); // same reference — no copy

Reading items

ts
import { getMapItem, requireMapItem, isMapItem, assertMapItem } from "shelving/util";

const scores = new Map([["alice", 42], ["bob", 7]]);

getMapItem(scores, "alice");    // 42
getMapItem(scores, "carol");    // undefined

requireMapItem(scores, "alice");  // 42
requireMapItem(scores, "carol");  // throws RequiredError

isMapItem(scores, "bob");       // true

Mutating maps

ts
import { setMapItem, setMapItems, removeMapItems } from "shelving/util";

const m: Map<string, number> = new Map();

setMapItem(m, "x", 10);                           // sets "x" → 10, returns 10
setMapItems(m, [["y", 20], ["z", 30]]);            // bulk set
removeMapItems(m, "x", "y");                       // removes "x" and "y"

Limiting size

ts
import { limitMap } from "shelving/util";

const limited = limitMap(bigMap, 100); // at most 100 entries

Functions

Go

isMap()function

Is an unknown value a map?

isMap(value: unknown): value is ImmutableMap
Go

assertMap()function

Assert that a value is a Map instance.

assertMap(value: unknown, caller: AnyCaller = assertMap): asserts value is ImmutableMap
Go

getMap()function

Convert an iterable to a Map (if it's already a Map it passes through unchanged).

getMap(input: PossibleStringMap<K, T>): ImmutableMap<K, T>
getMap(input: PossibleMap<K, T>): ImmutableMap<K, T>
Go

limitMap()function

Apply a limit to a map.

limitMap(map: ImmutableMap<T>, limit: number): ImmutableMap<T>
Go

isMapItem()function

Is an unknown value a key for an item in a map?

isMapItem(map: ImmutableMap<K, V>, key: unknown): key is K
Go

assertMapItem()function

Assert that an unknown value is a key for an item in a map.

assertMapItem(map: ImmutableMap<K, V>, key: unknown, caller: AnyCaller = assertMapItem): asserts key is K
Go

setMapItem()function

Set an item in a map (by reference) and return the value that was set.

setMapItem(map: MutableMap<K, T>, key: K, value: T): T
Go

setMapItems()function

Add multiple items to a map (by reference).

setMapItems(map: MutableMap<K, T>, items: Iterable<MapItem<ImmutableMap<K, T>>>): void
Go

removeMapItems()function

Remove multiple items from a map (by reference).

removeMapItems(map: MutableMap<K, T>, ...keys: K[]): void
Go

getMapItem()function

Get an item in a map, or undefined if it doesn't exist.

getMapItem(map: ImmutableMap<K, T>, key: K): T | undefined
Go

requireMapItem()function

Get an item in a map, or throw RequiredError if it doesn't exist.

requireMapItem(map: ImmutableMap<K, T>, key: K, caller: AnyCaller = requireMapItem): T

Types

Go

ImmutableMaptype

Map that cannot be changed.

ReadonlyMap<K, T>
ImmutableMap: { new <K, T>(...params: ConstructorParameters<typeof Map<K, T>>): ImmutableMap<K, T> }
Go

MutableMaptype

Map that can be changed.

Map<K, T>
Go

MapKeytype

Extract the type for the key of a map.

X extends ReadonlyMap<infer Y, unknown> ? Y : never
Go

MapValuetype

Extract the type for the value of a map.

X extends ReadonlyMap<unknown, infer Y> ? Y : never
Go

MapItemtype

Get the type for an item of a map in entry format.

readonly [MapKey<T>, MapValue<T>]
Go

PossibleMaptype

Things that can be converted to maps.

ImmutableMap<K, T> | Iterable<Entry<K, T>>
Go

PossibleStringMaptype

Things that can be converted to maps with string keys.

PossibleMap<K, T> | { readonly [KK in K]: T }