@evolu/common 6.0.1-preview.9 → 7.1.0

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>;
 };

package/src/Console.ts

@@ -1,5 +1,5 @@
 /**
- * 📝 Cross-platform console
+ * 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
@@ -13,14 +13,28 @@
  * ### Example
  *
  * ```ts
- * deps.console.log("[db]", "send data message", protocolMessage);
+ * deps.console.log("[evolu]", "createEvoluInstance", { name });
  * ```
  *
  * **Tip**: In browser dev tools, you can filter logs by tag (e.g., `[db]`) to
- * quickly find relevant messages.
+ * quickly find relevant messages. In Node.js, use `grep` to filter output:
  *
- * **Warning**: If you encounter platform-specific issues or missing methods,
- * please contribute a PR with details about the environment and behavior.
+ * ```bash
+ * node app.js | grep "\[relay\]"         # Show only relay logs
+ * node app.js | grep -E "\[db\]|\[sql\]" # Show db and sql logs
+ * node app.js | grep -v "\[debug\]"      # Hide debug logs
+ * ```
+ *
+ * Or add to package.json scripts:
+ *
+ * ```json
+ * {
+ *   "scripts": {
+ *     "dev:relay": "node app.js | grep \"\\[relay\\]\"",
+ *     "dev:db": "node app.js | grep -E \"\\[db\\]|\\[sql\\]\""
+ *   }
+ * }
+ * ```
  *
  * @module
  */
@@ -51,6 +65,9 @@ export interface Console {
   /** Starts a timer with an optional label */
   time: (label?: string) => void;
 
+  /** Logs the elapsed time for a timer without ending it */
+  timeLog: (label?: string, ...data: Array<any>) => void;
+
   /** Ends a timer and logs the elapsed time */
   timeEnd: (label?: string) => void;
 
@@ -69,9 +86,6 @@ export interface Console {
   /** 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;
 }
@@ -121,6 +135,10 @@ export const createConsole = (config: ConsoleConfig = {}): Console => {
       // eslint-disable-next-line no-console
       if (instance.enabled) console.time(label);
     },
+    timeLog: (label, ...data) => {
+      // eslint-disable-next-line no-console, @typescript-eslint/no-unsafe-argument
+      if (instance.enabled) console.timeLog(label, ...data);
+    },
     timeEnd: (label) => {
       // eslint-disable-next-line no-console
       if (instance.enabled) console.timeEnd(label);
@@ -145,10 +163,6 @@ export const createConsole = (config: ConsoleConfig = {}): Console => {
       // 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);
@@ -157,3 +171,69 @@ export const createConsole = (config: ConsoleConfig = {}): Console => {
 
   return instance;
 };
+
+export interface ConsoleWithTimeConfig extends ConsoleConfig {
+  /**
+   * Type of timestamp to prepend to log messages.
+   *
+   * - 'absolute': Shows actual time (e.g., "14:32:15.234")
+   * - 'relative': Shows time since console creation (e.g., "+1.234s")
+   */
+  readonly timestampType: "absolute" | "relative";
+}
+
+/** Creates a console instance with timestamp prefixes. */
+export const createConsoleWithTime = (
+  config: ConsoleWithTimeConfig = { timestampType: "relative" },
+): Console => {
+  const console = createConsole(config);
+  const startTime = performance.now();
+
+  const getTimestamp = (): string => {
+    if (config.timestampType === "relative") {
+      const elapsed = (performance.now() - startTime) / 1000;
+
+      // Format for better readability at different time scales
+      if (elapsed < 60) {
+        // Under 1 minute: show seconds with millisecond precision
+        return `+${elapsed.toFixed(3)}s`;
+      } else if (elapsed < 3600) {
+        // 1 minute to 1 hour: show minutes and seconds with millisecond precision
+        const minutes = Math.floor(elapsed / 60);
+        const seconds = (elapsed % 60).toFixed(3);
+        return `+${minutes}m${seconds}s`;
+      } else {
+        // Over 1 hour: show hours, minutes, and seconds with millisecond precision
+        const hours = Math.floor(elapsed / 3600);
+        const minutes = Math.floor((elapsed % 3600) / 60);
+        const seconds = ((elapsed % 3600) % 60).toFixed(3);
+        return `+${hours}h${minutes}m${seconds}s`;
+      }
+    } else {
+      // Absolute time - format as HH:MM:SS.mmm
+      const now = new Date();
+      const hours = now.getHours().toString().padStart(2, "0");
+      const minutes = now.getMinutes().toString().padStart(2, "0");
+      const seconds = now.getSeconds().toString().padStart(2, "0");
+      const milliseconds = now.getMilliseconds().toString().padStart(3, "0");
+      return `${hours}:${minutes}:${seconds}.${milliseconds}`;
+    }
+  };
+
+  const withTimestamp =
+    (fn: (...args: Array<any>) => void) =>
+    (...args: Array<any>) => {
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-argument
+      fn(`[${getTimestamp()}]`, ...args);
+    };
+
+  // Override methods that should have timestamps
+  console.log = withTimestamp(console.log);
+  console.info = withTimestamp(console.info);
+  console.warn = withTimestamp(console.warn);
+  console.error = withTimestamp(console.error);
+  console.debug = withTimestamp(console.debug);
+  console.trace = withTimestamp(console.trace);
+
+  return console;
+};

package/src/Crypto.ts

@@ -1,53 +1,71 @@
 /**
- * 🔒
+ * Cryptographic utilities
+ *
+ * Type-safe cryptographic operations including random number generation, SLIP21
+ * key derivation, XChaCha20-Poly1305 symmetric encryption, PADMÉ padding, and
+ * timing-safe comparisons.
  *
  * @module
  */
-
-import { xchacha20poly1305 } from "@noble/ciphers/chacha";
-import { hmac } from "@noble/hashes/hmac";
-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 { 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;
+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";
+
+export interface RandomBytes {
+  /**
+   * Creates cryptographically secure random bytes with type-safe length
+   * branding.
+   *
+   * Uses the operating system's cryptographically secure random number
+   * generator (crypto.getRandomValues) to generate high-quality entropy
+   * suitable for cryptographic operations.
+   *
+   * ### Type Safety
+   *
+   * Returns specific branded types for common sizes:
+   *
+   * - `Random16` for 16-byte values (128 bits)
+   * - `Random32` for 32-byte values (256 bits)
+   * - `Random64` for 64-byte values (512 bits)
+   * - `Random` for any other size
+   *
+   * ### Example
+   *
+   * ```ts
+   * const nonce = randomBytes.create(16); // Type: Random16
+   * 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: 32): Entropy32;
+  create(bytesLength: 64): Entropy64;
+  create(bytesLength: number): Entropy;
 }
 
-/** Cryptographically secure PRNG. Uses internal OS-level crypto.getRandomValues. */
-export const createRandomBytes: CreateRandomBytes = (bytesLength = 32) =>
-  randomBytes(bytesLength) as RandomBytes;
+export interface RandomBytesDep {
+  readonly randomBytes: RandomBytes;
+}
 
-export type CreateMnemonic = () => Mnemonic;
+const Entropy = brand("Entropy", Uint8Array);
+type Entropy = typeof Entropy.Type;
 
-export interface CreateMnemonicDep {
-  readonly createMnemonic: CreateMnemonic;
-}
+export const Entropy16 = length(16)(Entropy);
+export type Entropy16 = typeof Entropy16.Type;
 
-export const createEnglishMnemonic: CreateMnemonic = () =>
-  bip39.generateMnemonic(wordlist, 128) as Mnemonic;
+export const Entropy32 = length(32)(Entropy);
+export type Entropy32 = typeof Entropy32.Type;
 
-export type MnemonicSeed = Uint8Array & Brand<"MnemonicSeed">;
+export const Entropy64 = length(64)(Entropy);
+export type Entropy64 = typeof Entropy64.Type;
 
-export const mnemonicToMnemonicSeed = (mnemonic: Mnemonic): MnemonicSeed =>
-  bip39.mnemonicToSeedSync(mnemonic) as MnemonicSeed;
+export const createRandomBytes = (): RandomBytes => ({
+  create: randomBytes as RandomBytes["create"],
+});
 
 /**
  * SLIP21.
@@ -55,54 +73,43 @@ export const mnemonicToMnemonicSeed = (mnemonic: Mnemonic): MnemonicSeed =>
  * https://github.com/satoshilabs/slips/blob/master/slip-0021.md
  */
 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);
+  seed: Entropy16 | Entropy32 | Entropy64,
+  path: ReadonlyArray<string | number>,
+): Entropy32 => {
+  let currentNode = hmac(
+    sha512,
+    utf8ToBytes("Symmetric key seed"),
+    seed,
+  ) as Entropy64;
+
+  for (const element of path) {
+    const label = typeof element === "number" ? element.toString() : element;
+    currentNode = deriveSlip21Node(label, currentNode);
   }
-  return m.slice(32, 64);
+
+  return currentNode.slice(32, 64) as Entropy32;
 };
 
 /**
- * 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).
+ * Derives a single node in the SLIP-21 hierarchical key derivation.
  *
- * See https://github.com/satoshilabs/slips/blob/master/slip-0021.md
+ * @see {@link createSlip21}
  */
-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;
-  }
-
-  return id;
+export const deriveSlip21Node = (
+  label: string,
+  parentNode: Entropy64,
+): Entropy64 => {
+  const labelBytes = utf8ToBytes(label);
+  const message = new globalThis.Uint8Array(labelBytes.byteLength + 1);
+  message[0] = 0;
+  message.set(labelBytes, 1);
+  return hmac(sha512, parentNode.slice(0, 32), message) as Entropy64;
 };
 
 /** The encryption key for {@link SymmetricCrypto}. */
-export const EncryptionKey = brand("EncryptionKey", length(32)(Uint8Array));
+export const EncryptionKey = brand("EncryptionKey", Entropy32);
 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;
@@ -137,15 +144,15 @@ export interface SymmetricCryptoDecryptError {
  * https://github.com/paulmillr/noble-ciphers?tab=readme-ov-file#which-cipher-should-i-pick
  */
 export const createSymmetricCrypto = (
-  deps: CreateRandomBytesDep,
+  deps: RandomBytesDep,
 ): SymmetricCrypto => {
-  const nonceLength = getOrThrow(NonNegativeInt.from(24));
+  const nonceLength = NonNegativeInt.orThrow(24);
 
   const symmetricCrypto: SymmetricCrypto = {
     nonceLength,
 
     encrypt: (plaintext, encryptionKey) => {
-      const nonce = deps.createRandomBytes(nonceLength);
+      const nonce = deps.randomBytes.create(nonceLength);
       const ciphertext = xchacha20poly1305(encryptionKey, nonce).encrypt(
         plaintext,
       );
@@ -169,25 +176,26 @@ export const createSymmetricCrypto = (
  * 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
+ * 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;
+export const createPadmePaddedLength = (
+  length: NonNegativeInt,
+): NonNegativeInt => {
+  if (length <= 0) return NonNegativeInt.orThrow(0);
   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;
+  return NonNegativeInt.orThrow((length + mask) & ~mask);
 };
 
-/**
- * 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;
+/** Creates a PADMÉ padding array of zeros for the given input length. */
+export const createPadmePadding = (length: NonNegativeInt): Uint8Array => {
+  const paddedLength = createPadmePaddedLength(length);
+  const paddingLength = NonNegativeInt.orThrow(paddedLength - length);
+  return new globalThis.Uint8Array(paddingLength);
 };
 
 /**