@evolu/common 7.4.0 → 8.0.0-next.0

package/src/Array.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,121 +93,186 @@
  *
  * // 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 { identity } from "./Function.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 as a default or initial value to avoid allocating new empty arrays.
+ *
+ * @group Constants
+ */
+export const emptyArray: ReadonlyArray<never> = [];
+
+/**
+ * Better `Array.from`.
  *
- * Use `if (!isNonEmptyArray(arr))` for empty checks.
+ * - 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 const isNonEmptyArray = <T>(
-  array: Array<T>,
-): array is NonEmptyArray<T> => array.length > 0;
+export function arrayFrom<T>(iterable: Iterable<T>): ReadonlyArray<T>;
+/** From length and map function. */
+export function arrayFrom<T>(
+  length: number,
+  map: (index: number) => T,
+): ReadonlyArray<T>;
+export function arrayFrom<T>(
+  iterableOrLength: Iterable<T> | number,
+  map?: (index: number) => T,
+): ReadonlyArray<T> {
+  if (typeof iterableOrLength === "number") {
+    return Array.from({ length: iterableOrLength }, (_, i) =>
+      (map as (index: number) => T)(i),
+    );
+  }
+  return Array.isArray(iterableOrLength)
+    ? (iterableOrLength as ReadonlyArray<T>)
+    : [...iterableOrLength];
+}
 
 /**
- * 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 const arrayFromAsync = async <T>(
+  iterable: AsyncIterable<T> | Iterable<T | PromiseLike<T>>,
+): Promise<ReadonlyArray<T>> => Array.fromAsync(iterable);
+
+/**
+ * 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 const isNonEmptyReadonlyArray = <T>(
+export function isNonEmptyArray<T>(array: Array<T>): array is NonEmptyArray<T>;
+/** Readonly array overload. */
+export function isNonEmptyArray<T>(
+  array: ReadonlyArray<T>,
+): array is NonEmptyReadonlyArray<T>;
+export function isNonEmptyArray<T>(
   array: ReadonlyArray<T>,
-): array is NonEmptyReadonlyArray<T> => array.length > 0;
+): array is NonEmptyReadonlyArray<T> {
+  return array.length > 0;
+}
 
 /**
  * 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 const appendToArray = <T>(
   array: ReadonlyArray<T>,
@@ -161,15 +283,13 @@ export const appendToArray = <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 const prependToArray = <T>(
   array: ReadonlyArray<T>,
@@ -177,9 +297,9 @@ export const prependToArray = <T>(
 ): NonEmptyReadonlyArray<T> => [item, ...array] as 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
  *
@@ -187,12 +307,13 @@ export const prependToArray = <T>(
  * mapArray([1, 2, 3], (x) => x * 2); // [2, 4, 6]
  * ```
  *
- * @category Transformations
+ * @group Transformations
  */
 export function mapArray<T, U>(
   array: NonEmptyReadonlyArray<T> | NonEmptyArray<T>,
   mapper: (item: T, index: number) => U,
 ): NonEmptyReadonlyArray<U>;
+/** Possibly empty array. */
 export function mapArray<T, U>(
   array: ReadonlyArray<T> | Array<T>,
   mapper: (item: T, index: number) => U,
@@ -201,27 +322,134 @@ export function mapArray<T, U>(
   array: ReadonlyArray<T> | Array<T>,
   mapper: (item: T, index: number) => U,
 ): ReadonlyArray<U> {
-  return array.map(mapper) as ReadonlyArray<U>;
+  // For loop is faster than array.map.
+  const length = array.length;
+  const result = new Array<U>(length);
+  for (let i = 0; i < length; i++) result[i] = mapper(array[i], i);
+  return result as 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 function flatMapArray<T>(
+  array:
+    | NonEmptyReadonlyArray<NonEmptyReadonlyArray<T> | NonEmptyArray<T>>
+    | NonEmptyArray<NonEmptyReadonlyArray<T> | NonEmptyArray<T>>,
+): NonEmptyReadonlyArray<T>;
+/** Possibly empty nested arrays. */
+export function flatMapArray<T>(
+  array:
+    | ReadonlyArray<ReadonlyArray<T> | Array<T>>
+    | Array<ReadonlyArray<T> | Array<T>>,
+): ReadonlyArray<T>;
+/** Non-empty with mapper returning non-empty. */
+export function flatMapArray<T, U>(
+  array: NonEmptyReadonlyArray<T> | NonEmptyArray<T>,
+  mapper: (
+    item: T,
+    index: number,
+  ) => NonEmptyReadonlyArray<U> | NonEmptyArray<U>,
+): NonEmptyReadonlyArray<U>;
+/** With mapper function. */
+export function flatMapArray<T, U>(
+  array: ReadonlyArray<T> | Array<T>,
+  mapper: (item: T, index: number) => ReadonlyArray<U> | Array<U>,
+): ReadonlyArray<U>;
+export function flatMapArray<T, U>(
+  array: ReadonlyArray<T> | Array<T>,
+  mapper: (
+    item: T,
+    index: number,
+  ) => ReadonlyArray<U> | Array<U> = identity as (
+    item: T,
+    index: number,
+  ) => ReadonlyArray<U> | Array<U>,
+): ReadonlyArray<U> {
+  return array.flatMap(mapper) as 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 function concatArrays<T>(
+  first: NonEmptyReadonlyArray<T> | NonEmptyArray<T>,
+  second: ReadonlyArray<T> | Array<T>,
+): NonEmptyReadonlyArray<T>;
+/** Second non-empty. */
+export function concatArrays<T>(
+  first: ReadonlyArray<T> | Array<T>,
+  second: NonEmptyReadonlyArray<T> | NonEmptyArray<T>,
+): NonEmptyReadonlyArray<T>;
+/** Both possibly empty. */
+export function concatArrays<T>(
+  first: ReadonlyArray<T> | Array<T>,
+  second: ReadonlyArray<T> | Array<T>,
+): ReadonlyArray<T>;
+export function concatArrays<T>(
+  first: ReadonlyArray<T> | Array<T>,
+  second: ReadonlyArray<T> | Array<T>,
+): ReadonlyArray<T> {
+  return [...first, ...second] as 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> = [
@@ -232,12 +460,13 @@ export function mapArray<T, U>(
  * // positiveInts: ReadonlyArray<PositiveInt> (narrowed type)
  * ```
  *
- * @category Transformations
+ * @group Transformations
  */
 export function filterArray<T, S extends T>(
   array: ReadonlyArray<T>,
   refinement: RefinementWithIndex<T, S>,
 ): ReadonlyArray<S>;
+/** With predicate. */
 export function filterArray<T>(
   array: ReadonlyArray<T>,
   predicate: PredicateWithIndex<T>,
@@ -255,7 +484,6 @@ export function filterArray<T>(
  * 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
@@ -275,12 +503,13 @@ export function filterArray<T>(
  * ); // [{ id: 1, name: "Alice" }, { id: 2, name: "Bob" }]
  * ```
  *
- * @category Transformations
+ * @group Transformations
  */
 export function dedupeArray<T>(
   array: NonEmptyReadonlyArray<T> | NonEmptyArray<T>,
   by?: (item: T) => unknown,
 ): NonEmptyReadonlyArray<T>;
+/** Possibly empty array. */
 export function dedupeArray<T>(
   array: ReadonlyArray<T> | Array<T>,
   by?: (item: T) => unknown,
@@ -303,20 +532,19 @@ export function dedupeArray<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(
@@ -327,7 +555,7 @@ export function dedupeArray<T>(
  * odds; // [1, 3, 5]
  * ```
  *
- * #### With refinement
+ * ### With refinement
  *
  * ```ts
  * const mixed: ReadonlyArray<NonEmptyString | PositiveInt> = [
@@ -339,12 +567,13 @@ export function dedupeArray<T>(
  * // strings: ReadonlyArray<NonEmptyString> (Exclude<T, PositiveInt>)
  * ```
  *
- * @category Transformations
+ * @group Transformations
  */
 export function partitionArray<T, S extends T>(
   array: ReadonlyArray<T>,
   refinement: RefinementWithIndex<T, S>,
 ): readonly [ReadonlyArray<S>, ReadonlyArray<Exclude<T, S>>];
+/** With predicate. */
 export function partitionArray<T>(
   array: ReadonlyArray<T>,
   predicate: PredicateWithIndex<T>,
@@ -368,9 +597,137 @@ export function partitionArray<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]
+ * ```
+ *
+ * @group Transformations
+ */
+export function sortArray<T>(
+  array: NonEmptyReadonlyArray<T>,
+  compareFn?: (a: T, b: T) => number,
+): NonEmptyReadonlyArray<T>;
+/** Possibly empty array. */
+export function sortArray<T>(
+  array: ReadonlyArray<T>,
+  compareFn?: (a: T, b: T) => number,
+): ReadonlyArray<T>;
+export function sortArray<T>(
+  array: ReadonlyArray<T>,
+  compareFn?: (a: T, b: T) => number,
+): ReadonlyArray<T> {
+  return array.toSorted(compareFn) as ReadonlyArray<T>;
+}
+
+/**
+ * Returns a new reversed readonly array.
+ *
+ * Wraps native `toReversed`. Preserves non-empty type.
+ *
+ * ### Example
  *
- * Accepts both mutable and readonly arrays. Does not mutate the original array.
+ * ```ts
+ * reverseArray([1, 2, 3]); // [3, 2, 1]
+ * ```
+ *
+ * @group Transformations
+ */
+export function reverseArray<T>(
+  array: NonEmptyReadonlyArray<T>,
+): NonEmptyReadonlyArray<T>;
+/** Possibly empty array. */
+export function reverseArray<T>(array: ReadonlyArray<T>): ReadonlyArray<T>;
+export function reverseArray<T>(array: ReadonlyArray<T>): ReadonlyArray<T> {
+  return array.toReversed() as 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 const spliceArray = <T>(
+  array: ReadonlyArray<T>,
+  start: number,
+  deleteCount: number,
+  ...items: ReadonlyArray<T>
+): ReadonlyArray<T> => array.toSpliced(start, deleteCount, ...items);
+
+/**
+ * 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 function zipArray<
+  T extends NonEmptyReadonlyArray<NonEmptyReadonlyArray<unknown>>,
+>(arrays: T): NonEmptyReadonlyArray<Readonly<ZipArrayResult<T>>>;
+/** Possibly empty arrays. */
+export function zipArray<T extends ReadonlyArray<ReadonlyArray<unknown>>>(
+  arrays: T,
+): ReadonlyArray<Readonly<ZipArrayResult<T>>>;
+export function zipArray<T extends ReadonlyArray<ReadonlyArray<unknown>>>(
+  arrays: T,
+): ReadonlyArray<Readonly<ZipArrayResult<T>>> {
+  if (arrays.length === 0) return emptyArray;
+
+  const minLength = Math.min(...mapArray(arrays, (a) => a.length));
+  const result = new Array<unknown>(minLength);
+
+  for (let i = 0; i < minLength; i++) {
+    result[i] = mapArray(arrays, (a) => a[i]);
+  }
+
+  return result as ReadonlyArray<Readonly<ZipArrayResult<T>>>;
+}
+
+/**
+ * Returns the first element of a non-empty array.
  *
  * ### Example
  *
@@ -378,56 +735,60 @@ export function partitionArray<T>(
  * firstInArray(["a", "b", "c"]); // "a"
  * ```
  *
- * @category Accessors
+ * @group Accessors
  */
 export const firstInArray = <T>(array: NonEmptyReadonlyArray<T>): T => array[0];
 
 /**
  * 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 const lastInArray = <T>(array: NonEmptyReadonlyArray<T>): T =>
   array[array.length - 1];
 
 /**
- * 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 const shiftArray = <T>(array: NonEmptyArray<T>): T => array.shift() as T;
+export const shiftFromArray = <T>(array: NonEmptyArray<T>): T =>
+  array.shift() as 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 const popArray = <T>(array: NonEmptyArray<T>): T => array.pop() as T;
+export const popFromArray = <T>(array: NonEmptyArray<T>): T => array.pop() as T;