@evolu/common 6.0.1-preview.9 → 7.0.0

package/src/Array.ts

@@ -1,39 +1,321 @@
-/** An array with at least one element. */
+/**
+ * 🔒 Type-safe array helpers that do not mutate
+ *
+ * Array types, guards, operations, transformations, accessors, and (rare)
+ * mutations.
+ *
+ * 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.).
+ *
+ * ### 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> = [];
+ *
+ * // 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]
+ *
+ * // 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]
+ * ```
+ *
+ * @module
+ */
+
+/**
+ * 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. Does not mutate the original array.
+ * 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 function, returning a new readonly array.
+ *
+ * Accepts both mutable and readonly arrays. Does not mutate the original array.
+ *
+ * ### Example
+ *
+ * ```ts
+ * filterArray([1, 2, 3, 4, 5], (x) => x % 2 === 0); // [2, 4]
+ * ```
+ *
+ * @category Transformations
+ */
+export const filterArray = <T>(
+  array: ReadonlyArray<T>,
+  predicate: (item: T, index: number) => boolean,
+): ReadonlyArray<T> => 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>;
+}
+
+/**
+ * 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

@@ -96,24 +96,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`.
+ *
+ * ### Examples
+ *
+ * - `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,85 @@
+/**
+ * 🗄️ Generic cache interface and LRU cache implementation.
+ *
+ * @module
+ */
+
+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 a Least Recently Used (LRU) 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,
+  };
+};

package/src/Callbacks.ts

@@ -1,43 +1,83 @@
-import { NanoIdLibDep } from "./NanoId.js";
-import { Brand } from "./Types.js";
+import { Brand } from "./Brand.js";
+import { RandomBytesDep } from "./Crypto.js";
+import { Result } from "./Result.js";
+import { createId, Id } from "./Type.js";
 
 /**
- * Manages one-time callback functions.
+ * Request-response correlation for callbacks across boundaries.
  *
- * Allows registering callbacks with a unique ID and executing them once with an
- * optional argument. Executed callbacks are automatically removed.
+ * Stores callbacks with unique IDs and executes them once with an optional
+ * argument. Executed callbacks are automatically removed.
  *
- * This is useful for managing event-driven or asynchronous workflows where
- * callbacks need to be invoked only once.
+ * This is useful for correlating asynchronous request-response operations
+ * across boundaries where callback functions cannot be passed directly (e.g.,
+ * web workers, message queues).
+ *
+ * The `execute` method intentionally does not use try-catch or {@link Result}
+ * because it's the callback's responsibility to handle its own errors.
+ *
+ * ### Example
+ *
+ * ```ts
+ * // No-argument callbacks
+ * const callbacks = createCallbacks(deps);
+ * const id = callbacks.register(() => console.log("called"));
+ * callbacks.execute(id);
+ *
+ * // With argument callbacks
+ * const stringCallbacks = createCallbacks<string>(deps);
+ * const id = stringCallbacks.register((value) => {
+ *   console.log(value);
+ * });
+ * stringCallbacks.execute(id, "hello");
+ *
+ * // Promise.withResolvers pattern
+ * const promiseCallbacks = createCallbacks<string>(deps);
+ * const { promise, resolve } = Promise.withResolvers<string>();
+ * const id = promiseCallbacks.register(resolve);
+ * promiseCallbacks.execute(id, "resolved value");
+ * await promise; // "resolved value"
+ * ```
+ *
+ * @template T - The type of argument passed to callbacks (defaults to undefined
+ *   for no-argument callbacks)
  */
-export interface Callbacks {
+export interface Callbacks<T = undefined> {
   /** Registers a callback function and returns a unique ID. */
-  readonly register: (callback: (arg?: unknown) => void) => CallbackId;
+  readonly register: (callback: (arg: T) => void) => CallbackId;
 
   /** Executes and removes a callback associated with the given ID. */
-  readonly execute: (id: CallbackId, arg?: unknown) => void;
+  readonly execute: T extends undefined
+    ? (id: CallbackId) => undefined
+    : (id: CallbackId, arg: T) => undefined;
 }
 
-export type CallbackId = string & Brand<"CallbackId">;
+/** Unique identifier for a callback in {@link Callbacks}. */
+export type CallbackId = Id & Brand<"Callback">;
 
-export const createCallbacks = (deps: NanoIdLibDep): Callbacks => {
-  const callbackMap = new Map<CallbackId, (arg?: unknown) => void>();
+/** Creates a new {@link Callbacks}. */
+export const createCallbacks = <T = undefined>(
+  deps: RandomBytesDep,
+): Callbacks<T> => {
+  const callbackMap = new Map<CallbackId, (arg: T) => void>();
 
-  const callbacks: Callbacks = {
+  return {
     register: (callback) => {
-      const id = deps.nanoIdLib.nanoid() as CallbackId;
+      const id = createId<"Callback">(deps);
       callbackMap.set(id, callback);
       return id;
     },
 
-    execute: (id, arg) => {
+    execute: (id: CallbackId, ...args: T extends undefined ? [] : [T]) => {
       const callback = callbackMap.get(id);
-      if (callback) {
-        callbackMap.delete(id);
-        callback(arg);
+      if (!callback) return;
+      callbackMap.delete(id);
+      if (args.length === 0) {
+        // Called without argument (undefined case)
+        (callback as () => void)();
+      } else {
+        callback(args[0]);
       }
     },
-  };
-
-  return callbacks;
+  } as Callbacks<T>;
 };