@evolu/common 7.4.0 → 8.0.0-next.0

package/dist/src/Brand.js

@@ -1 +1,6 @@
+/**
+ * A utility interface for creating branded types.
+ *
+ * @module
+ */
 export {};

package/dist/src/Buffer.d.ts

@@ -1,3 +1,8 @@
+/**
+ * Binary data handling and byte array utilities.
+ *
+ * @module
+ */
 import { NonNegativeInt } from "./Type.js";
 export { bytesToHex, bytesToUtf8, concatBytes, hexToBytes, utf8ToBytes, } from "@noble/ciphers/utils.js";
 /**
@@ -13,7 +18,7 @@ export declare class BufferError extends Error {
  * its capacity) to minimize memory reallocations and uses `subarray` for
  * efficient, copy-free data access in methods like `unwrap` and `shift`.
  *
- * ### Recommended Usage
+ * ## 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

package/dist/src/Buffer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Buffer.d.ts","sourceRoot":"","sources":["../../src/Buffer.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EACL,UAAU,EACV,WAAW,EACX,WAAW,EACX,UAAU,EACV,WAAW,GACZ,MAAM,yBAAyB,CAAC;AAEjC;;;GAGG;AACH,qBAAa,WAAY,SAAQ,KAAK;gBACxB,OAAO,EAAE,MAAM;CAM5B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,MAAM,WAAW,MAAM;IACrB,kDAAkD;IAClD,WAAW,EAAE,MAAM,cAAc,CAAC;IAElC,gEAAgE;IAChE,SAAS,EAAE,MAAM,cAAc,CAAC;IAEhC;;;OAGG;IACH,MAAM,EAAE,CAAC,GAAG,EAAE,UAAU,GAAG,SAAS,CAAC,MAAM,CAAC,KAAK,IAAI,CAAC;IAEtD;;;OAGG;IACH,KAAK,EAAE,MAAM,cAAc,CAAC;IAE5B;;;OAGG;IACH,MAAM,EAAE,CAAC,CAAC,EAAE,cAAc,KAAK,UAAU,CAAC;IAE1C;;;OAGG;IACH,QAAQ,EAAE,CAAC,MAAM,EAAE,cAAc,KAAK,IAAI,CAAC;IAE3C;;;;;;OAMG;IACH,KAAK,EAAE,MAAM,IAAI,CAAC;IAElB;;;;OAIG;IACH,MAAM,EAAE,MAAM,UAAU,CAAC;CAC1B;AAED,8DAA8D;AAC9D,eAAO,MAAM,YAAY,GACvB,YAAY,UAAU,GAAG,SAAS,CAAC,MAAM,CAAC,KACzC,MA4DF,CAAC"}
+{"version":3,"file":"Buffer.d.ts","sourceRoot":"","sources":["../../src/Buffer.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,cAAc,EAAsB,MAAM,WAAW,CAAC;AAC/D,OAAO,EACL,UAAU,EACV,WAAW,EACX,WAAW,EACX,UAAU,EACV,WAAW,GACZ,MAAM,yBAAyB,CAAC;AAEjC;;;GAGG;AACH,qBAAa,WAAY,SAAQ,KAAK;gBACxB,OAAO,EAAE,MAAM;CAM5B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,MAAM,WAAW,MAAM;IACrB,kDAAkD;IAClD,WAAW,EAAE,MAAM,cAAc,CAAC;IAElC,gEAAgE;IAChE,SAAS,EAAE,MAAM,cAAc,CAAC;IAEhC;;;OAGG;IACH,MAAM,EAAE,CAAC,GAAG,EAAE,UAAU,GAAG,SAAS,CAAC,MAAM,CAAC,KAAK,IAAI,CAAC;IAEtD;;;OAGG;IACH,KAAK,EAAE,MAAM,cAAc,CAAC;IAE5B;;;OAGG;IACH,MAAM,EAAE,CAAC,CAAC,EAAE,cAAc,KAAK,UAAU,CAAC;IAE1C;;;OAGG;IACH,QAAQ,EAAE,CAAC,MAAM,EAAE,cAAc,KAAK,IAAI,CAAC;IAE3C;;;;;;OAMG;IACH,KAAK,EAAE,MAAM,IAAI,CAAC;IAElB;;;;OAIG;IACH,MAAM,EAAE,MAAM,UAAU,CAAC;CAC1B;AAED,8DAA8D;AAC9D,eAAO,MAAM,YAAY,GACvB,YAAY,UAAU,GAAG,SAAS,CAAC,MAAM,CAAC,KACzC,MA4DF,CAAC"}

package/dist/src/Buffer.js

@@ -1,4 +1,9 @@
-import { NonNegativeInt } from "./Type.js";
+/**
+ * Binary data handling and byte array utilities.
+ *
+ * @module
+ */
+import { NonNegativeInt, zeroNonNegativeInt } from "./Type.js";
 export { bytesToHex, bytesToUtf8, concatBytes, hexToBytes, utf8ToBytes, } from "@noble/ciphers/utils.js";
 /**
  * Custom error for {@link Buffer}-related failures like premature end of data.
@@ -56,7 +61,7 @@ export const createBuffer = (arrayLike) => {
             length = newLength;
         },
         reset: () => {
-            length = NonNegativeInt.orThrow(0);
+            length = zeroNonNegativeInt;
         },
         unwrap: () => value.subarray(0, length),
     };

package/dist/src/Cache.d.ts

@@ -1,11 +1,19 @@
+/**
+ * Cache implementations including LRU eviction.
+ *
+ * @module
+ */
 import { PositiveInt } from "./Type.js";
 /**
  * Generic cache interface providing basic key-value storage operations.
  *
  * Keys are compared by reference (standard Map semantics).
  *
- * Note: Cache does not extend Map because eviction policies (like in LRU)
- * violate the Liskov Substitution Principle.
+ * Note: Cache has a Map-like API but does not extend Map because it behaves
+ * differently. Eviction policies (like LRU) can remove entries implicitly, and
+ * code that accepts a Map can assume values remain until deleted explicitly. An
+ * evicting cache is not a safe substitute for Map (Liskov Substitution
+ * Principle).
  */
 export interface Cache<K, V> {
     /** Checks if a key exists in the cache. */

package/dist/src/Cache.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Cache.d.ts","sourceRoot":"","sources":["../../src/Cache.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAExC;;;;;;;GAOG;AACH,MAAM,WAAW,KAAK,CAAC,CAAC,EAAE,CAAC;IACzB,2CAA2C;IAC3C,GAAG,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,OAAO,CAAC;IAEzB,kEAAkE;IAClE,GAAG,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,GAAG,SAAS,CAAC;IAE/B,4CAA4C;IAC5C,GAAG,EAAE,CAAC,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,KAAK,IAAI,CAAC;IAE9B,oCAAoC;IACpC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,IAAI,CAAC;IAEzB,mDAAmD;IACnD,QAAQ,CAAC,GAAG,EAAE,WAAW,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;CACjC;AAED;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,cAAc,GAAI,CAAC,EAAE,CAAC,EAAE,UAAU,WAAW,KAAG,KAAK,CAAC,CAAC,EAAE,CAAC,CAmCtE,CAAC"}
+{"version":3,"file":"Cache.d.ts","sourceRoot":"","sources":["../../src/Cache.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAExC;;;;;;;;;;GAUG;AACH,MAAM,WAAW,KAAK,CAAC,CAAC,EAAE,CAAC;IACzB,2CAA2C;IAC3C,GAAG,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,OAAO,CAAC;IAEzB,kEAAkE;IAClE,GAAG,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,GAAG,SAAS,CAAC;IAE/B,4CAA4C;IAC5C,GAAG,EAAE,CAAC,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,KAAK,IAAI,CAAC;IAE9B,oCAAoC;IACpC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,IAAI,CAAC;IAEzB,mDAAmD;IACnD,QAAQ,CAAC,GAAG,EAAE,WAAW,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;CACjC;AAED;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,cAAc,GAAI,CAAC,EAAE,CAAC,EAAE,UAAU,WAAW,KAAG,KAAK,CAAC,CAAC,EAAE,CAAC,CAmCtE,CAAC"}

package/dist/src/Cache.js

@@ -1,3 +1,9 @@
+/**
+ * Cache implementations including LRU eviction.
+ *
+ * @module
+ */
+import { PositiveInt } from "./Type.js";
 /**
  * Creates an LRU (least recently used) cache with a maximum capacity.
  *

package/dist/src/Callbacks.d.ts

@@ -1,6 +1,11 @@
-import { Brand } from "./Brand.js";
-import { RandomBytesDep } from "./Crypto.js";
+/**
+ * Request-response correlation for callbacks across boundaries.
+ *
+ * @module
+ */
+import type { RandomBytesDep } from "./Crypto.js";
 import { Id } from "./Type.js";
+import type { Callback } from "./Types.js";
 /**
  * Request-response correlation for callbacks across boundaries.
  *
@@ -40,14 +45,12 @@ import { Id } from "./Type.js";
  * @template T - The type of argument passed to callbacks (defaults to undefined
  *   for no-argument callbacks)
  */
-export interface Callbacks<T = undefined> {
+export interface Callbacks<T = undefined> extends Disposable {
     /** Registers a callback function and returns a unique ID. */
-    readonly register: (callback: (arg: T) => void) => CallbackId;
+    readonly register: (callback: Callback<T>) => Id;
     /** Executes and removes a callback associated with the given ID. */
-    readonly execute: T extends undefined ? (id: CallbackId) => undefined : (id: CallbackId, arg: T) => undefined;
+    readonly execute: T extends undefined ? (id: Id) => undefined : (id: Id, arg: T) => undefined;
 }
-/** Unique identifier for a callback in {@link Callbacks}. */
-export type CallbackId = Id & Brand<"Callback">;
 /** Creates a {@link Callbacks} registry for managing callbacks. */
 export declare const createCallbacks: <T = undefined>(deps: RandomBytesDep) => Callbacks<T>;
 //# sourceMappingURL=Callbacks.d.ts.map

package/dist/src/Callbacks.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Callbacks.d.ts","sourceRoot":"","sources":["../../src/Callbacks.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAE7C,OAAO,EAAY,EAAE,EAAE,MAAM,WAAW,CAAC;AAEzC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,MAAM,WAAW,SAAS,CAAC,CAAC,GAAG,SAAS;IACtC,6DAA6D;IAC7D,QAAQ,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,IAAI,KAAK,UAAU,CAAC;IAE9D,oEAAoE;IACpE,QAAQ,CAAC,OAAO,EAAE,CAAC,SAAS,SAAS,GACjC,CAAC,EAAE,EAAE,UAAU,KAAK,SAAS,GAC7B,CAAC,EAAE,EAAE,UAAU,EAAE,GAAG,EAAE,CAAC,KAAK,SAAS,CAAC;CAC3C;AAED,6DAA6D;AAC7D,MAAM,MAAM,UAAU,GAAG,EAAE,GAAG,KAAK,CAAC,UAAU,CAAC,CAAC;AAEhD,mEAAmE;AACnE,eAAO,MAAM,eAAe,GAAI,CAAC,GAAG,SAAS,EAC3C,MAAM,cAAc,KACnB,SAAS,CAAC,CAAC,CAsBb,CAAC"}
+{"version":3,"file":"Callbacks.d.ts","sourceRoot":"","sources":["../../src/Callbacks.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElD,OAAO,EAAY,EAAE,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE3C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,MAAM,WAAW,SAAS,CAAC,CAAC,GAAG,SAAS,CAAE,SAAQ,UAAU;IAC1D,6DAA6D;IAC7D,QAAQ,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC;IAEjD,oEAAoE;IACpE,QAAQ,CAAC,OAAO,EAAE,CAAC,SAAS,SAAS,GACjC,CAAC,EAAE,EAAE,EAAE,KAAK,SAAS,GACrB,CAAC,EAAE,EAAE,EAAE,EAAE,GAAG,EAAE,CAAC,KAAK,SAAS,CAAC;CACnC;AAED,mEAAmE;AACnE,eAAO,MAAM,eAAe,GAAI,CAAC,GAAG,SAAS,EAC3C,MAAM,cAAc,KACnB,SAAS,CAAC,CAAC,CA6Bb,CAAC"}

package/dist/src/Callbacks.js

@@ -1,25 +1,35 @@
-import { createId } from "./Type.js";
+/**
+ * Request-response correlation for callbacks across boundaries.
+ *
+ * @module
+ */
+import { createId, Id } from "./Type.js";
 /** Creates a {@link Callbacks} registry for managing callbacks. */
 export const createCallbacks = (deps) => {
     const callbackMap = new Map();
+    const execute = ((id, ...args) => {
+        const callback = callbackMap.get(id);
+        if (!callback)
+            return undefined;
+        callbackMap.delete(id);
+        if (args.length === 0) {
+            // Called without argument (undefined case)
+            callback();
+        }
+        else {
+            callback(args[0]);
+        }
+        return undefined;
+    });
     return {
         register: (callback) => {
             const id = createId(deps);
             callbackMap.set(id, callback);
             return id;
         },
-        execute: (id, ...args) => {
-            const callback = callbackMap.get(id);
-            if (!callback)
-                return;
-            callbackMap.delete(id);
-            if (args.length === 0) {
-                // Called without argument (undefined case)
-                callback();
-            }
-            else {
-                callback(args[0]);
-            }
+        execute,
+        [Symbol.dispose]: () => {
+            callbackMap.clear();
         },
     };
 };

package/dist/src/Console.d.ts

@@ -1,95 +1,387 @@
 /**
- * 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.
+ * Platform-agnostic console with structured logging.
  *
- * **Convention**: Use a tag (e.g., `[db]`) as the first argument for log
- * filtering.
+ * @module
+ */
+import type { ReadonlyStore } from "./Store.js";
+import { type Millis, type TimeDep } from "./Time.js";
+/**
+ * Platform-agnostic console with structured logging.
+ *
+ * Captures structured log entries and routes them to configurable outputs.
+ * Provides methods guaranteed to be available across browsers, Node.js, and
+ * React Native.
+ *
+ * Key features:
+ *
+ * - Structured entries — logs are captured as {@link ConsoleEntry} objects with
+ *   method, path, and args
+ * - Pluggable outputs — route logs to console, files, arrays, or custom
+ *   destinations via {@link ConsoleOutput}
+ * - Child consoles — use {@link Console.child} to create derived consoles
+ * - Level filtering — see {@link ConsoleLevel} for severity ordering
+ * - Entry formatting — use {@link createConsoleFormatter} for timestamps and path
+ *   prefixes
+ *
+ * Built-in outputs:
+ *
+ * - {@link createNativeConsoleOutput} — writes to `globalThis.console` (default)
+ * - {@link createConsoleArrayOutput} — captures entries to an array (testing)
+ * - {@link createConsoleStoreOutput} — stores latest entry in a
+ *   {@link ReadonlyStore} for subscribing
+ * - {@link createMultiOutput} — fans out to multiple outputs
  *
  * ### Example
  *
  * ```ts
- * deps.console.log("[evolu]", "createEvoluInstance", { name });
- * ```
+ * // Basic usage - defaults to "log"
+ * const console = createConsole();
  *
- * **Tip**: In browser dev tools, you can filter logs by tag (e.g., `[db]`) to
- * quickly find relevant messages. In Node.js, use `grep` to filter output:
+ * // With formatting (timestamps and path prefixes)
+ * const console = createConsole({
+ *   level: "info",
+ *   formatter: createConsoleFormatter()({ timestampFormat: "relative" }),
+ * });
  *
- * ```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
- * ```
+ * // Children inherit level at creation, then are independent
+ * const console = run.deps.console.child("relay");
+ * console.setLevel("silent");
  *
- * Or add to package.json scripts:
+ * // Tip: Wrap logged values in objects for labeled output in DevTools
+ * console.info("Creating instance", { config }); // Good — expandable "config:" label
+ * console.info("Creating instance", config); // Avoid — anonymous object, no label
  *
- * ```json
- * {
- *   "scripts": {
- *     "dev:relay": "node app.js | grep \"\\[relay\\]\"",
- *     "dev:db": "node app.js | grep -E \"\\[db\\]|\\[sql\\]\""
- *   }
- * }
+ * // Batch update via children
+ * const setLevelRecursive = (c: Console, level: ConsoleLevel): void => {
+ *   c.setLevel(level);
+ *   for (const child of c.children) setLevelRecursive(child, level);
+ * };
  * ```
+ *
+ * Console intentionally does not use {@link Task}. Logging must be as fast as
+ * possible and always work, even during error handling or shutdown.
+ *
+ * For testing, use {@link testCreateConsole} which creates a {@link TestConsole}
+ * with array output and snapshot helpers.
+ *
+ * @see {@link createConsole}
  */
 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;
-    /** 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;
-    /** 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;
-    /** Prints a stack trace with an optional message */
-    trace: (message?: any, ...optionalParams: Array<any>) => void;
+    /** 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.
+     */
+    readonly getLevel: () => ConsoleLevel;
+    /**
+     * Sets the log level for this console.
+     *
+     * Pass a level to override the inherited level, or `null` to revert to the
+     * inherited level.
+     */
+    readonly setLevel: (level: ConsoleLevel | null) => void;
+    /** Returns true if this console has its own level set (not inherited). */
+    readonly hasOwnLevel: () => boolean;
+    /**
+     * 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.
+     */
+    readonly child: (name: string) => Console;
+    /** Outputs a stack trace. */
+    readonly trace: (...args: ReadonlyArray<unknown>) => void;
+    /** Development diagnostics. */
+    readonly debug: (...args: ReadonlyArray<unknown>) => void;
+    /** General-purpose messages. */
+    readonly log: (...args: ReadonlyArray<unknown>) => void;
+    /** Operational milestones (startup, shutdown). */
+    readonly info: (...args: ReadonlyArray<unknown>) => void;
+    /** Recoverable issues that may need attention. */
+    readonly warn: (...args: ReadonlyArray<unknown>) => void;
+    /** 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.
+     */
+    readonly write: (entry: ConsoleEntry) => void;
 }
-/** Dependency interface for injecting a Console instance. */
 export interface ConsoleDep {
     readonly console: Console;
 }
+/**
+ * Log level controlling which messages are output.
+ *
+ * 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
+ * - `"log"` — General-purpose messages
+ * - `"info"` — Operational milestones (startup, shutdown)
+ * - `"warn"` — Recoverable issues that may need attention
+ * - `"error"` — Failures requiring immediate attention
+ * - `"silent"` — Disables all logging
+ */
+export type ConsoleLevel = "trace" | "debug" | "log" | "info" | "warn" | "error" | "silent";
+/**
+ * Structured log entry captured by {@link Console}.
+ *
+ * Contains all information needed for outputs to route the log: method for
+ * routing, path for context, and the original arguments.
+ */
+export interface ConsoleEntry {
+    /** The console method that was called. */
+    readonly method: ConsoleMethod;
+    /** Hierarchical path from {@link Console.child} calls (e.g., ["relay", "db"]). */
+    readonly path: ReadonlyArray<string>;
+    /** Original arguments passed to the console method. */
+    readonly args: ReadonlyArray<unknown>;
+}
+/**
+ * Console method being called.
+ *
+ * Used in {@link ConsoleEntry} to identify which console method was invoked.
+ * Outputs can route or format differently based on the method.
+ */
+export type ConsoleMethod = "trace" | "debug" | "log" | "info" | "warn" | "error" | "dir" | "table" | "time" | "timeLog" | "timeEnd" | "count" | "countReset";
+/**
+ * Output destination for {@link Console}.
+ *
+ * Implement this interface to create custom log destinations (file, network,
+ * array for testing, etc.).
+ *
+ * Use {@link createNativeConsoleOutput} for native console output.
+ */
+export interface ConsoleOutput {
+    /** Write a log entry to this output. */
+    readonly write: (entry: ConsoleEntry, formatter?: ConsoleFormatter) => void;
+}
+/**
+ * Transforms a {@link ConsoleEntry} before output.
+ *
+ * Used by {@link ConsoleConfig.formatter} and {@link ConsoleOutput.write}. Create
+ * one with {@link createConsoleFormatter}.
+ */
+export type ConsoleFormatter = (entry: ConsoleEntry) => ReadonlyArray<unknown>;
+/** Configuration for {@link createConsole}. */
 export interface ConsoleConfig {
+    /** Name of this console. Defaults to empty string. */
+    readonly name?: string;
+    /** Initial log level. Defaults to `"log"`. */
+    readonly level?: ConsoleLevel;
     /**
-     * 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.
+     * Output destination for log entries. Defaults to
+     * {@link createNativeConsoleOutput}.
      */
-    readonly enableLogging?: boolean;
+    readonly output?: ConsoleOutput;
+    /** Path prefix for this console. Defaults to `[]`. */
+    readonly path?: ReadonlyArray<string>;
+    /**
+     * Transforms entry args before writing (e.g., adds timestamps, path
+     * prefixes).
+     *
+     * Receives the entry and returns modified args. Use
+     * {@link createConsoleFormatter} for common formatting options.
+     */
+    readonly formatter?: ConsoleFormatter;
 }
-/** Creates a {@link Console} for logging with configurable output. */
-export declare const createConsole: (config?: ConsoleConfig) => Console;
-export interface ConsoleWithTimeConfig extends ConsoleConfig {
+/** Configuration for {@link createConsoleFormatter}. */
+export interface ConsoleFormatterConfig {
     /**
-     * Type of timestamp to prepend to log messages.
+     * Timestamp format 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")
+     * - `"relative"` — elapsed since start: `+0.000s`, `+1.500s`, `+1m30.000s`
+     * - `"absolute"` — local clock time: `14:32:15.234`
+     * - `"iso"` — ISO 8601 UTC: `2026-01-28T14:30:00.123Z`
+     * - `"none"` — no timestamp (default)
      */
-    readonly timestampType: "absolute" | "relative";
+    readonly timestampFormat?: ConsoleEntryTimestampFormat;
+    /**
+     * Start time for relative timestamps. Defaults to first entry timestamp.
+     *
+     * Pass a {@link Millis} value to use a custom start time, useful when multiple
+     * consoles should share the same relative timeline.
+     */
+    readonly startTime?: Millis;
+}
+/** Timestamp format for {@link ConsoleFormatterConfig}. */
+export type ConsoleEntryTimestampFormat = "relative" | "absolute" | "iso" | "none";
+/**
+ * A {@link ConsoleOutput} that stores the latest entry in a
+ * {@link ReadonlyStore}.
+ *
+ * Subscribe to {@link ConsoleStoreOutput.entry} to observe all log entries.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const storeOutput = createConsoleStoreOutput();
+ * const console = createConsole({ output: storeOutput });
+ *
+ * storeOutput.entry.subscribe(() => {
+ *   const entry = storeOutput.entry.get();
+ *   if (entry) forwardToClient(entry);
+ * });
+ * ```
+ */
+export interface ConsoleStoreOutput extends ConsoleOutput {
+    /** Latest entry written to this output. */
+    readonly entry: ReadonlyStore<ConsoleEntry | null>;
+}
+/**
+ * Dependency providing the latest {@link ConsoleEntry} from a
+ * {@link ConsoleStoreOutput}.
+ */
+export interface ConsoleStoreOutputEntryDep {
+    readonly consoleStoreOutputEntry: ReadonlyStore<ConsoleEntry | null>;
+}
+/**
+ * A test console that captures all output for assertions.
+ *
+ * Use as a drop-in replacement for {@link Console} in tests.
+ */
+export interface TestConsole extends Console {
+    /** Gets all captured entries and clears the internal buffer. */
+    readonly getEntriesSnapshot: () => ReadonlyArray<ConsoleEntry>;
+    /** Clears all captured entries. */
+    readonly clearEntries: () => void;
 }
-/** Creates a console instance with timestamp prefixes. */
-export declare const createConsoleWithTime: (config?: ConsoleWithTimeConfig) => Console;
+export interface TestConsoleDep {
+    readonly console: TestConsole;
+}
+/** Creates a {@link Console}. */
+export declare const createConsole: ({ name, level, output, path, formatter, }?: ConsoleConfig) => Console;
+/**
+ * Creates a {@link ConsoleOutput} that writes to `globalThis.console`.
+ *
+ * Pure transport - just calls the native console method with the entry args.
+ * Use {@link createConsoleFormatter} with {@link ConsoleConfig.formatter} for
+ * timestamps and path prefixes.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const output = createNativeConsoleOutput();
+ * ```
+ */
+export declare const createNativeConsoleOutput: () => ConsoleOutput;
+/**
+ * Creates a {@link ConsoleFormatter} for {@link ConsoleConfig.formatter}.
+ *
+ * Prepends timestamps and path prefixes to entry args.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const root = createConsole({
+ *   formatter: createConsoleFormatter()({
+ *     timestampFormat: "relative",
+ *   }),
+ * });
+ *
+ * // Relative — elapsed since start
+ * const relay = root.child("relay");
+ * relay.log("connected"); // +0.000s [relay] connected
+ * relay.log("synced"); // +1.500s [relay] synced
+ *
+ * // Nested children
+ * const db = relay.child("db");
+ * db.log("opened"); // +1.500s [relay] [db] opened
+ *
+ * // Absolute — local clock time (HH:MM:SS.mmm)
+ * // relay.log("connected"); // 15:30:15.123 [relay] connected
+ * ```
+ */
+export declare const createConsoleFormatter: ({ time }?: Partial<TimeDep>) => (config?: ConsoleFormatterConfig) => ConsoleFormatter;
+/** Creates a {@link ConsoleStoreOutput}. */
+export declare const createConsoleStoreOutput: () => ConsoleStoreOutput;
+/**
+ * Creates a {@link ConsoleOutput} that captures entries to an array.
+ *
+ * Useful for testing. Pass your own array to inspect captured entries.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const entries: Array<ConsoleEntry> = [];
+ * const output = createConsoleArrayOutput(entries);
+ *
+ * // After logging...
+ * expect(entries).toMatchInlineSnapshot();
+ * ```
+ */
+export declare const createConsoleArrayOutput: (entries: Array<ConsoleEntry>) => ConsoleOutput;
+/**
+ * Creates a {@link ConsoleOutput} that fans out to multiple outputs.
+ *
+ * Each entry is written to all outputs in order. Useful for combining a native
+ * console output with a store output for forwarding.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const storeOutput = createConsoleStoreOutput();
+ * const console = createConsole({
+ *   output: createMultiOutput([createNativeConsoleOutput(), storeOutput]),
+ * });
+ * ```
+ */
+export declare const createMultiOutput: (outputs: ReadonlyArray<ConsoleOutput>) => ConsoleOutput;
+/**
+ * Creates a {@link TestConsole} that captures all output for testing.
+ *
+ * Unlike {@link createConsole}, this doesn't require dependencies and uses a
+ * simple incrementing counter for timestamps (starting at 0).
+ *
+ * ### Example
+ *
+ * ```ts
+ * test("logging", () => {
+ *   const console = testCreateConsole();
+ *   console.info("Hello");
+ *
+ *   expect(console.getEntriesSnapshot()).toMatchInlineSnapshot(`
+ *     [
+ *       {
+ *         "method": "info",
+ *         "path": [],
+ *         "args": ["Hello"]
+ *       }
+ *     ]
+ *   `);
+ * });
+ *
+ * test("level filtering", () => {
+ *   const console = testCreateConsole({ level: "warn" });
+ *   console.debug("ignored");
+ *   console.warn("logged");
+ *   expect(console.getEntriesSnapshot()).toHaveLength(1);
+ * });
+ * ```
+ */
+export declare const testCreateConsole: ({ level, }?: {
+    level?: ConsoleLevel;
+}) => TestConsole;
 //# sourceMappingURL=Console.d.ts.map