@evolu/nodejs 3.2.0 → 4.0.0

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/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/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"}

package/dist/src/index.js

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

package/dist/src/local-first/Relay.d.ts

@@ -1,8 +1,11 @@
-import { type CreateSqliteDriverDep, type RandomDep, type Task, type TimingSafeEqualDep } from "@evolu/common";
+import { type CreateSqliteDriverDep, Port, type RandomDep, type Task, type TimingSafeEqualDep } from "@evolu/common";
 import { type Relay, type RelayConfig } from "@evolu/common/local-first";
 export interface NodeJsRelayConfig extends RelayConfig {
-    /** The port number for the HTTP server. */
-    readonly port?: number;
+    /**
+     * The HTTP server's {@link Port}. Zero requests an automatically assigned
+     * port.
+     */
+    readonly port?: Port;
 }
 export type RelayDeps = CreateSqliteDriverDep & RandomDep & TimingSafeEqualDep;
 /** Dependencies for {@link createRelay} using better-sqlite3. */
@@ -16,32 +19,17 @@ export declare const createRelayDeps: () => RelayDeps;
  * ### Example
  *
  * ```ts
- * // Ensure the database is created in a predictable location for Docker.
- * mkdirSync("data", { recursive: true });
- * process.chdir("data");
- *
- * const console = createConsole({
- *   // level: "debug",
- *   formatter: createConsoleFormatter()({
- *     timestampFormat: "relative",
- *   }),
+ * import { assertType, Port, type Task } from "@evolu/common";
+ * import type { Relay } from "@evolu/common/local-first";
+ * import { createRelay, type RelayDeps } from "@evolu/nodejs";
+ *
+ * const main = createRelay({
+ *   port: Port.orThrow(4000),
+ *   isOwnerWithinQuota: (_ownerId, requiredBytes) =>
+ *     requiredBytes <= 1024 * 1024,
  * });
  *
- * const deps = { ...createRelayDeps(), console };
- *
- * await runMain(deps)(
- *   createRelay({
- *     port: 4000,
- *
- *     // Note: Relay requires URL in format ws://host:port?ownerId=<ownerId>
- *     // isOwnerAllowed: (_ownerId, { signal: _signal }) => true,
- *
- *     isOwnerWithinQuota: (_ownerId, requiredBytes) => {
- *       const maxBytes = 1024 * 1024; // 1MB
- *       return requiredBytes <= maxBytes;
- *     },
- *   }),
- * );
+ * assertType<typeof main, Task<Relay, never, RelayDeps>>();
  * ```
  */
 export declare const createRelay: ({ port, name, isOwnerAllowed, isOwnerWithinQuota, }: NodeJsRelayConfig) => Task<Relay, never, RelayDeps>;

package/dist/src/local-first/Relay.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Relay.d.ts","sourceRoot":"","sources":["../../../src/local-first/Relay.ts"],"names":[],"mappings":"AAAA,OAAO,EAKL,KAAK,qBAAqB,EAK1B,KAAK,SAAS,EACd,KAAK,IAAI,EACT,KAAK,kBAAkB,EAGxB,MAAM,eAAe,CAAC;AACvB,OAAO,EAQL,KAAK,KAAK,EACV,KAAK,WAAW,EACjB,MAAM,2BAA2B,CAAC;AAQnC,MAAM,WAAW,iBAAkB,SAAQ,WAAW;IACpD,2CAA2C;IAC3C,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,MAAM,SAAS,GAAG,qBAAqB,GAAG,SAAS,GAAG,kBAAkB,CAAC;AAE/E,iEAAiE;AACjE,eAAO,MAAM,eAAe,QAAO,SAIjC,CAAC;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,eAAO,MAAM,WAAW,wDAMnB,iBAAiB,KAAG,IAAI,CAAC,KAAK,EAAE,KAAK,EAAE,SAAS,CAkNlD,CAAC"}
+{"version":3,"file":"Relay.d.ts","sourceRoot":"","sources":["../../../src/local-first/Relay.ts"],"names":[],"mappings":"AAAA,OAAO,EAKL,KAAK,qBAAqB,EAK1B,IAAI,EACJ,KAAK,SAAS,EACd,KAAK,IAAI,EACT,KAAK,kBAAkB,EAGxB,MAAM,eAAe,CAAC;AACvB,OAAO,EAQL,KAAK,KAAK,EACV,KAAK,WAAW,EACjB,MAAM,2BAA2B,CAAC;AAQnC,MAAM,WAAW,iBAAkB,SAAQ,WAAW;IACpD;;;OAGG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC;CACtB;AAED,MAAM,MAAM,SAAS,GAAG,qBAAqB,GAAG,SAAS,GAAG,kBAAkB,CAAC;AAE/E,iEAAiE;AACjE,eAAO,MAAM,eAAe,QAAO,SAIjC,CAAC;AAEH;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,WAAW,wDAMnB,iBAAiB,KAAG,IAAI,CAAC,KAAK,EAAE,KAAK,EAAE,SAAS,CAkNlD,CAAC"}

package/dist/src/local-first/Relay.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 { assert, createRandom, createRelation, createSqlite, daemon, Name, ok, OwnerId, tryAsync, Uint8Array, } from "@evolu/common";
+import { assert, createRandom, createRelation, createSqlite, daemon, Name, ok, OwnerId, Port, tryAsync, Uint8Array, } from "@evolu/common";
 import { applyProtocolMessageAsRelay, createBaseSqliteStorageTables, createRelaySqliteStorage, createRelayStorageTables, defaultProtocolMessageMaxSize, parseOwnerIdFromOwnerWebSocketTransportUrl, } from "@evolu/common/local-first";
 import { once } from "events";
 import { existsSync } from "fs";
@@ -73,35 +73,20 @@ export const createRelayDeps = () => ({
  * ### Example
  *
  * ```ts
- * // Ensure the database is created in a predictable location for Docker.
- * mkdirSync("data", { recursive: true });
- * process.chdir("data");
+ * import { assertType, Port, type Task } from "@evolu/common";
+ * import type { Relay } from "@evolu/common/local-first";
+ * import { createRelay, type RelayDeps } from "@evolu/nodejs";
  *
- * const console = createConsole({
- *   // level: "debug",
- *   formatter: createConsoleFormatter()({
- *     timestampFormat: "relative",
- *   }),
+ * const main = createRelay({
+ *   port: Port.orThrow(4000),
+ *   isOwnerWithinQuota: (_ownerId, requiredBytes) =>
+ *     requiredBytes <= 1024 * 1024,
  * });
  *
- * const deps = { ...createRelayDeps(), console };
- *
- * await runMain(deps)(
- *   createRelay({
- *     port: 4000,
- *
- *     // Note: Relay requires URL in format ws://host:port?ownerId=<ownerId>
- *     // isOwnerAllowed: (_ownerId, { signal: _signal }) => true,
- *
- *     isOwnerWithinQuota: (_ownerId, requiredBytes) => {
- *       const maxBytes = 1024 * 1024; // 1MB
- *       return requiredBytes <= maxBytes;
- *     },
- *   }),
- * );
+ * assertType<typeof main, Task<Relay, never, RelayDeps>>();
  * ```
  */
-export const createRelay = ({ port = 443, name = Name.orThrow("evolu-relay"), isOwnerAllowed, isOwnerWithinQuota, }) => async (run) => {
+export const createRelay = ({ port = Port.orThrow(443), name = Name.orThrow("evolu-relay"), isOwnerAllowed, isOwnerWithinQuota, }) => async (run) => {
     const env_1 = { stack: [], error: void 0, hasError: false };
     try {
         const disposer = __addDisposableResource(env_1, new AsyncDisposableStack(), true);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evolu/nodejs",
-  "version": "3.2.0",
+  "version": "4.0.0",
   "description": "Evolu for Node.js",
   "author": "Daniel Steigerwald <daniel@steigerwald.cz>",
   "license": "MIT",
@@ -60,7 +60,7 @@
     "ws": "^8.21.3"
   },
   "devDependencies": {
-    "@evolu/common": "8.8.0",
+    "@evolu/common": "8.10.0",
     "@evolu/oxlint-config": "0.2.0",
     "@evolu/typescript-config": "0.1.1",
     "@types/better-sqlite3": "^9.6.0",
@@ -73,9 +73,9 @@
     "webpack": "^5.109.2"
   },
   "peerDependencies": {
-    "@evolu/common": "^8.0.0",
+    "@evolu/common": "^8.10.0",
     "@evolu/oxlint-config": "^0.2.0",
-    "@evolu/typescript-config": "^0.1.0",
+    "@evolu/typescript-config": "^0.1.1",
     "oxlint": "^1.79.0",
     "oxlint-tsgolint": "7.0.2001",
     "typescript": ">=7.0.0",