shelving/util/arraymodule

Typed helpers for reading, validating, and immutably transforming arrays. All immutable operations return the original reference when nothing changed, which keeps React state and memoisation stable.

  • with* / omit* / toggle* functions accept any PossibleArray (an array or any Iterable) but always return a typed ImmutableArray.
  • add* / delete* functions mutate the array in place — use them only when you own the reference.
  • withArrayItem() / withArrayItems() are set-semantics: they skip items already present rather than creating duplicates.

Usage

Checking and asserting

ts
import { isArray, assertArray, requireArray } from "shelving/util";

isArray(value);           // true if Array
isArray(value, 1);        // true if Array with at least 1 item
isArray(value, 2, 5);     // true if Array with 2–5 items

assertArray(value, 1);    // throws RequiredError if empty or not an array
requireArray(iterable, 1); // converts iterable then asserts, returns ImmutableArray

Reading items

ts
import { getFirst, requireFirst, getLast, requireLast, getNext, getPrev } from "shelving/util";

getFirst([10, 20, 30]);          // 10
requireFirst([]);                // throws RequiredError
getLast([10, 20, 30]);           // 30
getNext([1, 2, 3], 2);           // 3
getPrev([1, 2, 3], 2);           // 1

Immutable updates

ts
import { withArrayItem, withArrayItems, omitArrayItem, omitArrayItems,
         toggleArrayItem, withArrayIndex, omitArrayIndex } from "shelving/util";

withArrayItem(["a", "b"], "c");          // ["a", "b", "c"]
withArrayItem(["a", "b"], "b");          // same ref — already present
omitArrayItem(["a", "b", "c"], "b");     // ["a", "c"]
toggleArrayItem(["a", "b"], "b");        // ["a"]
toggleArrayItem(["a", "b"], "c");        // ["a", "b", "c"]
withArrayIndex([10, 20, 30], 1, 99);     // [10, 99, 30]
omitArrayIndex([10, 20, 30], 1);         // [10, 30]

Mutable updates (by reference)

ts
import { addArrayItem, addArrayItems, deleteArrayItem, deleteArrayItems } from "shelving/util";

const arr = ["a", "b"];
addArrayItem(arr, "c");      // arr is now ["a", "b", "c"]; returns "c"
addArrayItem(arr, "b");      // no-op — already present
deleteArrayItem(arr, "a");   // arr is now ["b", "c"]

Filtering and shaping

ts
import { getUniqueArray, limitArray, interleaveArray,
         pickArrayItems, shuffleArray } from "shelving/util";

getUniqueArray([1, 2, 2, 3]);           // [1, 2, 3]
limitArray([1, 2, 3, 4, 5], 3);         // [1, 2, 3]
interleaveArray(["a", "b", "c"], ", "); // ["a", ", ", "b", ", ", "c"]
pickArrayItems([1, 2, 3, 4], 2, 4);     // [2, 4]
shuffleArray([1, 2, 3]);                // randomised copy

Membership checks

ts
import { isArrayItem, assertArrayItem } from "shelving/util";

isArrayItem(["x", "y"], "x");    // true
assertArrayItem(["x", "y"], "z"); // throws RequiredError

Functions

Go

isArray()function

Is an unknown value an array (optionally with specified min/max length)?

isArray(arr: MutableArray<T>, min: 1, max: 1): arr is [T]
isArray(arr: MutableArray<T>, min: 2, max: 2): arr is [T, T]
isArray(arr: MutableArray<T>, min: 3, max: 3): arr is [T, T, T]
isArray(arr: MutableArray<T>, min?: 1, max?: number): arr is [T, ...T[]]
isArray(arr: MutableArray<T>, min: 2, max?: number): arr is [T, T, ...T[]]
isArray(arr: MutableArray<T>, min: 3, max?: number): arr is [T, T, T, ...T[]]
isArray(arr: MutableArray<T>, min?: number, max?: number): arr is MutableArray<T>
isArray(arr: ImmutableArray<T>, min: 1, max: 1): arr is readonly [T]
isArray(arr: ImmutableArray<T>, min: 2, max: 2): arr is readonly [T, T]
isArray(arr: ImmutableArray<T>, min: 3, max: 3): arr is readonly [T, T, T]
isArray(arr: ImmutableArray<T>, min?: 1, max?: number): arr is readonly [T, ...T[]]
isArray(arr: ImmutableArray<T>, min: 2, max?: number): arr is readonly [T, T, ...T[]]
isArray(arr: ImmutableArray<T>, min: 3, max?: number): arr is readonly [T, T, T, ...T[]]
isArray(value: unknown, min?: number, max?: number): value is ImmutableArray<T>
Go

assertArray()function

Assert that an unknown value is an array (optionally with specified min/max length).

assertArray(arr: MutableArray<T>, min: 1, max: 1, caller?: AnyCaller): asserts arr is [T]
assertArray(arr: MutableArray<T>, min: 2, max: 2, caller?: AnyCaller): asserts arr is [T, T]
assertArray(arr: MutableArray<T>, min: 3, max: 3, caller?: AnyCaller): asserts arr is [T, T, T]
assertArray(arr: MutableArray<T>, min?: 1, max?: number, caller?: AnyCaller): asserts arr is [T, ...T[]]
assertArray(arr: MutableArray<T>, min: 2, max?: number, caller?: AnyCaller): asserts arr is [T, T, ...T[]]
assertArray(arr: MutableArray<T>, min: 3, max?: number, caller?: AnyCaller): asserts arr is [T, T, T, ...T[]]
assertArray(arr: MutableArray<T>, min: number, max?: number, caller?: AnyCaller): asserts arr is MutableArray<T>
assertArray(arr: ImmutableArray<T>, min: 1, max: 1, caller?: AnyCaller): asserts arr is readonly [T]
assertArray(arr: ImmutableArray<T>, min: 2, max: 2, caller?: AnyCaller): asserts arr is readonly [T, T]
assertArray(arr: ImmutableArray<T>, min: 3, max: 3, caller?: AnyCaller): asserts arr is readonly [T, T, T]
assertArray(arr: ImmutableArray<T>, min?: 1, max?: number, caller?: AnyCaller): asserts arr is readonly [T, ...T[]]
assertArray(arr: ImmutableArray<T>, min: 2, max?: number, caller?: AnyCaller): asserts arr is readonly [T, T, ...T[]]
assertArray(arr: ImmutableArray<T>, min: 3, max?: number, caller?: AnyCaller): asserts arr is readonly [T, T, T, ...T[]]
assertArray(arr: ImmutableArray<T>, min?: number, max?: number, caller?: AnyCaller): asserts arr is ImmutableArray<T>
Go

getArray()function

Convert a possible array to an array.

getArray(list: unknown): ImmutableArray<unknown> | undefined
Go

requireArray()function

Convert a possible array to an array (optionally with specified min/max length), or throw RequiredError if conversion fails.

requireArray(arr: MutableArray<T>, min: 1, max: 1, caller?: AnyCaller): [T]
requireArray(arr: MutableArray<T>, min: 2, max: 2, caller?: AnyCaller): [T, T]
requireArray(arr: MutableArray<T>, min: 3, max: 3, caller?: AnyCaller): [T, T, T]
requireArray(arr: MutableArray<T>, min?: 1, max?: number, caller?: AnyCaller): [T, ...T[]]
requireArray(arr: MutableArray<T>, min: 2, max?: number, caller?: AnyCaller): [T, T, ...T[]]
requireArray(arr: MutableArray<T>, min: 3, max?: number, caller?: AnyCaller): [T, T, T, ...T[]]
requireArray(arr: MutableArray<T>, min?: number, max?: number, caller?: AnyCaller): MutableArray<T>
requireArray(arr: ImmutableArray<T>, min: 1, max: 1, caller?: AnyCaller): readonly [T]
requireArray(arr: ImmutableArray<T>, min: 2, max: 2, caller?: AnyCaller): readonly [T, T]
requireArray(arr: ImmutableArray<T>, min: 3, max: 3, caller?: AnyCaller): readonly [T, T, T]
requireArray(arr: ImmutableArray<T>, min?: 1, max?: number, caller?: AnyCaller): readonly [T, ...T[]]
requireArray(arr: ImmutableArray<T>, min: 2, max?: number, caller?: AnyCaller): readonly [T, T, ...T[]]
requireArray(arr: ImmutableArray<T>, min: 3, max?: number, caller?: AnyCaller): readonly [T, T, T, ...T[]]
requireArray(list: PossibleArray<T>, min?: number, max?: number, caller?: AnyCaller): ImmutableArray<T>
Go

isArrayItem()function

Is an unknown value an item in a specified array or iterable?

isArrayItem(list: PossibleArray<T>, item: unknown): item is T
Go

assertArrayItem()function

Assert that an unknown value is an item in a specified array.

assertArrayItem(arr: PossibleArray<T>, item: unknown, caller: AnyCaller = assertArrayItem): asserts item is T
Go

withArrayItems()function

Add multiple items to an array (immutably) and return a new array with those items (or the same array if no changes were made).

withArrayItems(list: PossibleArray<T>, ...add: T[]): ImmutableArray<T>
Go

pickArrayItems()function

Pick multiple items from an array (immutably) and return a new array with those items (or the same array if no changes were made).

pickArrayItems(items: PossibleArray<T>, ...pick: T[]): ImmutableArray<T>
Go

omitArrayItems()function

Remove multiple items from an array (immutably) and return a new array without those items (or the same array if no changes were made).

omitArrayItems(items: PossibleArray<T>, ...omit: T[]): ImmutableArray<T>
Go

toggleArrayItems()function

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).

toggleArrayItems(items: PossibleArray<T>, ...toggle: T[]): ImmutableArray<T>
Go

shuffleArray()function

Return a shuffled version of an array or iterable.

shuffleArray(items: PossibleArray<T>): ImmutableArray<T>
Go

addArrayItem()function

Add an item to an array (by reference) and return the item.

addArrayItem(arr: MutableArray<T>, item: T): T
Go

addArrayItems()function

Add multiple items to an array (by reference).

addArrayItems(arr: MutableArray<T>, ...items: T[]): void
Go

deleteArrayItems()function

Remove multiple items from an array (by reference).

deleteArrayItems(arr: MutableArray<T>, ...items: T[]): void
Go

getUniqueArray()function

Return an array of the unique items in an array.

getUniqueArray(list: PossibleArray<T>): ImmutableArray<T>
Go

limitArray()function

Apply a limit to an array.

limitArray(list: PossibleArray<T>, limit: number): ImmutableArray<T>
Go

countArray()function

Count the items in an array.

countArray(arr: ImmutableArray<T>): number
Go

interleaveArray()function

Interleave array items with a separator.

interleaveArray(items: PossibleArray<T>, separator: T): ImmutableArray<T>
interleaveArray(items: PossibleArray<A>, separator: B): ImmutableArray<A | B>
Go

withArrayIndex()function

Return a new array with a new value replacing a specific index in the array (or the same array if the value was unchanged).

withArrayIndex(arr: ImmutableArray<T>, index: number, value: T): ImmutableArray<T>
Go

omitArrayIndex()function

Return a new array without a specific index in the array (or the same array if the value was unchanged).

omitArrayIndex(arr: ImmutableArray<T>, index: number): ImmutableArray<T>
Go

getFirst()function

Get the first item from an array or iterable, or undefined if it didn't exist.

getFirst(items: PossibleArray<T>): T | undefined
Go

requireFirst()function

Get the first item from an array or iterable.

requireFirst(items: PossibleArray<T>, caller: AnyCaller = requireFirst): T
Go

getLast()function

Get the last item from an array or iterable, or undefined if it didn't exist.

getLast(items: PossibleArray<T>): T | undefined
Go

requireLast()function

Get the last item from an array or iterable.

requireLast(items: PossibleArray<T>, caller: AnyCaller = requireLast): T
Go

getNext()function

Get the next item in an array or iterable.

getNext(items: PossibleArray<T>, item: T): T | undefined
Go

requireNext()function

Get the next item from an array or iterable.

requireNext(items: PossibleArray<T>, item: T, caller: AnyCaller = requireNext): T
Go

getPrev()function

Get the previous item in an array or iterable.

getPrev(items: PossibleArray<T>, value: T): T | undefined
Go

requirePrev()function

Get the previous item from an array or iterable.

requirePrev(items: PossibleArray<T>, item: T, caller: AnyCaller = requirePrev): T

Types

Go

MutableArraytype

Mutable array: an array that can be changed.

T[]
Go

ImmutableArraytype

Immutable array: an array that cannot be changed.

readonly T[]
Go

ArrayItemtype

Get the type of the items in an array.

T[number]
Go

PossibleArraytype

Things that can be converted to arrays.

ImmutableArray<T> | Iterable<T>

Constants

Go

withArrayItemconstant

Add an item to an array (immutably) and return a new array with that item (or the same array if no changes were made).

withArrayItem: <T>(items: PossibleArray<T>, add: T) => ImmutableArray<T>
Go

pickArrayItemconstant

Pick an item from an array (immutably) and return a new array with that item (or the same array if no changes were made).

pickArrayItem: <T>(items: PossibleArray<T>, pick: T) => ImmutableArray<T>
Go

omitArrayItemconstant

Remove an item from an array (immutably) and return a new array without that item (or the same array if no changes were made).

omitArrayItem: <T>(items: PossibleArray<T>, omit: T) => ImmutableArray<T>
Go

toggleArrayItemconstant

Toggle an item in and out of an array (immutably) and return a new array with or without the specified item (or the same array if no changes were made).

toggleArrayItem: <T>(items: PossibleArray<T>, toggle: T) => ImmutableArray<T>
Go

deleteArrayItemconstant

Remove an item from an array (by reference).

deleteArrayItem: <T>(arr: MutableArray<T>, item: T) => void