@evolu/common 8.4.0 → 8.6.0

package/src/Array.ts

@@ -16,13 +16,16 @@
  * to track:
  *
  * ```ts
- * const sortScores = (arr: number[]) => arr.sort((a, b) => a - b);
+ * import { assertEqual, assertSame } from "@evolu/common";
+ *
+ * // oxlint-disable-next-line unicorn/no-array-sort -- This example intentionally demonstrates mutating Array.sort.
+ * const sortScores = (arr: Array<number>) => arr.sort((a, b) => a - b);
  *
  * const scores = [3, 1, 2];
  * const leaderboard = sortScores(scores);
- * expect(leaderboard).toEqual([1, 2, 3]);
- * expect(scores).toEqual([1, 2, 3]);
- * expect(leaderboard).toBe(scores);
+ * assertEqual(leaderboard, [1, 2, 3]);
+ * assertEqual(scores, [1, 2, 3]);
+ * assertSame(leaderboard, scores);
  * ```
  *
  * Imagine every method doing that.
@@ -31,30 +34,35 @@
  * instead:
  *
  * ```ts
- * import { sortArray } from "@evolu/common";
+ * import { assertEqual, assertTrue, 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);
- * expect(leaderboard).toEqual([1, 2, 3]);
- * expect(scores).toEqual([3, 1, 2]);
- * expect(leaderboard).not.toBe(scores);
+ * assertEqual(leaderboard, [1, 2, 3]);
+ * assertEqual(scores, [3, 1, 2]);
+ * assertTrue(leaderboard !== 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";
+ * import {
+ *   assertEqual,
+ *   assertType,
+ *   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>>();
+ * assertEqual(leaderboard, [1, 2, 3]);
+ * assertType<NonEmptyReadonlyArray<number>, typeof leaderboard>();
  * ```
  *
  * Sorting an empty array isn't expensive, but functions can have side effects
@@ -68,13 +76,16 @@
  * readonly arrays without mutation — use them directly.
  *
  * ```ts
- * import { type NonEmptyReadonlyArray } from "@evolu/common";
+ * import { assertEqual, type NonEmptyReadonlyArray } from "@evolu/common";
  *
  * const valid: NonEmptyReadonlyArray<number> = [1, 2, 3];
  * // @ts-expect-error An empty array is not non-empty.
- * const invalid: NonEmptyReadonlyArray<number> = [];
+ * const _invalid: NonEmptyReadonlyArray<number> = [];
  *
- * expect(valid.find((value) => value === 2)).toBe(2);
+ * assertEqual(
+ *   valid.find((value) => value === 2),
+ *   2,
+ * );
  * ```
  *
  * ## Composition
@@ -83,7 +94,7 @@
  * because it's natural for single operations:
  *
  * ```ts
- * import { mapArray } from "@evolu/common";
+ * import { assertEqual, mapArray } from "@evolu/common";
  *
  * interface Message {
  *   readonly timestamp: number;
@@ -94,7 +105,7 @@
  *   { timestamp: 20 },
  * ];
  * const timestamps = mapArray(messages, (m) => m.timestamp);
- * expect(timestamps).toEqual([10, 20]);
+ * assertEqual(timestamps, [10, 20]);
  * ```
  *
  * Data-first style also reads well for a few operations, often fitting on a
@@ -102,6 +113,7 @@
  *
  * ```ts
  * import {
+ *   assertEqual,
  *   dedupeArray,
  *   filterArray,
  *   firstInArray,
@@ -113,11 +125,11 @@
  * } from "@evolu/common";
  *
  * const cheapest = firstInArray(sortArray([30, 10, 20], orderNumber));
- * expect(cheapest).toBe(10);
+ * assertEqual(cheapest, 10);
  *
  * const users = [{ name: "Ada" }, { name: "Linus" }, { name: "Ada" }];
  * const uniqueNames = dedupeArray(mapArray(users, (u) => u.name));
- * expect(uniqueNames).toEqual(["Ada", "Linus"]);
+ * assertEqual(uniqueNames, ["Ada", "Linus"]);
  *
  * const jobs = [
  *   { id: 1, done: false },
@@ -127,7 +139,7 @@
  * if (!isNonEmptyArray(completedJobs)) throw new Error("Expected a job");
  * const latestDone = lastInArray(completedJobs);
  *
- * expect(latestDone).toEqual({ id: 2, done: true });
+ * assertEqual(latestDone, { id: 2, done: true });
  * ```
  *
  * For more operations, create a function like `getOldestActiveUser` or a
@@ -175,6 +187,37 @@ export type AtLeastTwoReadonlyArray<T> = readonly [T, T, ...ReadonlyArray<T>];
  */
 export const emptyArray: ReadonlyArray<never> = [];
 
+/**
+ * Creates a mutable sparse Array with the specified length.
+ *
+ * Use it to build an Array with indexed writes when its final length is known.
+ * Assign every index before exposing the completed Array as readonly.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import {
+ *   assertEqual,
+ *   assertType,
+ *   createMutableArray,
+ * } from "@evolu/common";
+ *
+ * const values = createMutableArray<number>(3);
+ *
+ * for (let index = 0; index < values.length; index++) {
+ *   values[index] = index * 10;
+ * }
+ *
+ * assertEqual(values, [0, 10, 20]);
+ * assertType<Array<number>, typeof values>();
+ * ```
+ *
+ * @group Constructors
+ */
+export const createMutableArray = <T>(length: number): Array<T> =>
+  // oxlint-disable-next-line unicorn/no-new-array -- Intentionally preallocates a sparse mutable Array.
+  new Array<T>(length);
+
 /**
  * Better `Array.from`.
  *
@@ -186,16 +229,24 @@ export const emptyArray: ReadonlyArray<never> = [];
  * ### Creating from iterables and lengths
  *
  * ```ts
- * import { arrayFrom } from "@evolu/common";
+ * import {
+ *   assertEqual,
+ *   assertSame,
+ *   assertType,
+ *   arrayFrom,
+ * } from "@evolu/common";
  *
  * const fromSet = arrayFrom(new Set([1, 2, 3]));
- * expect(fromSet).toEqual([1, 2, 3]);
- * expectTypeOf(fromSet).toEqualTypeOf<ReadonlyArray<number>>();
+ * assertEqual(fromSet, [1, 2, 3]);
+ * assertType<ReadonlyArray<number>, typeof fromSet>();
  *
- * expect(arrayFrom(3, (i) => i * 10)).toEqual([0, 10, 20]);
+ * assertEqual(
+ *   arrayFrom(3, (i) => i * 10),
+ *   [0, 10, 20],
+ * );
  *
  * const existing: ReadonlyArray<number> = [1, 2, 3];
- * expect(arrayFrom(existing)).toBe(existing);
+ * assertSame(arrayFrom(existing), existing);
  * ```
  *
  * Unlike `Array.from`, there's no map parameter for iterables — use
@@ -234,19 +285,24 @@ export function arrayFrom<T>(
  * ### Awaiting sync and async iterables
  *
  * ```ts
- * import { arrayFromAsync } from "@evolu/common";
+ * import { assertEqual, assertType, arrayFromAsync } from "@evolu/common";
  *
- * const fromIterable = await arrayFromAsync(new Set([1, 2, 3]));
- * expect(fromIterable).toEqual([1, 2, 3]);
+ * const fromIterable = await arrayFromAsync([
+ *   Promise.resolve(1),
+ *   Promise.resolve(2),
+ *   Promise.resolve(3),
+ * ]);
+ * assertEqual(fromIterable, [1, 2, 3]);
  *
  * const fromAsyncIterable = await arrayFromAsync(
- *   (async function* () {
- *     yield Promise.resolve(1);
- *     yield Promise.resolve(2);
+ *   (async function* (): AsyncGenerator<number> {
+ *     await Promise.resolve();
+ *     yield 1;
+ *     yield 2;
  *   })(),
  * );
- * expect(fromAsyncIterable).toEqual([1, 2]);
- * expectTypeOf(fromAsyncIterable).toEqualTypeOf<ReadonlyArray<number>>();
+ * assertEqual(fromAsyncIterable, [1, 2]);
+ * assertType<ReadonlyArray<number>, typeof fromAsyncIterable>();
  * ```
  *
  * Unlike `Array.fromAsync`, there's no map parameter — map the result with
@@ -272,6 +328,8 @@ export const arrayFromAsync = async <T>(
  *
  * ```ts
  * import {
+ *   assertEqual,
+ *   assertType,
  *   firstInArray,
  *   isNonEmptyArray,
  *   type NonEmptyArray,
@@ -284,9 +342,9 @@ export const arrayFromAsync = async <T>(
  *   throw new Error("Expected values");
  * }
  *
- * expectTypeOf(mutable).toEqualTypeOf<NonEmptyArray<number>>();
- * expectTypeOf(readonly).toEqualTypeOf<NonEmptyReadonlyArray<number>>();
- * expect(firstInArray(readonly)).toBe(1);
+ * assertType<NonEmptyArray<number>, typeof mutable>();
+ * assertType<NonEmptyReadonlyArray<number>, typeof readonly>();
+ * assertEqual(firstInArray(readonly), 1);
  * ```
  *
  * @group Types
@@ -309,13 +367,15 @@ export function isNonEmptyArray<T>(
  *
  * ```ts
  * import {
+ *   assertEqual,
+ *   assertType,
  *   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>>();
+ * assertEqual(values, [1, 2, 3, 4]);
+ * assertType<NonEmptyReadonlyArray<number>, typeof values>();
  * ```
  *
  * @group Transformations
@@ -335,13 +395,15 @@ export const appendToArray = <T>(
  *
  * ```ts
  * import {
+ *   assertEqual,
+ *   assertType,
  *   prependToArray,
  *   type NonEmptyReadonlyArray,
  * } from "@evolu/common";
  *
  * const values = prependToArray([2, 3], 1);
- * expect(values).toEqual([1, 2, 3]);
- * expectTypeOf(values).toEqualTypeOf<NonEmptyReadonlyArray<number>>();
+ * assertEqual(values, [1, 2, 3]);
+ * assertType<NonEmptyReadonlyArray<number>, typeof values>();
  * ```
  *
  * @group Transformations
@@ -359,17 +421,21 @@ export const prependToArray = <T>(
  * ### Mapping with indexes while preserving non-emptiness
  *
  * ```ts
- * import { mapArray, type NonEmptyReadonlyArray } from "@evolu/common";
+ * import {
+ *   assertEqual,
+ *   assertType,
+ *   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>>();
+ * assertEqual(indexed, [1, 3, 5]);
+ * assertType<ReadonlyArray<number>, typeof indexed>();
  *
  * const nonEmpty: NonEmptyReadonlyArray<number> = [1, 2, 3];
- * expectTypeOf(mapArray(nonEmpty, (x) => x * 2)).toEqualTypeOf<
- *   NonEmptyReadonlyArray<number>
- * >();
+ * const doubled = mapArray(nonEmpty, (x) => x * 2);
+ * assertType<NonEmptyReadonlyArray<number>, typeof doubled>();
  * ```
  *
  * The mapper receives `(item, index, array)`, matching native `Array.map`.
@@ -402,7 +468,12 @@ export function mapArray<T, U>(
  * ### Flattening and expanding values
  *
  * ```ts
- * import { flatMapArray, type NonEmptyReadonlyArray } from "@evolu/common";
+ * import {
+ *   assertEqual,
+ *   assertType,
+ *   flatMapArray,
+ *   type NonEmptyReadonlyArray,
+ * } from "@evolu/common";
  *
  * const flattened = flatMapArray([
  *   [1, 2],
@@ -413,9 +484,9 @@ export function mapArray<T, U>(
  *   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]);
+ * assertEqual(flattened, [1, 2, 3, 4]);
+ * assertType<NonEmptyReadonlyArray<number>, typeof expanded>();
+ * assertEqual(expanded, [1, 0, 2, 1, 3, 2]);
  * ```
  *
  * ### Filter and map in one pass
@@ -423,7 +494,7 @@ export function mapArray<T, U>(
  * Return `[]` to filter out, `[value]` to keep:
  *
  * ```ts
- * import { err, flatMapArray, ok } from "@evolu/common";
+ * import { assertEqual, err, flatMapArray, ok } from "@evolu/common";
  *
  * const validate = (value: number) =>
  *   value > 0 ? ok(value) : err(`${value} is not positive`);
@@ -432,7 +503,7 @@ export function mapArray<T, U>(
  *   const result = validate(f);
  *   return result.ok ? [] : [result.error];
  * });
- * expect(errors).toEqual(["-2 is not positive", "-4 is not positive"]);
+ * assertEqual(errors, ["-2 is not positive", "-4 is not positive"]);
  * ```
  *
  * The mapper receives `(item, index, array)`, matching native `Array.flatMap`.
@@ -483,16 +554,21 @@ export function flatMapArray<T, U>(
  * ### Concatenating non-empty inputs
  *
  * ```ts
- * import { concatArrays, type NonEmptyReadonlyArray } from "@evolu/common";
+ * import {
+ *   assertEqual,
+ *   assertType,
+ *   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>>();
+ * assertEqual(joined, [1, 2, 3, 4]);
+ * assertType<NonEmptyReadonlyArray<number>, typeof fromLeft>();
+ * assertType<NonEmptyReadonlyArray<number>, typeof fromRight>();
  * ```
  *
  * @group Transformations
@@ -529,16 +605,18 @@ export function concatArrays<T>(
  * ### With predicate
  *
  * ```ts
- * import { filterArray } from "@evolu/common";
+ * import { assertEqual, filterArray } from "@evolu/common";
  *
  * const evens = filterArray([1, 2, 3, 4, 5], (x) => x % 2 === 0);
- * expect(evens).toEqual([2, 4]);
+ * assertEqual(evens, [2, 4]);
  * ```
  *
  * ### With refinement
  *
  * ```ts
  * import {
+ *   assertEqual,
+ *   assertType,
  *   filterArray,
  *   NonEmptyTrimmedString,
  *   PositiveInt,
@@ -549,8 +627,8 @@ export function concatArrays<T>(
  *   PositiveInt.orThrow(42),
  * ];
  * const positiveInts = filterArray(mixed, PositiveInt.is);
- * expect(positiveInts).toEqual([42]);
- * expectTypeOf(positiveInts).toEqualTypeOf<ReadonlyArray<PositiveInt>>();
+ * assertEqual(positiveInts, [42]);
+ * assertType<ReadonlyArray<PositiveInt>, typeof positiveInts>();
  * ```
  *
  * The predicate receives `(item, index, array)`, matching native
@@ -584,7 +662,12 @@ export function filterArray<T>(
  * ### Deduplicating by value or key
  *
  * ```ts
- * import { dedupeArray, type NonEmptyReadonlyArray } from "@evolu/common";
+ * import {
+ *   assertEqual,
+ *   assertType,
+ *   dedupeArray,
+ *   type NonEmptyReadonlyArray,
+ * } from "@evolu/common";
  *
  * const numbers = dedupeArray([1, 2, 1, 3, 2]);
  * const people = dedupeArray(
@@ -595,9 +678,9 @@ export function filterArray<T>(
  *   ],
  *   (item) => item.id,
  * );
- * expectTypeOf(numbers).toEqualTypeOf<NonEmptyReadonlyArray<number>>();
- * expect(numbers).toEqual([1, 2, 3]);
- * expect(people).toEqual([
+ * assertType<NonEmptyReadonlyArray<number>, typeof numbers>();
+ * assertEqual(numbers, [1, 2, 3]);
+ * assertEqual(people, [
  *   { id: 1, name: "Alice" },
  *   { id: 2, name: "Bob" },
  * ]);
@@ -645,20 +728,22 @@ export function dedupeArray<T>(
  * ### With predicate
  *
  * ```ts
- * import { partitionArray } from "@evolu/common";
+ * import { assertEqual, partitionArray } from "@evolu/common";
  *
  * const [evens, odds] = partitionArray(
  *   [1, 2, 3, 4, 5],
  *   (x) => x % 2 === 0,
  * );
- * expect(evens).toEqual([2, 4]);
- * expect(odds).toEqual([1, 3, 5]);
+ * assertEqual(evens, [2, 4]);
+ * assertEqual(odds, [1, 3, 5]);
  * ```
  *
  * ### With refinement
  *
  * ```ts
  * import {
+ *   assertEqual,
+ *   assertType,
  *   NonEmptyTrimmedString,
  *   partitionArray,
  *   PositiveInt,
@@ -669,11 +754,9 @@ export function dedupeArray<T>(
  *   PositiveInt.orThrow(42),
  * ];
  * const [positiveInts, strings] = partitionArray(mixed, PositiveInt.is);
- * expect(positiveInts).toEqual([42]);
- * expectTypeOf(positiveInts).toEqualTypeOf<ReadonlyArray<PositiveInt>>();
- * expectTypeOf(strings).toEqualTypeOf<
- *   ReadonlyArray<NonEmptyTrimmedString>
- * >();
+ * assertEqual(positiveInts, [42]);
+ * assertType<ReadonlyArray<PositiveInt>, typeof positiveInts>();
+ * assertType<ReadonlyArray<NonEmptyTrimmedString>, typeof strings>();
  * ```
  *
  * The predicate receives `(item, index, array)`.
@@ -715,12 +798,17 @@ export function partitionArray<T>(
  * ### Sorting without mutation
  *
  * ```ts
- * import { sortArray, type NonEmptyReadonlyArray } from "@evolu/common";
+ * import {
+ *   assertEqual,
+ *   assertType,
+ *   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>>();
+ * assertEqual(sorted, [1, 2, 3]);
+ * assertType<NonEmptyReadonlyArray<number>, typeof sorted>();
  * ```
  *
  * @group Transformations
@@ -749,12 +837,17 @@ export function sortArray<T>(
  * ### Reversing without mutation
  *
  * ```ts
- * import { reverseArray, type NonEmptyReadonlyArray } from "@evolu/common";
+ * import {
+ *   assertEqual,
+ *   assertType,
+ *   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>>();
+ * assertEqual(reversed, [3, 2, 1]);
+ * assertType<NonEmptyReadonlyArray<number>, typeof reversed>();
  * ```
  *
  * @group Transformations
@@ -776,12 +869,12 @@ export function reverseArray<T>(array: ReadonlyArray<T>): ReadonlyArray<T> {
  * ### Removing and replacing values
  *
  * ```ts
- * import { spliceArray } from "@evolu/common";
+ * import { assertEqual, 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]);
+ * assertEqual(spliceArray(values, 1, 2), [1, 4]);
+ * assertEqual(spliceArray([1, 2, 3], 1, 1, 10, 11), [1, 10, 11, 3]);
+ * assertEqual(values, [1, 2, 3, 4]);
  * ```
  *
  * @group Transformations
@@ -813,29 +906,36 @@ export type ZipArrayResult<T extends ReadonlyArray<ReadonlyArray<unknown>>> = {
  * ### Zipping to the shortest input
  *
  * ```ts
- * import { zipArray, type NonEmptyReadonlyArray } from "@evolu/common";
+ * import {
+ *   assertEqual,
+ *   assertType,
+ *   zipArray,
+ *   type NonEmptyReadonlyArray,
+ * } from "@evolu/common";
  *
  * const pairs = zipArray([
  *   [1, 2, 3],
  *   ["a", "b", "c"],
  * ]);
- * expect(pairs).toEqual([
+ * assertEqual(pairs, [
  *   [1, "a"],
  *   [2, "b"],
  *   [3, "c"],
  * ]);
- * expect(
+ * assertEqual(
  *   zipArray([
  *     [1, 2],
  *     ["a", "b", "c"],
  *     [true, false],
  *   ]),
- * ).toEqual([
- *   [1, "a", true],
- *   [2, "b", false],
- * ]);
- * expectTypeOf(pairs).toEqualTypeOf<
- *   NonEmptyReadonlyArray<Readonly<[number, string]>>
+ *   [
+ *     [1, "a", true],
+ *     [2, "b", false],
+ *   ],
+ * );
+ * assertType<
+ *   NonEmptyReadonlyArray<Readonly<[number, string]>>,
+ *   typeof pairs
  * >();
  * ```
  *
@@ -854,7 +954,7 @@ export function zipArray<T extends ReadonlyArray<ReadonlyArray<unknown>>>(
   if (arrays.length === 0) return emptyArray;
 
   const minLength = Math.min(...mapArray(arrays, (a) => a.length));
-  const result = new Array<unknown>(minLength);
+  const result = createMutableArray<unknown>(minLength);
 
   for (let i = 0; i < minLength; i++) {
     result[i] = mapArray(arrays, (a) => a[i]);
@@ -869,9 +969,9 @@ export function zipArray<T extends ReadonlyArray<ReadonlyArray<unknown>>>(
  * ### Reading the first value
  *
  * ```ts
- * import { firstInArray } from "@evolu/common";
+ * import { assertEqual, firstInArray } from "@evolu/common";
  *
- * expect(firstInArray(["a", "b", "c"])).toBe("a");
+ * assertEqual(firstInArray(["a", "b", "c"]), "a");
  * ```
  *
  * @group Accessors
@@ -884,9 +984,9 @@ export const firstInArray = <T>(array: NonEmptyReadonlyArray<T>): T => array[0];
  * ### Reading the last value
  *
  * ```ts
- * import { lastInArray } from "@evolu/common";
+ * import { assertEqual, lastInArray } from "@evolu/common";
  *
- * expect(lastInArray(["a", "b", "c"])).toBe("c");
+ * assertEqual(lastInArray(["a", "b", "c"]), "c");
  * ```
  *
  * @group Accessors