@evolu/common 7.4.1 → 8.0.0-next.0

package/dist/src/Array.d.ts

@@ -1,8 +1,67 @@
 /**
- * Array types, type guards, operations, transformations, accessors, and (rare)
- * mutations
+ * Array helpers that help TypeScript help you.
  *
- * ### Example
+ * - **Non-empty arrays**: compile-time guarantee of at least one element
+ * - **Readonly arrays**: prevents accidental mutation
+ *
+ * Instead of checking array length at runtime, use {@link NonEmptyReadonlyArray}
+ * so TypeScript rejects empty arrays at compile time. Functions like
+ * {@link firstInArray} require a non-empty array — TypeScript won't let us pass
+ * an empty one. {@link mapArray} preserves non-emptiness (native `map` doesn't),
+ * while {@link appendToArray} and {@link prependToArray} guarantee the result is
+ * non-empty.
+ *
+ * All helpers return readonly arrays for safety. Consider how dangerous native
+ * `sort()` is — it mutates the original array and returns it, making bugs hard
+ * to track:
+ *
+ * ```ts
+ * const sortScores = (arr: number[]) => arr.sort((a, b) => a - b);
+ *
+ * const scores = [3, 1, 2];
+ * const leaderboard = sortScores(scores);
+ * leaderboard; // [1, 2, 3]
+ * scores; // [1, 2, 3] — original order lost!
+ * ```
+ *
+ * Imagine every method doing that.
+ *
+ * On a `ReadonlyArray`, `.sort()` doesn't even exist. Use {@link sortArray}
+ * instead:
+ *
+ * ```ts
+ * const sortScores = (arr: ReadonlyArray<number>) =>
+ *   sortArray(arr, (a, b) => a - b);
+ *
+ * const scores: ReadonlyArray<number> = [3, 1, 2];
+ * const leaderboard = sortScores(scores);
+ * leaderboard; // [1, 2, 3]
+ * scores; // [3, 1, 2] — safe!
+ * ```
+ *
+ * Even better, require a {@link NonEmptyReadonlyArray} — there's nothing to sort
+ * if the array is empty anyway:
+ *
+ * ```ts
+ * const sortScores = (arr: NonEmptyReadonlyArray<number>) =>
+ *   sortArray(arr, (a, b) => a - b);
+ * ```
+ *
+ * Sorting an empty array isn't expensive, but functions can have side effects
+ * like database queries or network requests. Using non-empty arrays whenever
+ * possible is a good convention.
+ *
+ * For performance-critical cases where mutation is needed, Evolu provides
+ * {@link shiftFromArray} and {@link popFromArray} — but only because they improve
+ * type safety by returning a guaranteed `T` rather than an optional value.
+ *
+ * ### When to use native methods
+ *
+ * These helpers only exist where they add type-level value. Native methods like
+ * `find`, `some`, `every`, `includes`, `indexOf`, and `findIndex` work well on
+ * readonly arrays without mutation — use them directly.
+ *
+ * ## Examples
  *
  * ```ts
  * // Types - compile-time guarantee of at least one element
@@ -12,15 +71,13 @@
  *
  * // Type guards
  * const arr: ReadonlyArray<number> = [1, 2, 3];
- * if (isNonEmptyReadonlyArray(arr)) {
+ * if (isNonEmptyArray(arr)) {
  *   firstInArray(arr);
  * }
  *
- * // Operations
+ * // Transformations
  * const appended = appendToArray([1, 2, 3], 4); // [1, 2, 3, 4]
  * const prepended = prependToArray([2, 3], 1); // [1, 2, 3]
- *
- * // Transformations
  * const readonly: ReadonlyArray<number> = [1, 2, 3];
  * const mapped = mapArray(readonly, (x) => x * 2); // [2, 4, 6]
  * const filtered = filterArray(readonly, (x) => x > 1); // [2, 3]
@@ -28,7 +85,7 @@
  * const [evens, odds] = partitionArray(
  *   [1, 2, 3, 4, 5],
  *   (x) => x % 2 === 0,
- * ); // [[2, 4], [1, 3, 5]]
+ * );
  *
  * // Accessors
  * const first = firstInArray(["a", "b", "c"]); // "a"
@@ -36,131 +93,170 @@
  *
  * // Mutations
  * const mutable: NonEmptyArray<number> = [1, 2, 3];
- * shiftArray(mutable); // 1 (guaranteed to exist)
+ * shiftFromArray(mutable); // 1 (guaranteed to exist)
  * mutable; // [2, 3]
  * ```
  *
- * Functions are intentionally data-first to be prepared for the upcoming
- * JavaScript pipe operator.
+ * ## Composition
+ *
+ * All array helpers use a data-first style (the array is the first argument)
+ * because it's natural for single operations:
  *
  * ```ts
- * // Data-first is natural for single operations.
  * const timestamps = mapArray(messages, (m) => m.timestamp);
+ * ```
  *
- * // But data-first can be hard to read for nested calls.
- * const result = firstInArray(
- *   mapArray(dedupeArray(appendToArray(value, 2)), (x) => x * 2),
- * );
+ * Data-first style also reads well for a few operations, often fitting on a
+ * line:
  *
- * // With the upcoming pipe operator, it's clear.
- * // const result = value
- * //   |> appendToArray(%, 2)
- * //   |> dedupeArray(%)
- * //   |> mapArray(%, (x) => x * 2)
- * //   |> firstInArray(%);
- *
- * // Until the pipe operator lands, use nested calls or name each step:
- * const appended = appendToArray(value, 2);
- * const deduped = dedupeArray(appended);
- * const mapped = mapArray(deduped, (x) => x * 2);
- * const result = firstInArray(mapped);
+ * ```ts
+ * const cheapest = firstInArray(sortArray(prices, orderNumber));
+ * const uniqueNames = dedupeArray(mapArray(users, (u) => u.name));
+ * const latestDone = lastInArray(filterArray(jobs, isCompletedJob));
  * ```
  *
- * ### Why data-first?
+ * For more operations, create a function like `getOldestActiveUser` or a
+ * generic helper.
  *
- * Evolu optimizes for consistent code style. We can't have both data-first
- * single operations and curried data-last helpers without sacrificing
- * consistency. We chose data-first because:
+ * Some libraries provide dual APIs with data-last for pipe-based composition.
+ * Evolu prefers simplicity (in Latin, simplex means "one") so we don't have to
+ * choose between seemingly equivalent options (Buridan's ass dilemma).
  *
- * - It's natural for single operations (for example `mapArray(messages, (m) =>
- *   m.timestamp)`).
- * - It aligns with the upcoming JavaScript pipe operator.
- *
- * **Note**: Feel free to use Array instance methods (mutation) if you think
- * it's better (performance, local scope, etc.).
+ * Evolu doesn't provide `pipe` because few operations compose well without it,
+ * and for more operations, well-named functions communicate intent better.
  *
  * @module
  */
-import { PredicateWithIndex, RefinementWithIndex } from "./Types.js";
+import type { PredicateWithIndex, RefinementWithIndex } from "./Types.js";
 /**
  * An array with at least one element.
  *
- * @category Types
+ * @group Types
  */
 export type NonEmptyArray<T> = [T, ...Array<T>];
 /**
  * A readonly array with at least one element.
  *
- * @category Types
+ * @group Types
  */
 export type NonEmptyReadonlyArray<T> = readonly [T, ...ReadonlyArray<T>];
 /**
- * Checks if an array is non-empty and narrows its type to {@link NonEmptyArray}.
+ * An empty readonly array.
  *
- * Use `if (!isNonEmptyArray(arr))` for empty checks.
+ * Use as a default or initial value to avoid allocating new empty arrays.
+ *
+ * @group Constants
+ */
+export declare const emptyArray: ReadonlyArray<never>;
+/**
+ * Better `Array.from`.
+ *
+ * - Returns readonly arrays
+ * - Accepts length directly: `arrayFrom(3, fn)` instead of `Array.from({ length:
+ *   3 }, fn)`
+ * - Skips copying if iterable is already an array (safe because readonly)
  *
  * ### Example
  *
  * ```ts
- * const arr: Array<number> = [1, 2, 3];
- * if (isNonEmptyArray(arr)) {
- *   firstInArray(arr); // arr is NonEmptyArray<number>
- * }
+ * arrayFrom(new Set([1, 2, 3])); // ReadonlyArray<number>
+ * arrayFrom(3, (i) => i * 10); // [0, 10, 20]
+ * arrayFrom(iterableMaybeArray); // no unnecessary copy
  * ```
  *
- * @category Type Guards
+ * Unlike `Array.from`, there's no map parameter for iterables — use
+ * {@link mapArray} instead, or
+ * {@link https://web.dev/blog/baseline-iterator-helpers | iterator helpers}
+ * directly on iterables.
+ *
+ * @group Constructors
  */
-export declare const isNonEmptyArray: <T>(array: Array<T>) => array is NonEmptyArray<T>;
+export declare function arrayFrom<T>(iterable: Iterable<T>): ReadonlyArray<T>;
+/** From length and map function. */
+export declare function arrayFrom<T>(length: number, map: (index: number) => T): ReadonlyArray<T>;
 /**
- * Checks if a readonly array is non-empty and narrows its type to
- * {@link NonEmptyReadonlyArray}.
+ * Better `Array.fromAsync`.
  *
- * Use `if (!isNonEmptyReadonlyArray(arr))` for empty checks.
+ * Returns a readonly array and awaits promised items from sync or async
+ * iterables.
  *
  * ### Example
  *
  * ```ts
- * const arr: ReadonlyArray<number> = [1, 2, 3];
- * if (isNonEmptyReadonlyArray(arr)) {
- *   firstInArray(arr); // arr is NonEmptyReadonlyArray<number>
+ * await arrayFromAsync(new Set([1, 2, 3])); // ReadonlyArray<number>
+ * await arrayFromAsync(
+ *   (async function* () {
+ *     yield Promise.resolve(1);
+ *     yield Promise.resolve(2);
+ *   })(),
+ * ); // [1, 2]
+ * ```
+ *
+ * Unlike `Array.fromAsync`, there's no map parameter — map the result with
+ * {@link mapArray} or use
+ * {@link https://web.dev/blog/baseline-iterator-helpers | iterator helpers}
+ * directly on iterables.
+ *
+ * @group Constructors
+ */
+export declare const arrayFromAsync: <T>(iterable: AsyncIterable<T> | Iterable<T | PromiseLike<T>>) => Promise<ReadonlyArray<T>>;
+/**
+ * Checks if an array is non-empty and narrows its type to {@link NonEmptyArray}
+ * or {@link NonEmptyReadonlyArray} based on the input.
+ *
+ * To check if an array is empty, use `if (!isNonEmptyArray(arr))` — using the
+ * negated guard is better than `.length === 0` for early returns because
+ * TypeScript narrows the type after the check.
+ *
+ * ### Example
+ *
+ * ```ts
+ * // Mutable array narrows to NonEmptyArray
+ * const arr: Array<number> = [1, 2, 3];
+ * if (isNonEmptyArray(arr)) {
+ *   shiftFromArray(arr); // arr is NonEmptyArray<number>
+ * }
+ *
+ * // Readonly array narrows to NonEmptyReadonlyArray
+ * const readonly: ReadonlyArray<number> = [1, 2, 3];
+ * if (isNonEmptyArray(readonly)) {
+ *   firstInArray(readonly); // readonly is NonEmptyReadonlyArray<number>
  * }
  * ```
  *
- * @category Type Guards
+ * @group Types
  */
-export declare const isNonEmptyReadonlyArray: <T>(array: ReadonlyArray<T>) => array is NonEmptyReadonlyArray<T>;
+export declare function isNonEmptyArray<T>(array: Array<T>): array is NonEmptyArray<T>;
+/** Readonly array overload. */
+export declare function isNonEmptyArray<T>(array: ReadonlyArray<T>): array is NonEmptyReadonlyArray<T>;
 /**
  * Appends an item to an array, returning a new non-empty readonly array.
  *
- * Accepts both mutable and readonly arrays. Does not mutate the original array.
- *
  * ### Example
  *
  * ```ts
  * appendToArray([1, 2, 3], 4); // [1, 2, 3, 4]
  * ```
  *
- * @category Operations
+ * @group Transformations
  */
 export declare const appendToArray: <T>(array: ReadonlyArray<T>, item: T) => NonEmptyReadonlyArray<T>;
 /**
  * Prepends an item to an array, returning a new non-empty readonly array.
  *
- * Accepts both mutable and readonly arrays. Does not mutate the original array.
- *
  * ### Example
  *
  * ```ts
  * prependToArray([2, 3], 1); // [1, 2, 3]
  * ```
  *
- * @category Operations
+ * @group Transformations
  */
 export declare const prependToArray: <T>(array: ReadonlyArray<T>, item: T) => NonEmptyReadonlyArray<T>;
 /**
- * Maps an array using a mapper function.
+ * Maps an array using a mapper function, returning a new readonly array.
  *
- * Accepts both mutable and readonly arrays. Preserves non-empty type.
+ * Preserves non-empty type.
  *
  * ### Example
  *
@@ -168,28 +264,86 @@ export declare const prependToArray: <T>(array: ReadonlyArray<T>, item: T) => No
  * mapArray([1, 2, 3], (x) => x * 2); // [2, 4, 6]
  * ```
  *
- * @category Transformations
+ * @group Transformations
  */
 export declare function mapArray<T, U>(array: NonEmptyReadonlyArray<T> | NonEmptyArray<T>, mapper: (item: T, index: number) => U): NonEmptyReadonlyArray<U>;
+/** Possibly empty array. */
 export declare function mapArray<T, U>(array: ReadonlyArray<T> | Array<T>, mapper: (item: T, index: number) => U): ReadonlyArray<U>;
+/**
+ * Maps each element to an array and flattens the result.
+ *
+ * Preserves non-empty type when the input is non-empty and the mapper returns
+ * non-empty arrays. When called without a mapper, flattens nested arrays using
+ * {@link identity}.
+ *
+ * ### Example
+ *
+ * ```ts
+ * flatMapArray([
+ *   [1, 2],
+ *   [3, 4],
+ * ]); // [1, 2, 3, 4]
+ *
+ * flatMapArray([1, 2, 3], (x) => [x, x * 10]); // [1, 10, 2, 20, 3, 30]
+ * ```
+ *
+ * ### Filter and map in one pass
+ *
+ * Return `[]` to filter out, `[value]` to keep:
+ *
+ * ```ts
+ * const errors = flatMapArray(fields, (f) => {
+ *   const result = validate(f);
+ *   return result.ok ? [] : [result.error];
+ * });
+ * ```
+ *
+ * @group Transformations
+ */
+export declare function flatMapArray<T>(array: NonEmptyReadonlyArray<NonEmptyReadonlyArray<T> | NonEmptyArray<T>> | NonEmptyArray<NonEmptyReadonlyArray<T> | NonEmptyArray<T>>): NonEmptyReadonlyArray<T>;
+/** Possibly empty nested arrays. */
+export declare function flatMapArray<T>(array: ReadonlyArray<ReadonlyArray<T> | Array<T>> | Array<ReadonlyArray<T> | Array<T>>): ReadonlyArray<T>;
+/** Non-empty with mapper returning non-empty. */
+export declare function flatMapArray<T, U>(array: NonEmptyReadonlyArray<T> | NonEmptyArray<T>, mapper: (item: T, index: number) => NonEmptyReadonlyArray<U> | NonEmptyArray<U>): NonEmptyReadonlyArray<U>;
+/** With mapper function. */
+export declare function flatMapArray<T, U>(array: ReadonlyArray<T> | Array<T>, mapper: (item: T, index: number) => ReadonlyArray<U> | Array<U>): ReadonlyArray<U>;
+/**
+ * Concatenates two arrays, returning a new readonly array.
+ *
+ * Returns a non-empty array when at least one input is non-empty.
+ *
+ * ### Example
+ *
+ * ```ts
+ * concatArrays([1, 2], [3, 4]); // [1, 2, 3, 4]
+ * concatArrays([], [1]); // [1] (non-empty)
+ * concatArrays([1], []); // [1] (non-empty)
+ * ```
+ *
+ * @group Transformations
+ */
+export declare function concatArrays<T>(first: NonEmptyReadonlyArray<T> | NonEmptyArray<T>, second: ReadonlyArray<T> | Array<T>): NonEmptyReadonlyArray<T>;
+/** Second non-empty. */
+export declare function concatArrays<T>(first: ReadonlyArray<T> | Array<T>, second: NonEmptyReadonlyArray<T> | NonEmptyArray<T>): NonEmptyReadonlyArray<T>;
+/** Both possibly empty. */
+export declare function concatArrays<T>(first: ReadonlyArray<T> | Array<T>, second: ReadonlyArray<T> | Array<T>): ReadonlyArray<T>;
 /**
  * Filters an array using a predicate or refinement function, returning a new
  * readonly array.
  *
- * Accepts both mutable and readonly arrays. When used with a refinement
- * function (with `value is Type` syntax), TypeScript will narrow the result
- * type to the narrowed type, making it useful for filtering with Evolu Types
- * like `PositiveInt.is`.
+ * When used with a refinement function (with `value is Type` syntax),
+ * TypeScript will narrow the result type to the narrowed type, making it useful
+ * for filtering with Evolu Types like `PositiveInt.is`.
  *
- * ### Examples
+ * ### Example
  *
- * #### With predicate
+ * ### With predicate
  *
  * ```ts
  * filterArray([1, 2, 3, 4, 5], (x) => x % 2 === 0); // [2, 4]
  * ```
  *
- * #### With refinement
+ * ### With refinement
  *
  * ```ts
  * const mixed: ReadonlyArray<NonEmptyString | PositiveInt> = [
@@ -200,9 +354,10 @@ export declare function mapArray<T, U>(array: ReadonlyArray<T> | Array<T>, mappe
  * // positiveInts: ReadonlyArray<PositiveInt> (narrowed type)
  * ```
  *
- * @category Transformations
+ * @group Transformations
  */
 export declare function filterArray<T, S extends T>(array: ReadonlyArray<T>, refinement: RefinementWithIndex<T, S>): ReadonlyArray<S>;
+/** With predicate. */
 export declare function filterArray<T>(array: ReadonlyArray<T>, predicate: PredicateWithIndex<T>): ReadonlyArray<T>;
 /**
  * Returns a new readonly array with duplicate items removed. If `by` is
@@ -210,7 +365,6 @@ export declare function filterArray<T>(array: ReadonlyArray<T>, predicate: Predi
  * are used directly. Dedupes by reference equality of values (or extracted keys
  * when `by` is used).
  *
- * Accepts both mutable and readonly arrays. Does not mutate the original array.
  * Preserves non-empty type.
  *
  * ### Example
@@ -230,25 +384,25 @@ export declare function filterArray<T>(array: ReadonlyArray<T>, predicate: Predi
  * ); // [{ id: 1, name: "Alice" }, { id: 2, name: "Bob" }]
  * ```
  *
- * @category Transformations
+ * @group Transformations
  */
 export declare function dedupeArray<T>(array: NonEmptyReadonlyArray<T> | NonEmptyArray<T>, by?: (item: T) => unknown): NonEmptyReadonlyArray<T>;
+/** Possibly empty array. */
 export declare function dedupeArray<T>(array: ReadonlyArray<T> | Array<T>, by?: (item: T) => unknown): ReadonlyArray<T>;
 /**
- * Partitions an array into two arrays based on a predicate or refinement
- * function.
+ * Partitions an array into two readonly arrays based on a predicate or
+ * refinement function.
  *
  * Returns a tuple where the first array contains elements that satisfy the
- * predicate, and the second array contains elements that do not. Accepts both
- * mutable and readonly arrays.
+ * predicate, and the second array contains elements that do not.
  *
  * When used with a refinement function (with `value is Type` syntax),
  * TypeScript will narrow the first array to the narrowed type, making it useful
  * for filtering with Evolu Types like `PositiveInt.is`.
  *
- * ### Examples
+ * ### Example
  *
- * #### With predicate
+ * ### With predicate
  *
  * ```ts
  * const [evens, odds] = partitionArray(
@@ -259,7 +413,7 @@ export declare function dedupeArray<T>(array: ReadonlyArray<T> | Array<T>, by?:
  * odds; // [1, 3, 5]
  * ```
  *
- * #### With refinement
+ * ### With refinement
  *
  * ```ts
  * const mixed: ReadonlyArray<NonEmptyString | PositiveInt> = [
@@ -271,14 +425,98 @@ export declare function dedupeArray<T>(array: ReadonlyArray<T> | Array<T>, by?:
  * // strings: ReadonlyArray<NonEmptyString> (Exclude<T, PositiveInt>)
  * ```
  *
- * @category Transformations
+ * @group Transformations
  */
 export declare function partitionArray<T, S extends T>(array: ReadonlyArray<T>, refinement: RefinementWithIndex<T, S>): readonly [ReadonlyArray<S>, ReadonlyArray<Exclude<T, S>>];
+/** With predicate. */
 export declare function partitionArray<T>(array: ReadonlyArray<T>, predicate: PredicateWithIndex<T>): readonly [ReadonlyArray<T>, ReadonlyArray<T>];
 /**
- * Returns the first element of a non-empty array.
+ * Returns a new sorted readonly array.
+ *
+ * Wraps native `toSorted`. Preserves non-empty type.
+ *
+ * ### Example
+ *
+ * ```ts
+ * sortArray([3, 1, 2], (a, b) => a - b); // [1, 2, 3]
+ * ```
  *
- * Accepts both mutable and readonly arrays. Does not mutate the original array.
+ * @group Transformations
+ */
+export declare function sortArray<T>(array: NonEmptyReadonlyArray<T>, compareFn?: (a: T, b: T) => number): NonEmptyReadonlyArray<T>;
+/** Possibly empty array. */
+export declare function sortArray<T>(array: ReadonlyArray<T>, compareFn?: (a: T, b: T) => number): ReadonlyArray<T>;
+/**
+ * Returns a new reversed readonly array.
+ *
+ * Wraps native `toReversed`. Preserves non-empty type.
+ *
+ * ### Example
+ *
+ * ```ts
+ * reverseArray([1, 2, 3]); // [3, 2, 1]
+ * ```
+ *
+ * @group Transformations
+ */
+export declare function reverseArray<T>(array: NonEmptyReadonlyArray<T>): NonEmptyReadonlyArray<T>;
+/** Possibly empty array. */
+export declare function reverseArray<T>(array: ReadonlyArray<T>): ReadonlyArray<T>;
+/**
+ * Returns a new readonly array with elements removed and/or replaced.
+ *
+ * Wraps native `toSpliced`.
+ *
+ * ### Example
+ *
+ * ```ts
+ * spliceArray([1, 2, 3, 4], 1, 2); // [1, 4]
+ * spliceArray([1, 2, 3], 1, 1, 10, 11); // [1, 10, 11, 3]
+ * ```
+ *
+ * @group Transformations
+ */
+export declare const spliceArray: <T>(array: ReadonlyArray<T>, start: number, deleteCount: number, ...items: ReadonlyArray<T>) => ReadonlyArray<T>;
+/**
+ * Extracts element types from a tuple of arrays, producing a tuple type.
+ *
+ * @group Types
+ */
+export type ZipArrayResult<T extends ReadonlyArray<ReadonlyArray<unknown>>> = {
+    [K in keyof T]: T[K] extends ReadonlyArray<infer U> ? U : never;
+};
+/**
+ * Combines multiple arrays into an array of tuples.
+ *
+ * Uses "shortest" mode — stops at the shortest input array. Preserves non-empty
+ * type when all input arrays are non-empty. See the
+ * {@link https://github.com/tc39/proposal-array-zip | TC39 Array.zip proposal}
+ * for the pattern this follows.
+ *
+ * ### Example
+ *
+ * ```ts
+ * zipArray([
+ *   [1, 2, 3],
+ *   ["a", "b", "c"],
+ * ]);
+ * // [[1, "a"], [2, "b"], [3, "c"]]
+ *
+ * zipArray([
+ *   [1, 2],
+ *   ["a", "b", "c"],
+ *   [true, false],
+ * ]);
+ * // [[1, "a", true], [2, "b", false]]
+ * ```
+ *
+ * @group Transformations
+ */
+export declare function zipArray<T extends NonEmptyReadonlyArray<NonEmptyReadonlyArray<unknown>>>(arrays: T): NonEmptyReadonlyArray<Readonly<ZipArrayResult<T>>>;
+/** Possibly empty arrays. */
+export declare function zipArray<T extends ReadonlyArray<ReadonlyArray<unknown>>>(arrays: T): ReadonlyArray<Readonly<ZipArrayResult<T>>>;
+/**
+ * Returns the first element of a non-empty array.
  *
  * ### Example
  *
@@ -286,53 +524,56 @@ export declare function partitionArray<T>(array: ReadonlyArray<T>, predicate: Pr
  * firstInArray(["a", "b", "c"]); // "a"
  * ```
  *
- * @category Accessors
+ * @group Accessors
  */
 export declare const firstInArray: <T>(array: NonEmptyReadonlyArray<T>) => T;
 /**
  * Returns the last element of a non-empty array.
  *
- * Accepts both mutable and readonly arrays. Does not mutate the original array.
- *
  * ### Example
  *
  * ```ts
  * lastInArray(["a", "b", "c"]); // "c"
  * ```
  *
- * @category Accessors
+ * @group Accessors
  */
 export declare const lastInArray: <T>(array: NonEmptyReadonlyArray<T>) => T;
 /**
- * Shifts an item from a non-empty mutable array, guaranteed to return T.
+ * Shifts (removes and returns) the first element from a non-empty mutable
+ * array.
  *
  * **Mutates** the original array.
  *
  * ### Example
  *
  * ```ts
- * const arr: NonEmptyArray<number> = [1, 2, 3];
- * shiftArray(arr); // 1
- * arr; // [2, 3]
+ * // Process a queue of callbacks
+ * const waitingQueue: Array<() => void> = [callback1, callback2];
+ * if (isNonEmptyArray(waitingQueue)) {
+ *   shiftFromArray(waitingQueue)(); // Remove and immediately invoke
+ * }
  * ```
  *
- * @category Mutations
+ * @group Mutations
  */
-export declare const shiftArray: <T>(array: NonEmptyArray<T>) => T;
+export declare const shiftFromArray: <T>(array: NonEmptyArray<T>) => T;
 /**
- * Pops an item from a non-empty mutable array, guaranteed to return T.
+ * Pops (removes and returns) the last element from a non-empty mutable array.
  *
  * **Mutates** the original array.
  *
  * ### Example
  *
  * ```ts
- * const arr: NonEmptyArray<number> = [1, 2, 3];
- * popArray(arr); // 3
- * arr; // [1, 2]
+ * // Process a stack of callbacks (LIFO)
+ * const callbackStack: Array<() => void> = [callback1, callback2];
+ * if (isNonEmptyArray(callbackStack)) {
+ *   popFromArray(callbackStack)(); // Remove and immediately invoke
+ * }
  * ```
  *
- * @category Mutations
+ * @group Mutations
  */
-export declare const popArray: <T>(array: NonEmptyArray<T>) => T;
+export declare const popFromArray: <T>(array: NonEmptyArray<T>) => T;
 //# sourceMappingURL=Array.d.ts.map

package/dist/src/Array.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Array.d.ts","sourceRoot":"","sources":["../../src/Array.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"Array.d.ts","sourceRoot":"","sources":["../../src/Array.ts"],"names":[],"mappings":"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"}