shelving/util/dictionary.d.ts

Toolkit for using data in JavaScript.

import type { AnyCaller } from "./function.js";
/** Readonly dictionary object. */
export type ImmutableDictionary<T = unknown> = {
    readonly [K in string]: T;
};
/** Writable dictionary object. */
export type MutableDictionary<T = unknown> = {
    [K in string]: T;
};
/** Single item for a dictionary object in entry format. */
export type DictionaryItem<T> = readonly [string, T];
/** Get the type of the _values_ of the items of a dictionary object. */
export type DictionaryValue<T extends ImmutableDictionary> = T[string];
/** Value that can be converted to a dictionary object. */
export type PossibleDictionary<T> = ImmutableDictionary<T> | Iterable<DictionaryItem<T>>;
/** Is an unknown value a dictionary object? */
export declare function isDictionary(value: unknown): value is ImmutableDictionary;
/** Assert that an unknown value is a dictionary object */
export declare function assertDictionary(value: unknown, caller?: AnyCaller): asserts value is ImmutableDictionary;
/** Convert a possible dictionary into a dictionary. */
export declare function getDictionary<T>(dict: PossibleDictionary<T>): ImmutableDictionary<T>;
/** Turn a dictionary object into a set of props. */
export declare function getDictionaryItems<T>(input: ImmutableDictionary<T>): readonly DictionaryItem<T>[];
export declare function getDictionaryItems<T>(input: PossibleDictionary<T>): Iterable<DictionaryItem<T>>;
/** Is an unknown value the key for an own prop of a dictionary. */
export declare function isDictionaryItem<T>(dict: ImmutableDictionary<T>, key: unknown): key is string;
/** Assert that an unknown value is the key for an own prop of a dictionary. */
export declare function assertDictionaryItem<T>(dict: ImmutableDictionary<T>, key: string, caller?: AnyCaller): asserts key is string;
/** Get an item in a map or throw `RequiredError` if it doesn't exist. */
export declare function requireDictionaryItem<T>(dict: ImmutableDictionary<T>, key: string, caller?: AnyCaller): T;
/** Get an item in a map or `undefined` if it doesn't exist. */
export declare function getDictionaryItem<T>(dict: ImmutableDictionary<T>, key: string): T | undefined;
/** Set a prop on a dictionary object (immutably) and return a new object including that prop. */
export declare const withDictionaryItem: <T>(dict: ImmutableDictionary<T>, key: string, value: T) => ImmutableDictionary<T>;
/** Set several props on a dictionary object (immutably) and return a new object including those props. */
export declare const withDictionaryItems: <T>(dict: ImmutableDictionary<T>, props: PossibleDictionary<T>) => ImmutableDictionary<T>;
/** Remove several key/value entries from a dictionary object (immutably) and return a new object without those props. */
export declare const omitDictionaryItems: <T>(dict: ImmutableDictionary<T>, ...keys: string[]) => ImmutableDictionary<T>;
/** Remove a key/value entry from a dictionary object (immutably) and return a new object without that prop. */
export declare const omitDictionaryItem: <T>(dict: ImmutableDictionary<T>, key: string) => ImmutableDictionary<T>;
/** Pick several props from a dictionary object and return a new object with only thos props. */
export declare const pickDictionaryItems: <T>(dict: ImmutableDictionary<T>, ...keys: string[]) => ImmutableDictionary<T>;
/** Set a single named prop on a dictionary object (by reference) and return its value. */
export declare const setDictionaryItem: <T>(dict: MutableDictionary<T>, key: string, value: T) => T;
/** Set several named props on a dictionary object (by reference). */
export declare const setDictionaryItems: <T>(dict: MutableDictionary<T>, entries: PossibleDictionary<T>) => void;
/** Remove several key/value entries from a dictionary object (by reference). */
export declare const deleteDictionaryItems: <T extends MutableDictionary>(dict: T, ...keys: string[]) => void;
/** Remove a key/value entry from a dictionary object (by reference). */
export declare const deleteDictionaryItem: <T extends MutableDictionary>(dict: T, key: string) => void;
/** Type that represents an empty dictionary object. */
export type EmptyDictionary = {
    readonly [K in never]: never;
};
/** An empty dictionary object. */
export declare const EMPTY_DICTIONARY: EmptyDictionary;