@evolu/common 7.4.0 → 8.0.0-next.0

package/src/Crypto.ts

@@ -1,18 +1,29 @@
 /**
- * Cryptographic utilities
+ * Cryptographic utilities.
  *
- * Type-safe cryptographic operations including random number generation, SLIP21
+ * Type-safe cryptographic operations including random bytes generation, SLIP21
  * key derivation, XChaCha20-Poly1305 symmetric encryption, PADMÉ padding, and
  * timing-safe comparisons.
  *
  * @module
  */
+
 import { xchacha20poly1305 } from "@noble/ciphers/chacha.js";
 import { hmac } from "@noble/hashes/hmac.js";
 import { sha512 } from "@noble/hashes/sha2.js";
 import { randomBytes, utf8ToBytes } from "@noble/hashes/utils.js";
-import { Result, trySync } from "./Result.js";
-import { brand, length, NonNegativeInt, Uint8Array } from "./Type.js";
+import { arrayFrom } from "./Array.js";
+import type { RandomLibDep } from "./Random.js";
+import type { Result } from "./Result.js";
+import { trySync } from "./Result.js";
+import {
+  brand,
+  length,
+  NonNegativeInt,
+  Uint8Array,
+  type Typed,
+  zeroNonNegativeInt,
+} from "./Type.js";
 
 export interface RandomBytes {
   /**
@@ -23,11 +34,12 @@ export interface RandomBytes {
    * generator (crypto.getRandomValues) to generate high-quality entropy
    * suitable for cryptographic operations.
    *
-   * ### Type Safety
+   * ## Type Safety
    *
    * Returns specific branded types for common sizes:
    *
    * - `Random16` for 16-byte values (128 bits)
+   * - `Random24` for 24-byte values (192 bits)
    * - `Random32` for 32-byte values (256 bits)
    * - `Random64` for 64-byte values (512 bits)
    * - `Random` for any other size
@@ -36,12 +48,14 @@ export interface RandomBytes {
    *
    * ```ts
    * const nonce = randomBytes.create(16); // Type: Random16
+   * const nonce24 = randomBytes.create(24); // Type: Random24
    * const key = randomBytes.create(32); // Type: Random32
    * const seed = randomBytes.create(64); // Type: Random64
    * const custom = randomBytes.create(48); // Type: Random
    * ```
    */
   create(bytesLength: 16): Entropy16;
+  create(bytesLength: 24): Entropy24;
   create(bytesLength: 32): Entropy32;
   create(bytesLength: 64): Entropy64;
   create(bytesLength: number): Entropy;
@@ -51,22 +65,34 @@ export interface RandomBytesDep {
   readonly randomBytes: RandomBytes;
 }
 
-const Entropy = brand("Entropy", Uint8Array);
+const Entropy = /*#__PURE__*/ brand("Entropy", Uint8Array);
 type Entropy = typeof Entropy.Type;
 
-export const Entropy16 = length(16)(Entropy);
+export const Entropy16 = /*#__PURE__*/ length(16)(Entropy);
 export type Entropy16 = typeof Entropy16.Type;
 
-export const Entropy32 = length(32)(Entropy);
+export const Entropy24 = /*#__PURE__*/ length(24)(Entropy);
+export type Entropy24 = typeof Entropy24.Type;
+
+export const Entropy32 = /*#__PURE__*/ length(32)(Entropy);
 export type Entropy32 = typeof Entropy32.Type;
 
-export const Entropy64 = length(64)(Entropy);
+export const Entropy64 = /*#__PURE__*/ length(64)(Entropy);
 export type Entropy64 = typeof Entropy64.Type;
 
 export const createRandomBytes = (): RandomBytes => ({
   create: randomBytes as RandomBytes["create"],
 });
 
+/** Creates seeded random bytes for deterministic tests. */
+export const testCreateRandomBytes = (deps: RandomLibDep): RandomBytes =>
+  ({
+    create: (bytesLength: number) => {
+      const array = arrayFrom(bytesLength, () => deps.randomLib.int(0, 255));
+      return new globalThis.Uint8Array(array);
+    },
+  }) as RandomBytes;
+
 /**
  * SLIP21.
  *
@@ -106,71 +132,94 @@ export const deriveSlip21Node = (
   return hmac(sha512, parentNode.slice(0, 32), message) as Entropy64;
 };
 
-/** The encryption key for {@link SymmetricCrypto}. */
-export const EncryptionKey = brand("EncryptionKey", Entropy32);
+/** The encryption key for symmetric encryption. */
+export const EncryptionKey = /*#__PURE__*/ brand("EncryptionKey", Entropy32);
 export type EncryptionKey = typeof EncryptionKey.Type;
 
-/** Symmetric cryptography. */
-export interface SymmetricCrypto {
-  readonly nonceLength: NonNegativeInt;
+/** The nonce length for XChaCha20-Poly1305 encryption. */
+export const xChaCha20Poly1305NonceLength = 24;
 
-  readonly encrypt: (
+/**
+ * Branded Uint8Array for XChaCha20-Poly1305 encryption.
+ *
+ * @see {@link encryptWithXChaCha20Poly1305}
+ */
+export const XChaCha20Poly1305Ciphertext = /*#__PURE__*/ brand(
+  "XChaCha20Poly1305Ciphertext",
+  Uint8Array,
+);
+export type XChaCha20Poly1305Ciphertext =
+  typeof XChaCha20Poly1305Ciphertext.Type;
+
+/**
+ * Encrypts plaintext with XChaCha20-Poly1305.
+ *
+ * Generates a random nonce internally and returns both the ciphertext and
+ * nonce. The nonce must be stored alongside the ciphertext for decryption.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const deps = { randomBytes: createRandomBytes() };
+ * const [ciphertext, nonce] = encryptWithXChaCha20Poly1305(deps)(
+ *   utf8ToBytes("secret message"),
+ *   encryptionKey,
+ * );
+ * ```
+ *
+ * @see https://github.com/paulmillr/noble-ciphers
+ */
+export const encryptWithXChaCha20Poly1305 =
+  (deps: RandomBytesDep) =>
+  (
     plaintext: Uint8Array,
     encryptionKey: EncryptionKey,
-  ) => {
-    readonly nonce: Uint8Array;
-    readonly ciphertext: Uint8Array;
+  ): [XChaCha20Poly1305Ciphertext, Entropy24] => {
+    const nonce = deps.randomBytes.create(xChaCha20Poly1305NonceLength);
+    const ciphertext = XChaCha20Poly1305Ciphertext.orThrow(
+      xchacha20poly1305(encryptionKey, nonce).encrypt(plaintext),
+    );
+    return [ciphertext, nonce];
   };
 
-  readonly decrypt: (
-    ciphertext: Uint8Array,
-    encryptionKey: EncryptionKey,
-    nonce: Uint8Array,
-  ) => Result<Uint8Array, SymmetricCryptoDecryptError>;
-}
-
-export interface SymmetricCryptoDep {
-  readonly symmetricCrypto: SymmetricCrypto;
-}
-
-export interface SymmetricCryptoDecryptError {
-  readonly type: "SymmetricCryptoDecryptError";
+export interface DecryptWithXChaCha20Poly1305Error extends Typed<"DecryptWithXChaCha20Poly1305Error"> {
   readonly error: unknown;
 }
 
 /**
- * XChaCha20-Poly1305 encryption
+ * Decrypts ciphertext with XChaCha20-Poly1305.
+ *
+ * Requires the same nonce that was used during encryption. Returns a
+ * {@link Result} that may contain a decryption error if the ciphertext was
+ * tampered with or the wrong key/nonce was used.
  *
- * https://github.com/paulmillr/noble-ciphers?tab=readme-ov-file#which-cipher-should-i-pick
+ * ### Example
+ *
+ * ```ts
+ * const result = decryptWithXChaCha20Poly1305(
+ *   ciphertext,
+ *   nonce,
+ *   encryptionKey,
+ * );
+ * if (!result.ok) {
+ *   // Handle decryption error
+ *   return result;
+ * }
+ * const plaintext = result.value;
+ * ```
  */
-export const createSymmetricCrypto = (
-  deps: RandomBytesDep,
-): SymmetricCrypto => {
-  const nonceLength = NonNegativeInt.orThrow(24);
-
-  const symmetricCrypto: SymmetricCrypto = {
-    nonceLength,
-
-    encrypt: (plaintext, encryptionKey) => {
-      const nonce = deps.randomBytes.create(nonceLength);
-      const ciphertext = xchacha20poly1305(encryptionKey, nonce).encrypt(
-        plaintext,
-      );
-      return { nonce, ciphertext };
-    },
-
-    decrypt: (ciphertext, encryptionKey, nonce) =>
-      trySync(
-        () => xchacha20poly1305(encryptionKey, nonce).decrypt(ciphertext),
-        (error): SymmetricCryptoDecryptError => ({
-          type: "SymmetricCryptoDecryptError",
-          error,
-        }),
-      ),
-  };
-
-  return symmetricCrypto;
-};
+export const decryptWithXChaCha20Poly1305 = (
+  ciphertext: XChaCha20Poly1305Ciphertext,
+  nonce: Entropy24,
+  encryptionKey: EncryptionKey,
+): Result<Uint8Array, DecryptWithXChaCha20Poly1305Error> =>
+  trySync(
+    () => xchacha20poly1305(encryptionKey, nonce).decrypt(ciphertext),
+    (error): DecryptWithXChaCha20Poly1305Error => ({
+      type: "DecryptWithXChaCha20Poly1305Error",
+      error,
+    }),
+  );
 
 /**
  * Returns the PADMÉ padded length for a given input length.
@@ -183,7 +232,7 @@ export const createSymmetricCrypto = (
 export const createPadmePaddedLength = (
   length: NonNegativeInt,
 ): NonNegativeInt => {
-  if (length <= 0) return NonNegativeInt.orThrow(0);
+  if (length <= 0) return zeroNonNegativeInt;
   const e = 31 - Math.clz32(length >>> 0);
   const s = 32 - Math.clz32(e >>> 0);
   const z = Math.max(0, e - s);

package/src/Eq.ts

@@ -1,5 +1,16 @@
-import { JsonArray, JsonObject, JsonValue, JsonValueInput } from "./Type.js";
-import { Order } from "./Order.js";
+/**
+ * Equality comparison functions and utilities.
+ *
+ * @module
+ */
+
+import type { Order } from "./Order.js";
+import type {
+  JsonArray,
+  JsonObject,
+  JsonValue,
+  JsonValueInput,
+} from "./Type.js";
 
 /**
  * Compares two values of the same type `A` for equality.
@@ -51,6 +62,22 @@ export const createEqArrayLike =
     return true;
   };
 
+/**
+ * Compares two array-like structures by strict reference equality (`===`).
+ *
+ * Useful for structural sharing checks where elements are compared by identity.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const a = { x: 1 };
+ * const b = { x: 1 };
+ * eqArrayStrict([a, a], [a, a]); // true (same references)
+ * eqArrayStrict([a], [b]); // false (different references, even if equal values)
+ * ```
+ */
+export const eqArrayStrict = /*#__PURE__*/ createEqArrayLike(eqStrict);
+
 /**
  * Compares two array-like structures of numbers for equality.
  *
@@ -62,7 +89,7 @@ export const createEqArrayLike =
  * eqArrayNumber([1, 2, 3], [1, 2, 4]); // false
  * ```
  */
-export const eqArrayNumber = createEqArrayLike(eqNumber);
+export const eqArrayNumber = /*#__PURE__*/ createEqArrayLike(eqNumber);
 
 /**
  * Creates an equivalence function for objects based on an equivalence for their

package/src/Error.ts

@@ -1,64 +1,80 @@
 /**
- * A serializable representation of an error for safe transfer between execution
- * contexts, such as Web Workers and the main thread.
+ * Error types and utilities for safe error handling.
  *
- * Use this type for unknown (unexpected) errors that need to be transferred
- * across boundaries where native Error objects cannot be sent directly. Not
- * intended for regular (expected) errors.
+ * @module
+ */
+
+import type { Typed } from "./Type.js";
+
+/**
+ * A wrapper for unknown errors caught at runtime.
+ *
+ * When catching errors from unsafe code (third-party libraries, worker
+ * boundaries, etc.), we wrap them in `UnknownError` so they can be used in
+ * union types and distinguished from other error types.
  *
- * The `error` property contains a plain object with error details, a string, or
- * a fallback value if serialization fails to preserve as much debugging
- * information as possible.
+ * The `error` property contains error details (including `message`, `stack`,
+ * and `cause` if available), a string, or a fallback value.
+ *
+ * Use {@link createUnknownError} to create instances.
  */
-export interface TransferableError {
-  readonly type: "TransferableError";
+export interface UnknownError extends Typed<"UnknownError"> {
   readonly error: unknown;
 }
 
-/** Creates a {@link TransferableError} from an unknown error. */
-export const createTransferableError = (error: unknown): TransferableError => {
+/**
+ * Creates an {@link UnknownError} from an unknown error.
+ *
+ * Error objects cannot be directly structured-cloned (for worker messaging) or
+ * JSON-serialized because their properties (`message`, `stack`, `cause`) are
+ * non-enumerable. This function extracts those properties into a plain object.
+ */
+export const createUnknownError = (error: unknown): UnknownError => {
   const convertError = (err: Error): Record<string, unknown> => {
-    const transferableError: Record<string, unknown> =
-      Object.getOwnPropertyNames(err).reduce<Record<string, unknown>>(
-        (acc, key) => {
-          const value = (err as never)[key] as unknown;
-          if (key === "cause" && value instanceof Error) {
-            // Recursively process the `cause` property
-            acc[key] = convertError(value);
-          } else if (typeof value !== "function") {
-            acc[key] = value;
-          }
-          return acc;
-        },
-        {},
-      );
-    return transferableError;
+    const result: Record<string, unknown> = Object.getOwnPropertyNames(
+      err,
+    ).reduce<Record<string, unknown>>((acc, key) => {
+      const value = (err as never)[key] as unknown;
+      if (key === "cause" && value instanceof Error) {
+        // Recursively process the `cause` property
+        acc[key] = convertError(value);
+      } else if (typeof value !== "function") {
+        acc[key] = value;
+      }
+      return acc;
+    }, {});
+    // Firefox defines `stack` as a getter on Error.prototype, not as an own
+    // property, so getOwnPropertyNames misses it. Explicitly include it.
+    if (err.stack !== undefined && !("stack" in result)) {
+      result.stack = err.stack;
+    }
+    return result;
   };
 
   if (error instanceof Error) {
     return {
-      type: "TransferableError",
+      type: "UnknownError",
       error: convertError(error),
     };
   }
 
   try {
-    // Clone other values that are transferable
+    // Clone other values that are structured-clonable
     return {
-      type: "TransferableError",
+      type: "UnknownError",
       error: structuredClone(error),
     };
   } catch {
-    // Fallback for non-transferable or problematic values
+    // Fallback for non-clonable values
     try {
       return {
-        type: "TransferableError",
-        error: String(error), // Attempt to convert to a string
+        type: "UnknownError",
+        error: String(error),
       };
     } catch {
       // Final fallback if even `String(error)` fails
       return {
-        type: "TransferableError",
+        type: "UnknownError",
         error: "[Unserializable Object]",
       };
     }

package/src/Function.ts

@@ -1,19 +1,19 @@
-import { NonEmptyArray, NonEmptyReadonlyArray } from "./Array.js";
-import { ReadonlyRecord } from "./Object.js";
+/**
+ * Function utilities including exhaustive checks and composition.
+ *
+ * @module
+ */
 
 /**
  * Helper function to ensure exhaustive matching in a switch statement. Throws
  * an error if an unhandled case is encountered.
  *
- * Remember, it's useful only when we don't return anything from the switch
- * statement. Otherwise, a return type of a function is enough.
- *
  * ### Example
  *
  * ```ts
  * type Color = "red" | "green" | "blue";
  *
- * function handleColor(color: Color): void {
+ * const handleColor = (color: Color): void => {
  *   switch (color) {
  *     case "red":
  *       console.log("Handling red");
@@ -27,7 +27,63 @@ import { ReadonlyRecord } from "./Object.js";
  *     default:
  *       exhaustiveCheck(color); // Ensures all cases are handled
  *   }
- * }
+ * };
+ * ```
+ *
+ * Use this primarily in side-effect switches (`void` branches). For
+ * value-producing switches, TypeScript can enforce exhaustiveness without a
+ * `default` branch.
+ *
+ * ### Example
+ *
+ * Return from each case for value-producing switches.
+ *
+ * ```ts
+ * type Color = "red" | "green" | "blue";
+ *
+ * const colorToHex = (color: Color): string => {
+ *   switch (color) {
+ *     case "red":
+ *       return "#ff0000";
+ *     case "green":
+ *       return "#00ff00";
+ *     case "blue":
+ *       return "#0000ff";
+ *   }
+ * };
+ * ```
+ *
+ * ### Example
+ *
+ * Use assignment + no `default` to get exhaustiveness by definite assignment.
+ *
+ * ```ts
+ * type Input =
+ *   | { readonly type: "Mutate" }
+ *   | { readonly type: "Query" }
+ *   | { readonly type: "Export" };
+ *
+ * const onInput = (input: Input): void => {
+ *   let result: "A" | "B" | "C";
+ *
+ *   switch (input.type) {
+ *     case "Mutate":
+ *       result = "A";
+ *       break;
+ *     case "Query":
+ *       result = "B";
+ *       break;
+ *     case "Export":
+ *       result = "C";
+ *       break;
+ *   }
+ *
+ *   handleKind(result);
+ * };
+ *
+ * const handleKind = (kind: "A" | "B" | "C"): void => {
+ *   console.log(kind);
+ * };
  * ```
  */
 export const exhaustiveCheck = (value: never): never => {
@@ -35,7 +91,7 @@ export const exhaustiveCheck = (value: never): never => {
 };
 
 /**
- * Returns the input value unchanged.
+ * Returns the value unchanged.
  *
  * Useful as a default transformation, placeholder callback, or when a function
  * is required but no transformation is needed.
@@ -53,80 +109,96 @@ export const exhaustiveCheck = (value: never): never => {
 export const identity = <A>(a: A): A => a;
 
 /**
- * Casts an array, set, record, or map to its readonly counterpart.
+ * A function that takes no arguments and returns a value of type T. Also known
+ * as a thunk.
  *
- * Zero runtime cost — returns the same value with a readonly type. Use this to
- * enforce immutability at the type level. Preserves {@link NonEmptyArray} as
- * {@link NonEmptyReadonlyArray}.
+ * Useful for:
+ *
+ * - Providing default callbacks (see {@link lazyVoid}, {@link lazyTrue}, etc.)
+ * - Delaying expensive operations until actually needed
+ * - Deferring side effects so the callee controls when they run
  *
  * ### Example
  *
  * ```ts
- * // Array literals become NonEmptyReadonlyArray
- * const items = readonly([1, 2, 3]);
- * // Type: NonEmptyReadonlyArray<number>
- *
- * // NonEmptyArray is preserved as NonEmptyReadonlyArray
- * const nonEmpty: NonEmptyArray<number> = [1, 2, 3];
- * const readonlyNonEmpty = readonly(nonEmpty);
- * // Type: NonEmptyReadonlyArray<number>
- *
- * // Regular arrays become ReadonlyArray
- * const arr: Array<number> = getNumbers();
- * const readonlyArr = readonly(arr);
- * // Type: ReadonlyArray<number>
- *
- * // Sets, Records, and Maps
- * const ids = readonly(new Set(["a", "b"]));
- * // Type: ReadonlySet<string>
- *
- * const users: Record<UserId, string> = { ... };
- * const readonlyUsers = readonly(users);
- * // Type: ReadonlyRecord<UserId, string>
- *
- * const lookup = readonly(new Map([["key", "value"]]));
- * // Type: ReadonlyMap<string, string>
+ * // Default callback
+ * const notify = (onDone: Lazy<void> = lazyVoid) => {
+ *   onDone();
+ * };
+ *
+ * // Delay computation
+ * const getData: Lazy<Data> = () => compute();
+ * const data = getData();
+ *
+ * // Defer side effects
+ * const schedule = (job: Lazy<void>) => {
+ *   queueMicrotask(job);
+ * };
+ * schedule(() => logMetric("loaded"));
  * ```
- *
- * @experimental
  */
-export function readonly<T>(array: NonEmptyArray<T>): NonEmptyReadonlyArray<T>;
-export function readonly<T>(array: Array<T>): ReadonlyArray<T>;
-export function readonly<T>(set: Set<T>): ReadonlySet<T>;
-export function readonly<K, V>(map: Map<K, V>): ReadonlyMap<K, V>;
-export function readonly<K extends keyof any, V>(
-  record: Record<K, V>,
-): ReadonlyRecord<K, V>;
-export function readonly<T, K extends keyof any, V>(
-  value: Array<T> | Set<T> | Map<K, V> | Record<K, V>,
-):
-  | ReadonlyArray<T>
-  | ReadonlySet<T>
-  | ReadonlyMap<K, V>
-  | ReadonlyRecord<K, V> {
-  return value;
-}
+export type Lazy<T> = () => T;
 
 /**
- * A function that delays computation and returns a value of type T.
+ * Creates a {@link Lazy} from a precomputed value.
  *
- * Useful for:
- *
- * - Lazy evaluation
- * - Returning constant values
- * - Providing default or placeholder behaviors
+ * Use when the value is expensive to compute and want to compute it once at
+ * definition time rather than on every call.
  *
  * ### Example
  *
  * ```ts
- * const getRandomNumber: LazyValue<number> = () => Math.random();
- * const randomValue = getRandomNumber();
+ * // Computed once at definition, returned on every call
+ * const getConfig = lazy(parseConfig(rawConfig));
+ *
+ * // vs. computed on every call
+ * const getConfig = () => parseConfig(rawConfig);
  * ```
  */
-export type LazyValue<T> = () => T;
+export const lazy =
+  <T>(value: T): Lazy<T> =>
+  () =>
+    value;
+
+/** A {@link Lazy} that returns `true`. */
+export const lazyTrue: Lazy<true> = /*#__PURE__*/ lazy(true);
+
+/** A {@link Lazy} that returns `false`. */
+export const lazyFalse: Lazy<false> = /*#__PURE__*/ lazy(false);
+
+/** A {@link Lazy} that returns `null`. */
+export const lazyNull: Lazy<null> = /*#__PURE__*/ lazy(null);
+
+/** A {@link Lazy} that returns `undefined`. */
+export const lazyUndefined: Lazy<undefined> = /*#__PURE__*/ lazy(undefined);
 
-export const constVoid: LazyValue<void> = () => undefined;
-export const constUndefined: LazyValue<undefined> = () => undefined;
-export const constNull: LazyValue<null> = () => null;
-export const constTrue: LazyValue<true> = () => true;
-export const constFalse: LazyValue<false> = () => false;
+/** A {@link Lazy} that returns `undefined` for void callbacks. */
+export const lazyVoid: Lazy<void> = lazyUndefined;
+
+/**
+ * Development placeholder that always throws.
+ *
+ * Use to sketch function bodies before implementing them. TypeScript infers the
+ * return type from context, so surrounding code still type-checks. Use an
+ * explicit generic when there is no return type annotation.
+ *
+ * ### Example
+ *
+ * ```ts
+ * // Type inferred from return type annotation
+ * const fetchUser = (id: UserId): Result<User, FetchError> => todo();
+ *
+ * expectTypeOf(fetchUser).returns.toEqualTypeOf<
+ *   Result<User, FetchError>
+ * >();
+ *
+ * // Explicit generic when no return type
+ * const getConfig = () => todo<Config>();
+ *
+ * expectTypeOf(getConfig).returns.toEqualTypeOf<Config>();
+ * ```
+ */
+// eslint-disable-next-line @typescript-eslint/no-unnecessary-type-parameters
+export const todo = <T>(): T => {
+  throw new Error("not yet implemented");
+};