shelving/util/map.d.ts

Toolkit for using data in JavaScript.

import type { Entry } from "./entry.js";
import type { AnyCaller } from "./function.js";
/** `Map` that cannot be changed. */
export type ImmutableMap<K = unknown, T = unknown> = ReadonlyMap<K, T>;
/** Class for a `Map` that cannot be changed (so you can extend `Map` while implementing `ImmutableMap`). */
export declare const ImmutableMap: {
    new <K, T>(...params: ConstructorParameters<typeof Map<K, T>>): ImmutableMap<K, T>;
};
/** `Map` that can be changed. */
export type MutableMap<K = unknown, T = unknown> = Map<K, T>;
/** Extract the type for the value of a map. */
export type MapKey<X> = X extends ReadonlyMap<infer Y, unknown> ? Y : never;
/** Extract the type for the value of a map. */
export type MapValue<X> = X extends ReadonlyMap<unknown, infer Y> ? Y : never;
/** Get the type for an item of a map in entry format. */
export type MapItem<T extends ImmutableMap> = readonly [MapKey<T>, MapValue<T>];
/** Things that can be converted to maps. */
export type PossibleMap<K, T> = ImmutableMap<K, T> | Iterable<Entry<K, T>>;
/** Things that can be converted to maps with string keys. */
export type PossibleStringMap<K extends string, T> = PossibleMap<K, T> | {
    readonly [KK in K]: T;
};
/** Is an unknown value a map? */
export declare function isMap(value: unknown): value is ImmutableMap;
/** Assert that a value is a `Map` instance. */
export declare function assertMap(value: unknown, caller?: AnyCaller): asserts value is ImmutableMap;
/** Convert an iterable to a `Map` (if it's already a `Map` it passes through unchanged). */
export declare function getMap<K extends string, T>(input: PossibleStringMap<K, T>): ImmutableMap<K, T>;
export declare function getMap<K, T>(input: PossibleMap<K, T>): ImmutableMap<K, T>;
/** Apply a limit to a map. */
export declare function limitMap<T>(map: ImmutableMap<T>, limit: number): ImmutableMap<T>;
/** Is an unknown value a key for an item in a map? */
export declare function isMapItem<K, V>(map: ImmutableMap<K, V>, key: unknown): key is K;
/** Assert that an unknown value is a key for an item in a map. */
export declare function assertMapItem<K, V>(map: ImmutableMap<K, V>, key: unknown, caller?: AnyCaller): asserts key is K;
/** Function that lets new items in a map be created and updated by calling a `reduce()` callback that receives the existing value. */
export declare function setMapItem<K, T>(map: MutableMap<K, T>, key: K, value: T): T;
/** Add multiple items to a set (by reference). */
export declare function setMapItems<K, T>(map: MutableMap<K, T>, items: Iterable<MapItem<ImmutableMap<K, T>>>): void;
/** Remove multiple items from a set (by reference). */
export declare function removeMapItems<K, T>(map: MutableMap<K, T>, ...keys: K[]): void;
/** Get an item in a map, or `undefined` if it doesn't exist. */
export declare function getMapItem<K, T>(map: ImmutableMap<K, T>, key: K): T | undefined;
/** Get an item in a map, or throw `RequiredError` if it doesn't exist. */
export declare function requireMapItem<K, T>(map: ImmutableMap<K, T>, key: K, caller?: AnyCaller): T;