shelving/util/dictionarymodule

Typed helpers for working with { [key: string]: T } objects — called dictionaries to distinguish them from the more permissive Data type. Mirrors the naming conventions of the array and object helpers: with* for immutable updates, set*/delete* for mutable by-reference mutations.

Usage

Type guards and conversion

ts
import { isDictionary, assertDictionary, requireDictionary } from "shelving/util";

isDictionary({ a: 1 });  // true
isDictionary(new Map()); // false

// Convert an iterable of entries to a dictionary:
requireDictionary([["a", 1], ["b", 2]]); // { a: 1, b: 2 }
requireDictionary({ a: 1 });             // { a: 1 }  (already a dictionary)

Reading items

ts
import { getDictionaryItem, requireDictionaryItem, isDictionaryItem, getDictionaryItems } from "shelving/util";

const dict = { uk: "London", fr: "Paris" };

getDictionaryItem(dict, "uk");      // "London"
getDictionaryItem(dict, "de");      // undefined
requireDictionaryItem(dict, "uk");  // "London"
requireDictionaryItem(dict, "de");  // throws RequiredError

isDictionaryItem(dict, "fr");       // true
getDictionaryItems(dict);           // [["uk", "London"], ["fr", "Paris"]]

Immutable updates

ts
import { withDictionaryItem, withDictionaryItems, omitDictionaryItem, omitDictionaryItems, pickDictionaryItems } from "shelving/util";

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

withDictionaryItem(dict, "d", 4);            // { a:1, b:2, c:3, d:4 }
withDictionaryItems(dict, { b: 99, d: 4 }); // { a:1, b:99, c:3, d:4 }
omitDictionaryItem(dict, "b");               // { a:1, c:3 }
omitDictionaryItems(dict, "a", "c");         // { b:2 }
pickDictionaryItems(dict, "a", "c");         // { a:1, c:3 }

Mutable updates (by reference)

ts
import { setDictionaryItem, setDictionaryItems, deleteDictionaryItem, deleteDictionaryItems } from "shelving/util";

const dict: MutableDictionary<number> = { a: 1, b: 2 };

setDictionaryItem(dict, "c", 3);          // dict is now { a:1, b:2, c:3 }
setDictionaryItems(dict, { d: 4 });       // dict is now { a:1, b:2, c:3, d:4 }
deleteDictionaryItem(dict, "a");          // dict is now { b:2, c:3, d:4 }
deleteDictionaryItems(dict, "b", "c");    // dict is now { d:4 }

Functions

Go

isDictionary()function

Is an unknown value a dictionary object?

isDictionary(value: unknown): value is ImmutableDictionary
Go

assertDictionary()function

Assert that an unknown value is a dictionary object.

assertDictionary(value: unknown, caller: AnyCaller = assertDictionary): asserts value is ImmutableDictionary
Go

requireDictionary()function

Convert a possible dictionary into a dictionary.

requireDictionary(dict: PossibleDictionary<T>): ImmutableDictionary<T>
Go

getDictionaryItems()function

Turn a dictionary object into a set of props.

getDictionaryItems(input: ImmutableDictionary<T>): readonly DictionaryItem<T>[]
getDictionaryItems(input: PossibleDictionary<T>): Iterable<DictionaryItem<T>>
Go

isDictionaryItem()function

Is an unknown value the key for an own prop of a dictionary.

isDictionaryItem(dict: ImmutableDictionary<T>, key: unknown): key is string
Go

assertDictionaryItem()function

Assert that an unknown value is the key for an own prop of a dictionary.

assertDictionaryItem(dict: ImmutableDictionary<T>, key: string, caller: AnyCaller = assertDictionaryItem): asserts key is string
Go

requireDictionaryItem()function

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

requireDictionaryItem(dict: ImmutableDictionary<T>, key: string, caller: AnyCaller = requireDictionaryItem): T
Go

getDictionaryItem()function

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

getDictionaryItem(dict: ImmutableDictionary<T>, key: string): T | undefined

Types

Go

ImmutableDictionarytype

Readonly dictionary object.

{ readonly [K in string]: T }
Go

MutableDictionarytype

Writable dictionary object.

{ [K in string]: T }
Go

DictionaryItemtype

Single item for a dictionary object in entry format.

readonly [string, T]
Go

DictionaryValuetype

Get the type of the values of the items of a dictionary object.

T[string]
Go

PossibleDictionarytype

Value that can be converted to a dictionary object.

ImmutableDictionary<T> | Iterable<DictionaryItem<T>>
Go

EmptyDictionarytype

Type that represents an empty dictionary object.

{ readonly [K in never]: never }

Constants

Go

withDictionaryItemconstant

Set an item on a dictionary object (immutably) and return a new object including that item.

withDictionaryItem: <T>(dict: ImmutableDictionary<T>, key: string, value: T) => ImmutableDictionary<T>
Go

withDictionaryItemsconstant

Set several items on a dictionary object (immutably) and return a new object including those items.

withDictionaryItems: <T>(dict: ImmutableDictionary<T>, props: PossibleDictionary<T>) => ImmutableDictionary<T>
Go

omitDictionaryItemsconstant

Remove several items from a dictionary object (immutably) and return a new object without those items.

omitDictionaryItems: <T>(dict: ImmutableDictionary<T>, ...keys: string[]) => ImmutableDictionary<T>
Go

omitDictionaryItemconstant

Remove an item from a dictionary object (immutably) and return a new object without that item.

omitDictionaryItem: <T>(dict: ImmutableDictionary<T>, key: string) => ImmutableDictionary<T>
Go

pickDictionaryItemsconstant

Pick several items from a dictionary object and return a new object with only those items.

pickDictionaryItems: <T>(dict: ImmutableDictionary<T>, ...keys: string[]) => ImmutableDictionary<T>
Go

setDictionaryItemconstant

Set a single named item on a dictionary object (by reference) and return its value.

setDictionaryItem: <T>(dict: MutableDictionary<T>, key: string, value: T) => T
Go

setDictionaryItemsconstant

Set several named items on a dictionary object (by reference).

setDictionaryItems: <T>(dict: MutableDictionary<T>, entries: PossibleDictionary<T>) => void
Go

deleteDictionaryItemsconstant

Remove several key/value entries from a dictionary object (by reference).

deleteDictionaryItems: <T extends MutableDictionary>(dict: T, ...keys: string[]) => void
Go

deleteDictionaryItemconstant

Remove a key/value entry from a dictionary object (by reference).

deleteDictionaryItem: <T extends MutableDictionary>(dict: T, key: string) => void
Go

EMPTY_DICTIONARYconstant

An empty dictionary object.

EMPTY_DICTIONARY: EmptyDictionary