@evolu/common 6.0.1-preview.9 → 7.1.0

package/src/Array.ts

@@ -1,39 +1,416 @@
-/** An array with at least one element. */
+/**
+ * Array types, type guards, operations, transformations, accessors, and
+ * mutations
+ *
+ * ### Example
+ *
+ * ```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 (isNonEmptyReadonlyArray(arr)) {
+ *   firstInArray(arr);
+ * }
+ *
+ * // Operations
+ * 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]
+ * const deduped = dedupeArray([1, 2, 1, 3, 2]); // [1, 2, 3]
+ * 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"
+ * const last = lastInArray(["a", "b", "c"]); // "c"
+ *
+ * // Mutations
+ * const mutable: NonEmptyArray<number> = [1, 2, 3];
+ * shiftArray(mutable); // 1 (guaranteed to exist)
+ * mutable; // [2, 3]
+ * ```
+ *
+ * Functions are intentionally data-first to be prepared for the upcoming
+ * JavaScript pipe operator.
+ *
+ * ```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),
+ * );
+ *
+ * // 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);
+ * ```
+ *
+ * ### Why data-first?
+ *
+ * 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:
+ *
+ * - 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.).
+ *
+ * @module
+ */
+
+import { PredicateWithIndex, RefinementWithIndex } from "./Types.js";
+
+/**
+ * An array with at least one element.
+ *
+ * @category Types
+ */
 export type NonEmptyArray<T> = [T, ...Array<T>];
 
-/** Checks if an array is non-empty. */
+/**
+ * A readonly array with at least one element.
+ *
+ * @category Types
+ */
+export type NonEmptyReadonlyArray<T> = readonly [T, ...ReadonlyArray<T>];
+
+/**
+ * Checks if an array is non-empty and narrows its type to {@link NonEmptyArray}.
+ *
+ * Use `if (!isNonEmptyArray(arr))` for empty checks.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const arr: Array<number> = [1, 2, 3];
+ * if (isNonEmptyArray(arr)) {
+ *   firstInArray(arr); // arr is NonEmptyArray<number>
+ * }
+ * ```
+ *
+ * @category Type Guards
+ */
 export const isNonEmptyArray = <T>(
   array: Array<T>,
 ): array is NonEmptyArray<T> => array.length > 0;
 
-/** A readonly array with at least one element. */
-export type NonEmptyReadonlyArray<T> = readonly [T, ...ReadonlyArray<T>];
-
-/** Checks if an array is non-empty. */
+/**
+ * Checks if a readonly array is non-empty and narrows its type to
+ * {@link NonEmptyReadonlyArray}.
+ *
+ * Use `if (!isNonEmptyReadonlyArray(arr))` for empty checks.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const arr: ReadonlyArray<number> = [1, 2, 3];
+ * if (isNonEmptyReadonlyArray(arr)) {
+ *   firstInArray(arr); // arr is NonEmptyReadonlyArray<number>
+ * }
+ * ```
+ *
+ * @category Type Guards
+ */
 export const isNonEmptyReadonlyArray = <T>(
   array: ReadonlyArray<T>,
 ): array is NonEmptyReadonlyArray<T> => array.length > 0;
 
-/** Appends an item to an array returning a non-empty array. */
+/**
+ * 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
+ */
 export const appendToArray = <T>(
-  item: T,
   array: ReadonlyArray<T>,
+  item: T,
 ): NonEmptyReadonlyArray<T> =>
-  [...array, item] as unknown as NonEmptyReadonlyArray<T>;
+  [...array, item] as ReadonlyArray<T> as NonEmptyReadonlyArray<T>;
 
-/** Prepends an item to an array returning a non-empty array. */
+/**
+ * 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
+ */
 export const prependToArray = <T>(
-  item: T,
   array: ReadonlyArray<T>,
-): NonEmptyReadonlyArray<T> =>
-  [item, ...array] as unknown as NonEmptyReadonlyArray<T>;
+  item: T,
+): NonEmptyReadonlyArray<T> => [item, ...array] as NonEmptyReadonlyArray<T>;
 
-/** Maps a non-empty array using a mapper function. */
-export const mapNonEmptyArray = <T, U>(
-  array: NonEmptyReadonlyArray<T>,
+/**
+ * Maps an array using a mapper function.
+ *
+ * Accepts both mutable and readonly arrays. Preserves non-empty type.
+ *
+ * ### Example
+ *
+ * ```ts
+ * mapArray([1, 2, 3], (x) => x * 2); // [2, 4, 6]
+ * ```
+ *
+ * @category Transformations
+ */
+export function mapArray<T, U>(
+  array: NonEmptyReadonlyArray<T> | NonEmptyArray<T>,
   mapper: (item: T, index: number) => U,
-): NonEmptyReadonlyArray<U> =>
-  array.map(mapper) as unknown as NonEmptyReadonlyArray<U>;
+): NonEmptyReadonlyArray<U>;
+export function mapArray<T, U>(
+  array: ReadonlyArray<T> | Array<T>,
+  mapper: (item: T, index: number) => U,
+): ReadonlyArray<U>;
+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>;
+}
+
+/**
+ * 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`.
+ *
+ * ### Examples
+ *
+ * #### With predicate
+ *
+ * ```ts
+ * filterArray([1, 2, 3, 4, 5], (x) => x % 2 === 0); // [2, 4]
+ * ```
+ *
+ * #### With refinement
+ *
+ * ```ts
+ * const mixed: ReadonlyArray<NonEmptyString | PositiveInt> = [
+ *   NonEmptyString.orThrow("hello"),
+ *   PositiveInt.orThrow(42),
+ * ];
+ * const positiveInts = filterArray(mixed, PositiveInt.is);
+ * // positiveInts: ReadonlyArray<PositiveInt> (narrowed type)
+ * ```
+ *
+ * @category Transformations
+ */
+export function filterArray<T, S extends T>(
+  array: ReadonlyArray<T>,
+  refinement: RefinementWithIndex<T, S>,
+): ReadonlyArray<S>;
+export function filterArray<T>(
+  array: ReadonlyArray<T>,
+  predicate: PredicateWithIndex<T>,
+): ReadonlyArray<T>;
+export function filterArray<T>(
+  array: ReadonlyArray<T>,
+  predicate: PredicateWithIndex<T>,
+): ReadonlyArray<T> {
+  return array.filter(predicate) as 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).
+ *
+ * Accepts both mutable and readonly arrays. Does not mutate the original array.
+ * Preserves non-empty type.
+ *
+ * ### Example
+ *
+ * ```ts
+ * // Dedupe primitives by value
+ * dedupeArray([1, 2, 1, 3, 2]); // [1, 2, 3]
+ *
+ * // Dedupe objects by property
+ * 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" }]
+ * ```
+ *
+ * @category Transformations
+ */
+export function dedupeArray<T>(
+  array: NonEmptyReadonlyArray<T> | NonEmptyArray<T>,
+  by?: (item: T) => unknown,
+): NonEmptyReadonlyArray<T>;
+export function dedupeArray<T>(
+  array: ReadonlyArray<T> | Array<T>,
+  by?: (item: T) => unknown,
+): ReadonlyArray<T>;
+export function dedupeArray<T>(
+  array: ReadonlyArray<T>,
+  by?: (item: T) => unknown,
+): ReadonlyArray<T> {
+  if (by == null) {
+    return Array.from(new Set(array)) as ReadonlyArray<T>;
+  }
+
+  const seen = new Set<unknown>();
+  return array.filter((item) => {
+    const key = by(item);
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  }) as ReadonlyArray<T>;
+}
+
+/**
+ * Partitions an array into two 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.
+ *
+ * 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
+ *
+ * #### With predicate
+ *
+ * ```ts
+ * const [evens, odds] = partitionArray(
+ *   [1, 2, 3, 4, 5],
+ *   (x) => x % 2 === 0,
+ * );
+ * evens; // [2, 4]
+ * odds; // [1, 3, 5]
+ * ```
+ *
+ * #### With refinement
+ *
+ * ```ts
+ * const mixed: ReadonlyArray<NonEmptyString | PositiveInt> = [
+ *   NonEmptyString.orThrow("hello"),
+ *   PositiveInt.orThrow(42),
+ * ];
+ * const [positiveInts, strings] = partitionArray(mixed, PositiveInt.is);
+ * // positiveInts: ReadonlyArray<PositiveInt> (narrowed type)
+ * // strings: ReadonlyArray<NonEmptyString> (Exclude<T, PositiveInt>)
+ * ```
+ *
+ * @category Transformations
+ */
+export function partitionArray<T, S extends T>(
+  array: ReadonlyArray<T>,
+  refinement: RefinementWithIndex<T, S>,
+): readonly [ReadonlyArray<S>, ReadonlyArray<Exclude<T, S>>];
+export function partitionArray<T>(
+  array: ReadonlyArray<T>,
+  predicate: PredicateWithIndex<T>,
+): readonly [ReadonlyArray<T>, ReadonlyArray<T>];
+export function partitionArray<T>(
+  array: ReadonlyArray<T>,
+  predicate: PredicateWithIndex<T>,
+): 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)) {
+      trueArray.push(array[i]);
+    } else {
+      falseArray.push(array[i]);
+    }
+  }
+
+  return [trueArray as ReadonlyArray<T>, falseArray as ReadonlyArray<T>];
+}
+
+/**
+ * Returns the first element of a non-empty array.
+ *
+ * Accepts both mutable and readonly arrays. Does not mutate the original array.
+ *
+ * ### Example
+ *
+ * ```ts
+ * firstInArray(["a", "b", "c"]); // "a"
+ * ```
+ *
+ * @category 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
+ */
+export const lastInArray = <T>(array: NonEmptyReadonlyArray<T>): T =>
+  array[array.length - 1];
 
-/** Shifts an item from a non-empty array, guaranteed to return T. */
+/**
+ * Shifts an item from a non-empty mutable array, guaranteed to return T.
+ *
+ * **Mutates** the original array.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const arr: NonEmptyArray<number> = [1, 2, 3];
+ * shiftArray(arr); // 1
+ * arr; // [2, 3]
+ * ```
+ *
+ * @category Mutations
+ */
 export const shiftArray = <T>(array: NonEmptyArray<T>): T => array.shift() as T;

package/src/Assert.ts

@@ -1,17 +1,3 @@
-/**
- * 🚨
- *
- * This module provides assertion utilities to prevent invalid states from
- * propagating through the system by halting execution when a condition fails,
- * improving reliability and debuggability.
- *
- * **Warning**: Do not use this instead of {@link Type}. Assertions are intended
- * for conditions that are logically guaranteed but not statically known by
- * TypeScript, or for catching and signaling developer mistakes eagerly (e.g.,
- * invalid configuration).
- *
- * @module
- */
 import type { Type } from "./Type.js";
 
 /**
@@ -96,24 +82,3 @@ export const assertNonEmptyReadonlyArray: <T>(
 ) => {
   assert(arr.length > 0, message);
 };
-
-/**
- * Asserts no error reaches a `.catch` block, throwing a developer error if it
- * does. Used in Promise chains where errors indicate bugs to be fixed.
- *
- * ### Example
- *
- * ```ts
- * Promise.reject("test").catch((e) =>
- *   assertNoErrorInCatch("WebSocket retry", e),
- * );
- * ```
- */
-export function assertNoErrorInCatch(context: string, error: unknown): never {
-  throw Object.assign(
-    new Error(
-      `Error in ${context}: an unexpected error reached a catch block and requires a fix`,
-    ),
-    { cause: error },
-  );
-}

package/src/Brand.ts

@@ -0,0 +1,75 @@
+/**
+ * A utility interface for creating branded types.
+ *
+ * Branded types enhance type safety by differentiating otherwise identical base
+ * types, such as `number` or `string`, to enforce stricter type checks.
+ *
+ * Supports multiple brands, allowing types to act like flags.
+ *
+ * ### Example 1: Single Brand
+ *
+ * ```ts
+ * // A branded type definition
+ * type UserId = number & Brand<"UserId">;
+ *
+ * // A function that creates `UserId` values.
+ * // Casting with `as UserId` is unsafe, so `createUserId` must be unit-tested.
+ * const createUserId = (): UserId => {
+ *   return 123 as UserId; // Unsafe casting
+ * };
+ *
+ * const userId = createUserId();
+ *
+ * // A function that accepts only `UserId`.
+ * const getUser = (id: UserId) => {
+ *   // Implementation
+ * };
+ *
+ * getUser(userId); // ✅ Valid
+ * getUser(123); // ❌ TypeScript error
+ * getUser("123"); // ❌ TypeScript error
+ * ```
+ *
+ * ### Example 2: Multiple Brands
+ *
+ * ```ts
+ * // Define branded types
+ * type Min1 = string & Brand<"Min1">;
+ * type Max100 = string & Brand<"Max100">;
+ * type Min1Max100 = string & Brand<"Min1" | "Max100">;
+ *
+ * // Functions requiring specific brands
+ * const requiresMin1 = (value: Min1): void => {};
+ * const requiresMax100 = (value: Max100): void => {};
+ *
+ * // Values with single brands
+ * const min1Value: Min1 = "hello" as Min1;
+ * const max100Value: Max100 = "world" as Max100;
+ *
+ * // Value with multiple brands
+ * const min1Max100Value: Min1Max100 = "typescript" as Min1Max100;
+ *
+ * // Valid cases
+ * requiresMin1(min1Value); // ✅ Valid
+ * requiresMax100(max100Value); // ✅ Valid
+ * requiresMin1(min1Max100Value); // ✅ Valid: Min1Max100 satisfies Min1
+ * requiresMax100(min1Max100Value); // ✅ Valid: Min1Max100 satisfies Max100
+ * ```
+ */
+export interface Brand<B extends string> {
+  readonly [__brand]: Readonly<Record<B, true>>;
+}
+
+declare const __brand: unique symbol;
+
+/**
+ * Determines whether a type `T` is a branded type.
+ *
+ * Works with any base type intersected with a `Brand`.
+ *
+ * ### Example
+ *
+ * - `IsBranded<string>` -> false
+ * - `IsBranded<string & Brand<"X">>` -> true
+ */
+export type IsBranded<T> = T extends Brand<string> ? true : false;

package/src/Buffer.ts

@@ -6,7 +6,7 @@ export {
   concatBytes,
   hexToBytes,
   utf8ToBytes,
-} from "@noble/ciphers/utils";
+} from "@noble/ciphers/utils.js";
 
 /**
  * Custom error for {@link Buffer}-related failures like premature end of data.
@@ -116,10 +116,10 @@ export const createBuffer = (
   let value = arrayLike
     ? new globalThis.Uint8Array(arrayLike)
     : new globalThis.Uint8Array(512);
-  let length = (arrayLike ? arrayLike.length : 0) as NonNegativeInt;
+  let length = NonNegativeInt.orThrow(arrayLike ? arrayLike.length : 0);
 
   const buffer: Buffer = {
-    getCapacity: () => value.length as NonNegativeInt,
+    getCapacity: () => NonNegativeInt.orThrow(value.length),
 
     getLength: () => length,
 
@@ -132,7 +132,7 @@ export const createBuffer = (
         value.set(oldValue);
       }
       value.set(arg, length);
-      length = (length + arg.length) as NonNegativeInt;
+      length = NonNegativeInt.orThrow(length + arg.length);
     },
 
     shift: () => {
@@ -142,7 +142,7 @@ export const createBuffer = (
       const first = value[0];
       value = value.subarray(1);
       length--;
-      return first as NonNegativeInt;
+      return NonNegativeInt.orThrow(first);
     },
 
     shiftN: (n) => {
@@ -151,7 +151,7 @@ export const createBuffer = (
       }
       const subarray = value.subarray(0, n);
       value = value.subarray(n);
-      length = (length - n) as NonNegativeInt;
+      length = NonNegativeInt.orThrow(length - n);
       return subarray;
     },
 
@@ -165,7 +165,7 @@ export const createBuffer = (
     },
 
     reset: () => {
-      length = 0 as NonNegativeInt;
+      length = NonNegativeInt.orThrow(0);
     },
 
     unwrap: () => value.subarray(0, length),

package/src/Cache.ts

@@ -0,0 +1,79 @@
+import { PositiveInt } from "./Type.js";
+
+/**
+ * Generic cache interface providing basic key-value storage operations.
+ *
+ * Keys are compared by reference (standard Map semantics).
+ *
+ * Note: Cache does not extend Map because eviction policies (like in LRU)
+ * violate the Liskov Substitution Principle.
+ */
+export interface Cache<K, V> {
+  /** Checks if a key exists in the cache. */
+  has: (key: K) => boolean;
+
+  /** Retrieves the value for a key, or undefined if not present. */
+  get: (key: K) => V | undefined;
+
+  /** Stores a key-value pair in the cache. */
+  set: (key: K, val: V) => void;
+
+  /** Removes a key from the cache. */
+  delete: (key: K) => void;
+
+  /** Returns a readonly view of the internal Map. */
+  readonly map: ReadonlyMap<K, V>;
+}
+
+/**
+ * Creates an LRU (least recently used) cache with a maximum capacity.
+ *
+ * When the cache reaches capacity, the least recently used entry is evicted.
+ * Both `get` and `set` operations update the access order.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const cache = createLruCache<string, number>(2);
+ * cache.set("a", 1);
+ * cache.set("b", 2);
+ * cache.set("c", 3); // Evicts "a"
+ * cache.has("a"); // false
+ * ```
+ */
+export const createLruCache = <K, V>(capacity: PositiveInt): Cache<K, V> => {
+  const internalMap = new Map<K, V>();
+
+  return {
+    has: (key) => internalMap.has(key),
+
+    get: (key) => {
+      const value = internalMap.get(key);
+      if (value === undefined) return undefined;
+
+      // Move to end (most recently used)
+      internalMap.delete(key);
+      internalMap.set(key, value);
+      return value;
+    },
+
+    set: (key, val) => {
+      // If key exists, delete it first to update order
+      if (internalMap.has(key)) {
+        internalMap.delete(key);
+      } else if (internalMap.size === capacity) {
+        // Evict least recently used (first entry)
+        const firstKey = internalMap.keys().next().value as K;
+        internalMap.delete(firstKey);
+      }
+
+      internalMap.set(key, val);
+    },
+
+    delete: (key) => {
+      internalMap.delete(key);
+    },
+
+    map: internalMap,
+  };
+};