@evolu/nodejs 3.1.0 → 4.0.0

package/README.md

@@ -1,11 +1,20 @@
 # Evolu for Node.js
 
-This package provides Evolu for [Node.js](https://nodejs.org) 24+.
+This package provides Evolu for [Node.js](https://nodejs.org) 24.20+.
 
 ## Documentation
 
 For detailed information and usage examples, please visit [evolu.dev](https://www.evolu.dev).
 
+## Test overview reporter
+
+`@evolu/nodejs/TestOverviewReporter` lists Node.js test files slowest-first while
+preserving native failure diagnostics, run totals, and coverage output:
+
+```sh
+node --test --test-reporter=@evolu/nodejs/TestOverviewReporter
+```
+
 ## Community
 
 The Evolu community is on [GitHub Discussions](https://github.com/evoluhq/evolu/discussions), where you can ask questions and voice ideas.

package/dist/src/Fs.d.ts

@@ -0,0 +1,63 @@
+/**
+ * File system operations using Node.js.
+ *
+ * @module
+ */
+import { type Fs } from "@evolu/common";
+/**
+ * Creates a {@link Fs} backed by `node:fs/promises`.
+ *
+ * `readFile` and `writeFile` pass the Run's abort signal to Node and propagate
+ * the Run's abort reason if Node rejects after cancellation. Cancellation can
+ * leave a write partially completed. Successful operations return their values
+ * even if an abort was requested. Other operations run to completion and return
+ * their results once started, so callers also receive created temporary
+ * directories and can dispose them.
+ *
+ * Temporary directory parents are resolved through the file system, preserving
+ * the meaning of symbolic links followed by `..`. Returned paths are absolute,
+ * so cleanup still targets the created directory after a change to the
+ * process's working directory.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import {
+ *   assertEqual,
+ *   assertFalse,
+ *   ok,
+ *   type FsDep,
+ *   type FsError,
+ *   type Task,
+ * } from "@evolu/common";
+ * import { createNodeFs, runMain } from "@evolu/nodejs";
+ * import { join } from "node:path";
+ *
+ * const main: Task<void, FsError, FsDep> = async (run) => {
+ *   const { fs } = run.deps;
+ *   const temp = await run(fs.createTempDirectory({ prefix: "evolu-" }));
+ *   if (!temp.ok) return temp;
+ *
+ *   {
+ *     await using directory = temp.value;
+ *     const path = join(directory.path, "config.json");
+ *
+ *     const result = await run(fs.writeFile(path, '{ "port": 4000 }'));
+ *     if (!result.ok) return result;
+ *
+ *     const text = await run(fs.readFile(path, "utf8"));
+ *     if (!text.ok) return text;
+ *     assertEqual(text.value, '{ "port": 4000 }');
+ *   }
+ *
+ *   const exists = await run(fs.exists(temp.value.path));
+ *   if (!exists.ok) return exists;
+ *   assertFalse(exists.value);
+ *   return ok();
+ * };
+ *
+ * await runMain({ fs: createNodeFs() }, { mode: "command" })(main);
+ * ```
+ */
+export declare const createNodeFs: () => Fs;
+//# sourceMappingURL=Fs.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Fs.d.ts","sourceRoot":"","sources":["../../src/Fs.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAOL,KAAK,EAAE,EAQR,MAAM,eAAe,CAAC;AAmBvB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AACH,eAAO,MAAM,YAAY,QAAO,EAgI/B,CAAC"}

package/dist/src/Fs.js

@@ -0,0 +1,217 @@
+/**
+ * File system operations using Node.js.
+ *
+ * @module
+ */
+import { assert, ByteLength, disposable, err, ok, tryAsync, } from "@evolu/common";
+import { constants } from "node:fs";
+import { access, copyFile, cp, mkdir, mkdtemp, readdir, readFile, realpath, rename, rm, stat, writeFile, } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join, sep } from "node:path";
+/**
+ * Creates a {@link Fs} backed by `node:fs/promises`.
+ *
+ * `readFile` and `writeFile` pass the Run's abort signal to Node and propagate
+ * the Run's abort reason if Node rejects after cancellation. Cancellation can
+ * leave a write partially completed. Successful operations return their values
+ * even if an abort was requested. Other operations run to completion and return
+ * their results once started, so callers also receive created temporary
+ * directories and can dispose them.
+ *
+ * Temporary directory parents are resolved through the file system, preserving
+ * the meaning of symbolic links followed by `..`. Returned paths are absolute,
+ * so cleanup still targets the created directory after a change to the
+ * process's working directory.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import {
+ *   assertEqual,
+ *   assertFalse,
+ *   ok,
+ *   type FsDep,
+ *   type FsError,
+ *   type Task,
+ * } from "@evolu/common";
+ * import { createNodeFs, runMain } from "@evolu/nodejs";
+ * import { join } from "node:path";
+ *
+ * const main: Task<void, FsError, FsDep> = async (run) => {
+ *   const { fs } = run.deps;
+ *   const temp = await run(fs.createTempDirectory({ prefix: "evolu-" }));
+ *   if (!temp.ok) return temp;
+ *
+ *   {
+ *     await using directory = temp.value;
+ *     const path = join(directory.path, "config.json");
+ *
+ *     const result = await run(fs.writeFile(path, '{ "port": 4000 }'));
+ *     if (!result.ok) return result;
+ *
+ *     const text = await run(fs.readFile(path, "utf8"));
+ *     if (!text.ok) return text;
+ *     assertEqual(text.value, '{ "port": 4000 }');
+ *   }
+ *
+ *   const exists = await run(fs.exists(temp.value.path));
+ *   if (!exists.ok) return exists;
+ *   assertFalse(exists.value);
+ *   return ok();
+ * };
+ *
+ * await runMain({ fs: createNodeFs() }, { mode: "command" })(main);
+ * ```
+ */
+export const createNodeFs = () => {
+    function readFileTask(path, encoding) {
+        return async (run) => {
+            const { signal } = run;
+            const result = await tryAsync(() => encoding === undefined
+                ? readFile(path, { signal })
+                : readFile(path, { ...toEncodingOptions(encoding), signal }));
+            if (result.ok)
+                return result;
+            signal.throwIfAborted();
+            return err(createFsError("readFile", path, result.error));
+        };
+    }
+    return {
+        readFile: readFileTask,
+        writeFile: (path, data, options) => async (run) => {
+            const { signal } = run;
+            const result = await tryAsync(() => writeFile(path, data, { ...options, signal }));
+            if (result.ok)
+                return result;
+            signal.throwIfAborted();
+            return err(createFsError("writeFile", path, result.error));
+        },
+        readDirectory: (path, options) => async () => {
+            const result = await tryAsync(() => readdir(path, options));
+            return result.ok
+                ? result
+                : err(createFsError("readDirectory", path, result.error));
+        },
+        createDirectory: (path, options) => async () => {
+            const result = await tryAsync(async () => {
+                await mkdir(path, options);
+            });
+            return result.ok
+                ? ok()
+                : err(createFsError("createDirectory", path, result.error));
+        },
+        copy: (source, destination, options) => async () => {
+            const result = await tryAsync(() => cp(source, destination, { ...options, recursive: true }));
+            return result.ok
+                ? ok()
+                : err(createFsError("copy", source, result.error, destination));
+        },
+        copyFile: (source, destination, { overwrite = false } = {}) => async () => {
+            const result = await tryAsync(() => copyFile(source, destination, overwrite ? 0 : constants.COPYFILE_EXCL));
+            return result.ok
+                ? ok()
+                : err(createFsError("copyFile", source, result.error, destination));
+        },
+        rename: (source, destination) => async () => {
+            const result = await tryAsync(() => rename(source, destination));
+            return result.ok
+                ? ok()
+                : err(createFsError("rename", source, result.error, destination));
+        },
+        remove: (path, options) => async () => {
+            const result = await tryAsync(() => rm(path, options));
+            return result.ok
+                ? ok()
+                : err(createFsError("remove", path, result.error));
+        },
+        getMetadata: (path) => async () => {
+            const result = await tryAsync(() => stat(path));
+            return result.ok
+                ? ok(statsToFsMetadata(result.value))
+                : err(createFsError("getMetadata", path, result.error));
+        },
+        exists: (path) => async () => {
+            const result = await tryAsync(() => access(path));
+            if (result.ok)
+                return ok(true);
+            const error = createFsError("exists", path, result.error);
+            return error.reason === "NotFound" ? ok(false) : err(error);
+        },
+        createTempDirectory: ({ directory, prefix = "" } = {}) => async () => {
+            const parent = directory ?? tmpdir();
+            const resolvedParent = await tryAsync(() => realpath(parent || "."), (error) => createFsError("createTempDirectory", parent, error));
+            if (!resolvedParent.ok)
+                return resolvedParent;
+            // Keep the parent separator even when the name prefix is empty.
+            const pathPrefix = join(resolvedParent.value, sep) + prefix;
+            const result = await tryAsync(() => mkdtemp(pathPrefix), (error) => createFsError("createTempDirectory", pathPrefix, error));
+            if (!result.ok)
+                return result;
+            const path = result.value;
+            const disposer = new AsyncDisposableStack();
+            disposer.defer(() => rm(path, { recursive: true, force: true }));
+            return ok(disposable({ path }, disposer));
+        },
+    };
+};
+const toEncodingOptions = (encoding) => typeof encoding === "string" ? { encoding } : encoding;
+const fsErrorReasonByCode = {
+    ENOENT: "NotFound",
+    EEXIST: "AlreadyExists",
+    EACCES: "PermissionDenied",
+    EPERM: "PermissionDenied",
+    EISDIR: "IsDirectory",
+    ERR_FS_EISDIR: "IsDirectory",
+    ERR_FS_CP_EEXIST: "AlreadyExists",
+    ERR_FS_CP_NON_DIR_TO_DIR: "IsDirectory",
+    ERR_FS_CP_DIR_TO_NON_DIR: "NotDirectory",
+    ENOTDIR: "NotDirectory",
+    ENOTEMPTY: "NotEmpty",
+    EBUSY: "Busy",
+};
+const createFsError = (method, path, error, destination) => {
+    assert(error instanceof Error, "Node fs rejects with an Error.");
+    const { code, syscall } = error;
+    return {
+        type: "FsError",
+        reason: fsErrorReasonByCode[String(code)] ?? "Unknown",
+        path: typeof path === "string" ? path : path.href,
+        ...(destination === undefined
+            ? {}
+            : {
+                destination: typeof destination === "string" ? destination : destination.href,
+            }),
+        syscall: syscall ?? method,
+        message: error.message,
+    };
+};
+const fsEntryTypeByMode = {
+    [constants.S_IFREG]: "File",
+    [constants.S_IFDIR]: "Directory",
+    [constants.S_IFLNK]: "SymbolicLink",
+    [constants.S_IFBLK]: "BlockDevice",
+    [constants.S_IFCHR]: "CharacterDevice",
+    [constants.S_IFIFO]: "FIFO",
+    [constants.S_IFSOCK]: "Socket",
+};
+const statsToFsMetadata = (stats) => ({
+    type: fsEntryTypeByMode[stats.mode & constants.S_IFMT] ?? "Unknown",
+    dev: stats.dev,
+    ino: stats.ino,
+    mode: stats.mode,
+    nlink: stats.nlink,
+    uid: stats.uid,
+    gid: stats.gid,
+    rdev: stats.rdev,
+    size: ByteLength.orThrow(stats.size),
+    blksize: stats.blksize,
+    blocks: stats.blocks,
+    atimeMs: stats.atimeMs,
+    mtimeMs: stats.mtimeMs,
+    ctimeMs: stats.ctimeMs,
+    birthtimeMs: stats.birthtimeMs,
+    atime: stats.atime,
+    mtime: stats.mtime,
+    ctime: stats.ctime,
+    birthtime: stats.birthtime,
+});

package/dist/src/Task.d.ts

@@ -22,69 +22,82 @@ export interface RunMainOptions {
      * How termination signals affect the process exit status.
      *
      * Services treat a gracefully handled signal as a successful shutdown.
-     * Commands use the conventional `128 + signal number` exit status unless a
-     * reported defect has already set a failure status.
+     * Commands use the conventional `128 + signal number` exit status unless
+     * `process.exitCode` is already set.
      *
      * @default "service"
      */
     readonly mode?: RunMainMode;
 }
 /**
- * Runs the main Task as the Node.js program lifecycle.
+ * Runs the main {@link Task} of a Node.js command or service.
  *
- * Creates one root {@link Run} and aborts it on:
+ * A command does a finite job, such as importing data. A service handles
+ * ongoing work, such as accepting connections. Choose a mode for how the
+ * program reports an interruption:
  *
- * - `SIGINT`: Ctrl-C on all platforms.
- * - `SIGTERM`: OS, service, Docker, or Kubernetes termination on Unix.
- * - `SIGBREAK`: Ctrl-Break on Windows.
+ * - `"command"`: A termination signal means the job was interrupted. After
+ *   cleanup, use the conventional signal exit status, such as 130 for Ctrl-C,
+ *   unless `process.exitCode` is already set.
+ * - `"service"` (default): A termination signal is an expected way to stop the
+ *   service. Graceful shutdown does not set a failure exit status.
  *
- * The first signal logs shutdown progress, aborts the root Run, and waits for
- * the main Task and structured cleanup to finish. A subsequent signal exits
- * immediately with its conventional signal status, abandoning cleanup. A signal
- * received during final cleanup still applies signal shutdown behavior.
+ * Both modes create one root {@link Run} and wait for cleanup. The mode controls
+ * signal exit status; the main Task controls how long `runMain` waits.
  *
- * A main Task returning {@link Resource} keeps the program running until a
- * termination signal and is disposed during shutdown. A main Task returning
- * `void` completes the program immediately. A Resource result transfers
- * ownership of a live resource that must remain valid after its creating Task
- * settles.
+ * ### Lifetime
  *
- * Service mode treats graceful signal shutdown as successful. Command mode
- * preserves conventional signal exit statuses. Every defect reported through
- * `reportDefect`, including an observer defect that does not abort the Run,
- * sets `process.exitCode` to 1. The default reporter logs to the configured
+ * When the main Task returns `void`, `runMain` finishes after the Task and root
+ * Run cleanup. It does not force the Node.js process to exit.
+ *
+ * A service can return a live {@link Resource}, such as the relay created by
+ * {@link createRelay}. This transfers ownership to `runMain`, which waits for
+ * shutdown and then disposes the Resource. It must remain usable after the
+ * creating Task finishes; do not dispose it before returning it.
+ *
+ * Alternatively, the main Task can own its resources with `using` or `await
+ * using` while awaiting {@link waitForAbort} with `run(waitForAbort)`. Waiting
+ * for abort does not itself keep Node.js running: the service needs active
+ * work, such as a listening server.
+ *
+ * ### Shutdown and errors
+ *
+ * Handles `SIGINT` (Ctrl-C), `SIGTERM` (termination by the OS or a service
+ * host), and `SIGBREAK` (Ctrl-Break on Windows). The first signal logs shutdown
+ * progress, aborts the root Run, and waits for cleanup. A second signal exits
+ * immediately with its conventional signal status, abandoning cleanup. Signals
+ * are still handled during final cleanup.
+ *
+ * An error returned by the main Task is fatal. {@link getOrThrow} preserves it
+ * in `Error.cause`; the Run reports the failure and finishes cleanup. Every
+ * reported defect sets `process.exitCode` to 1, including an observer defect
+ * that does not abort the Run. The default reporter logs to the configured
  * Evolu console.
  *
  * Escaped uncaught exceptions and unhandled rejections remain under Node.js
  * native reporting and termination.
  *
- * ### Service Example
+ * ### Example
  *
- * ```ts
- * const deps = { ...createRelayDeps(), console: createConsole() };
- *
- * await runMain(deps)(createRelay({ port: 4000 }));
- * ```
- *
- * A Task returning `void` can keep a service alive explicitly when no Resource
- * owns its lifetime:
+ * A command finishes when its main Task completes:
  *
  * ```ts
- * await runMain(deps)(async (run) => {
- *   void run(processMessages);
- *   return await run(waitForAbort);
- * });
- * ```
+ * import { assertTrue, ok, type Task } from "@evolu/common";
+ * import { runMain } from "@evolu/nodejs";
  *
- * ### Command Example
+ * let completed = false;
+ * const command: Task<void> = () => {
+ *   completed = true;
+ *   return ok();
+ * };
  *
- * ```ts
  * await runMain(command, { mode: "command" });
+ * assertTrue(completed);
  * ```
  *
  * @group Node.js Task
  */
-export declare function runMain<T extends void | Resource>(main: Task<T>, options?: RunMainOptions): Promise<void>;
+export declare function runMain<T extends void | Resource, E = never>(main: Task<T, E>, options?: RunMainOptions): Promise<void>;
 /** With custom dependencies. */
-export declare function runMain<D extends object>(deps: RunCustomDeps<D>, options?: RunMainOptions): <T extends void | Resource>(main: Task<T, never, D>) => Promise<void>;
+export declare function runMain<D extends object>(deps: RunCustomDeps<D>, options?: RunMainOptions): <T extends void | Resource, E = never>(main: Task<T, E, D>) => Promise<void>;
 //# sourceMappingURL=Task.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"Task.d.ts","sourceRoot":"","sources":["../../src/Task.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAQL,KAAK,QAAQ,EAEb,KAAK,aAAa,EAClB,KAAK,IAAI,EACT,KAAK,KAAK,EACX,MAAM,eAAe,CAAC;AAEvB;;;;GAIG;AACH,MAAM,WAAW,qBAAsB,SAAQ,KAAK,CAAC,uBAAuB,CAAC;IAC3E,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;CAC7B;AAED,+DAA+D;AAC/D,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,SAAS,GAAG,UAAU,CAAC;AAE3D,sDAAsD;AACtD,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,SAAS,CAAC;AAEhD,mCAAmC;AACnC,MAAM,WAAW,cAAc;IAC7B;;;;;;;;OAQG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,WAAW,CAAC;CAC7B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AACH,wBAAgB,OAAO,CAAC,CAAC,SAAS,IAAI,GAAG,QAAQ,EAC/C,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,EACb,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,IAAI,CAAC,CAAC;AACjB,gCAAgC;AAChC,wBAAgB,OAAO,CAAC,CAAC,SAAS,MAAM,EACtC,IAAI,EAAE,aAAa,CAAC,CAAC,CAAC,EACtB,OAAO,CAAC,EAAE,cAAc,GACvB,CAAC,CAAC,SAAS,IAAI,GAAG,QAAQ,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC"}
+{"version":3,"file":"Task.d.ts","sourceRoot":"","sources":["../../src/Task.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EASL,KAAK,QAAQ,EAEb,KAAK,aAAa,EAClB,KAAK,IAAI,EACT,KAAK,KAAK,EACX,MAAM,eAAe,CAAC;AAGvB;;;;GAIG;AACH,MAAM,WAAW,qBAAsB,SAAQ,KAAK,CAAC,uBAAuB,CAAC;IAC3E,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;CAC7B;AAED,+DAA+D;AAC/D,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,SAAS,GAAG,UAAU,CAAC;AAE3D,sDAAsD;AACtD,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,SAAS,CAAC;AAEhD,mCAAmC;AACnC,MAAM,WAAW,cAAc;IAC7B;;;;;;;;OAQG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,WAAW,CAAC;CAC7B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmEG;AACH,wBAAgB,OAAO,CAAC,CAAC,SAAS,IAAI,GAAG,QAAQ,EAAE,CAAC,GAAG,KAAK,EAC1D,IAAI,EAAE,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,EAChB,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,IAAI,CAAC,CAAC;AACjB,gCAAgC;AAChC,wBAAgB,OAAO,CAAC,CAAC,SAAS,MAAM,EACtC,IAAI,EAAE,aAAa,CAAC,CAAC,CAAC,EACtB,OAAO,CAAC,EAAE,cAAc,GACvB,CAAC,CAAC,SAAS,IAAI,GAAG,QAAQ,EAAE,CAAC,GAAG,KAAK,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC"}

package/dist/src/Task.js

@@ -55,7 +55,7 @@ var __disposeResources = (this && this.__disposeResources) || (function (Suppres
     var e = new Error(message);
     return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
 });
-import { createConsole, createRun, isDisposable, ok, waitForAbort, } from "@evolu/common";
+import { createConsole, createRun, getOrThrow, isDisposable, ok, waitForAbort, } from "@evolu/common";
 export function runMain(mainOrDeps, { mode = "service" } = {}) {
     return typeof mainOrDeps === "function"
         ? runMainInternal(mainOrDeps, {}, mode)
@@ -106,7 +106,7 @@ const runMainInternal = async (main, deps, mode) => {
             await run(async (run) => {
                 const env_2 = { stack: [], error: void 0, hasError: false };
                 try {
-                    const resource = await run.ok(main);
+                    const resource = getOrThrow(await run(main));
                     if (!isDisposable(resource))
                         return ok();
                     const _resource = __addDisposableResource(env_2, resource, true);

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

@@ -1 +1 @@
-{"version":3,"file":"TestBundle.d.ts","sourceRoot":"","sources":["../../src/TestBundle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAYL,KAAK,gBAAgB,EACrB,KAAK,cAAc,EAQpB,MAAM,eAAe,CAAC;AA4CvB,wCAAwC;AACxC,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,mDAAmD;IACnD,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;CACpC;AAED,sDAAsD;AACtD,MAAM,MAAM,oBAAoB,GAAG,cAAc,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;AAE1E,0DAA0D;AAC1D,MAAM,MAAM,gBAAgB,GAAG,cAAc,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC;AAE5E,qEAAqE;AACrE,MAAM,WAAW,UAAW,SAAQ,cAAc;IAChD,gEAAgE;IAChE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,6EAA6E;IAC7E,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CACpC;AAED,kCAAkC;AAClC,MAAM,WAAW,cAAc;IAC7B;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,mEAAmE;IACnE,QAAQ,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/E;AAED,8DAA8D;AAC9D,MAAM,WAAW,iBAAiB;IAChC,wDAAwD;IACxD,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IACvD;;;OAGG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,cAAc,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClD;;;OAGG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,uEAAuE;IACvE,QAAQ,CAAC,eAAe,CAAC,EAAE,gBAAgB,CAAC;IAC5C,8EAA8E;IAC9E,QAAQ,CAAC,OAAO,CAAC,EAAE,gBAAgB,CAAC;CACrC;AAOD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,eAAO,MAAM,UAAU,qFAMpB,iBAAiB,KAAG,OAAO,CAAC,gBAAgB,CAgK9C,CAAC"}
+{"version":3,"file":"TestBundle.d.ts","sourceRoot":"","sources":["../../src/TestBundle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAaL,KAAK,gBAAgB,EACrB,KAAK,cAAc,EASpB,MAAM,eAAe,CAAC;AA4CvB,wCAAwC;AACxC,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,mDAAmD;IACnD,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;CACpC;AAED,sDAAsD;AACtD,MAAM,MAAM,oBAAoB,GAAG,cAAc,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;AAE1E,0DAA0D;AAC1D,MAAM,MAAM,gBAAgB,GAAG,cAAc,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC;AAE5E,qEAAqE;AACrE,MAAM,WAAW,UAAW,SAAQ,cAAc;IAChD,gEAAgE;IAChE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,6EAA6E;IAC7E,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CACpC;AAED,kCAAkC;AAClC,MAAM,WAAW,cAAc;IAC7B;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,mEAAmE;IACnE,QAAQ,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/E;AAED,8DAA8D;AAC9D,MAAM,WAAW,iBAAiB;IAChC,wDAAwD;IACxD,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IACvD;;;OAGG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,cAAc,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClD;;;OAGG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,uEAAuE;IACvE,QAAQ,CAAC,eAAe,CAAC,EAAE,gBAAgB,CAAC;IAC5C,8EAA8E;IAC9E,QAAQ,CAAC,OAAO,CAAC,EAAE,gBAAgB,CAAC;CACrC;AAOD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,eAAO,MAAM,UAAU,qFAMpB,iBAAiB,KAAG,OAAO,CAAC,gBAAgB,CA+J9C,CAAC"}

package/dist/src/TestBundle.js

@@ -62,7 +62,7 @@ var __disposeResources = (this && this.__disposeResources) || (function (Suppres
     var e = new Error(message);
     return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
 });
-import { allSettled, assert, assertType, instanceOf, createRun, durationToMillis, escapeRegExp, filterArray, isErr, mapArray, safelyStringifyUnknownValue, String as StringType, timeout, TimeoutError, tryAsync, } from "@evolu/common";
+import { allSettled, assert, assertLength, assertSame, assertType, instanceOf, createRun, durationToMillis, escapeRegExp, isErr, mapArray, partitionArray, safelyStringifyUnknownValue, String as StringType, timeout, TimeoutError, tryAsync, } from "@evolu/common";
 import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { dirname, isAbsolute, join, resolve } from "node:path";
@@ -186,7 +186,7 @@ export const testBundle = async ({ cases, aliases = {}, outputDirectory, bundlin
                 error,
             };
         }), { concurrency: availableParallelism() }));
-        const failures = filterArray(results, isErr);
+        const [failures, successes] = partitionArray(results, isErr);
         if (failures.length > 0) {
             const errors = mapArray(failures, ({ error: { caseName, bundler, error } }) => {
                 const message = error instanceof Error
@@ -202,8 +202,7 @@ export const testBundle = async ({ cases, aliases = {}, outputDirectory, bundlin
         const bundleEntriesByCase = new Map();
         for (const [caseName] of caseEntries)
             bundleEntriesByCase.set(caseName, []);
-        for (const result of results) {
-            assert(result.ok, "Expected every bundle test to succeed.");
+        for (const result of successes) {
             const { caseName, bundle } = result.value;
             const entries = bundleEntriesByCase.get(caseName);
             assert(entries, `Missing bundle test case "${caseName}".`);
@@ -314,13 +313,11 @@ const testViteBundler = {
         });
         assert(Array.isArray(output), "Vite did not return build outputs.");
         const outputs = output;
-        assert(outputs.length === 1, "Vite did not return one build output.");
-        const viteOutput = outputs.at(0);
-        assert(viteOutput, "Vite did not return a build output.");
-        assert(viteOutput.output.length === 1, "Vite did not emit one JavaScript chunk.");
-        const chunk = viteOutput.output.at(0);
-        assert(chunk, "Vite did not emit a JavaScript chunk.");
-        assert(chunk.type === "chunk", "Vite did not emit a JavaScript chunk.");
+        assertLength(outputs, 1);
+        const viteOutput = outputs[0];
+        assertLength(viteOutput.output, 1);
+        const chunk = viteOutput.output[0];
+        assertSame(chunk.type, "chunk");
         assertType(StringType, chunk.code);
         return {
             code: chunk.code,
@@ -415,7 +412,7 @@ const runTestBundler = (bundlerName, options) => async (run) => tryAsync(async (
     assertType(ErrorType, error);
     return error;
 });
-const ErrorType = /*#__PURE__*/ instanceOf(globalThis.Error);
+const ErrorType = /*#__PURE__*/ instanceOf(Error);
 // TODO: Replace the evaluated CommonJS worker with an ESM module worker.
 const testBundleWorkerSource = String.raw `
 const { parentPort, workerData } = require("node:worker_threads");

package/dist/src/TestJSDoc.d.ts

@@ -14,7 +14,10 @@ import { type ReadonlyRecord } from "@evolu/common";
 export interface TestJSDocExamplesOptions {
     /** Source files or glob patterns resolved from `cwd`. */
     readonly include: string | ReadonlyArray<string>;
-    /** Package imports redirected to absolute TypeScript entry paths. */
+    /**
+     * Package imports redirected to absolute TypeScript entry paths. Type
+     * checking also applies these aliases to imports within those modules.
+     */
     readonly aliases?: ReadonlyRecord<string, string>;
     /** Directory used for globbing and package resolution. */
     readonly cwd?: string;

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

@@ -1 +1 @@
-{"version":3,"file":"TestJSDoc.d.ts","sourceRoot":"","sources":["../../src/TestJSDoc.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAY,KAAK,cAAc,EAAE,MAAM,eAAe,CAAC;AAiB9D;;;GAGG;AACH,MAAM,WAAW,wBAAwB;IACvC,yDAAyD;IACzD,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC;IACjD,qEAAqE;IACrE,QAAQ,CAAC,OAAO,CAAC,EAAE,cAAc,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClD,0DAA0D;IAC1D,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,+DAA+D;IAC/D,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;CACrC;AA+CD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDG;AACH,eAAO,MAAM,iBAAiB,kDAK3B,wBAAwB,KAAG,OAAO,CAAC,IAAI,CAgKzC,CAAC"}
+{"version":3,"file":"TestJSDoc.d.ts","sourceRoot":"","sources":["../../src/TestJSDoc.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAY,KAAK,cAAc,EAAE,MAAM,eAAe,CAAC;AAiB9D;;;GAGG;AACH,MAAM,WAAW,wBAAwB;IACvC,yDAAyD;IACzD,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC;IACjD;;;OAGG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,cAAc,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClD,0DAA0D;IAC1D,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,+DAA+D;IAC/D,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;CACrC;AA+CD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDG;AACH,eAAO,MAAM,iBAAiB,kDAK3B,wBAAwB,KAAG,OAAO,CAAC,IAAI,CAmKzC,CAAC"}

package/dist/src/TestJSDoc.js

@@ -113,6 +113,7 @@ export const testJSDocExamples = async ({ include, aliases = {}, cwd = process.c
                 noEmit: true,
                 noUnusedLocals: false,
                 noUnusedParameters: false,
+                paths: Object.fromEntries(Object.entries(aliases).map(([name, target]) => [name, [target]])),
                 target: "es2022",
                 types: ["node"],
             },

package/dist/src/TestOverviewReporter.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Overview reporting for Node.js tests.
+ *
+ * Use the dedicated `@evolu/nodejs/TestOverviewReporter` entry point directly
+ * with Node.js:
+ *
+ * ```sh
+ * node --test --test-reporter=@evolu/nodejs/TestOverviewReporter
+ * ```
+ *
+ * @module
+ */
+import { type TestEvent } from "node:test/reporters";
+/**
+ * Lists test files slowest-first and preserves Node.js failure diagnostics, run
+ * totals, and coverage output.
+ *
+ * Durations longer than 300 ms are highlighted when terminal colors are
+ * supported.
+ */
+declare const testOverviewReporter: (source: AsyncIterable<TestEvent> | Iterable<TestEvent>) => AsyncGenerator<string | Uint8Array, void>;
+export default testOverviewReporter;
+//# sourceMappingURL=TestOverviewReporter.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"TestOverviewReporter.d.ts","sourceRoot":"","sources":["../../src/TestOverviewReporter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,EAAa,KAAK,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAKhE;;;;;;GAMG;AACH,QAAA,MAAM,oBAAoB,WAChB,aAAa,CAAC,SAAS,CAAC,GAAG,QAAQ,CAAC,SAAS,CAAC,KACrD,cAAc,CAAC,MAAM,GAAG,UAAU,EAAE,IAAI,CAuD1C,CAAC;eAEa,oBAAoB"}

package/dist/src/TestOverviewReporter.js

@@ -0,0 +1,66 @@
+/**
+ * Overview reporting for Node.js tests.
+ *
+ * Use the dedicated `@evolu/nodejs/TestOverviewReporter` entry point directly
+ * with Node.js:
+ *
+ * ```sh
+ * node --test --test-reporter=@evolu/nodejs/TestOverviewReporter
+ * ```
+ *
+ * @module
+ */
+import { relative } from "node:path";
+import { dot, spec } from "node:test/reporters";
+import { styleText } from "node:util";
+const slowTestThresholdMs = 300;
+/**
+ * Lists test files slowest-first and preserves Node.js failure diagnostics, run
+ * totals, and coverage output.
+ *
+ * Durations longer than 300 ms are highlighted when terminal colors are
+ * supported.
+ */
+const testOverviewReporter = async function* (source) {
+    const fileSummaries = [];
+    const dotOutput = [];
+    const specEvents = [];
+    let hasFailures = false;
+    const captureEvents = async function* () {
+        for await (const event of source) {
+            if (event.type === "test:fail")
+                hasFailures = true;
+            if (event.type === "test:summary" && event.data.file !== undefined) {
+                fileSummaries.push({ ...event.data, file: event.data.file });
+            }
+            if (event.type === "test:coverage" || event.type === "test:diagnostic") {
+                specEvents.push(event);
+            }
+            yield event;
+        }
+    };
+    for await (const output of dot(captureEvents()))
+        dotOutput.push(output);
+    fileSummaries.sort((a, b) => b.duration_ms - a.duration_ms);
+    if (hasFailures) {
+        for (const output of dotOutput)
+            yield output;
+    }
+    if (fileSummaries.length > 0) {
+        yield `${styleText("bold", "Test files:")}\n\n`;
+        for (const { counts, duration_ms, file, success } of fileSummaries) {
+            const testLabel = counts.tests === 1 ? "test" : "tests";
+            const status = styleText(success ? "green" : "red", success ? "✔" : "✖");
+            const tests = styleText("dim", `(${counts.tests} ${testLabel})`);
+            const duration = styleText(duration_ms > slowTestThresholdMs ? "yellow" : "green", `${Math.round(duration_ms)}ms`);
+            yield `${status} ${relative(process.cwd(), file)} ${tests} ${duration}\n`;
+        }
+        yield "\n";
+    }
+    const summaryReporter = spec();
+    for (const event of specEvents)
+        summaryReporter.write(event);
+    summaryReporter.end();
+    yield* summaryReporter;
+};
+export default testOverviewReporter;

package/dist/src/index.d.ts

@@ -4,6 +4,7 @@
  */
 export * from "./Cli.ts";
 export * from "./Crypto.ts";
+export * from "./Fs.ts";
 export * from "./local-first/Relay.ts";
 export * from "./Platform.ts";
 export * from "./Sqlite.ts";

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC;AAC5B,cAAc,wBAAwB,CAAC;AACvC,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,WAAW,CAAC;AAC1B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC;AAC5B,cAAc,SAAS,CAAC;AACxB,cAAc,wBAAwB,CAAC;AACvC,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,WAAW,CAAC;AAC1B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC"}