@evolu/nodejs 3.0.0-next.3 → 3.0.1

package/dist/src/Cli.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Abort-aware CLI process utilities.
+ *
+ * @module
+ */
+import { type Task, type Typed } from "@evolu/common";
+/** Runs a command with inherited stdio. */
+export type Spawn = (file: string, args: ReadonlyArray<string>, options?: {
+    readonly cwd?: string | URL;
+}) => Task<void, SpawnError>;
+/** Failure to start a command or an unsuccessful command exit. */
+export interface SpawnError extends Typed<"SpawnError"> {
+    readonly command: string;
+    readonly exitCode: number | null;
+    readonly signal: NodeJS.Signals | null;
+    readonly message: string;
+}
+/** Dependency wrapper for {@link spawn}. */
+export interface SpawnDep {
+    readonly spawn: Spawn;
+}
+/**
+ * Runs a command with inherited stdio and aborts it with the current Run.
+ *
+ * A zero exit code succeeds. A start failure, non-zero exit code, or signal
+ * exit returns {@link SpawnError}.
+ */
+export declare const spawn: Spawn;
+//# sourceMappingURL=Cli.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Cli.d.ts","sourceRoot":"","sources":["../../src/Cli.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAqB,KAAK,IAAI,EAAE,KAAK,KAAK,EAAE,MAAM,eAAe,CAAC;AAGzE,2CAA2C;AAC3C,MAAM,MAAM,KAAK,GAAG,CAClB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,aAAa,CAAC,MAAM,CAAC,EAC3B,OAAO,CAAC,EAAE;IACR,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,GAAG,CAAC;CAC7B,KACE,IAAI,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;AAE5B,kEAAkE;AAClE,MAAM,WAAW,UAAW,SAAQ,KAAK,CAAC,YAAY,CAAC;IACrD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,OAAO,GAAG,IAAI,CAAC;IACvC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,4CAA4C;AAC5C,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;CACvB;AAED;;;;;GAKG;AACH,eAAO,MAAM,KAAK,EAAE,KAwCnB,CAAC"}

package/dist/src/Cli.js

@@ -0,0 +1,49 @@
+/**
+ * Abort-aware CLI process utilities.
+ *
+ * @module
+ */
+import { callback, err, ok } from "@evolu/common";
+import { spawn as nodeSpawn } from "node:child_process";
+/**
+ * Runs a command with inherited stdio and aborts it with the current Run.
+ *
+ * A zero exit code succeeds. A start failure, non-zero exit code, or signal
+ * exit returns {@link SpawnError}.
+ */
+export const spawn = (file, args, { cwd } = {}) => {
+    const command = [file, ...args].join(" ");
+    return callback(({ run, resolve }) => {
+        const child = nodeSpawn(file, args, {
+            cwd,
+            signal: run.signal,
+            stdio: "inherit",
+        });
+        child.once("error", (error) => {
+            if (run.signal.aborted)
+                return;
+            resolve(err({
+                type: "SpawnError",
+                command,
+                exitCode: null,
+                signal: null,
+                message: `Failed to start ${command}: ${error.message}`,
+            }));
+        });
+        child.once("close", (exitCode, signal) => {
+            if (run.signal.aborted)
+                return;
+            resolve(exitCode === 0
+                ? ok()
+                : err({
+                    type: "SpawnError",
+                    command,
+                    exitCode,
+                    signal,
+                    message: signal == null
+                        ? `${command} exited with code ${exitCode}.`
+                        : `${command} exited from ${signal}.`,
+                }));
+        });
+    });
+};

package/dist/src/Platform.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Node.js platform utilities.
+ *
+ * @module
+ */
+import { PositiveInt } from "@evolu/common";
+/** Returns the recommended amount of parallelism available to this process. */
+export type AvailableParallelism = () => PositiveInt;
+/** Dependency wrapper for {@link availableParallelism}. */
+export interface AvailableParallelismDep {
+    readonly availableParallelism: AvailableParallelism;
+}
+/** Returns the recommended amount of parallelism available to this process. */
+export declare const availableParallelism: AvailableParallelism;
+//# sourceMappingURL=Platform.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Platform.d.ts","sourceRoot":"","sources":["../../src/Platform.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAG5C,+EAA+E;AAC/E,MAAM,MAAM,oBAAoB,GAAG,MAAM,WAAW,CAAC;AAErD,2DAA2D;AAC3D,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,oBAAoB,EAAE,oBAAoB,CAAC;CACrD;AAED,+EAA+E;AAC/E,eAAO,MAAM,oBAAoB,EAAE,oBACc,CAAC"}

package/dist/src/Platform.js

@@ -0,0 +1,9 @@
+/**
+ * Node.js platform utilities.
+ *
+ * @module
+ */
+import { PositiveInt } from "@evolu/common";
+import { availableParallelism as nodeAvailableParallelism } from "node:os";
+/** Returns the recommended amount of parallelism available to this process. */
+export const availableParallelism = () => PositiveInt.orThrow(nodeAvailableParallelism());

package/dist/src/Sqlite.js

@@ -50,7 +50,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 { createPreparedStatementsCache, lazyVoid, ok, } from "@evolu/common";
+import { constVoid, createPreparedStatementsCache, ok, } from "@evolu/common";
 import BetterSQLite, {} from "better-sqlite3";
 import { rmSync } from "fs";
 export const createBetterSqliteDriver = (name, options) => () => {
@@ -72,7 +72,7 @@ export const createBetterSqliteDriver = (name, options) => () => {
         const cache = disposer.use(createPreparedStatementsCache((sql) => db.prepare(sql), 
         // Not needed.
         // https://github.com/WiseLibs/better-sqlite3/blob/master/docs/api.md#class-statement
-        lazyVoid));
+        constVoid));
         const disposables = disposer.move();
         return ok({
             exec: (query) => {

package/dist/src/Task.d.ts

@@ -3,43 +3,88 @@
  *
  * @module
  */
-import { type CreateRun, type RunDefaultDeps } from "@evolu/common";
+import { type Resource, type RunCustomDeps, type Task, type Typed } from "@evolu/common";
 /**
- * A promise that resolves when a termination signal is received.
+ * An abort requested by a Node.js termination signal.
  *
- * Resolves on `SIGINT` (Ctrl-C), `SIGTERM` (OS/k8s/Docker termination),
- * `SIGHUP` (console close/terminal disconnect), or `SIGBREAK` (Windows
- * Ctrl-Break).
- *
- * @group Node.js Run
+ * @group Node.js Task
  */
-export type Shutdown = Promise<void>;
-export interface ShutdownDep {
-    readonly shutdown: Shutdown;
+export interface NodeSignalAbortReason extends Typed<"NodeSignalAbortReason"> {
+    readonly signal: NodeSignal;
+}
+/** A Node.js termination signal handled by {@link runMain}. */
+export type NodeSignal = "SIGINT" | "SIGTERM" | "SIGBREAK";
+/** Process lifecycle behavior for {@link runMain}. */
+export type RunMainMode = "service" | "command";
+/** Options for {@link runMain}. */
+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.
+     *
+     * @default "service"
+     */
+    readonly mode?: RunMainMode;
 }
 /**
- * Creates {@link Run} for Node.js with global error handling and graceful
- * shutdown.
+ * Runs the main Task as the Node.js program lifecycle.
+ *
+ * Creates one root {@link Run} and aborts it on:
+ *
+ * - `SIGINT`: Ctrl-C on all platforms.
+ * - `SIGTERM`: OS, service, Docker, or Kubernetes termination on Unix.
+ * - `SIGBREAK`: Ctrl-Break on Windows.
+ *
+ * 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.
+ *
+ * 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.
+ *
+ * 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
+ * Evolu console.
  *
- * Registers `uncaughtException` and `unhandledRejection` handlers that log
- * errors and initiate graceful shutdown. Adds a `shutdown` promise to deps that
- * resolves on termination signals (`SIGINT`, `SIGTERM`, `SIGHUP`). Handlers are
- * removed when the Run is disposed.
+ * Escaped uncaught exceptions and unhandled rejections remain under Node.js
+ * native reporting and termination.
  *
- * ### Example
+ * ### Service Example
  *
  * ```ts
- * const deps = { ...createRelayDeps(), console };
+ * const deps = { ...createRelayDeps(), console: createConsole() };
  *
- * await using run = createRun(deps);
- * await using disposer = new AsyncDisposableStack();
+ * await runMain(deps)(createRelay({ port: 4000 }));
+ * ```
+ *
+ * A Task returning `void` can keep a service alive explicitly when no Resource
+ * owns its lifetime:
+ *
+ * ```ts
+ * await runMain(deps)(async (run) => {
+ *   void run(processMessages);
+ *   return await run(waitForAbort);
+ * });
+ * ```
  *
- * disposer.use(await run.orThrow(startRelay({ port: 4000 })));
+ * ### Command Example
  *
- * await run.deps.shutdown;
+ * ```ts
+ * await runMain(command, { mode: "command" });
  * ```
  *
- * @group Node.js Run
+ * @group Node.js Task
  */
-export declare const createRun: CreateRun<RunDefaultDeps & ShutdownDep>;
+export declare function runMain<T extends void | Resource>(main: Task<T>, 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>;
 //# 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,EAGL,KAAK,SAAS,EAEd,KAAK,cAAc,EACpB,MAAM,eAAe,CAAC;AAEvB;;;;;;;;GAQG;AACH,MAAM,MAAM,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAErC,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;CAC7B;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,SAAS,EAAE,SAAS,CAAC,cAAc,GAAG,WAAW,CAuC7D,CAAC"}
+{"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"}

package/dist/src/Task.js

@@ -3,57 +3,153 @@
  *
  * @module
  */
-import { createRun as createCommonRun, createUnknownError, } from "@evolu/common";
-/**
- * Creates {@link Run} for Node.js with global error handling and graceful
- * shutdown.
- *
- * Registers `uncaughtException` and `unhandledRejection` handlers that log
- * errors and initiate graceful shutdown. Adds a `shutdown` promise to deps that
- * resolves on termination signals (`SIGINT`, `SIGTERM`, `SIGHUP`). Handlers are
- * removed when the Run is disposed.
- *
- * ### Example
- *
- * ```ts
- * const deps = { ...createRelayDeps(), console };
- *
- * await using run = createRun(deps);
- * await using disposer = new AsyncDisposableStack();
- *
- * disposer.use(await run.orThrow(startRelay({ port: 4000 })));
- *
- * await run.deps.shutdown;
- * ```
- *
- * @group Node.js Run
- */
-export const createRun = (deps) => {
-    const { promise: shutdown, resolve: resolveShutdown } = Promise.withResolvers();
-    const run = createCommonRun({ ...deps, shutdown });
-    const console = run.deps.console.child("global");
-    const handleError = (source) => (error) => {
-        console.error(source, createUnknownError(error));
-        process.exitCode = 1;
-        // Resolve shutdown so `await run.deps.shutdown` unblocks
-        // and allows the stack to be disposed.
-        resolveShutdown();
+var __addDisposableResource = (this && this.__addDisposableResource) || function (env, value, async) {
+    if (value !== null && value !== void 0) {
+        if (typeof value !== "object" && typeof value !== "function") throw new TypeError("Object expected.");
+        var dispose, inner;
+        if (async) {
+            if (!Symbol.asyncDispose) throw new TypeError("Symbol.asyncDispose is not defined.");
+            dispose = value[Symbol.asyncDispose];
+        }
+        if (dispose === void 0) {
+            if (!Symbol.dispose) throw new TypeError("Symbol.dispose is not defined.");
+            dispose = value[Symbol.dispose];
+            if (async) inner = dispose;
+        }
+        if (typeof dispose !== "function") throw new TypeError("Object not disposable.");
+        if (inner) dispose = function() { try { inner.call(this); } catch (e) { return Promise.reject(e); } };
+        env.stack.push({ value: value, dispose: dispose, async: async });
+    }
+    else if (async) {
+        env.stack.push({ async: true });
+    }
+    return value;
+};
+var __disposeResources = (this && this.__disposeResources) || (function (SuppressedError) {
+    return function (env) {
+        function fail(e) {
+            env.error = env.hasError ? new SuppressedError(e, env.error, "An error was suppressed during disposal.") : e;
+            env.hasError = true;
+        }
+        var r, s = 0;
+        function next() {
+            while (r = env.stack.pop()) {
+                try {
+                    if (!r.async && s === 1) return s = 0, env.stack.push(r), Promise.resolve().then(next);
+                    if (r.dispose) {
+                        var result = r.dispose.call(r.value);
+                        if (r.async) return s |= 2, Promise.resolve(result).then(next, function(e) { fail(e); return next(); });
+                    }
+                    else s |= 1;
+                }
+                catch (e) {
+                    fail(e);
+                }
+            }
+            if (s === 1) return env.hasError ? Promise.reject(env.error) : Promise.resolve();
+            if (env.hasError) throw env.error;
+        }
+        return next();
     };
-    const handleUncaughtException = handleError("uncaughtException");
-    const handleUnhandledRejection = handleError("unhandledRejection");
-    process.on("uncaughtException", handleUncaughtException);
-    process.on("unhandledRejection", handleUnhandledRejection);
-    process.on("SIGINT", resolveShutdown); // Ctrl-C (all platforms)
-    process.on("SIGTERM", resolveShutdown); // OS/k8s/Docker termination (Unix)
-    process.on("SIGHUP", resolveShutdown); // Console close (Windows), terminal disconnect (Unix)
-    process.on("SIGBREAK", resolveShutdown); // Ctrl-Break (Windows)
-    run.onAbort(() => {
-        process.off("uncaughtException", handleUncaughtException);
-        process.off("unhandledRejection", handleUnhandledRejection);
-        process.off("SIGINT", resolveShutdown);
-        process.off("SIGTERM", resolveShutdown);
-        process.off("SIGHUP", resolveShutdown);
-        process.off("SIGBREAK", resolveShutdown);
-    });
-    return run;
+})(typeof SuppressedError === "function" ? SuppressedError : function (error, suppressed, message) {
+    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";
+export function runMain(mainOrDeps, { mode = "service" } = {}) {
+    return typeof mainOrDeps === "function"
+        ? runMainInternal(mainOrDeps, {}, mode)
+        : (main) => runMainInternal(main, mainOrDeps, mode);
+}
+const commandExitCodeBySignal = {
+    SIGINT: 130,
+    SIGTERM: 143,
+    SIGBREAK: 149,
+};
+const runMainInternal = async (main, deps, mode) => {
+    const env_1 = { stack: [], error: void 0, hasError: false };
+    try {
+        const console = deps.console ?? createConsole();
+        const mainConsole = console.child("main");
+        let defectReported = false;
+        let receivedSignal = null;
+        const disposer = __addDisposableResource(env_1, new AsyncDisposableStack(), true);
+        const run = disposer.use(createRun({
+            ...deps,
+            console,
+            reportDefect: (reported) => {
+                defectReported = true;
+                process.exitCode = 1;
+                if (deps.reportDefect)
+                    deps.reportDefect(reported);
+                else
+                    console.error(reported);
+            },
+        }));
+        ["SIGINT", "SIGTERM", "SIGBREAK"].forEach((signal) => {
+            const handleSignal = () => {
+                if (receivedSignal !== null) {
+                    mainConsole.warn("Forcing shutdown...");
+                    process.exit(commandExitCodeBySignal[signal]);
+                    return;
+                }
+                receivedSignal = signal;
+                mainConsole.info("Shutting down...");
+                run.abort({ type: "NodeSignalAbortReason", signal });
+            };
+            process.on(signal, handleSignal);
+            run.defer(() => {
+                process.off(signal, handleSignal);
+            });
+        });
+        try {
+            await run(async (run) => {
+                const env_2 = { stack: [], error: void 0, hasError: false };
+                try {
+                    const resource = await run.ok(main);
+                    if (!isDisposable(resource))
+                        return ok();
+                    const _resource = __addDisposableResource(env_2, resource, true);
+                    return await run(waitForAbort);
+                }
+                catch (e_2) {
+                    env_2.error = e_2;
+                    env_2.hasError = true;
+                }
+                finally {
+                    const result_2 = __disposeResources(env_2);
+                    if (result_2)
+                        await result_2;
+                }
+            });
+        }
+        catch {
+            // Aborts are control flow; defects are already handled by reportDefect.
+        }
+        // Move ownership out of the await-using setup safety net so an already
+        // reported finalizer defect can be suppressed during explicit disposal.
+        try {
+            await disposer.move().disposeAsync();
+        }
+        catch {
+            // Finalizer defects are already handled by reportDefect.
+        }
+        if (receivedSignal !== null) {
+            if (defectReported)
+                mainConsole.warn("Shutdown finished with errors");
+            else
+                mainConsole.info("Shutdown complete");
+            if (mode === "command")
+                process.exitCode ??= commandExitCodeBySignal[receivedSignal];
+        }
+    }
+    catch (e_1) {
+        env_1.error = e_1;
+        env_1.hasError = true;
+    }
+    finally {
+        const result_1 = __disposeResources(env_1);
+        if (result_1)
+            await result_1;
+    }
 };

package/dist/src/TestBundle.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Node.js utilities for testing production bundles.
+ *
+ * These utilities use the dedicated `@evolu/nodejs/TestBundle` entry point so
+ * normal `@evolu/nodejs` imports do not evaluate the test toolchain, while
+ * bundle tests do not evaluate unrelated Evolu Node.js adapters.
+ *
+ * The {@link testBundle} function loads its optional Webpack and Vite peer
+ * dependencies only when called.
+ *
+ * @module
+ */
+import { type PositiveDuration, type ReadonlyRecord } from "@evolu/common";
+/** The measured sizes of one bundle. */
+export interface TestBundleSize {
+    readonly rawSizeInBytes: number;
+    /** The Brotli-compressed size using quality 11. */
+    readonly brotliSizeInBytes: number;
+}
+/** Bundle sizes keyed by bundler name and version. */
+export type TestBundleCaseResult = ReadonlyRecord<string, TestBundleSize>;
+/** Case results keyed by case name for size snapshots. */
+export type TestBundleResult = ReadonlyRecord<string, TestBundleCaseResult>;
+/** The measured output supplied to {@link TestBundleCase.verify}. */
+export interface TestBundle extends TestBundleSize {
+    /** The bundler name and version, for example `"vite@8.1.5"`. */
+    readonly bundler: string;
+    readonly code: string;
+    /** The copied artifact, or `null` when no output directory was requested. */
+    readonly outputPath: string | null;
+}
+/** One named bundle test case. */
+export interface TestBundleCase {
+    /**
+     * A JavaScript or erasable-TypeScript entry.
+     *
+     * TypeScript dependencies are supported. TSX and TypeScript syntax that
+     * requires JavaScript generation are not supported by Webpack.
+     */
+    readonly entryPath: string;
+    /** Verifies the default export returned by each emitted bundle. */
+    readonly verify: (value: unknown, bundle: TestBundle) => void | Promise<void>;
+}
+/** Options for producing and verifying equivalent bundles. */
+export interface TestBundleOptions {
+    /** Named cases bundled with every supported bundler. */
+    readonly cases: ReadonlyRecord<string, TestBundleCase>;
+    /**
+     * Package aliases resolved for every case and bundler. Targets must be
+     * absolute paths to modules using JavaScript syntax.
+     */
+    readonly aliases?: ReadonlyRecord<string, string>;
+    /**
+     * Copies emitted bundles into this directory for later inspection. Relative
+     * paths are resolved from the current working directory.
+     */
+    readonly outputDirectory?: string;
+    /** Maximum duration for producing each bundle. Defaults to `"30s"`. */
+    readonly bundlingTimeout?: PositiveDuration;
+    /** Maximum duration for executing each emitted bundle. Defaults to `"5s"`. */
+    readonly timeout?: PositiveDuration;
+}
+/**
+ * Bundles, executes, measures, and verifies named cases with every supported
+ * bundler.
+ *
+ * The fixture must default-export either a value, a promise, or a function that
+ * returns one. The resolved value must be structured-cloneable so it can cross
+ * the worker boundary. All asynchronous work started by the fixture must be
+ * awaited by that returned promise; detached work scheduled after it settles is
+ * outside the execution contract. Verification runs outside the measured
+ * bundle. Each emitted bundle runs in an isolated worker so evaluation errors,
+ * rejected promises, uncaught errors and unhandled rejections observed before
+ * completion, and timeouts fail the test without affecting the test process.
+ * Cases and bundlers form one flattened job list that runs concurrently,
+ * bounded by the CPU parallelism available to the process. If multiple jobs
+ * fail, all failures are reported together with their case and bundler names.
+ * The returned record contains only raw and Brotli byte counts grouped by case
+ * and versioned bundler name, so it can be compared directly with an inline
+ * snapshot.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import { mkdtemp, rm, writeFile } from "node:fs/promises";
+ * import { tmpdir } from "node:os";
+ * import { join } from "node:path";
+ * import { testBundle } from "@evolu/nodejs/TestBundle";
+ *
+ * const directory = await mkdtemp(join(tmpdir(), "evolu-test-bundle-"));
+ * try {
+ *   const entryPath = join(directory, "entry.ts");
+ *   await writeFile(entryPath, "export default { answer: 42 };\n");
+ *   const result = await testBundle({
+ *     cases: {
+ *       example: {
+ *         entryPath,
+ *         verify: (value) => {
+ *           expect(value).toEqual({ answer: 42 });
+ *         },
+ *       },
+ *     },
+ *   });
+ *   for (const size of Object.values(result.example)) {
+ *     expect(size.brotliSizeInBytes).toBeGreaterThan(0);
+ *   }
+ * } finally {
+ *   await rm(directory, { recursive: true });
+ * }
+ * ```
+ */
+export declare const testBundle: ({ cases, aliases, outputDirectory, bundlingTimeout, timeout: executionTimeout, }: TestBundleOptions) => Promise<TestBundleResult>;
+//# sourceMappingURL=TestBundle.d.ts.map

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

@@ -0,0 +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"}