shelving/util/array.d.ts

Toolkit for using data in JavaScript.

import type { AnyCaller } from "./function.js";
/**
 * Mutable array: an array that can be changed.
 * - Consistency with `MutableObject<T>` and `ImmutableArray<T>`
 */
export type MutableArray<T = unknown> = T[];
/**
 * Immutable array: an array that cannot be changed.
 * - Consistency with `ImmutableObject<T>` and `MutableArray<T>`
 */
export type ImmutableArray<T = unknown> = readonly T[];
/** Get the type of the _items_ in an array. */
export type ArrayItem<T extends ImmutableArray> = T[number];
/** Things that can be converted to arrays. */
export type PossibleArray<T> = ImmutableArray<T> | Iterable<T>;
/** Is an unknown value an array (optionally with specified min/max length). */
export declare function isArray<T>(arr: MutableArray<T>, min: 1, max: 1): arr is [T];
export declare function isArray<T>(arr: MutableArray<T>, min: 2, max: 2): arr is [T, T];
export declare function isArray<T>(arr: MutableArray<T>, min: 3, max: 3): arr is [T, T, T];
export declare function isArray<T>(arr: MutableArray<T>, min?: 1, max?: number): arr is [T, ...T[]];
export declare function isArray<T>(arr: MutableArray<T>, min: 2, max?: number): arr is [T, T, ...T[]];
export declare function isArray<T>(arr: MutableArray<T>, min: 3, max?: number): arr is [T, T, T, ...T[]];
export declare function isArray<T>(arr: MutableArray<T>, min?: number, max?: number): arr is MutableArray<T>;
export declare function isArray<T>(arr: ImmutableArray<T>, min: 1, max: 1): arr is readonly [T];
export declare function isArray<T>(arr: ImmutableArray<T>, min: 2, max: 2): arr is readonly [T, T];
export declare function isArray<T>(arr: ImmutableArray<T>, min: 3, max: 3): arr is readonly [T, T, T];
export declare function isArray<T>(arr: ImmutableArray<T>, min?: 1, max?: number): arr is readonly [T, ...T[]];
export declare function isArray<T>(arr: ImmutableArray<T>, min: 2, max?: number): arr is readonly [T, T, ...T[]];
export declare function isArray<T>(arr: ImmutableArray<T>, min: 3, max?: number): arr is readonly [T, T, T, ...T[]];
export declare function isArray<T>(value: unknown, min?: number, max?: number): value is ImmutableArray;
/** Assert that an unknown value is an array (optionally with specified min/max length). */
export declare function assertArray<T>(arr: MutableArray<T>, min: 1, max: 1, caller?: AnyCaller): asserts arr is [T];
export declare function assertArray<T>(arr: MutableArray<T>, min: 2, max: 2, caller?: AnyCaller): asserts arr is [T, T];
export declare function assertArray<T>(arr: MutableArray<T>, min: 3, max: 3, caller?: AnyCaller): asserts arr is [T, T, T];
export declare function assertArray<T>(arr: MutableArray<T>, min?: 1, max?: number, caller?: AnyCaller): asserts arr is [T, ...T[]];
export declare function assertArray<T>(arr: MutableArray<T>, min: 2, max?: number, caller?: AnyCaller): asserts arr is [T, T, ...T[]];
export declare function assertArray<T>(arr: MutableArray<T>, min: 3, max?: number, caller?: AnyCaller): asserts arr is [T, T, T, ...T[]];
export declare function assertArray<T>(arr: MutableArray<T>, min: number, max?: number, caller?: AnyCaller): asserts arr is MutableArray<T>;
export declare function assertArray<T>(arr: ImmutableArray<T>, min: 1, max: 1, caller?: AnyCaller): asserts arr is readonly [T];
export declare function assertArray<T>(arr: ImmutableArray<T>, min: 2, max: 2, caller?: AnyCaller): asserts arr is readonly [T, T];
export declare function assertArray<T>(arr: ImmutableArray<T>, min: 3, max: 3, caller?: AnyCaller): asserts arr is readonly [T, T, T];
export declare function assertArray<T>(arr: ImmutableArray<T>, min?: 1, max?: number, caller?: AnyCaller): asserts arr is readonly [T, ...T[]];
export declare function assertArray<T>(arr: ImmutableArray<T>, min: 2, max?: number, caller?: AnyCaller): asserts arr is readonly [T, T, ...T[]];
export declare function assertArray<T>(arr: ImmutableArray<T>, min: 3, max?: number, caller?: AnyCaller): asserts arr is readonly [T, T, T, ...T[]];
export declare function assertArray<T>(value: unknown, min?: number, max?: number, caller?: AnyCaller): asserts value is ImmutableArray<T>;
/** Convert a possible array to an array. */
export declare function getArray<T>(list: PossibleArray<T>): ImmutableArray<T>;
/** Convert a possible array to an array (optionally with specified min/max length), or throw `RequiredError` if conversion fails. */
export declare function requireArray<T>(arr: MutableArray<T>, min: 1, max: 1, caller?: AnyCaller): [T];
export declare function requireArray<T>(arr: MutableArray<T>, min: 2, max: 2, caller?: AnyCaller): [T, T];
export declare function requireArray<T>(arr: MutableArray<T>, min: 3, max: 3, caller?: AnyCaller): [T, T, T];
export declare function requireArray<T>(arr: MutableArray<T>, min?: 1, max?: number, caller?: AnyCaller): [T, ...T[]];
export declare function requireArray<T>(arr: MutableArray<T>, min: 2, max?: number, caller?: AnyCaller): [T, T, ...T[]];
export declare function requireArray<T>(arr: MutableArray<T>, min: 3, max?: number, caller?: AnyCaller): [T, T, T, ...T[]];
export declare function requireArray<T>(arr: MutableArray<T>, min?: number, max?: number, caller?: AnyCaller): MutableArray<T>;
export declare function requireArray<T>(arr: ImmutableArray<T>, min: 1, max: 1, caller?: AnyCaller): readonly [T];
export declare function requireArray<T>(arr: ImmutableArray<T>, min: 2, max: 2, caller?: AnyCaller): readonly [T, T];
export declare function requireArray<T>(arr: ImmutableArray<T>, min: 3, max: 3, caller?: AnyCaller): readonly [T, T, T];
export declare function requireArray<T>(arr: ImmutableArray<T>, min?: 1, max?: number, caller?: AnyCaller): readonly [T, ...T[]];
export declare function requireArray<T>(arr: ImmutableArray<T>, min: 2, max?: number, caller?: AnyCaller): readonly [T, T, ...T[]];
export declare function requireArray<T>(arr: ImmutableArray<T>, min: 3, max?: number, caller?: AnyCaller): readonly [T, T, T, ...T[]];
export declare function requireArray<T>(list: PossibleArray<T>, min?: number, max?: number, caller?: AnyCaller): ImmutableArray<T>;
/** Is an unknown value an item in a specified array or iterable? */
export declare function isItem<T>(list: PossibleArray<T>, item: unknown): item is T;
/** Assert that an unknown value is an item in a specified array. */
export declare function assertItem<T>(arr: PossibleArray<T>, item: unknown, caller?: AnyCaller): asserts item is T;
/** Add multiple items to an array (immutably) and return a new array with those items (or the same array if no changes were made). */
export declare function withArrayItems<T>(list: PossibleArray<T>, ...add: T[]): ImmutableArray<T>;
/** Pick multiple items from an array (immutably) and return a new array without those items (or the same array if no changes were made). */
export declare function pickArrayItems<T>(items: PossibleArray<T>, ...pick: T[]): ImmutableArray<T>;
/** Remove multiple items from an array (immutably) and return a new array without those items (or the same array if no changes were made). */
export declare function omitArrayItems<T>(items: PossibleArray<T>, ...omit: T[]): ImmutableArray<T>;
/** Toggle an item in and out of an array (immutably) and return a new array with or without the specified items (or the same array if no changes were made). */
export declare function toggleArrayItems<T>(items: PossibleArray<T>, ...toggle: T[]): ImmutableArray<T>;
/** Return a shuffled version of an array or iterable. */
export declare function shuffleArray<T>(items: PossibleArray<T>): ImmutableArray<T>;
/**
 * Add an item to an array (by reference) and return the item.
 * - Skip items that already exist.
 */
export declare function addArrayItem<T>(arr: MutableArray<T>, item: T): T;
/**
 * Add multiple items to an array (by reference).
 * - Skip items that already exist.
 */
export declare function addArrayItems<T>(arr: MutableArray<T>, ...items: T[]): void;
/**
 * Remove multiple items from an array (by reference).
 * - Skip items that already exist.
 */
export declare function deleteArrayItems<T>(arr: MutableArray<T>, ...items: T[]): void;
/** Return an array of the unique items in an array. */
export declare function getUniqueArray<T>(list: PossibleArray<T>): ImmutableArray<T>;
/** Apply a limit to an array. */
export declare function limitArray<T>(list: PossibleArray<T>, limit: number): ImmutableArray<T>;
/** Count the items in an array. */
export declare function countArray<T>(arr: ImmutableArray<T>): number;
/** Get the first item from an array or iterable, or `undefined` if it didn't exist. */
export declare function getFirst<T>(items: PossibleArray<T>): T | undefined;
/** Get the first item from an array or iterable. */
export declare function requireFirst<T>(items: PossibleArray<T>, caller?: AnyCaller): T;
/** Get the last item from an array or iterable, or `undefined` if it didn't exist. */
export declare function getLast<T>(items: PossibleArray<T>): T | undefined;
/** Get the last item from an array or iterable. */
export declare function requireLast<T>(items: PossibleArray<T>, caller?: AnyCaller): T;
/** Get the next item in an array or iterable. */
export declare function getNext<T>(items: PossibleArray<T>, item: T): T | undefined;
/** Get the next item from an array or iterable. */
export declare function requireNext<T>(items: PossibleArray<T>, item: T, caller?: AnyCaller): T;
/** Get the previous item in an array or iterable. */
export declare function getPrev<T>(items: PossibleArray<T>, value: T): T | undefined;
/** Get the previous item from an array or iterable. */
export declare function requirePrev<T>(items: PossibleArray<T>, item: T, caller?: AnyCaller): T;