@evolu/common 5.4.8 → 6.0.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@evolu/common",
-  "version": "5.4.8",
-  "description": "Local-first platform designed for privacy, ease of use, and no vendor lock-in to sync and backup people's lifetime data",
+  "version": "6.0.0",
+  "description": "TypeScript library and local-first framework",
   "keywords": [
     "evolu",
     "local-first",
@@ -22,19 +22,17 @@
     ".": {
       "types": "./dist/src/index.d.ts",
       "import": "./dist/src/index.js",
-      "browser": "./dist/src/index.js"
+      "browser": "./dist/src/index.js",
+      "react-native": "./dist/src/index.js"
     },
-    "./public": {
-      "import": "./dist/src/Public.js"
+    "./evolu": {
+      "import": "./dist/src/Evolu/Internal.js"
     }
   },
-  "react-native": {
-    "./index.js": "./dist/src/index.js"
-  },
   "typesVersions": {
     "*": {
-      "public": [
-        "./dist/src/Public.d.ts"
+      "evolu": [
+        "./dist/src/Evolu/Internal.d.ts"
       ]
     }
   },
@@ -44,45 +42,38 @@
     "README.md"
   ],
   "dependencies": {
-    "@noble/ciphers": "^1.0.0",
-    "@noble/hashes": "^1.4.0",
-    "@protobuf-ts/runtime": "^2.9.4",
-    "@scure/bip39": "^1.3.0",
-    "kysely": "^0.27.3",
-    "nanoid": "^5.0.7"
+    "@noble/ciphers": "^1.3.0",
+    "@noble/hashes": "^1.8.0",
+    "@scure/bip39": "^1.6.0",
+    "kysely": "^0.28.2",
+    "msgpackr": "^1.11.4",
+    "nanoid": "^3.3.11",
+    "random": "^5.4.0"
   },
   "devDependencies": {
-    "@effect/platform": "0.69.9",
-    "@effect/schema": "0.75.5",
-    "@protobuf-ts/plugin": "^2.9.4",
-    "@protobuf-ts/protoc": "^2.9.4",
-    "array-shuffle": "^3.0.0",
-    "effect": "3.10.4",
-    "eslint": "^8.57.0",
-    "typescript": "^5.4.5",
-    "vitest": "^2.0.0",
-    "@evolu/tsconfig": "0.0.2",
-    "eslint-config-evolu": "1.0.0"
-  },
-  "peerDependencies": {
-    "@effect/platform": "0.69.9",
-    "@effect/schema": "0.75.5",
-    "effect": "3.10.4"
+    "@bokuweb/zstd-wasm": "0.0.27",
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/ws": "^8.18.1",
+    "better-sqlite3": "^11.10.0",
+    "shx": "^0.3.4",
+    "typescript": "^5.8.3",
+    "vitest": "^3.2.2",
+    "ws": "^8.18.2",
+    "@evolu/tsconfig": "0.0.2"
   },
   "publishConfig": {
     "access": "public"
   },
   "engines": {
-    "node": ">=20.0.0"
+    "node": ">=22.0.0"
   },
   "sideEffects": [],
   "scripts": {
     "dev": "tsc --watch",
-    "build": "rm -rf dist ./README.md && tsc && cp ../../README.md ./",
-    "lint": "eslint src --ext .ts,.tsx",
-    "test": "vitest run",
-    "clean": "rm -rf .turbo node_modules dist",
+    "build": "shx rm -rf dist ./README.md && tsc && shx cp ../../README.md ./",
+    "test": "vitest --disableConsoleIntercept",
+    "clean": "shx rm -rf .turbo node_modules dist",
     "format": "prettier --write \"src/*.{ts,tsx,md}\"",
-    "protobuf": "pnpm protoc --ts_out ./src --proto_path protobuf protobuf/Protobuf.proto --ts_opt eslint_disable --ts_opt optimize_code_size && pnpm format"
+    "bench": "vitest bench"
   }
 }

package/src/Array.ts

@@ -0,0 +1,39 @@
+/** An array with at least one element. */
+export type NonEmptyArray<T> = [T, ...Array<T>];
+
+/** Checks if an array is non-empty. */
+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. */
+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. */
+export const appendToArray = <T>(
+  item: T,
+  array: ReadonlyArray<T>,
+): NonEmptyReadonlyArray<T> =>
+  [...array, item] as unknown as NonEmptyReadonlyArray<T>;
+
+/** Prepends an item to an array returning a non-empty array. */
+export const prependToArray = <T>(
+  item: T,
+  array: ReadonlyArray<T>,
+): NonEmptyReadonlyArray<T> =>
+  [item, ...array] as unknown as NonEmptyReadonlyArray<T>;
+
+/** Maps a non-empty array using a mapper function. */
+export const mapNonEmptyArray = <T, U>(
+  array: NonEmptyReadonlyArray<T>,
+  mapper: (item: T, index: number) => U,
+): NonEmptyReadonlyArray<U> =>
+  array.map(mapper) as unknown as NonEmptyReadonlyArray<U>;
+
+/** Shifts an item from a non-empty array, guaranteed to return T. */
+export const shiftArray = <T>(array: NonEmptyArray<T>): T => array.shift() as T;

package/src/Assert.ts

@@ -0,0 +1,116 @@
+/**
+ * 🚨
+ *
+ * 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";
+
+/**
+ * Ensures a condition is true, throwing an error with the provided message if
+ * not.
+ *
+ * Prevents 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).
+ *
+ * ### Example
+ *
+ * ```ts
+ * assert(true, "true is not true"); // no-op
+ * assert(false, "true is not true"); // throws Error
+ *
+ * const size = fooSize - buffer.getLength();
+ * // Ensure required type
+ * assert(PositiveInt.is(size), "size is not positive int");
+ * ```
+ */
+export const assert: (
+  condition: unknown,
+  message: string,
+) => asserts condition = (condition, message) => {
+  if (!condition) {
+    throw new Error(message);
+  }
+};
+
+/**
+ * Asserts that an array is non-empty.
+ *
+ * Ensures the provided array has at least one element, helping TypeScript infer
+ * the array as non-empty when this is logically guaranteed but not statically
+ * known.
+ *
+ * ### Example
+ *
+ * ```ts
+ * assertNonEmptyArray([1, 2, 3]); // no-op
+ * assertNonEmptyArray([]); // throws Error
+ * ```
+ */
+export const assertNonEmptyArray: <T>(
+  arr: Array<T>,
+  message?: string,
+) => asserts arr is [T, ...Array<T>] = (
+  arr,
+  message = "Expected a non-empty array.",
+) => {
+  assert(arr.length > 0, message);
+};
+
+/**
+ * Asserts that a readonly array is non-empty.
+ *
+ * Ensures the provided readonly array has at least one element, helping
+ * TypeScript infer non-emptiness when this is logically guaranteed but not
+ * statically known.
+ *
+ * ### Example
+ *
+ * ```ts
+ * assertNonEmptyReadonlyArray([1, 2, 3]); // no-op
+ * assertNonEmptyReadonlyArray([]); // throws Error
+ * ```
+ */
+export const assertNonEmptyReadonlyArray: <T>(
+  arr: ReadonlyArray<T>,
+  message?: string,
+) => asserts arr is readonly [T, ...Array<T>] = (
+  arr,
+  message = "Expected a non-empty readonly array.",
+) => {
+  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/BigInt.ts

@@ -0,0 +1,29 @@
+import { Predicate } from "./Types.js";
+
+/** Increments a bigint by 1. */
+export const incrementBigInt = (n: bigint): bigint => n + 1n;
+
+/** Decrements a bigint by 1. */
+export const decrementBigInt = (n: bigint): bigint => n - 1n;
+
+/** Clamps a bigint within a given range. */
+export const clampBigInt =
+  (min: bigint, max: bigint) =>
+  (n: bigint): bigint =>
+    n < min ? min : n > max ? max : n;
+
+/**
+ * Creates a predicate that checks if a BigInt is within a range, inclusive.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const isBetween10And20 = isBetweenBigInt(10n, 20n);
+ * console.log(isBetween10And20(15n)); // true
+ * console.log(isBetween10And20(25n)); // false
+ * ```
+ */
+export const isBetweenBigInt =
+  (min: bigint, max: bigint): Predicate<bigint> =>
+  (value) =>
+    value >= min && value <= max;

package/src/Buffer.ts

@@ -0,0 +1,175 @@
+import { Result } from "./Result.js";
+import { NonNegativeInt } from "./Type.js";
+export {
+  bytesToHex,
+  bytesToUtf8,
+  concatBytes,
+  hexToBytes,
+  utf8ToBytes,
+} from "@noble/ciphers/utils";
+
+/**
+ * Custom error for {@link Buffer}-related failures like premature end of data.
+ * Provides better stack traces for debugging binary protocol issues.
+ */
+export class BufferError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = this.constructor.name;
+
+    Error.captureStackTrace(this, this.constructor);
+  }
+}
+
+/**
+ * A Buffer is a dynamic, resizable container for binary data, optimized for
+ * scenarios where the final size is unknown. It grows exponentially (doubling
+ * its capacity) to minimize memory reallocations and uses `subarray` for
+ * efficient, copy-free data access in methods like `unwrap` and `shift`.
+ *
+ * ### Recommended Usage
+ *
+ * Create as few Buffers as possible—typically one main Buffer for the final
+ * output. Temporary Buffers are allowed when necessary (e.g., for
+ * variable-length headers), but avoid excessive allocations. Buffers can be
+ * reused within functions by leveraging `reset` to clear contents while
+ * preserving capacity, or `truncate` to adjust the length to a specific size,
+ * reducing the need for new allocations. Pass Buffers to `encode*` functions to
+ * append serialized data and use `decode*` functions to extract data. Both
+ * `shift` and `shiftN` throw an {@link BufferError} with message "Buffer parse
+ * ended prematurely" on failure, as do higher-level `decode*` functions,
+ * providing stack traces for debugging instead of using {@link Result}. This
+ * avoids allocation overhead in success cases and leverages exceptions'
+ * diagnostic benefits.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const buffer = createBuffer();
+ * encodeNonNegativeInt(buffer, someInt);
+ * encodeId(buffer, someId);
+ * const result = buffer.unwrap(); // Final serialized data
+ *
+ * // Decoding example (throws on error)
+ * try {
+ *   const num = decodeNonNegativeInt(buffer);
+ *   const id = decodeId(buffer);
+ * } catch (e) {
+ *   console.error(e.stack); // Stack trace for debugging
+ * }
+ * ```
+ *
+ * For more on exponential growth, see:
+ * https://blog.mozilla.org/nnethercote/2014/11/04/please-grow-your-buffers-exponentially
+ */
+export interface Buffer {
+  /** Returns the total allocated size of the buffer. */
+  getCapacity: () => NonNegativeInt;
+
+  /** Returns the current number of bytes stored in the buffer. */
+  getLength: () => NonNegativeInt;
+
+  /**
+   * Appends binary data to the buffer, resizing if necessary. Throws if
+   * `arg.length` is not a non-negative integer.
+   */
+  extend: (arg: Uint8Array | ArrayLike<number>) => void;
+
+  /**
+   * Removes and returns the first byte. Throws an `Error` with message "Buffer
+   * parse ended prematurely" if the buffer is empty.
+   */
+  shift: () => NonNegativeInt;
+
+  /**
+   * Removes and returns the first `n` bytes. Throws an `Error` with message
+   * "Buffer parse ended prematurely" if fewer than `n` bytes remain.
+   */
+  shiftN: (n: NonNegativeInt) => Uint8Array;
+
+  /**
+   * Truncates the buffer to the specified length, discarding data from the end.
+   * Throws if the new length is greater than the current length.
+   */
+  truncate: (length: NonNegativeInt) => void;
+
+  /**
+   * Resets the buffer to its initial empty state, preserving its capacity.
+   *
+   * This allows efficient buffer reuse without reallocating memory. Use this
+   * when you want to clear the buffer and write new data, avoiding unnecessary
+   * allocations.
+   */
+  reset: () => void;
+
+  /**
+   * Returns a view of the buffer’s current data. Do not modify this array, as
+   * it directly alters the buffer’s internal state, potentially breaking
+   * subsequent operations.
+   */
+  unwrap: () => Uint8Array;
+}
+
+export const createBuffer = (
+  arrayLike?: Uint8Array | ArrayLike<number>,
+): Buffer => {
+  let value = arrayLike
+    ? new globalThis.Uint8Array(arrayLike)
+    : new globalThis.Uint8Array(512);
+  let length = (arrayLike ? arrayLike.length : 0) as NonNegativeInt;
+
+  const buffer: Buffer = {
+    getCapacity: () => value.length as NonNegativeInt,
+
+    getLength: () => length,
+
+    extend: (arg) => {
+      const targetSize = length + arg.length;
+      if (value.length < targetSize) {
+        const oldValue = value;
+        const newCapacity = Math.max(value.length * 2, targetSize);
+        value = new globalThis.Uint8Array(newCapacity);
+        value.set(oldValue);
+      }
+      value.set(arg, length);
+      length = (length + arg.length) as NonNegativeInt;
+    },
+
+    shift: () => {
+      if (length === 0) {
+        throw new BufferError("Buffer parse ended prematurely");
+      }
+      const first = value[0];
+      value = value.subarray(1);
+      length--;
+      return first as NonNegativeInt;
+    },
+
+    shiftN: (n) => {
+      if (length < n) {
+        throw new BufferError("Buffer parse ended prematurely");
+      }
+      const subarray = value.subarray(0, n);
+      value = value.subarray(n);
+      length = (length - n) as NonNegativeInt;
+      return subarray;
+    },
+
+    truncate: (newLength) => {
+      if (newLength > length) {
+        throw new BufferError(
+          "Cannot truncate to a length greater than current",
+        );
+      }
+      length = newLength;
+    },
+
+    reset: () => {
+      length = 0 as NonNegativeInt;
+    },
+
+    unwrap: () => value.subarray(0, length),
+  };
+
+  return buffer;
+};

package/src/Callbacks.ts

@@ -0,0 +1,43 @@
+import { NanoIdLibDep } from "./NanoId.js";
+import { Brand } from "./Types.js";
+
+/**
+ * Manages one-time callback functions.
+ *
+ * Allows registering callbacks with a unique ID and executing 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.
+ */
+export interface Callbacks {
+  /** Registers a callback function and returns a unique ID. */
+  readonly register: (callback: (arg?: unknown) => void) => CallbackId;
+
+  /** Executes and removes a callback associated with the given ID. */
+  readonly execute: (id: CallbackId, arg?: unknown) => void;
+}
+
+export type CallbackId = string & Brand<"CallbackId">;
+
+export const createCallbacks = (deps: NanoIdLibDep): Callbacks => {
+  const callbackMap = new Map<CallbackId, (arg?: unknown) => void>();
+
+  const callbacks: Callbacks = {
+    register: (callback) => {
+      const id = deps.nanoIdLib.nanoid() as CallbackId;
+      callbackMap.set(id, callback);
+      return id;
+    },
+
+    execute: (id, arg) => {
+      const callback = callbackMap.get(id);
+      if (callback) {
+        callbackMap.delete(id);
+        callback(arg);
+      }
+    },
+  };
+
+  return callbacks;
+};

package/src/Console.ts

@@ -0,0 +1,159 @@
+/**
+ * 📝 Cross-platform console
+ *
+ * Console abstraction for Chrome 123+, Firefox 125+, Safari 18.1+, Node.js
+ * 22.x+, and React Native 0.75+. Includes methods guaranteed to be available in
+ * these environments and expected to remain compatible in future versions.
+ * Output formatting may vary (e.g., interactive UI in browsers vs. text in
+ * Node.js/React Native), but functionality is consistent across platforms.
+ *
+ * **Convention**: Use a tag (e.g., `[db]`) as the first argument for log
+ * filtering.
+ *
+ * ### Example
+ *
+ * ```ts
+ * deps.console.log("[db]", "send data message", protocolMessage);
+ * ```
+ *
+ * **Tip**: In browser dev tools, you can filter logs by tag (e.g., `[db]`) to
+ * quickly find relevant messages.
+ *
+ * **Warning**: If you encounter platform-specific issues or missing methods,
+ * please contribute a PR with details about the environment and behavior.
+ *
+ * @module
+ */
+
+/**
+ * Cross-platform Console interface for Chrome 123+, Firefox 125+, Safari 18.1+,
+ * Node.js 22.x+, and React Native 0.75+
+ */
+export interface Console {
+  /** Controls whether console methods produce output (default: true) */
+  enabled?: boolean;
+
+  /** Outputs a message to the console */
+  log: (...args: Array<any>) => void;
+
+  /** Outputs an informational message (often same as log) */
+  info: (...args: Array<any>) => void;
+
+  /** Outputs a warning message */
+  warn: (...args: Array<any>) => void;
+
+  /** Outputs an error message */
+  error: (...args: Array<any>) => void;
+
+  /** Outputs a debug message */
+  debug: (...args: Array<any>) => void;
+
+  /** Starts a timer with an optional label */
+  time: (label?: string) => void;
+
+  /** Ends a timer and logs the elapsed time */
+  timeEnd: (label?: string) => void;
+
+  /** Displays an object's properties in a detailed format */
+  dir: (object: any, options?: any) => void;
+
+  /** Displays tabular data as a table */
+  table: (tabularData: any, properties?: Array<string>) => void;
+
+  /** Logs the number of times this has been called with the given label */
+  count: (label?: string) => void;
+
+  /** Resets the counter for the given label */
+  countReset: (label?: string) => void;
+
+  /** Writes a message if the value is falsy, otherwise does nothing */
+  assert: (value: any, message?: string, ...optionalParams: Array<any>) => void;
+
+  /** Logs the elapsed time for a timer without ending it */
+  timeLog: (label?: string, ...data: Array<any>) => void;
+
+  /** Prints a stack trace with an optional message */
+  trace: (message?: any, ...optionalParams: Array<any>) => void;
+}
+
+/** Dependency interface for injecting a Console instance. */
+export interface ConsoleDep {
+  readonly console: Console;
+}
+
+export interface ConsoleConfig {
+  /**
+   * Enable or disable console logging (default: false). When true, logs are
+   * output to the {@link Console}; when false, logging is disabled for all
+   * methods except `error`, which always outputs to ensure critical issues are
+   * not missed.
+   */
+  readonly enableLogging?: boolean;
+}
+
+/** Creates a console instance using the global console. */
+export const createConsole = (config: ConsoleConfig = {}): Console => {
+  const instance: Console = {
+    enabled: config.enableLogging ?? false,
+
+    log: (...args) => {
+      // eslint-disable-next-line no-console, @typescript-eslint/no-unsafe-argument
+      if (instance.enabled) console.log(...args);
+    },
+    info: (...args) => {
+      // eslint-disable-next-line no-console, @typescript-eslint/no-unsafe-argument
+      if (instance.enabled) console.info(...args);
+    },
+    warn: (...args) => {
+      // eslint-disable-next-line no-console, @typescript-eslint/no-unsafe-argument
+      if (instance.enabled) console.warn(...args);
+    },
+    error: (...args) => {
+      // Always log errors, even if disabled
+      // eslint-disable-next-line no-console, @typescript-eslint/no-unsafe-argument
+      console.error(...args);
+    },
+    debug: (...args) => {
+      // eslint-disable-next-line no-console, @typescript-eslint/no-unsafe-argument
+      if (instance.enabled) console.debug(...args);
+    },
+    time: (label) => {
+      // eslint-disable-next-line no-console
+      if (instance.enabled) console.time(label);
+    },
+    timeEnd: (label) => {
+      // eslint-disable-next-line no-console
+      if (instance.enabled) console.timeEnd(label);
+    },
+    dir: (object, options) => {
+      // eslint-disable-next-line no-console
+      if (instance.enabled) console.dir(object, options);
+    },
+    table: (tabularData, properties) => {
+      // eslint-disable-next-line no-console
+      if (instance.enabled) console.table(tabularData, properties);
+    },
+    count: (label) => {
+      // eslint-disable-next-line no-console
+      if (instance.enabled) console.count(label);
+    },
+    countReset: (label) => {
+      // eslint-disable-next-line no-console
+      if (instance.enabled) console.countReset(label);
+    },
+    assert: (value, message, ...optionalParams) => {
+      // eslint-disable-next-line no-console, @typescript-eslint/no-unsafe-argument
+      if (instance.enabled) console.assert(value, message, ...optionalParams);
+    },
+    timeLog: (label, ...data) => {
+      // eslint-disable-next-line no-console, @typescript-eslint/no-unsafe-argument
+      if (instance.enabled) console.timeLog(label, ...data);
+    },
+    trace: (message, ...optionalParams) => {
+      // eslint-disable-next-line no-console, @typescript-eslint/no-unsafe-argument
+      if (instance.enabled) console.trace(message, ...optionalParams);
+    },
+  };
+
+  return instance;
+};