@evolu/common 8.0.0-next.4 → 8.0.0

package/dist/src/Array.d.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
@@ -127,7 +142,6 @@
  *
  * @module
  */
-import type { PredicateWithIndex, RefinementWithIndex } from "./Types.js";
 /**
  * An array with at least one element.
  *
@@ -140,6 +154,12 @@ export type NonEmptyArray<T> = [T, ...Array<T>];
  * @group Types
  */
 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.
  *
@@ -154,14 +174,21 @@ export declare 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
@@ -180,16 +207,22 @@ export declare function arrayFrom<T>(length: number, map: (index: number) => 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
@@ -208,20 +241,25 @@ export declare const arrayFromAsync: <T>(iterable: AsyncIterable<T> | Iterable<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
@@ -232,10 +270,17 @@ export declare function isNonEmptyArray<T>(array: ReadonlyArray<T>): array is No
 /**
  * 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
@@ -244,10 +289,17 @@ export declare const appendToArray: <T>(array: ReadonlyArray<T>, item: T) => Non
 /**
  * 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
@@ -258,17 +310,29 @@ export declare const prependToArray: <T>(array: ReadonlyArray<T>, item: T) => No
  *
  * 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 declare function mapArray<T, U>(array: NonEmptyReadonlyArray<T> | NonEmptyArray<T>, mapper: (item: T, index: number) => U): NonEmptyReadonlyArray<U>;
+export declare function mapArray<T, U>(array: NonEmptyReadonlyArray<T>, mapper: (item: T, index: number, array: ReadonlyArray<T>) => 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>;
+export declare function mapArray<T, U>(array: ReadonlyArray<T>, mapper: (item: T, index: number, array: ReadonlyArray<T>) => U): ReadonlyArray<U>;
 /**
  * Maps each element to an array and flattens the result.
  *
@@ -276,15 +340,23 @@ export declare function mapArray<T, U>(array: ReadonlyArray<T> | Array<T>, mappe
  * 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
@@ -292,41 +364,56 @@ export declare function mapArray<T, U>(array: ReadonlyArray<T> | Array<T>, mappe
  * 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 declare function flatMapArray<T>(array: NonEmptyReadonlyArray<NonEmptyReadonlyArray<T> | NonEmptyArray<T>> | NonEmptyArray<NonEmptyReadonlyArray<T> | NonEmptyArray<T>>): NonEmptyReadonlyArray<T>;
+export declare function flatMapArray<T>(array: NonEmptyReadonlyArray<NonEmptyReadonlyArray<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>;
+export declare function flatMapArray<T>(array: ReadonlyArray<ReadonlyArray<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>;
+export declare function flatMapArray<T, U>(array: NonEmptyReadonlyArray<T>, mapper: (item: T, index: number, array: ReadonlyArray<T>) => NonEmptyReadonlyArray<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>;
+export declare function flatMapArray<T, U>(array: ReadonlyArray<T>, mapper: (item: T, index: number, array: ReadonlyArray<T>) => ReadonlyArray<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
+ * ### 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 declare function concatArrays<T>(first: NonEmptyReadonlyArray<T> | NonEmptyArray<T>, second: ReadonlyArray<T> | Array<T>): NonEmptyReadonlyArray<T>;
+export declare function concatArrays<T>(first: NonEmptyReadonlyArray<T>, second: ReadonlyArray<T>): NonEmptyReadonlyArray<T>;
 /** Second non-empty. */
-export declare function concatArrays<T>(first: ReadonlyArray<T> | Array<T>, second: NonEmptyReadonlyArray<T> | NonEmptyArray<T>): NonEmptyReadonlyArray<T>;
+export declare function concatArrays<T>(first: ReadonlyArray<T>, second: NonEmptyReadonlyArray<T>): NonEmptyReadonlyArray<T>;
 /** Both possibly empty. */
-export declare function concatArrays<T>(first: ReadonlyArray<T> | Array<T>, second: ReadonlyArray<T> | Array<T>): ReadonlyArray<T>;
+export declare function concatArrays<T>(first: ReadonlyArray<T>, second: ReadonlyArray<T>): ReadonlyArray<T>;
 /**
  * Filters an array using a predicate or refinement function, returning a new
  * readonly array.
@@ -335,60 +422,75 @@ export declare function concatArrays<T>(first: ReadonlyArray<T> | Array<T>, seco
  * 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 declare function filterArray<T, S extends T>(array: ReadonlyArray<T>, refinement: RefinementWithIndex<T, S>): ReadonlyArray<S>;
+export declare function filterArray<T, S extends T>(array: ReadonlyArray<T>, refinement: (item: T, index: number, array: ReadonlyArray<T>) => item is S): ReadonlyArray<S>;
 /** With predicate. */
-export declare function filterArray<T>(array: ReadonlyArray<T>, predicate: PredicateWithIndex<T>): ReadonlyArray<T>;
+export declare function filterArray<T>(array: ReadonlyArray<T>, predicate: (item: T, index: number, array: ReadonlyArray<T>) => boolean): ReadonlyArray<T>;
 /**
- * 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 declare function dedupeArray<T>(array: NonEmptyReadonlyArray<T> | NonEmptyArray<T>, by?: (item: T) => unknown): NonEmptyReadonlyArray<T>;
+export declare function dedupeArray<T>(array: NonEmptyReadonlyArray<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>;
+export declare function dedupeArray<T>(array: ReadonlyArray<T>, by?: (item: T) => unknown): ReadonlyArray<T>;
 /**
  * Partitions an array into two readonly arrays based on a predicate or
  * refinement function.
@@ -400,45 +502,61 @@ export declare function dedupeArray<T>(array: ReadonlyArray<T> | Array<T>, by?:
  * 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 declare function partitionArray<T, S extends T>(array: ReadonlyArray<T>, refinement: RefinementWithIndex<T, S>): readonly [ReadonlyArray<S>, ReadonlyArray<Exclude<T, S>>];
+export declare function partitionArray<T, S extends T>(array: ReadonlyArray<T>, refinement: (item: T, index: number, array: ReadonlyArray<T>) => item is 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>];
+export declare function partitionArray<T>(array: ReadonlyArray<T>, predicate: (item: T, index: number, array: ReadonlyArray<T>) => boolean): readonly [ReadonlyArray<T>, ReadonlyArray<T>];
 /**
  * Returns a new sorted readonly array.
  *
  * 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
@@ -451,10 +569,15 @@ export declare function sortArray<T>(array: ReadonlyArray<T>, compareFn?: (a: 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
@@ -467,11 +590,15 @@ export declare function reverseArray<T>(array: ReadonlyArray<T>): ReadonlyArray<
  *
  * 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
@@ -493,35 +620,49 @@ 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
  */
 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>>>;
+export declare function zipArray<const T extends ReadonlyArray<ReadonlyArray<unknown>>>(arrays: T): ReadonlyArray<Readonly<ZipArrayResult<T>>>;
 /**
  * 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
@@ -530,50 +671,15 @@ export declare const firstInArray: <T>(array: NonEmptyReadonlyArray<T>) => T;
 /**
  * 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 declare const lastInArray: <T>(array: NonEmptyReadonlyArray<T>) => T;
-/**
- * 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 declare const shiftFromArray: <T>(array: NonEmptyArray<T>) => 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 declare const popFromArray: <T>(array: NonEmptyArray<T>) => T;
 //# sourceMappingURL=Array.d.ts.map