@evolu/common 8.15.1 → 8.17.0

package/src/Console.ts

@@ -4,7 +4,6 @@
  * @module
  */
 
-import { objectFrom } from "./Object.ts";
 import type { ReadonlyStore } from "./Store.ts";
 import { createStore } from "./Store.ts";
 import type { Task } from "./Task.ts";
@@ -54,9 +53,7 @@ import {
  *   createConsole,
  *   createConsoleArrayOutput,
  *   Data,
- *   type Console,
  *   type ConsoleEntry,
- *   type ConsoleLevel,
  * } from "@evolu/common";
  *
  * const entries: Array<ConsoleEntry> = [];
@@ -75,16 +72,11 @@ import {
  * assertType(Data, args);
  * assertEqual(args, ["Creating instance", { config: { port: 4000 } }]);
  *
- * const setLevelRecursive = (
- *   console: Console,
- *   level: ConsoleLevel,
- * ): void => {
- *   console.setLevel(level);
- *   for (const child of console.children) setLevelRecursive(child, level);
- * };
- * setLevelRecursive(root, "warn");
- * assertEqual(root.getLevel(), "warn");
- * assertEqual(relay.getLevel(), "warn");
+ * // Children without their own level follow their parent.
+ * const db = root.child("db");
+ * root.setLevel("warn");
+ * assertEqual(db.getLevel(), "warn");
+ * assertEqual(relay.getLevel(), "silent");
  * ```
  *
  * Console intentionally does not use {@link Task}. Logging must be as fast as
@@ -97,17 +89,12 @@ import {
  * @see {@link createConsole}
  */
 export interface Console {
-  /** Name of this console. Empty for root. */
-  readonly name: string;
-
-  /** Child consoles created via {@link Console.child}. */
-  readonly children: ReadonlySet<Console>;
-
   /**
    * Returns the effective log level.
    *
    * If this console has its own level set via {@link Console.setLevel}, returns
-   * that. Otherwise returns the inherited level from creation time.
+   * that. Otherwise returns its parent's current level, or
+   * {@link ConsoleConfig.level} for a root console.
    */
   readonly getLevel: () => ConsoleLevel;
 
@@ -125,12 +112,12 @@ export interface Console {
   /**
    * Creates a child console with the given name added to the path.
    *
-   * Child inherits the parent's configured level (not any runtime override).
-   * Use {@link Console.children} to access all children for batch operations.
+   * A child without its own level follows its parent's level, including later
+   * changes.
    */
   readonly child: (name: string) => Console;
 
-  /** Outputs a stack trace. */
+  /** Most detailed execution flow, such as every SQL query. */
   readonly trace: (...args: ReadonlyArray<unknown>) => void;
 
   /** Development diagnostics. */
@@ -148,31 +135,10 @@ export interface Console {
   /** Failures requiring immediate attention. */
   readonly error: (...args: ReadonlyArray<unknown>) => void;
 
-  /** Displays an object with expandable properties. Level: debug. */
-  readonly dir: (item: unknown) => void;
-
-  /** Displays tabular data. Level: debug. */
-  readonly table: (data: unknown) => void;
-
-  /** Starts a timer with the given label. Level: debug. */
-  readonly time: (label: string) => void;
-
-  /** Logs elapsed time for a timer. Level: debug. */
-  readonly timeLog: (label: string, ...args: ReadonlyArray<unknown>) => void;
-
-  /** Ends a timer and logs elapsed time. Level: debug. */
-  readonly timeEnd: (label: string) => void;
-
-  /** Increments and logs a counter. Level: debug. */
-  readonly count: (label?: string) => void;
-
-  /** Resets a counter. Level: debug. */
-  readonly countReset: (label?: string) => void;
-
   /**
-   * Writes a pre-built {@link ConsoleEntry} directly to the output, bypassing
-   * level filtering. Used to replay entries from another context (e.g., a
-   * SharedWorker) where filtering was already applied.
+   * Writes a pre-built {@link ConsoleEntry} to the output if this console's
+   * level allows its method. Used to replay entries from another context, such
+   * as a worker, that filtered them by its own level.
    */
   readonly write: (entry: ConsoleEntry) => void;
 }
@@ -192,8 +158,8 @@ export interface ConsoleDep {
  * Setting a level enables all logs at that level and above (ordered by
  * severity):
  *
- * - `"trace"` — Stack traces and detailed execution flow
- * - `"debug"` — Development diagnostics, timers, counters
+ * - `"trace"` — Most detailed execution flow, such as every SQL query
+ * - `"debug"` — Development diagnostics
  * - `"log"` — General-purpose messages
  * - `"info"` — Operational milestones (startup, shutdown)
  * - `"warn"` — Recoverable issues that may need attention
@@ -233,19 +199,7 @@ export interface ConsoleEntry {
  * @group Core
  */
 export type ConsoleMethod =
-  | "trace"
-  | "debug"
-  | "log"
-  | "info"
-  | "warn"
-  | "error"
-  | "dir"
-  | "table"
-  | "time"
-  | "timeLog"
-  | "timeEnd"
-  | "count"
-  | "countReset";
+  "trace" | "debug" | "log" | "info" | "warn" | "error";
 
 /**
  * Output destination for {@link Console}.
@@ -278,9 +232,6 @@ export type ConsoleFormatter = (entry: ConsoleEntry) => ReadonlyArray<unknown>;
  * @group Core
  */
 export interface ConsoleConfig {
-  /** Name of this console. Defaults to empty string. */
-  readonly name?: string;
-
   /** Initial log level. Defaults to `"log"`. */
   readonly level?: ConsoleLevel;
 
@@ -320,7 +271,8 @@ export interface ConsoleFormatterConfig {
   readonly timestampFormat?: ConsoleEntryTimestampFormat;
 
   /**
-   * Start time for relative timestamps. Defaults to first entry timestamp.
+   * Start time for relative timestamps. Defaults to the time the first entry is
+   * formatted.
    *
    * Pass a {@link Millis} value to use a custom start time, useful when multiple
    * consoles should share the same relative timeline.
@@ -427,65 +379,66 @@ const levelOrder: Record<ConsoleLevel, number> = {
  * @group Core
  */
 export const createConsole = ({
-  name = "",
   level = "log",
   output = createNativeConsoleOutput(),
   path = [],
   formatter,
-}: ConsoleConfig = {}): Console => {
-  const childrenSet = new Set<Console>();
+}: ConsoleConfig = {}): Console =>
+  createConsoleWithInheritedLevel({
+    getInheritedLevel: () => level,
+    output,
+    path,
+    formatter,
+  });
+
+const createConsoleWithInheritedLevel = ({
+  getInheritedLevel,
+  output,
+  path,
+  formatter,
+}: {
+  getInheritedLevel: () => ConsoleLevel;
+  output: ConsoleOutput;
+  path: ReadonlyArray<string>;
+  formatter: ConsoleFormatter | undefined;
+}): Console => {
   let ownLevel: ConsoleLevel | null = null;
 
-  const getLevel = (): ConsoleLevel => ownLevel ?? level;
+  const getLevel = (): ConsoleLevel => ownLevel ?? getInheritedLevel();
+
+  const isEnabled = (method: ConsoleMethod): boolean =>
+    levelOrder[method] >= levelOrder[getLevel()];
 
   const createMethod =
-    (
-      method: ConsoleMethod,
-      methodLevel: ConsoleLevel,
-      formatter?: ConsoleFormatter,
-    ) =>
+    (method: ConsoleMethod) =>
     (...args: ReadonlyArray<unknown>): void => {
-      if (levelOrder[methodLevel] >= levelOrder[getLevel()])
-        output.write({ method, path, args }, formatter);
+      if (isEnabled(method)) output.write({ method, path, args }, formatter);
     };
 
-  const levelMethod = (method: ConsoleLevel & ConsoleMethod) =>
-    createMethod(method, method, formatter);
-
-  const debugMethod = (method: ConsoleMethod) => createMethod(method, "debug");
-
   return {
-    name,
-    children: childrenSet,
     getLevel,
     setLevel: (level) => {
       ownLevel = level;
     },
     hasOwnLevel: () => ownLevel !== null,
 
-    child: (name) => {
-      const childConsole = createConsole({
-        name,
-        level,
+    child: (name) =>
+      createConsoleWithInheritedLevel({
+        getInheritedLevel: getLevel,
         output,
         path: [...path, name],
-        ...(formatter && { formatter }),
-      });
-      childrenSet.add(childConsole);
-      return childConsole;
-    },
+        formatter,
+      }),
 
-    ...objectFrom(
-      ["trace", "debug", "log", "info", "warn", "error"],
-      levelMethod,
-    ),
-    ...objectFrom(
-      ["dir", "table", "time", "timeLog", "timeEnd", "count", "countReset"],
-      debugMethod,
-    ),
+    trace: createMethod("trace"),
+    debug: createMethod("debug"),
+    log: createMethod("log"),
+    info: createMethod("info"),
+    warn: createMethod("warn"),
+    error: createMethod("error"),
 
     write: (entry) => {
-      output.write(entry, formatter);
+      if (isEnabled(entry.method)) output.write(entry, formatter);
     },
   };
 };
@@ -497,6 +450,9 @@ export const createConsole = ({
  * Use {@link createConsoleFormatter} with {@link ConsoleConfig.formatter} for
  * timestamps and path prefixes.
  *
+ * Trace entries are written with native `console.debug`, because native
+ * `console.trace` prints a stack trace with every call.
+ *
  * ### Example
  *
  * ```ts
@@ -517,11 +473,9 @@ export const createNativeConsoleOutput = (): ConsoleOutput => ({
   write: (entry, formatter) => {
     const args = formatter ? formatter(entry) : entry.args;
     // oxlint-disable-next-line evolu/no-unnecessary-global-this -- Write to the global object console even if a realm lexical binding shadows it.
-    const nativeConsole = globalThis.console as unknown as Record<
-      ConsoleMethod,
-      (...args: Array<unknown>) => void
-    >;
-    nativeConsole[entry.method](...args);
+    globalThis.console[entry.method === "trace" ? "debug" : entry.method](
+      ...args,
+    );
   },
 });
 
@@ -592,7 +546,11 @@ export const createConsoleFormatter =
           timestamp = "";
           break;
         case "relative":
-          timestamp = `+${formatMillisAsDuration((now - startTime) as Millis)}`;
+          // A clock set back, or a startTime ahead of now, must not print a
+          // negative duration.
+          timestamp = `+${formatMillisAsDuration(
+            Math.max(0, now - startTime) as Millis,
+          )}`;
           break;
         case "absolute":
           timestamp = formatMillisAsClockTime(now);
@@ -709,8 +667,8 @@ export const createMultiOutput = (
 /**
  * Creates a {@link TestConsole} that captures all output for testing.
  *
- * Unlike {@link createConsole}, this doesn't require dependencies and captures
- * entries in memory.
+ * Captures entries in memory and defaults to the `"trace"` level, so tests see
+ * every entry.
  *
  * ### Example
  *

package/src/Crypto.ts

@@ -102,6 +102,14 @@ type Entropy = typeof Entropy.Output;
 export const Entropy16 = /*#__PURE__*/ length(16)(Entropy);
 export type Entropy16 = typeof Entropy16.Output;
 
+/**
+ * Cryptographic entropy of exactly 20 bytes.
+ *
+ * @group Random bytes
+ */
+export const Entropy20 = /*#__PURE__*/ length(20)(Entropy);
+export type Entropy20 = typeof Entropy20.Output;
+
 /**
  * Cryptographic entropy of exactly 24 bytes.
  *
@@ -110,6 +118,14 @@ export type Entropy16 = typeof Entropy16.Output;
 export const Entropy24 = /*#__PURE__*/ length(24)(Entropy);
 export type Entropy24 = typeof Entropy24.Output;
 
+/**
+ * Cryptographic entropy of exactly 28 bytes.
+ *
+ * @group Random bytes
+ */
+export const Entropy28 = /*#__PURE__*/ length(28)(Entropy);
+export type Entropy28 = typeof Entropy28.Output;
+
 /**
  * Cryptographic entropy of exactly 32 bytes.
  *
@@ -150,14 +166,18 @@ export const testCreateRandomBytes = (deps: RandomLibDep): RandomBytes =>
   }) as RandomBytes;
 
 /**
- * SLIP21.
+ * Derives a 32-byte key from a seed and a path using
+ * [SLIP-21](https://github.com/satoshilabs/slips/blob/master/slip-0021.md).
  *
- * https://github.com/satoshilabs/slips/blob/master/slip-0021.md
+ * Derived keys are no stronger than the seed. A 16-byte seed gives 128 bits of
+ * security, or about 64 against a quantum computer, whatever the output length.
+ * Use a 32-byte random seed for keys that must stay safe against a quantum
+ * computer.
  *
  * @group Key derivation
  */
 export const createSlip21 = (
-  seed: Entropy16 | Entropy32 | Entropy64,
+  seed: Entropy16 | Entropy20 | Entropy24 | Entropy28 | Entropy32 | Entropy64,
   path: ReadonlyArray<string | number>,
 ): Entropy32 => {
   let currentNode = hmac(

package/src/Error.test.ts

@@ -75,6 +75,91 @@ describe("createUnknownError", () => {
     assertFalse("nonClonable" in result.error);
   });
 
+  it("describes error properties that cannot be cloned", () => {
+    const error = new Error("Test error", {
+      cause: { attempt: 2, retry: () => undefined },
+    });
+    const result = createUnknownError(error);
+
+    assertType(Object, result.error);
+    assertEqual(result.error.cause, '{"attempt":2}');
+    assertEqual(structuredClone(result), result);
+  });
+
+  it("converts errors in an array that cannot be cloned", () => {
+    const error = new AggregateError(
+      [
+        new Error("first", { cause: { retry: () => undefined } }),
+        new Error("second"),
+      ],
+      "both",
+    );
+    const result = createUnknownError(error);
+
+    assertType(Object, result.error);
+    const errors = result.error.errors as ReadonlyArray<{
+      readonly message: string;
+    }>;
+    assertEqual(
+      errors.map(({ message }) => message),
+      ["first", "second"],
+    );
+    assertEqual(structuredClone(result), result);
+  });
+
+  it("keeps reference cycles through errors and arrays", () => {
+    const error = new Error("Test error") as Error & {
+      originalError?: unknown;
+      items?: ReadonlyArray<unknown>;
+    };
+    const items: Array<unknown> = [() => undefined];
+    items.push(items);
+    error.cause = error;
+    error.originalError = error;
+    error.items = items;
+
+    const result = structuredClone(createUnknownError(error));
+
+    assertType(Object, result.error);
+    assertSame(result.error.cause, result.error);
+    assertSame(result.error.originalError, result.error);
+    const convertedItems = result.error.items as ReadonlyArray<unknown>;
+    assertSame(convertedItems[0], "() => undefined");
+    assertSame(convertedItems[1], convertedItems);
+  });
+
+  it("converts the errors of an AggregateError that can be cloned", () => {
+    const inner = globalThis.Object.assign(new Error("connect failed"), {
+      code: "ECONNREFUSED",
+    });
+    const result = structuredClone(
+      createUnknownError(new AggregateError([inner], "all failed")),
+    );
+
+    assertType(Object, result.error);
+    assertEqual(result.error.errors, [
+      {
+        stack: inner.stack,
+        message: "connect failed",
+        code: "ECONNREFUSED",
+        name: "Error",
+      },
+    ]);
+  });
+
+  it("includes the inherited name and message of a DOMException", () => {
+    const result = createUnknownError(
+      new Error("write failed", {
+        cause: new DOMException("Quota exceeded", "QuotaExceededError"),
+      }),
+    );
+
+    assertType(Object, result.error);
+    assertType(Object, result.error.cause);
+    assertEqual(result.error.cause.name, "QuotaExceededError");
+    assertEqual(result.error.cause.message, "Quota exceeded");
+  });
+
   it("handles structured cloneable objects", () => {
     const error = { key: "value" };
     const result = createUnknownError(error);

package/src/Error.ts

@@ -34,31 +34,57 @@ export interface UnknownError extends InferType<typeof UnknownError> {}
  * Creates an {@link UnknownError} from an unknown error.
  *
  * An `Error` becomes a plain object of its own properties, such as `message`
- * and `stack`. A `cause` that is an `Error` is converted the same way, a
- * function is dropped, and any other property is kept as it is. An `Error`'s
- * properties are not enumerable, so JSON and comparisons by content miss them,
- * and a structured clone creates a new `Error`. Any other value is
- * structured-cloned, or described by `String` when it cannot be, or as
- * `"[Unserializable Object]"` when even that throws.
+ * and `stack`, plus its `name`, `message`, and `stack` when they are inherited,
+ * as in a `DOMException`. A property that is an `Error`, such as `cause`, is
+ * converted the same way, an array, such as the `errors` of an
+ * `AggregateError`, is converted element by element, a function is dropped, and
+ * any other property is kept when it can be structured-cloned, or described as
+ * a string when it cannot. Reference cycles through errors and arrays stay
+ * cycles in the result. An `Error`'s properties are not enumerable, so JSON and
+ * comparisons by content miss them, and a structured clone creates a new
+ * `Error`. Any other value is structured-cloned, or described by `String` when
+ * it cannot be, or as `"[Unserializable Object]"` when even that throws.
  */
 export const createUnknownError = (error: unknown): UnknownError => {
-  const convertError = (err: Error): Record<string, unknown> => {
-    const result: Record<string, unknown> = Object.getOwnPropertyNames(
-      err,
-    ).reduce<Record<string, unknown>>((acc, key) => {
+  // An UnknownError is posted between workers, so its values must clone.
+  // Each error and array is converted once and registered before its values,
+  // so a reference cycle becomes a cycle in the result instead of endless
+  // recursion, and structured cloning preserves it.
+  const converted = new Map<object, unknown>();
+
+  const convertValue = (value: unknown): unknown => {
+    if (value instanceof Error) return convertError(value);
+    if (Array.isArray(value)) {
+      const known = converted.get(value);
+      if (known !== undefined) return known;
+      const result: Array<unknown> = [];
+      converted.set(value, result);
+      for (const element of value) result.push(convertValue(element));
+      return result;
+    }
+    try {
+      structuredClone(value);
+      return value;
+    } catch {
+      return safelyStringifyUnknownValue(value);
+    }
+  };
+
+  const convertError = (err: Error): unknown => {
+    const known = converted.get(err);
+    if (known !== undefined) return known;
+    const result: Record<string, unknown> = {};
+    converted.set(err, result);
+    for (const key of Object.getOwnPropertyNames(err)) {
       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;
+      if (typeof value !== "function") result[key] = convertValue(value);
+    }
+    // A DOMException keeps `name` and `message` on its prototype, and Firefox
+    // defines `stack` as a getter on Error.prototype, so getOwnPropertyNames
+    // misses them. Explicitly include them.
+    for (const key of ["name", "message", "stack"] as const) {
+      const value = err[key];
+      if (value !== undefined && !(key in result)) result[key] = value;
     }
     return result;
   };

package/src/Sqlite.ts

@@ -14,6 +14,7 @@ import { createMutableRecord, objectToEntries } from "./Object.ts";
 import type { Result } from "./Result.ts";
 import { ok } from "./Result.ts";
 import { type Task, testCreateRun, type TestRunDep } from "./Task.ts";
+import { performanceDurationBetween } from "./Time.ts";
 import {
   array,
   type ArrayType,
@@ -330,7 +331,7 @@ export const createSqlite =
     options?: SqliteDriverOptions,
   ): Task<Sqlite, never, CreateSqliteDriverDep> =>
   async (run) => {
-    const { createSqliteDriver } = run.deps;
+    const { createSqliteDriver, time } = run.deps;
     const console = run.deps.console.child("sql");
     await using disposer = new AsyncDisposableStack();
 
@@ -343,16 +344,23 @@ export const createSqlite =
       disposable<Sqlite>(
         {
           exec: <R extends SqliteRow = SqliteRow>(query: SqliteQuery) => {
-            console.debug({ query });
+            console.trace({ query });
 
-            const label =
+            const start =
               query.options?.logQueryExecutionTime === true
-                ? `SqliteQueryExecutionTime ${query.sql}`
+                ? time.performance.now()
                 : null;
-
-            if (label !== null) console.time(label);
             const result = driver.exec(query);
-            if (label !== null) console.timeEnd(label);
+            if (start !== null) {
+              const duration = performanceDurationBetween(
+                start,
+                time.performance.now(),
+              );
+              console.log("[logQueryExecutionTime]", {
+                query,
+                duration: `${duration.toFixed(3)}ms`,
+              });
+            }
 
             if (query.options?.logExplainQueryPlan) {
               const result = driver.exec({
@@ -367,12 +375,12 @@ export const createSqlite =
               );
             }
 
-            console.debug({ result });
+            console.trace({ result });
             return result as SqliteExecResult<R>;
           },
 
           transaction: ((callback: () => Result<unknown, unknown> | void) => {
-            console.debug("begin");
+            console.trace("begin");
             driver.exec(sql`begin;`);
 
             // After errors such as SQLITE_FULL or SQLITE_IOERR, SQLite may roll
@@ -386,14 +394,14 @@ export const createSqlite =
             let shouldRollback = true;
             rollback.defer(() => {
               if (!shouldRollback) return;
-              console.debug("rollback");
+              console.trace("rollback");
               driver.exec(sql`rollback;`);
             });
 
             const result = callback();
             if (result != null && !result.ok) return result;
 
-            console.debug("commit");
+            console.trace("commit");
             driver.exec(sql`commit;`);
             shouldRollback = false;
 

package/src/Task.test.ts

@@ -19,6 +19,7 @@ import {
 } from "./Assert.ts";
 
 import { emptyArray, type NonEmptyReadonlyArray } from "./Array.ts";
+import { testCreateConsole } from "./Console.ts";
 import { emptyRecord } from "./Object.ts";
 import type { Int1To100OrPositiveInt } from "./Number.ts";
 import { none, some, type Option } from "./Option.ts";
@@ -1640,6 +1641,51 @@ describe("Run", () => {
       assertSame(secondRun.deps.console.getLevel(), secondRunLevel);
     });
 
+    it("reports leaks to the console passed to createRun", async () => {
+      const console = testCreateConsole();
+      let report: ((leak: unknown) => void) | undefined;
+      // Captures the callback that garbage collection would call.
+      using _registry = testStubGlobal(
+        "FinalizationRegistry",
+        function (callback: (leak: unknown) => void) {
+          report = callback;
+          return { register: () => undefined, unregister: () => undefined };
+        },
+      );
+      await using _run = createRun({ console });
+
+      assertNotUndefined(report);
+      report({ name: "Lease", isLeaked: () => true, stack: "stack" });
+
+      assertEqual(console.getEntriesSnapshot(), [
+        {
+          method: "warn",
+          path: [],
+          args: [
+            "Lease was garbage-collected without cleanup. Tracked at:",
+            "stack",
+          ],
+        },
+      ]);
+    });
+
+    it("reports leaks to the console passed to testCreateRun", async () => {
+      const console = testCreateConsole();
+      await using run = testCreateRun({ console });
+
+      run.deps.leakDetector.track(
+        {},
+        { name: "Lease", isLeaked: () => true },
+        {},
+      );
+
+      assertEqual(run.deps.leakDetector.collect(), 1);
+      assertEqual(
+        console.getEntriesSnapshot().map(({ args }) => args[0]),
+        ["Lease was garbage-collected without cleanup. Tracked at:"],
+      );
+    });
+
     it("lets custom deps override defaults in createRun", async () => {
       await using run = createRun({ random });