@evolu/common 8.0.0-next.4 → 8.0.0

package/src/Console.ts

@@ -4,17 +4,17 @@
  * @module
  */
 
-import { objectFrom } from "./Object.js";
-import type { ReadonlyStore } from "./Store.js";
-import { createStore } from "./Store.js";
-import type { Task } from "./Task.js";
+import { objectFrom } from "./Object.ts";
+import type { ReadonlyStore } from "./Store.ts";
+import { createStore } from "./Store.ts";
+import type { Task } from "./Task.ts";
 import {
   createTime,
   formatMillisAsClockTime,
   formatMillisAsDuration,
   type Millis,
   type TimeDep,
-} from "./Time.js";
+} from "./Time.ts";
 
 /**
  * Platform-agnostic console with structured logging.
@@ -42,31 +42,47 @@ import {
  *   {@link ReadonlyStore} for subscribing
  * - {@link createMultiOutput} — fans out to multiple outputs
  *
+ * Wrap logged values in named objects such as `{ config }` so developer tools
+ * display useful, expandable labels.
+ *
  * ### Example
  *
  * ```ts
- * // Basic usage - defaults to "log"
- * const console = createConsole();
+ * import {
+ *   createConsole,
+ *   createConsoleArrayOutput,
+ *   type Console,
+ *   type ConsoleEntry,
+ *   type ConsoleLevel,
+ * } from "@evolu/common";
  *
- * // With formatting (timestamps and path prefixes)
- * const console = createConsole({
- *   level: "info",
- *   formatter: createConsoleFormatter()({ timestampFormat: "relative" }),
+ * const entries: Array<ConsoleEntry> = [];
+ * const root = createConsole({
+ *   output: createConsoleArrayOutput(entries),
  * });
- *
- * // Children inherit level at creation, then are independent
- * const console = run.deps.console.child("relay");
- * console.setLevel("silent");
- *
- * // 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
- *
- * // Batch update via children
- * const setLevelRecursive = (c: Console, level: ConsoleLevel): void => {
- *   c.setLevel(level);
- *   for (const child of c.children) setLevelRecursive(child, level);
+ * const relay = root.child("relay");
+ * // Silence a noisy subsystem without affecting root logs.
+ * relay.setLevel("silent");
+ * relay.info("polling");
+ * root.info("Creating instance", { config: { port: 4000 } });
+ *
+ * expect(root.getLevel()).toBe("log");
+ * expect(relay.getLevel()).toBe("silent");
+ * expect(entries[0]?.args).toEqual([
+ *   "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");
+ * expect(root.getLevel()).toBe("warn");
+ * expect(relay.getLevel()).toBe("warn");
  * ```
  *
  * Console intentionally does not use {@link Task}. Logging must be as fast as
@@ -177,13 +193,7 @@ export interface ConsoleDep {
  * - `"silent"` — Disables all logging
  */
 export type ConsoleLevel =
-  | "trace"
-  | "debug"
-  | "log"
-  | "info"
-  | "warn"
-  | "error"
-  | "silent";
+  "trace" | "debug" | "log" | "info" | "warn" | "error" | "silent";
 
 /**
  * Structured log entry captured by {@link Console}.
@@ -294,10 +304,7 @@ export interface ConsoleFormatterConfig {
 
 /** Timestamp format for {@link ConsoleFormatterConfig}. */
 export type ConsoleEntryTimestampFormat =
-  | "relative"
-  | "absolute"
-  | "iso"
-  | "none";
+  "relative" | "absolute" | "iso" | "none";
 
 /**
  * A {@link ConsoleOutput} that stores the latest entry in a
@@ -308,12 +315,26 @@ export type ConsoleEntryTimestampFormat =
  * ### Example
  *
  * ```ts
+ * import {
+ *   createConsole,
+ *   createConsoleStoreOutput,
+ *   type ConsoleEntry,
+ * } from "@evolu/common";
+ *
  * const storeOutput = createConsoleStoreOutput();
  * const console = createConsole({ output: storeOutput });
+ * let forwardedEntry: ConsoleEntry | null = null;
+ * const unsubscribe = storeOutput.entry.subscribe(() => {
+ *   forwardedEntry = storeOutput.entry.get();
+ * });
+ *
+ * console.child("relay").info("connected");
+ * unsubscribe();
  *
- * storeOutput.entry.subscribe(() => {
- *   const entry = storeOutput.entry.get();
- *   if (entry) forwardToClient(entry);
+ * expect(forwardedEntry).toEqual({
+ *   method: "info",
+ *   path: ["relay"],
+ *   args: ["connected"],
  * });
  * ```
  */
@@ -432,16 +453,26 @@ export const createConsole = ({
  * ### Example
  *
  * ```ts
+ * import {
+ *   createNativeConsoleOutput,
+ *   type ConsoleOutput,
+ * } from "@evolu/common";
+ *
  * const output = createNativeConsoleOutput();
+ *
+ * expectTypeOf(output).toEqualTypeOf<ConsoleOutput>();
+ * expect(output.write).toBeTypeOf("function");
  * ```
  */
 export const createNativeConsoleOutput = (): ConsoleOutput => ({
   write: (entry, formatter) => {
     const args = formatter ? formatter(entry) : entry.args;
-    const fn = globalThis.console[entry.method] as (
-      ...args: Array<unknown>
-    ) => void;
-    fn(...args);
+    (
+      globalThis.console as unknown as Record<
+        ConsoleMethod,
+        (...args: Array<unknown>) => void
+      >
+    )[entry.method](...args);
   },
 });
 
@@ -453,23 +484,52 @@ export const createNativeConsoleOutput = (): ConsoleOutput => ({
  * ### Example
  *
  * ```ts
- * const root = createConsole({
- *   formatter: createConsoleFormatter()({
- *     timestampFormat: "relative",
- *   }),
+ * import {
+ *   createConsoleFormatter,
+ *   Millis,
+ *   testCreateTime,
+ *   type ConsoleEntry,
+ * } from "@evolu/common";
+ *
+ * const time = testCreateTime({ startAt: Millis.orThrow(0) });
+ * const formatRelative = createConsoleFormatter({ time })({
+ *   timestampFormat: "relative",
  * });
+ * const connected: ConsoleEntry = {
+ *   method: "log",
+ *   path: ["relay"],
+ *   args: ["connected"],
+ * };
  *
- * // 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
+ * expect(formatRelative(connected)).toEqual([
+ *   "+0.000s [relay]",
+ *   "connected",
+ * ]);
+ * time.advance("1.5s");
+ * expect(
+ *   formatRelative({
+ *     ...connected,
+ *     path: ["relay", "db"],
+ *     args: ["opened"],
+ *   }),
+ * ).toEqual(["+1.500s [relay] [db]", "opened"]);
+ *
+ * const localTimestamp = new globalThis.Date(
+ *   2026,
+ *   0,
+ *   28,
+ *   14,
+ *   30,
+ *   15,
+ *   123,
+ * ).getTime();
+ * const formatAbsolute = createConsoleFormatter({
+ *   time: testCreateTime({ startAt: Millis.orThrow(localTimestamp) }),
+ * })({ timestampFormat: "absolute" });
+ * expect(formatAbsolute(connected)).toEqual([
+ *   "14:30:15.123 [relay]",
+ *   "connected",
+ * ]);
  * ```
  */
 export const createConsoleFormatter =
@@ -524,11 +584,20 @@ export const createConsoleStoreOutput = (): ConsoleStoreOutput => {
  * ### Example
  *
  * ```ts
- * const entries: Array<ConsoleEntry> = [];
- * const output = createConsoleArrayOutput(entries);
+ * import {
+ *   createConsole,
+ *   createConsoleArrayOutput,
+ *   type ConsoleEntry,
+ * } from "@evolu/common";
  *
- * // After logging...
- * expect(entries).toMatchInlineSnapshot();
+ * const entries: Array<ConsoleEntry> = [];
+ * const console = createConsole({
+ *   output: createConsoleArrayOutput(entries),
+ * });
+ * console.info("connected");
+ * expect(entries).toEqual([
+ *   { method: "info", path: [], args: ["connected"] },
+ * ]);
  * ```
  */
 export const createConsoleArrayOutput = (
@@ -548,10 +617,25 @@ export const createConsoleArrayOutput = (
  * ### Example
  *
  * ```ts
+ * import {
+ *   createConsole,
+ *   createConsoleArrayOutput,
+ *   createConsoleStoreOutput,
+ *   createMultiOutput,
+ *   type ConsoleEntry,
+ * } from "@evolu/common";
+ *
+ * const entries: Array<ConsoleEntry> = [];
  * const storeOutput = createConsoleStoreOutput();
  * const console = createConsole({
- *   output: createMultiOutput([createNativeConsoleOutput(), storeOutput]),
+ *   output: createMultiOutput([
+ *     createConsoleArrayOutput(entries),
+ *     storeOutput,
+ *   ]),
  * });
+ * console.error("disconnected");
+ *
+ * expect(storeOutput.entry.get()).toEqual(entries[0]);
  * ```
  */
 export const createMultiOutput = (
@@ -565,33 +649,21 @@ export const createMultiOutput = (
 /**
  * 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).
+ * Unlike {@link createConsole}, this doesn't require dependencies and captures
+ * entries in memory.
  *
  * ### Example
  *
  * ```ts
- * test("logging", () => {
- *   const console = testCreateConsole();
- *   console.info("Hello");
- *
- *   expect(console.getEntriesSnapshot()).toMatchInlineSnapshot(`
- *     [
- *       {
- *         "method": "info",
- *         "path": [],
- *         "args": ["Hello"]
- *       }
- *     ]
- *   `);
- * });
+ * import { testCreateConsole } from "@evolu/common";
  *
- * test("level filtering", () => {
- *   const console = testCreateConsole({ level: "warn" });
- *   console.debug("ignored");
- *   console.warn("logged");
- *   expect(console.getEntriesSnapshot()).toHaveLength(1);
- * });
+ * const console = testCreateConsole({ level: "info" });
+ * console.debug("ignored");
+ * console.child("relay").info("connected");
+ *
+ * expect(console.getEntriesSnapshot()).toEqual([
+ *   { method: "info", path: ["relay"], args: ["connected"] },
+ * ]);
  * ```
  */
 export const testCreateConsole = ({

package/src/Crypto.ts

@@ -12,10 +12,9 @@ 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 { arrayFrom } from "./Array.js";
-import type { RandomLibDep } from "./Random.js";
-import type { Result } from "./Result.js";
-import { trySync } from "./Result.js";
+import type { RandomLibDep } from "./Random.ts";
+import type { Result } from "./Result.ts";
+import { trySync } from "./Result.ts";
 import {
   brand,
   length,
@@ -23,7 +22,7 @@ import {
   Uint8Array,
   type Typed,
   zeroNonNegativeInt,
-} from "./Type.js";
+} from "./Type.ts";
 
 export interface RandomBytes {
   /**
@@ -38,20 +37,35 @@ export interface RandomBytes {
    *
    * Returns specific branded types for common sizes:
    *
-   * - `Random16` for 16-byte values (128 bits)
-   * - `Random24` for 24-byte values (192 bits)
-   * - `Random32` for 32-byte values (256 bits)
-   * - `Random64` for 64-byte values (512 bits)
-   * - `Random` for any other size
+   * - `Entropy16` for 16-byte values (128 bits)
+   * - `Entropy24` for 24-byte values (192 bits)
+   * - `Entropy32` for 32-byte values (256 bits)
+   * - `Entropy64` for 64-byte values (512 bits)
+   * - `Entropy` for any other size
    *
    * ### Example
    *
    * ```ts
-   * const nonce = randomBytes.create(16); // Type: Random16
-   * const nonce24 = randomBytes.create(24); // Type: Random24
-   * const key = randomBytes.create(32); // Type: Random32
-   * const seed = randomBytes.create(64); // Type: Random64
-   * const custom = randomBytes.create(48); // Type: Random
+   * import {
+   *   createRandomBytes,
+   *   type Entropy16,
+   *   type Entropy24,
+   *   type Entropy32,
+   *   type Entropy64,
+   * } from "@evolu/common";
+   *
+   * const randomBytes = createRandomBytes();
+   * const nonce16 = randomBytes.create(16);
+   * const nonce24 = randomBytes.create(24);
+   * const key = randomBytes.create(32);
+   * const seed = randomBytes.create(64);
+   * const custom = randomBytes.create(48);
+   *
+   * expectTypeOf(nonce16).toEqualTypeOf<Entropy16>();
+   * expectTypeOf(nonce24).toEqualTypeOf<Entropy24>();
+   * expectTypeOf(key).toEqualTypeOf<Entropy32>();
+   * expectTypeOf(seed).toEqualTypeOf<Entropy64>();
+   * expect(custom).toHaveLength(48);
    * ```
    */
   create(bytesLength: 16): Entropy16;
@@ -66,19 +80,19 @@ export interface RandomBytesDep {
 }
 
 const Entropy = /*#__PURE__*/ brand("Entropy", Uint8Array);
-type Entropy = typeof Entropy.Type;
+type Entropy = typeof Entropy.Output;
 
 export const Entropy16 = /*#__PURE__*/ length(16)(Entropy);
-export type Entropy16 = typeof Entropy16.Type;
+export type Entropy16 = typeof Entropy16.Output;
 
 export const Entropy24 = /*#__PURE__*/ length(24)(Entropy);
-export type Entropy24 = typeof Entropy24.Type;
+export type Entropy24 = typeof Entropy24.Output;
 
 export const Entropy32 = /*#__PURE__*/ length(32)(Entropy);
-export type Entropy32 = typeof Entropy32.Type;
+export type Entropy32 = typeof Entropy32.Output;
 
 export const Entropy64 = /*#__PURE__*/ length(64)(Entropy);
-export type Entropy64 = typeof Entropy64.Type;
+export type Entropy64 = typeof Entropy64.Output;
 
 export const createRandomBytes = (): RandomBytes => ({
   create: randomBytes as RandomBytes["create"],
@@ -87,10 +101,10 @@ export const createRandomBytes = (): RandomBytes => ({
 /** Creates seeded random bytes for deterministic tests. */
 export const testCreateRandomBytes = (deps: RandomLibDep): RandomBytes =>
   ({
-    create: (bytesLength: number) => {
-      const array = arrayFrom(bytesLength, () => deps.randomLib.int(0, 255));
-      return new globalThis.Uint8Array(array);
-    },
+    create: (bytesLength: number) =>
+      globalThis.Uint8Array.from({ length: bytesLength }, () =>
+        deps.randomLib.int(0, 255),
+      ),
   }) as RandomBytes;
 
 /**
@@ -134,7 +148,7 @@ export const deriveSlip21Node = (
 
 /** The encryption key for symmetric encryption. */
 export const EncryptionKey = /*#__PURE__*/ brand("EncryptionKey", Entropy32);
-export type EncryptionKey = typeof EncryptionKey.Type;
+export type EncryptionKey = typeof EncryptionKey.Output;
 
 /** The nonce length for XChaCha20-Poly1305 encryption. */
 export const xChaCha20Poly1305NonceLength = 24;
@@ -149,7 +163,7 @@ export const XChaCha20Poly1305Ciphertext = /*#__PURE__*/ brand(
   Uint8Array,
 );
 export type XChaCha20Poly1305Ciphertext =
-  typeof XChaCha20Poly1305Ciphertext.Type;
+  typeof XChaCha20Poly1305Ciphertext.Output;
 
 /**
  * Encrypts plaintext with XChaCha20-Poly1305.
@@ -160,11 +174,22 @@ export type XChaCha20Poly1305Ciphertext =
  * ### Example
  *
  * ```ts
- * const deps = { randomBytes: createRandomBytes() };
- * const [ciphertext, nonce] = encryptWithXChaCha20Poly1305(deps)(
- *   utf8ToBytes("secret message"),
- *   encryptionKey,
- * );
+ * import {
+ *   createRandomBytes,
+ *   EncryptionKey,
+ *   encryptWithXChaCha20Poly1305,
+ *   type XChaCha20Poly1305Ciphertext,
+ *   utf8ToBytes,
+ * } from "@evolu/common";
+ *
+ * const plaintext = utf8ToBytes("secret message");
+ * const encryptionKey = EncryptionKey.orThrow(new Uint8Array(32).fill(7));
+ * const [ciphertext, nonce] = encryptWithXChaCha20Poly1305({
+ *   randomBytes: createRandomBytes(),
+ * })(plaintext, encryptionKey);
+ *
+ * expectTypeOf(ciphertext).toEqualTypeOf<XChaCha20Poly1305Ciphertext>();
+ * expect(nonce).toHaveLength(24);
  * ```
  *
  * @see https://github.com/paulmillr/noble-ciphers
@@ -196,16 +221,33 @@ export interface DecryptWithXChaCha20Poly1305Error extends Typed<"DecryptWithXCh
  * ### Example
  *
  * ```ts
- * const result = decryptWithXChaCha20Poly1305(
- *   ciphertext,
- *   nonce,
- *   encryptionKey,
- * );
- * if (!result.ok) {
- *   // Handle decryption error
- *   return result;
- * }
- * const plaintext = result.value;
+ * import {
+ *   bytesToUtf8,
+ *   createRandomBytes,
+ *   decryptWithXChaCha20Poly1305,
+ *   EncryptionKey,
+ *   encryptWithXChaCha20Poly1305,
+ *   ok,
+ *   utf8ToBytes,
+ * } from "@evolu/common";
+ *
+ * const plaintext = utf8ToBytes("secret message");
+ * const encryptionKey = EncryptionKey.orThrow(new Uint8Array(32).fill(7));
+ * const [ciphertext, nonce] = encryptWithXChaCha20Poly1305({
+ *   randomBytes: createRandomBytes(),
+ * })(plaintext, encryptionKey);
+ *
+ * const decryptMessage = () => {
+ *   const result = decryptWithXChaCha20Poly1305(
+ *     ciphertext,
+ *     nonce,
+ *     encryptionKey,
+ *   );
+ *   if (!result.ok) return result;
+ *   return ok(bytesToUtf8(result.value));
+ * };
+ *
+ * expectOk(decryptMessage(), "secret message");
  * ```
  */
 export const decryptWithXChaCha20Poly1305 = (