@evolu/common 5.4.8 → 6.0.0

package/src/Crypto.ts

@@ -1,137 +1,191 @@
-import * as S from "@effect/schema/Schema";
-import { secretbox } from "@noble/ciphers/salsa";
-import { concatBytes } from "@noble/ciphers/utils";
+/**
+ * 🔒
+ *
+ * @module
+ */
+
+import { xchacha20poly1305 } from "@noble/ciphers/chacha";
 import { hmac } from "@noble/hashes/hmac";
-import { sha512 } from "@noble/hashes/sha512";
+import { sha512 } from "@noble/hashes/sha2";
 import { randomBytes } from "@noble/hashes/utils";
 import * as bip39 from "@scure/bip39";
 import { wordlist } from "@scure/bip39/wordlists/english";
-import * as Brand from "effect/Brand";
-import * as Context from "effect/Context";
-import * as Effect from "effect/Effect";
-import * as Layer from "effect/Layer";
-import { Id } from "./Model.js";
+import { urlAlphabet } from "nanoid";
+import { getOrThrow, Result, trySync } from "./Result.js";
+import {
+  brand,
+  Id,
+  length,
+  Mnemonic,
+  NonNegativeInt,
+  Uint8Array,
+} from "./Type.js";
+import { Brand } from "./Types.js";
+
+/** `Uint8Array` created by {@link createRandomBytes}. */
+export type RandomBytes = Uint8Array & Brand<"RandomBytes">;
+
+export type CreateRandomBytes = (bytesLength?: number) => RandomBytes;
+
+export interface CreateRandomBytesDep {
+  readonly createRandomBytes: CreateRandomBytes;
+}
+
+/** Cryptographically secure PRNG. Uses internal OS-level crypto.getRandomValues. */
+export const createRandomBytes: CreateRandomBytes = (bytesLength = 32) =>
+  randomBytes(bytesLength) as RandomBytes;
+
+export type CreateMnemonic = () => Mnemonic;
+
+export interface CreateMnemonicDep {
+  readonly createMnemonic: CreateMnemonic;
+}
+
+export const createEnglishMnemonic: CreateMnemonic = () =>
+  bip39.generateMnemonic(wordlist, 128) as Mnemonic;
+
+export type MnemonicSeed = Uint8Array & Brand<"MnemonicSeed">;
+
+export const mnemonicToMnemonicSeed = (mnemonic: Mnemonic): MnemonicSeed =>
+  bip39.mnemonicToSeedSync(mnemonic) as MnemonicSeed;
 
 /**
- * Mnemonic is a password generated by Evolu in BIP39 format.
+ * SLIP21.
  *
- * A mnemonic, also known as a "seed phrase," is a set of 12 words in a specific
- * order chosen from a predefined list. The purpose of the BIP39 mnemonic is to
- * provide a human-readable way of storing a private key.
+ * https://github.com/satoshilabs/slips/blob/master/slip-0021.md
  */
-export type Mnemonic = string & Brand.Brand<"Mnemonic">;
+export const createSlip21 = (
+  seed: MnemonicSeed,
+  path: ReadonlyArray<string>,
+): Uint8Array => {
+  let m = hmac(sha512, "Symmetric key seed", seed);
+  for (const component of path) {
+    const p = new TextEncoder().encode(component);
+    const e = new globalThis.Uint8Array(p.byteLength + 1);
+    e[0] = 0;
+    e.set(p, 1);
+    m = hmac(sha512, m.slice(0, 32), e);
+  }
+  return m.slice(32, 64);
+};
 
 /**
- * Mnemonic is a password generated by Evolu in BIP39 format.
+ * Creates a 21-character Base64URL ID (also known as nanoid) from a SLIP-21
+ * derived key.
+ *
+ * Reduces the 256-bit SLIP-21 output to 126 bits (21 chars × 6 bits) for a
+ * compact, human-readable, and shareable identifier suitable for UI display or
+ * URL use. While this lowers entropy, 126 bits remains cryptographically secure
+ * for uniqueness and unpredictability in most applications (comparable to
+ * UUIDv4's 122 bits).
  *
- * A mnemonic, also known as a "seed phrase," is a set of 12 words in a specific
- * order chosen from a predefined list. The purpose of the BIP39 mnemonic is to
- * provide a human-readable way of storing a private key.
+ * See https://github.com/satoshilabs/slips/blob/master/slip-0021.md
  */
-export const createMnemonic = (): Mnemonic =>
-  bip39.generateMnemonic(wordlist, 128) as Mnemonic;
+export const createSlip21Id = (
+  seed: MnemonicSeed,
+  path: ReadonlyArray<string>,
+): Id => {
+  const slip21 = createSlip21(seed, path);
+  let id = "" as Id;
+
+  // Convert the key to the Id/NanoId/Base64Url format.
+  for (let i = 0; i < 21; i++) {
+    id = (id + urlAlphabet[slip21[i] & 63]) as Id;
+  }
 
-/** Parse a string to {@link Mnemonic}. */
-export const parseMnemonic = (
-  mnemonic: string,
-): Effect.Effect<Mnemonic, InvalidMnemonicError> => {
-  const mnemonicTrimmed = mnemonic.trim();
-  return bip39.validateMnemonic(mnemonicTrimmed, wordlist)
-    ? Effect.succeed(mnemonicTrimmed as Mnemonic)
-    : Effect.fail<InvalidMnemonicError>({
-        _tag: "InvalidMnemonicError",
-      });
+  return id;
 };
 
-export interface InvalidMnemonicError {
-  readonly _tag: "InvalidMnemonicError";
+/** The encryption key for {@link SymmetricCrypto}. */
+export const EncryptionKey = brand("EncryptionKey", length(32)(Uint8Array));
+export type EncryptionKey = typeof EncryptionKey.Type;
+
+export const createEncryptionKey = (seed: MnemonicSeed): EncryptionKey =>
+  createSlip21(seed, ["Evolu", "Encryption Key"]) as EncryptionKey;
+
+/** Symmetric cryptography. */
+export interface SymmetricCrypto {
+  readonly nonceLength: NonNegativeInt;
+
+  readonly encrypt: (
+    plaintext: Uint8Array,
+    encryptionKey: EncryptionKey,
+  ) => {
+    readonly nonce: Uint8Array;
+    readonly ciphertext: Uint8Array;
+  };
+
+  readonly decrypt: (
+    ciphertext: Uint8Array,
+    encryptionKey: EncryptionKey,
+    nonce: Uint8Array,
+  ) => Result<Uint8Array, SymmetricCryptoDecryptError>;
 }
 
-export const mnemonicToSeed = (mnemonic: Mnemonic): Uint8Array =>
-  bip39.mnemonicToSeedSync(mnemonic);
+export interface SymmetricCryptoDep {
+  readonly symmetricCrypto: SymmetricCrypto;
+}
 
-export class NanoIdGenerator extends Context.Tag("NanoIdGenerator")<
-  NanoIdGenerator,
-  {
-    readonly nanoid: Effect.Effect<NanoId>;
-    readonly nodeId: Effect.Effect<NodeId>;
-    readonly rowId: Effect.Effect<Id>;
-  }
->() {}
-
-export const createNanoIdGeneratorLive = (
-  customAlphabet: (
-    alphabet: string,
-    defaultSize?: number,
-  ) => (size?: number) => string,
-  nanoid: (size?: number) => string,
-): Layer.Layer<NanoIdGenerator, never, never> => {
-  const nanoidForNodeId = customAlphabet("0123456789abcdef", 16);
-  return Layer.succeed(
-    NanoIdGenerator,
-    NanoIdGenerator.of({
-      nanoid: Effect.sync(() => nanoid() as NanoId),
-      nodeId: Effect.sync(() => nanoidForNodeId() as NodeId),
-      rowId: Effect.sync(() => nanoid() as Id),
-    }),
-  );
-};
+export interface SymmetricCryptoDecryptError {
+  readonly type: "SymmetricCryptoDecryptError";
+  readonly error: unknown;
+}
 
-export type NanoId = string & Brand.Brand<"NanoId">;
+/**
+ * XChaCha20-Poly1305 encryption
+ *
+ * https://github.com/paulmillr/noble-ciphers?tab=readme-ov-file#which-cipher-should-i-pick
+ */
+export const createSymmetricCrypto = (
+  deps: CreateRandomBytesDep,
+): SymmetricCrypto => {
+  const nonceLength = getOrThrow(NonNegativeInt.from(24));
 
-export const NodeId = S.String.pipe(
-  S.pattern(/^[\w-]{16}$/),
-  S.brand("NodeId"),
-);
-export type NodeId = typeof NodeId.Type;
+  const symmetricCrypto: SymmetricCrypto = {
+    nonceLength,
 
-// SLIP-21 implementation
-// https://github.com/satoshilabs/slips/blob/master/slip-0021.md
-export const slip21Derive = (
-  seed: Uint8Array,
-  path: ReadonlyArray<string>,
-): Effect.Effect<Uint8Array> =>
-  Effect.sync(() => {
-    let m = hmac(sha512, "Symmetric key seed", seed);
-    for (let i = 0; i < path.length; i++) {
-      const p = new TextEncoder().encode(path[i]);
-      const e = new Uint8Array(p.byteLength + 1);
-      e[0] = 0;
-      e.set(p, 1);
-      m = hmac(sha512, m.slice(0, 32), e);
-    }
-    return m.slice(32, 64);
-  });
-
-export class SecretBox extends Context.Tag("SecretBox")<
-  SecretBox,
-  {
-    readonly seal: (
-      key: Uint8Array,
-      plaintext: Uint8Array,
-    ) => Effect.Effect<Uint8Array>;
-
-    readonly open: (
-      key: Uint8Array,
-      ciphertext: Uint8Array,
-    ) => Effect.Effect<Uint8Array>;
-  }
->() {
-  static Live = Layer.succeed(
-    SecretBox,
-    SecretBox.of({
-      seal: (key, plaintext) =>
-        Effect.sync(() => {
-          const nonce = randomBytes(24);
-          const ciphertext = secretbox(key, nonce).seal(plaintext);
-          return concatBytes(nonce, ciphertext);
-        }),
-      open: (key, ciphertext) =>
-        Effect.sync(() => {
-          const nonce = ciphertext.subarray(0, 24);
-          const ciphertextWithoutNonce = ciphertext.subarray(24);
-          return secretbox(key, nonce).open(ciphertextWithoutNonce);
+    encrypt: (plaintext, encryptionKey) => {
+      const nonce = deps.createRandomBytes(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;
+};
+
+/**
+ * Returns the PADMÉ padded length for a given input length.
+ *
+ * PADMÉ limits information leakage about the length of the plain-text for a
+ * wide range of encrypted data sizes. See the PURBs paper for details:
+ * https://bford.info/pub/sec/purb.pdf
+ */
+export const padmePaddedLength = (length: NonNegativeInt): NonNegativeInt => {
+  if (length <= 0) return 0 as NonNegativeInt;
+  const e = 31 - Math.clz32(length >>> 0);
+  const s = 32 - Math.clz32(e >>> 0);
+  const z = Math.max(0, e - s);
+  const mask = (1 << z) - 1;
+  return ((length + mask) & ~mask) as NonNegativeInt;
+};
+
+/**
+ * Returns the PADMÉ padding length for a given input length. Uses
+ * {@link padmePaddedLength}.
+ */
+
+export const padmePaddingLength = (length: NonNegativeInt): NonNegativeInt => {
+  return (padmePaddedLength(length) - length) as NonNegativeInt;
+};

package/src/Eq.ts

@@ -0,0 +1,204 @@
+import { JsonArray, JsonObject, JsonValue, JsonValueInput } from "./Type.js";
+import { Order } from "./Order.js";
+
+/**
+ * Compares two values of the same type `A` for equality.
+ *
+ * Equality functions start with an 'eq' prefix, e.g., `eqString`.
+ *
+ * TODO: Explain, examples (composition etc.)
+ */
+export type Eq<in A> = (x: A, y: A) => boolean;
+
+export const eqStrict = <A>(x: A, y: A): boolean => x === y;
+
+export const eqString: Eq<string> = eqStrict;
+export const eqNumber: Eq<number> = eqStrict;
+export const eqBigInt: Eq<bigint> = eqStrict;
+export const eqBoolean: Eq<boolean> = eqStrict;
+export const eqUndefined: Eq<undefined> = eqStrict;
+export const eqNull: Eq<null> = eqStrict;
+
+/** Derives an {@link Eq} from an {@link Order}. */
+export const eqFromOrder =
+  <A>(order: Order<A>): Eq<A> =>
+  (x, y) =>
+    order(x, y) === 0;
+
+/**
+ * Creates an equivalence function for array-like structures based on an
+ * equivalence for their elements.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const eqArrayNumber = createEqArrayLike(eqNumber);
+ * eqArrayNumber([1, 2, 3], [1, 2, 3]); // true (works with regular arrays)
+ * eqArrayNumber(new Uint8Array([1, 2, 3]), new Uint8Array([1, 2, 3])); // true (works with Uint8Array)
+ * eqArrayNumber([1, 2, 3], [1, 2, 4]); // false
+ * ```
+ */
+export const createEqArrayLike =
+  <A>(item: Eq<A>): Eq<ArrayLike<A>> =>
+  (x, y) => {
+    if (x === y) return true;
+    if (x.length !== y.length) return false;
+
+    for (let i = 0; i < x.length; i++) {
+      if (!item(x[i], y[i])) return false;
+    }
+
+    return true;
+  };
+
+/**
+ * Compares two array-like structures of numbers for equality.
+ *
+ * ### Example
+ *
+ * ```ts
+ * eqArrayNumber([1, 2, 3], [1, 2, 3]); // true (works with regular arrays)
+ * eqArrayNumber(new Uint8Array([1, 2, 3]), new Uint8Array([1, 2, 3])); // true (works with Uint8Array)
+ * eqArrayNumber([1, 2, 3], [1, 2, 4]); // false
+ * ```
+ */
+export const eqArrayNumber = createEqArrayLike(eqNumber);
+
+/**
+ * Creates an equivalence function for objects based on an equivalence for their
+ * fields.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const eqObjectNumber = createEqObject({ a: eqNumber });
+ * eqObjectNumber({ a: 1 }, { a: 1 }); // true
+ * eqObjectNumber({ a: 1 }, { a: 2 }); // false
+ * ```
+ */
+export const createEqObject =
+  <A>(eqs: { [K in keyof A]: Eq<A[K]> }): Eq<{
+    readonly [K in keyof A]: A[K];
+  }> =>
+  (x, y) => {
+    if (x === y) return true;
+    for (const key in eqs) {
+      if (!eqs[key](x[key], y[key])) {
+        return false;
+      }
+    }
+    return true;
+  };
+
+/**
+ * Deeply compares two {@link JsonValue} values for equality.
+ *
+ * - Uses an iterative approach with a stack to handle large or deeply nested
+ *   objects without risking stack overflow.
+ * - Handles circular references with a WeakMap to prevent infinite loops.
+ * - Unlike JSON.stringify, this function directly compares values, avoiding
+ *   serialization overhead and leveraging short-circuit evaluation for faster
+ *   failure on mismatched structures.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const obj1: Json = { name: "Alice", hobbies: ["reading", "hiking"] };
+ * const obj2: Json = { name: "Alice", hobbies: ["reading", "hiking"] };
+ * console.log(eqJson(obj1, obj2)); // true
+ * ```
+ */
+export const eqJsonValue = (a: JsonValue, b: JsonValue): boolean => {
+  const stack: Array<[JsonValue, JsonValue]> = [[a, b]];
+
+  const seen = new WeakMap<object, WeakSet<object>>();
+
+  while (stack.length > 0) {
+    const [x, y] = stack.pop()!;
+
+    if (x === y) continue;
+
+    const typeX = typeof x;
+    const typeY = typeof y;
+
+    if (typeX !== typeY || x === null || y === null) return false;
+
+    if (typeX === "number" && isNaN(x as number) && isNaN(y as number)) {
+      continue;
+    }
+
+    if (typeX === "object") {
+      const isArrayX = Array.isArray(x);
+      const isArrayY = Array.isArray(y);
+
+      if (isArrayX !== isArrayY) return false;
+
+      const xObj = x as object;
+      const yObj = y as object;
+
+      if (seen.has(xObj)) {
+        const ySet = seen.get(xObj)!;
+        if (ySet.has(yObj)) {
+          continue;
+        }
+        ySet.add(yObj);
+      } else {
+        const ySet = new WeakSet<object>();
+        ySet.add(yObj);
+        seen.set(xObj, ySet);
+      }
+
+      if (isArrayX && isArrayY) {
+        const xArr = x as JsonArray;
+        const yArr = y as JsonArray;
+
+        if (xArr.length !== yArr.length) return false;
+        for (let i = 0; i < xArr.length; i++) {
+          stack.push([xArr[i], yArr[i]]);
+        }
+      } else {
+        const xObjTyped = x as JsonObject;
+        const yObjTyped = y as JsonObject;
+
+        const xKeys = Object.keys(xObjTyped);
+        const yKeys = Object.keys(yObjTyped);
+
+        if (xKeys.length !== yKeys.length) return false;
+
+        const yKeySet = new Set(yKeys);
+
+        for (const key of xKeys) {
+          if (!yKeySet.has(key)) return false;
+          stack.push([xObjTyped[key], yObjTyped[key]]);
+        }
+      }
+    } else {
+      return false;
+    }
+  }
+
+  return true;
+};
+
+/**
+ * Deeply compares two {@link JsonValueInput} values for equality.
+ *
+ * - Uses an iterative approach with a stack to handle large or deeply nested
+ *   objects without risking stack overflow.
+ * - Handles circular references with a WeakMap to prevent infinite loops.
+ * - Unlike JSON.stringify, this function directly compares values, avoiding
+ *   serialization overhead and leveraging short-circuit evaluation for faster
+ *   failure on mismatched structures.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const obj1: Json = { name: "Alice", hobbies: ["reading", "hiking"] };
+ * const obj2: Json = { name: "Alice", hobbies: ["reading", "hiking"] };
+ * console.log(eqJson(obj1, obj2)); // true
+ * ```
+ */
+export const eqJsonValueInput = (
+  a: JsonValueInput,
+  b: JsonValueInput,
+): boolean => eqJsonValue(a as JsonValue, b as JsonValue);

package/src/Error.ts

@@ -1,29 +1,66 @@
-import { TimestampError } from "./Crdt.js";
-
-/** The EvoluError type is used to represent errors that can occur in Evolu. */
-export type EvoluError = TimestampError | UnexpectedError;
-
 /**
- * UnexpectedError represents errors that can occur unexpectedly anywhere, even
- * in third-party libraries, because Evolu uses Effect to track all errors.
+ * A serializable representation of an error for safe transfer between execution
+ * contexts, such as Web Workers and the main thread.
+ *
+ * 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.
+ *
+ * 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.
  */
-export interface UnexpectedError {
-  readonly _tag: "UnexpectedError";
+export interface TransferableError {
+  readonly type: "TransferableError";
   readonly error: unknown;
 }
 
-export const makeUnexpectedError = (error: unknown): UnexpectedError => ({
-  _tag: "UnexpectedError",
-  error,
-});
+/** Creates a {@link TransferableError} from an unknown error. */
+export const createTransferableError = (error: unknown): TransferableError => {
+  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;
+  };
+
+  if (error instanceof Error) {
+    return {
+      type: "TransferableError",
+      error: convertError(error),
+    };
+  }
 
-/** Error isn't a structured cloneable object. */
-export const ensureTransferableError = (error: unknown): unknown => {
-  if (error instanceof Error)
+  try {
+    // Clone other values that are transferable
     return {
-      message: error.message,
-      name: error.name,
-      stack: error.stack,
+      type: "TransferableError",
+      error: structuredClone(error),
     };
-  return error;
+  } catch {
+    // Fallback for non-transferable or problematic values
+    try {
+      return {
+        type: "TransferableError",
+        error: String(error), // Attempt to convert to a string
+      };
+    } catch {
+      // Final fallback if even `String(error)` fails
+      return {
+        type: "TransferableError",
+        error: "[Unserializable Object]",
+      };
+    }
+  }
 };

package/src/Evolu/Config.ts

@@ -0,0 +1,83 @@
+import { ConsoleConfig } from "../Console.js";
+import { getOrThrow } from "../Result.js";
+import { Mnemonic, SimpleName } from "../Type.js";
+import type { DbIndexesBuilder } from "./Kysely.js";
+
+export interface Config extends ConsoleConfig {
+  /**
+   * The name of Evolu instances. Evolu is multitenant - it can run more
+   * instances concurrently. Every Evolu instance has to have its own unique
+   * name. Database files are separated and invisible to each other.
+   *
+   * The default value is: `Evolu`.
+   *
+   * ### Example
+   *
+   * ```ts
+   * // name: getOrThrow(SimpleName.from("MyApp"))
+   * ```
+   */
+  readonly name: SimpleName;
+
+  /**
+   * URL for Evolu sync and backup server.
+   *
+   * The default value is `https://evolu.world`.
+   */
+  readonly syncUrl: string;
+
+  /**
+   * URL to reload browser tabs after reset or restore.
+   *
+   * The default value is `/`.
+   */
+  readonly reloadUrl: string;
+
+  /**
+   * Maximum physical clock drift allowed in ms.
+   *
+   * The default value is 5 * 60 * 1000 (5 minutes).
+   */
+  readonly maxDrift: number;
+
+  /**
+   * Use the `indexes` option to define SQLite indexes.
+   *
+   * Table and column names are not typed because Kysely doesn't support it.
+   *
+   * https://medium.com/@JasonWyatt/squeezing-performance-from-sqlite-indexes-indexes-c4e175f3c346
+   *
+   * ### Example
+   *
+   * ```ts
+   * const evolu = createEvolu(evoluReactDeps)(Schema, {
+   *   indexes: (create) => [
+   *     create("todoCreatedAt").on("todo").column("createdAt"),
+   *     create("todoCategoryCreatedAt")
+   *       .on("todoCategory")
+   *       .column("createdAt"),
+   *   ],
+   * });
+   * ```
+   */
+  readonly indexes?: DbIndexesBuilder;
+
+  /**
+   * Use this option to create Evolu with the specified mnemonic. If omitted,
+   * the mnemonic will be autogenerated. That should be the default behavior
+   * until special UX requirements are needed (e.g., multitenancy).
+   */
+  readonly mnemonic?: Mnemonic;
+}
+
+export interface ConfigDep {
+  readonly config: Config;
+}
+
+export const defaultConfig: Config = {
+  name: getOrThrow(SimpleName.fromParent("Evolu")),
+  syncUrl: "https://evolu.world",
+  reloadUrl: "/",
+  maxDrift: 5 * 60 * 1000,
+  enableLogging: false,
+};