@evolu/common 8.0.0-next.4 → 8.0.0

package/src/Array.ts

@@ -20,8 +20,9 @@
  *
  * const scores = [3, 1, 2];
  * const leaderboard = sortScores(scores);
- * leaderboard; // [1, 2, 3]
- * scores; // [1, 2, 3] — original order lost!
+ * expect(leaderboard).toEqual([1, 2, 3]);
+ * expect(scores).toEqual([1, 2, 3]);
+ * expect(leaderboard).toBe(scores);
  * ```
  *
  * Imagine every method doing that.
@@ -30,71 +31,50 @@
  * instead:
  *
  * ```ts
+ * import { sortArray } from "@evolu/common";
+ *
  * 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!
+ * expect(leaderboard).toEqual([1, 2, 3]);
+ * expect(scores).toEqual([3, 1, 2]);
+ * expect(leaderboard).not.toBe(scores);
  * ```
  *
  * Even better, require a {@link NonEmptyReadonlyArray} — there's nothing to sort
  * if the array is empty anyway:
  *
  * ```ts
+ * import { sortArray, type NonEmptyReadonlyArray } from "@evolu/common";
+ *
  * const sortScores = (arr: NonEmptyReadonlyArray<number>) =>
  *   sortArray(arr, (a, b) => a - b);
+ *
+ * const leaderboard = sortScores([3, 1, 2]);
+ * expect(leaderboard).toEqual([1, 2, 3]);
+ * expectTypeOf(leaderboard).toEqualTypeOf<NonEmptyReadonlyArray<number>>();
  * ```
  *
  * 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
- * const _valid: NonEmptyReadonlyArray<number> = [1, 2, 3];
- * // ts-expect-error - empty array is not a valid NonEmptyReadonlyArray
- * const _invalid: NonEmptyReadonlyArray<number> = [];
- *
- * // Type guards
- * const arr: ReadonlyArray<number> = [1, 2, 3];
- * if (isNonEmptyArray(arr)) {
- *   firstInArray(arr);
- * }
- *
- * // Transformations
- * const appended = appendToArray([1, 2, 3], 4); // [1, 2, 3, 4]
- * const prepended = prependToArray([2, 3], 1); // [1, 2, 3]
- * 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]
- * const deduped = dedupeArray([1, 2, 1, 3, 2]); // [1, 2, 3]
- * const [evens, odds] = partitionArray(
- *   [1, 2, 3, 4, 5],
- *   (x) => x % 2 === 0,
- * );
+ * import { type NonEmptyReadonlyArray } from "@evolu/common";
  *
- * // Accessors
- * const first = firstInArray(["a", "b", "c"]); // "a"
- * const last = lastInArray(["a", "b", "c"]); // "c"
+ * const valid: NonEmptyReadonlyArray<number> = [1, 2, 3];
+ * // @ts-expect-error An empty array is not non-empty.
+ * const invalid: NonEmptyReadonlyArray<number> = [];
  *
- * // Mutations
- * const mutable: NonEmptyArray<number> = [1, 2, 3];
- * shiftFromArray(mutable); // 1 (guaranteed to exist)
- * mutable; // [2, 3]
+ * expect(valid.find((value) => value === 2)).toBe(2);
  * ```
  *
  * ## Composition
@@ -103,16 +83,51 @@
  * because it's natural for single operations:
  *
  * ```ts
+ * import { mapArray } from "@evolu/common";
+ *
+ * interface Message {
+ *   readonly timestamp: number;
+ * }
+ *
+ * const messages: ReadonlyArray<Message> = [
+ *   { timestamp: 10 },
+ *   { timestamp: 20 },
+ * ];
  * const timestamps = mapArray(messages, (m) => m.timestamp);
+ * expect(timestamps).toEqual([10, 20]);
  * ```
  *
  * Data-first style also reads well for a few operations, often fitting on a
  * line:
  *
  * ```ts
- * const cheapest = firstInArray(sortArray(prices, orderNumber));
+ * import {
+ *   dedupeArray,
+ *   filterArray,
+ *   firstInArray,
+ *   isNonEmptyArray,
+ *   lastInArray,
+ *   mapArray,
+ *   orderNumber,
+ *   sortArray,
+ * } from "@evolu/common";
+ *
+ * const cheapest = firstInArray(sortArray([30, 10, 20], orderNumber));
+ * expect(cheapest).toBe(10);
+ *
+ * const users = [{ name: "Ada" }, { name: "Linus" }, { name: "Ada" }];
  * const uniqueNames = dedupeArray(mapArray(users, (u) => u.name));
- * const latestDone = lastInArray(filterArray(jobs, isCompletedJob));
+ * expect(uniqueNames).toEqual(["Ada", "Linus"]);
+ *
+ * const jobs = [
+ *   { id: 1, done: false },
+ *   { id: 2, done: true },
+ * ];
+ * const completedJobs = filterArray(jobs, (job) => job.done);
+ * if (!isNonEmptyArray(completedJobs)) throw new Error("Expected a job");
+ * const latestDone = lastInArray(completedJobs);
+ *
+ * expect(latestDone).toEqual({ id: 2, done: true });
  * ```
  *
  * For more operations, create a function like `getOldestActiveUser` or a
@@ -128,8 +143,7 @@
  * @module
  */
 
-import { identity } from "./Function.js";
-import type { PredicateWithIndex, RefinementWithIndex } from "./Types.js";
+import { identity } from "./Function.ts";
 
 /**
  * An array with at least one element.
@@ -145,6 +159,13 @@ export type NonEmptyArray<T> = [T, ...Array<T>];
  */
 export type NonEmptyReadonlyArray<T> = readonly [T, ...ReadonlyArray<T>];
 
+/**
+ * A readonly array with at least two elements.
+ *
+ * @group Types
+ */
+export type AtLeastTwoReadonlyArray<T> = readonly [T, T, ...ReadonlyArray<T>];
+
 /**
  * An empty readonly array.
  *
@@ -160,14 +181,21 @@ export const emptyArray: ReadonlyArray<never> = [];
  * - 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)
+ * - Returns existing arrays unchanged
  *
- * ### Example
+ * ### Creating from iterables and lengths
  *
  * ```ts
- * arrayFrom(new Set([1, 2, 3])); // ReadonlyArray<number>
- * arrayFrom(3, (i) => i * 10); // [0, 10, 20]
- * arrayFrom(iterableMaybeArray); // no unnecessary copy
+ * import { arrayFrom } from "@evolu/common";
+ *
+ * const fromSet = arrayFrom(new Set([1, 2, 3]));
+ * expect(fromSet).toEqual([1, 2, 3]);
+ * expectTypeOf(fromSet).toEqualTypeOf<ReadonlyArray<number>>();
+ *
+ * expect(arrayFrom(3, (i) => i * 10)).toEqual([0, 10, 20]);
+ *
+ * const existing: ReadonlyArray<number> = [1, 2, 3];
+ * expect(arrayFrom(existing)).toBe(existing);
  * ```
  *
  * Unlike `Array.from`, there's no map parameter for iterables — use
@@ -203,16 +231,22 @@ export function arrayFrom<T>(
  * Returns a readonly array and awaits promised items from sync or async
  * iterables.
  *
- * ### Example
+ * ### Awaiting sync and async iterables
  *
  * ```ts
- * await arrayFromAsync(new Set([1, 2, 3])); // ReadonlyArray<number>
- * await arrayFromAsync(
+ * import { arrayFromAsync } from "@evolu/common";
+ *
+ * const fromIterable = await arrayFromAsync(new Set([1, 2, 3]));
+ * expect(fromIterable).toEqual([1, 2, 3]);
+ *
+ * const fromAsyncIterable = await arrayFromAsync(
  *   (async function* () {
  *     yield Promise.resolve(1);
  *     yield Promise.resolve(2);
  *   })(),
- * ); // [1, 2]
+ * );
+ * expect(fromAsyncIterable).toEqual([1, 2]);
+ * expectTypeOf(fromAsyncIterable).toEqualTypeOf<ReadonlyArray<number>>();
  * ```
  *
  * Unlike `Array.fromAsync`, there's no map parameter — map the result with
@@ -234,20 +268,25 @@ export const arrayFromAsync = async <T>(
  * negated guard is better than `.length === 0` for early returns because
  * TypeScript narrows the type after the check.
  *
- * ### Example
+ * ### Narrowing mutable and readonly arrays
  *
  * ```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
+ * import {
+ *   firstInArray,
+ *   isNonEmptyArray,
+ *   type NonEmptyArray,
+ *   type NonEmptyReadonlyArray,
+ * } from "@evolu/common";
+ *
+ * const mutable: Array<number> = [1, 2, 3];
  * const readonly: ReadonlyArray<number> = [1, 2, 3];
- * if (isNonEmptyArray(readonly)) {
- *   firstInArray(readonly); // readonly is NonEmptyReadonlyArray<number>
+ * if (!isNonEmptyArray(mutable) || !isNonEmptyArray(readonly)) {
+ *   throw new Error("Expected values");
  * }
+ *
+ * expectTypeOf(mutable).toEqualTypeOf<NonEmptyArray<number>>();
+ * expectTypeOf(readonly).toEqualTypeOf<NonEmptyReadonlyArray<number>>();
+ * expect(firstInArray(readonly)).toBe(1);
  * ```
  *
  * @group Types
@@ -266,10 +305,17 @@ export function isNonEmptyArray<T>(
 /**
  * Appends an item to an array, returning a new non-empty readonly array.
  *
- * ### Example
+ * ### Appending a value
  *
  * ```ts
- * appendToArray([1, 2, 3], 4); // [1, 2, 3, 4]
+ * import {
+ *   appendToArray,
+ *   type NonEmptyReadonlyArray,
+ * } from "@evolu/common";
+ *
+ * const values = appendToArray([1, 2, 3], 4);
+ * expect(values).toEqual([1, 2, 3, 4]);
+ * expectTypeOf(values).toEqualTypeOf<NonEmptyReadonlyArray<number>>();
  * ```
  *
  * @group Transformations
@@ -278,15 +324,24 @@ export const appendToArray = <T>(
   array: ReadonlyArray<T>,
   item: T,
 ): NonEmptyReadonlyArray<T> =>
+  // The appended item guarantees non-emptiness, but TypeScript cannot infer a
+  // leading element after spreading a possibly empty array.
   [...array, item] as ReadonlyArray<T> as NonEmptyReadonlyArray<T>;
 
 /**
  * Prepends an item to an array, returning a new non-empty readonly array.
  *
- * ### Example
+ * ### Prepending a value
  *
  * ```ts
- * prependToArray([2, 3], 1); // [1, 2, 3]
+ * import {
+ *   prependToArray,
+ *   type NonEmptyReadonlyArray,
+ * } from "@evolu/common";
+ *
+ * const values = prependToArray([2, 3], 1);
+ * expect(values).toEqual([1, 2, 3]);
+ * expectTypeOf(values).toEqualTypeOf<NonEmptyReadonlyArray<number>>();
  * ```
  *
  * @group Transformations
@@ -294,39 +349,47 @@ export const appendToArray = <T>(
 export const prependToArray = <T>(
   array: ReadonlyArray<T>,
   item: T,
-): NonEmptyReadonlyArray<T> => [item, ...array] as NonEmptyReadonlyArray<T>;
+): NonEmptyReadonlyArray<T> => [item, ...array];
 
 /**
  * Maps an array using a mapper function, returning a new readonly array.
  *
  * Preserves non-empty type.
  *
- * ### Example
+ * ### Mapping with indexes while preserving non-emptiness
  *
  * ```ts
- * mapArray([1, 2, 3], (x) => x * 2); // [2, 4, 6]
+ * import { mapArray, type NonEmptyReadonlyArray } from "@evolu/common";
+ *
+ * const values: ReadonlyArray<number> = [1, 2, 3];
+ * const indexed = mapArray(values, (value, index) => value + index);
+ * expect(indexed).toEqual([1, 3, 5]);
+ * expectTypeOf(indexed).toEqualTypeOf<ReadonlyArray<number>>();
+ *
+ * const nonEmpty: NonEmptyReadonlyArray<number> = [1, 2, 3];
+ * expectTypeOf(mapArray(nonEmpty, (x) => x * 2)).toEqualTypeOf<
+ *   NonEmptyReadonlyArray<number>
+ * >();
  * ```
  *
+ * The mapper receives `(item, index, array)`, matching native `Array.map`.
+ *
  * @group Transformations
  */
 export function mapArray<T, U>(
-  array: NonEmptyReadonlyArray<T> | NonEmptyArray<T>,
-  mapper: (item: T, index: number) => U,
+  array: NonEmptyReadonlyArray<T>,
+  mapper: (item: T, index: number, array: ReadonlyArray<T>) => U,
 ): NonEmptyReadonlyArray<U>;
 /** Possibly empty array. */
 export function mapArray<T, U>(
-  array: ReadonlyArray<T> | Array<T>,
-  mapper: (item: T, index: number) => U,
+  array: ReadonlyArray<T>,
+  mapper: (item: T, index: number, array: ReadonlyArray<T>) => U,
 ): ReadonlyArray<U>;
 export function mapArray<T, U>(
-  array: ReadonlyArray<T> | Array<T>,
-  mapper: (item: T, index: number) => U,
+  array: ReadonlyArray<T>,
+  mapper: (item: T, index: number, array: ReadonlyArray<T>) => U,
 ): 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;
+  return array.map(mapper);
 }
 
 /**
@@ -336,15 +399,23 @@ export function mapArray<T, U>(
  * non-empty arrays. When called without a mapper, flattens nested arrays using
  * {@link identity}.
  *
- * ### Example
+ * ### Flattening and expanding values
  *
  * ```ts
- * flatMapArray([
+ * import { flatMapArray, type NonEmptyReadonlyArray } from "@evolu/common";
+ *
+ * const flattened = flatMapArray([
  *   [1, 2],
  *   [3, 4],
- * ]); // [1, 2, 3, 4]
- *
- * flatMapArray([1, 2, 3], (x) => [x, x * 10]); // [1, 10, 2, 20, 3, 30]
+ * ]);
+ * const values: NonEmptyReadonlyArray<number> = [1, 2, 3];
+ * const expanded = flatMapArray(
+ *   values,
+ *   (value, index): NonEmptyReadonlyArray<number> => [value, index],
+ * );
+ * expect(flattened).toEqual([1, 2, 3, 4]);
+ * expectTypeOf(expanded).toEqualTypeOf<NonEmptyReadonlyArray<number>>();
+ * expect(expanded).toEqual([1, 0, 2, 1, 3, 2]);
  * ```
  *
  * ### Filter and map in one pass
@@ -352,47 +423,54 @@ export function mapArray<T, U>(
  * Return `[]` to filter out, `[value]` to keep:
  *
  * ```ts
+ * import { err, flatMapArray, ok } from "@evolu/common";
+ *
+ * const validate = (value: number) =>
+ *   value > 0 ? ok(value) : err(`${value} is not positive`);
+ * const fields = [1, -2, 3, -4];
  * const errors = flatMapArray(fields, (f) => {
  *   const result = validate(f);
  *   return result.ok ? [] : [result.error];
  * });
+ * expect(errors).toEqual(["-2 is not positive", "-4 is not positive"]);
  * ```
  *
+ * The mapper receives `(item, index, array)`, matching native `Array.flatMap`.
+ *
  * @group Transformations
  */
 export function flatMapArray<T>(
-  array:
-    | NonEmptyReadonlyArray<NonEmptyReadonlyArray<T> | NonEmptyArray<T>>
-    | NonEmptyArray<NonEmptyReadonlyArray<T> | NonEmptyArray<T>>,
+  array: NonEmptyReadonlyArray<NonEmptyReadonlyArray<T>>,
 ): NonEmptyReadonlyArray<T>;
 /** Possibly empty nested arrays. */
 export function flatMapArray<T>(
-  array:
-    | ReadonlyArray<ReadonlyArray<T> | Array<T>>
-    | Array<ReadonlyArray<T> | Array<T>>,
+  array: ReadonlyArray<ReadonlyArray<T>>,
 ): ReadonlyArray<T>;
 /** Non-empty with mapper returning non-empty. */
 export function flatMapArray<T, U>(
-  array: NonEmptyReadonlyArray<T> | NonEmptyArray<T>,
+  array: NonEmptyReadonlyArray<T>,
   mapper: (
     item: T,
     index: number,
-  ) => NonEmptyReadonlyArray<U> | NonEmptyArray<U>,
+    array: ReadonlyArray<T>,
+  ) => NonEmptyReadonlyArray<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>,
+  array: ReadonlyArray<T>,
+  mapper: (item: T, index: number, array: ReadonlyArray<T>) => ReadonlyArray<U>,
 ): ReadonlyArray<U>;
 export function flatMapArray<T, U>(
-  array: ReadonlyArray<T> | Array<T>,
+  array: ReadonlyArray<T>,
   mapper: (
     item: T,
     index: number,
-  ) => ReadonlyArray<U> | Array<U> = identity as (
+    array: ReadonlyArray<T>,
+  ) => ReadonlyArray<U> = identity as (
     item: T,
     index: number,
-  ) => ReadonlyArray<U> | Array<U>,
+    array: ReadonlyArray<T>,
+  ) => ReadonlyArray<U>,
 ): ReadonlyArray<U> {
   return array.flatMap(mapper);
 }
@@ -402,35 +480,42 @@ export function flatMapArray<T, U>(
  *
  * Returns a non-empty array when at least one input is non-empty.
  *
- * ### Example
+ * ### Concatenating non-empty inputs
  *
  * ```ts
- * concatArrays([1, 2], [3, 4]); // [1, 2, 3, 4]
- * concatArrays([], [1]); // [1] (non-empty)
- * concatArrays([1], []); // [1] (non-empty)
+ * import { concatArrays, type NonEmptyReadonlyArray } from "@evolu/common";
+ *
+ * const nonEmpty: NonEmptyReadonlyArray<number> = [1];
+ * const joined = concatArrays([1, 2], [3, 4]);
+ * const fromLeft = concatArrays(nonEmpty, []);
+ * const fromRight = concatArrays([], nonEmpty);
+ *
+ * expect(joined).toEqual([1, 2, 3, 4]);
+ * expectTypeOf(fromLeft).toEqualTypeOf<NonEmptyReadonlyArray<number>>();
+ * expectTypeOf(fromRight).toEqualTypeOf<NonEmptyReadonlyArray<number>>();
  * ```
  *
  * @group Transformations
  */
 export function concatArrays<T>(
-  first: NonEmptyReadonlyArray<T> | NonEmptyArray<T>,
-  second: ReadonlyArray<T> | Array<T>,
+  first: NonEmptyReadonlyArray<T>,
+  second: ReadonlyArray<T>,
 ): NonEmptyReadonlyArray<T>;
 /** Second non-empty. */
 export function concatArrays<T>(
-  first: ReadonlyArray<T> | Array<T>,
-  second: NonEmptyReadonlyArray<T> | NonEmptyArray<T>,
+  first: ReadonlyArray<T>,
+  second: NonEmptyReadonlyArray<T>,
 ): NonEmptyReadonlyArray<T>;
 /** Both possibly empty. */
 export function concatArrays<T>(
-  first: ReadonlyArray<T> | Array<T>,
-  second: ReadonlyArray<T> | Array<T>,
+  first: ReadonlyArray<T>,
+  second: ReadonlyArray<T>,
 ): ReadonlyArray<T>;
 export function concatArrays<T>(
-  first: ReadonlyArray<T> | Array<T>,
-  second: ReadonlyArray<T> | Array<T>,
+  first: ReadonlyArray<T>,
+  second: ReadonlyArray<T>,
 ): ReadonlyArray<T> {
-  return [...first, ...second] as ReadonlyArray<T>;
+  return [...first, ...second];
 }
 
 /**
@@ -441,77 +526,92 @@ export function concatArrays<T>(
  * TypeScript will narrow the result type to the narrowed type, making it useful
  * for filtering with Evolu Types like `PositiveInt.is`.
  *
- * ### Example
- *
  * ### With predicate
  *
  * ```ts
- * filterArray([1, 2, 3, 4, 5], (x) => x % 2 === 0); // [2, 4]
+ * import { filterArray } from "@evolu/common";
+ *
+ * const evens = filterArray([1, 2, 3, 4, 5], (x) => x % 2 === 0);
+ * expect(evens).toEqual([2, 4]);
  * ```
  *
  * ### With refinement
  *
  * ```ts
- * const mixed: ReadonlyArray<NonEmptyString | PositiveInt> = [
- *   NonEmptyString.orThrow("hello"),
+ * import {
+ *   filterArray,
+ *   NonEmptyTrimmedString,
+ *   PositiveInt,
+ * } from "@evolu/common";
+ *
+ * const mixed: ReadonlyArray<NonEmptyTrimmedString | PositiveInt> = [
+ *   NonEmptyTrimmedString.orThrow("hello"),
  *   PositiveInt.orThrow(42),
  * ];
  * const positiveInts = filterArray(mixed, PositiveInt.is);
- * // positiveInts: ReadonlyArray<PositiveInt> (narrowed type)
+ * expect(positiveInts).toEqual([42]);
+ * expectTypeOf(positiveInts).toEqualTypeOf<ReadonlyArray<PositiveInt>>();
  * ```
  *
+ * The predicate receives `(item, index, array)`, matching native
+ * `Array.filter`.
+ *
  * @group Transformations
  */
 export function filterArray<T, S extends T>(
   array: ReadonlyArray<T>,
-  refinement: RefinementWithIndex<T, S>,
+  refinement: (item: T, index: number, array: ReadonlyArray<T>) => item is S,
 ): ReadonlyArray<S>;
 /** With predicate. */
 export function filterArray<T>(
   array: ReadonlyArray<T>,
-  predicate: PredicateWithIndex<T>,
+  predicate: (item: T, index: number, array: ReadonlyArray<T>) => boolean,
 ): ReadonlyArray<T>;
 export function filterArray<T>(
   array: ReadonlyArray<T>,
-  predicate: PredicateWithIndex<T>,
+  predicate: (item: T, index: number, array: ReadonlyArray<T>) => boolean,
 ): ReadonlyArray<T> {
   return array.filter(predicate);
 }
 
 /**
- * Returns a new readonly array with duplicate items removed. If `by` is
- * provided, it will be used to derive the key for uniqueness; otherwise values
- * are used directly. Dedupes by reference equality of values (or extracted keys
- * when `by` is used).
+ * Returns a new readonly array with duplicate items removed. Items are compared
+ * using `Set` equality (SameValueZero): primitives by value, and objects and
+ * arrays by reference. If `by` is provided, it derives the comparison key.
  *
  * Preserves non-empty type.
  *
- * ### Example
+ * ### Deduplicating by value or key
  *
  * ```ts
- * // Dedupe primitives by value
- * dedupeArray([1, 2, 1, 3, 2]); // [1, 2, 3]
+ * import { dedupeArray, type NonEmptyReadonlyArray } from "@evolu/common";
  *
- * // Dedupe objects by property
- * dedupeArray(
+ * const numbers = dedupeArray([1, 2, 1, 3, 2]);
+ * const people = dedupeArray(
  *   [
  *     { id: 1, name: "Alice" },
  *     { id: 2, name: "Bob" },
  *     { id: 1, name: "Alice 2" },
  *   ],
  *   (item) => item.id,
- * ); // [{ id: 1, name: "Alice" }, { id: 2, name: "Bob" }]
+ * );
+ * expectTypeOf(numbers).toEqualTypeOf<NonEmptyReadonlyArray<number>>();
+ * expect(numbers).toEqual([1, 2, 3]);
+ * expect(people).toEqual([
+ *   { id: 1, name: "Alice" },
+ *   { id: 2, name: "Bob" },
+ * ]);
  * ```
  *
  * @group Transformations
  */
 export function dedupeArray<T>(
-  array: NonEmptyReadonlyArray<T> | NonEmptyArray<T>,
+  array: NonEmptyReadonlyArray<T>,
   by?: (item: T) => unknown,
 ): NonEmptyReadonlyArray<T>;
 /** Possibly empty array. */
 export function dedupeArray<T>(
-  array: ReadonlyArray<T> | Array<T>,
+  array: ReadonlyArray<T>,
   by?: (item: T) => unknown,
 ): ReadonlyArray<T>;
 export function dedupeArray<T>(
@@ -542,51 +642,62 @@ export function dedupeArray<T>(
  * TypeScript will narrow the first array to the narrowed type, making it useful
  * for filtering with Evolu Types like `PositiveInt.is`.
  *
- * ### Example
- *
  * ### With predicate
  *
  * ```ts
+ * import { partitionArray } from "@evolu/common";
+ *
  * const [evens, odds] = partitionArray(
  *   [1, 2, 3, 4, 5],
  *   (x) => x % 2 === 0,
  * );
- * evens; // [2, 4]
- * odds; // [1, 3, 5]
+ * expect(evens).toEqual([2, 4]);
+ * expect(odds).toEqual([1, 3, 5]);
  * ```
  *
  * ### With refinement
  *
  * ```ts
- * const mixed: ReadonlyArray<NonEmptyString | PositiveInt> = [
- *   NonEmptyString.orThrow("hello"),
+ * import {
+ *   NonEmptyTrimmedString,
+ *   partitionArray,
+ *   PositiveInt,
+ * } from "@evolu/common";
+ *
+ * const mixed: ReadonlyArray<NonEmptyTrimmedString | PositiveInt> = [
+ *   NonEmptyTrimmedString.orThrow("hello"),
  *   PositiveInt.orThrow(42),
  * ];
  * const [positiveInts, strings] = partitionArray(mixed, PositiveInt.is);
- * // positiveInts: ReadonlyArray<PositiveInt> (narrowed type)
- * // strings: ReadonlyArray<NonEmptyString> (Exclude<T, PositiveInt>)
+ * expect(positiveInts).toEqual([42]);
+ * expectTypeOf(positiveInts).toEqualTypeOf<ReadonlyArray<PositiveInt>>();
+ * expectTypeOf(strings).toEqualTypeOf<
+ *   ReadonlyArray<NonEmptyTrimmedString>
+ * >();
  * ```
  *
+ * The predicate receives `(item, index, array)`.
+ *
  * @group Transformations
  */
 export function partitionArray<T, S extends T>(
   array: ReadonlyArray<T>,
-  refinement: RefinementWithIndex<T, S>,
+  refinement: (item: T, index: number, array: ReadonlyArray<T>) => item is S,
 ): readonly [ReadonlyArray<S>, ReadonlyArray<Exclude<T, S>>];
 /** With predicate. */
 export function partitionArray<T>(
   array: ReadonlyArray<T>,
-  predicate: PredicateWithIndex<T>,
+  predicate: (item: T, index: number, array: ReadonlyArray<T>) => boolean,
 ): readonly [ReadonlyArray<T>, ReadonlyArray<T>];
 export function partitionArray<T>(
   array: ReadonlyArray<T>,
-  predicate: PredicateWithIndex<T>,
+  predicate: (item: T, index: number, array: ReadonlyArray<T>) => boolean,
 ): readonly [ReadonlyArray<T>, ReadonlyArray<T>] {
   const trueArray: Array<T> = [];
   const falseArray: Array<T> = [];
 
   for (let i = 0; i < array.length; i++) {
-    if (predicate(array[i], i)) {
+    if (predicate(array[i], i, array)) {
       trueArray.push(array[i]);
     } else {
       falseArray.push(array[i]);
@@ -601,10 +712,15 @@ export function partitionArray<T>(
  *
  * Wraps native `toSorted`. Preserves non-empty type.
  *
- * ### Example
+ * ### Sorting without mutation
  *
  * ```ts
- * sortArray([3, 1, 2], (a, b) => a - b); // [1, 2, 3]
+ * import { sortArray, type NonEmptyReadonlyArray } from "@evolu/common";
+ *
+ * const values: NonEmptyReadonlyArray<number> = [3, 1, 2];
+ * const sorted = sortArray(values, (a, b) => a - b);
+ * expect(sorted).toEqual([1, 2, 3]);
+ * expectTypeOf(sorted).toEqualTypeOf<NonEmptyReadonlyArray<number>>();
  * ```
  *
  * @group Transformations
@@ -630,10 +746,15 @@ export function sortArray<T>(
  *
  * Wraps native `toReversed`. Preserves non-empty type.
  *
- * ### Example
+ * ### Reversing without mutation
  *
  * ```ts
- * reverseArray([1, 2, 3]); // [3, 2, 1]
+ * import { reverseArray, type NonEmptyReadonlyArray } from "@evolu/common";
+ *
+ * const values: NonEmptyReadonlyArray<number> = [1, 2, 3];
+ * const reversed = reverseArray(values);
+ * expect(reversed).toEqual([3, 2, 1]);
+ * expectTypeOf(reversed).toEqualTypeOf<NonEmptyReadonlyArray<number>>();
  * ```
  *
  * @group Transformations
@@ -652,11 +773,15 @@ export function reverseArray<T>(array: ReadonlyArray<T>): ReadonlyArray<T> {
  *
  * Wraps native `toSpliced`.
  *
- * ### Example
+ * ### Removing and replacing values
  *
  * ```ts
- * spliceArray([1, 2, 3, 4], 1, 2); // [1, 4]
- * spliceArray([1, 2, 3], 1, 1, 10, 11); // [1, 10, 11, 3]
+ * import { spliceArray } from "@evolu/common";
+ *
+ * const values: ReadonlyArray<number> = [1, 2, 3, 4];
+ * expect(spliceArray(values, 1, 2)).toEqual([1, 4]);
+ * expect(spliceArray([1, 2, 3], 1, 1, 10, 11)).toEqual([1, 10, 11, 3]);
+ * expect(values).toEqual([1, 2, 3, 4]);
  * ```
  *
  * @group Transformations
@@ -685,21 +810,33 @@ export type ZipArrayResult<T extends ReadonlyArray<ReadonlyArray<unknown>>> = {
  * {@link https://github.com/tc39/proposal-array-zip | TC39 Array.zip proposal}
  * for the pattern this follows.
  *
- * ### Example
+ * ### Zipping to the shortest input
  *
  * ```ts
- * zipArray([
+ * import { zipArray, type NonEmptyReadonlyArray } from "@evolu/common";
+ *
+ * const pairs = zipArray([
  *   [1, 2, 3],
  *   ["a", "b", "c"],
  * ]);
- * // [[1, "a"], [2, "b"], [3, "c"]]
- *
- * zipArray([
- *   [1, 2],
- *   ["a", "b", "c"],
- *   [true, false],
+ * expect(pairs).toEqual([
+ *   [1, "a"],
+ *   [2, "b"],
+ *   [3, "c"],
  * ]);
- * // [[1, "a", true], [2, "b", false]]
+ * expect(
+ *   zipArray([
+ *     [1, 2],
+ *     ["a", "b", "c"],
+ *     [true, false],
+ *   ]),
+ * ).toEqual([
+ *   [1, "a", true],
+ *   [2, "b", false],
+ * ]);
+ * expectTypeOf(pairs).toEqualTypeOf<
+ *   NonEmptyReadonlyArray<Readonly<[number, string]>>
+ * >();
  * ```
  *
  * @group Transformations
@@ -708,7 +845,7 @@ 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>>>(
+export function zipArray<const T extends ReadonlyArray<ReadonlyArray<unknown>>>(
   arrays: T,
 ): ReadonlyArray<Readonly<ZipArrayResult<T>>>;
 export function zipArray<T extends ReadonlyArray<ReadonlyArray<unknown>>>(
@@ -729,10 +866,12 @@ export function zipArray<T extends ReadonlyArray<ReadonlyArray<unknown>>>(
 /**
  * Returns the first element of a non-empty array.
  *
- * ### Example
+ * ### Reading the first value
  *
  * ```ts
- * firstInArray(["a", "b", "c"]); // "a"
+ * import { firstInArray } from "@evolu/common";
+ *
+ * expect(firstInArray(["a", "b", "c"])).toBe("a");
  * ```
  *
  * @group Accessors
@@ -742,53 +881,15 @@ export const firstInArray = <T>(array: NonEmptyReadonlyArray<T>): T => array[0];
 /**
  * Returns the last element of a non-empty array.
  *
- * ### Example
+ * ### Reading the last value
  *
  * ```ts
- * lastInArray(["a", "b", "c"]); // "c"
+ * import { lastInArray } from "@evolu/common";
+ *
+ * expect(lastInArray(["a", "b", "c"])).toBe("c");
  * ```
  *
  * @group Accessors
  */
 export const lastInArray = <T>(array: NonEmptyReadonlyArray<T>): T =>
   array[array.length - 1];
-
-/**
- * Shifts (removes and returns) the first element from a non-empty mutable
- * array.
- *
- * **Mutates** the original array.
- *
- * ### Example
- *
- * ```ts
- * // Process a queue of callbacks
- * const waitingQueue: Array<() => void> = [callback1, callback2];
- * if (isNonEmptyArray(waitingQueue)) {
- *   shiftFromArray(waitingQueue)(); // Remove and immediately invoke
- * }
- * ```
- *
- * @group Mutations
- */
-export const shiftFromArray = <T>(array: NonEmptyArray<T>): T =>
-  array.shift() as T;
-
-/**
- * Pops (removes and returns) the last element from a non-empty mutable array.
- *
- * **Mutates** the original array.
- *
- * ### Example
- *
- * ```ts
- * // Process a stack of callbacks (LIFO)
- * const callbackStack: Array<() => void> = [callback1, callback2];
- * if (isNonEmptyArray(callbackStack)) {
- *   popFromArray(callbackStack)(); // Remove and immediately invoke
- * }
- * ```
- *
- * @group Mutations
- */
-export const popFromArray = <T>(array: NonEmptyArray<T>): T => array.pop() as T;