@evolu/nodejs 3.1.0 → 4.0.0

package/src/Fs.ts

@@ -0,0 +1,300 @@
+/**
+ * File system operations using Node.js.
+ *
+ * @module
+ */
+
+import {
+  assert,
+  ByteLength,
+  disposable,
+  err,
+  ok,
+  tryAsync,
+  type Fs,
+  type FsEncoding,
+  type FsEntryType,
+  type FsError,
+  type FsErrorReason,
+  type FsMetadata,
+  type FsPath,
+  type Task,
+} from "@evolu/common";
+import { constants, type Stats } 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 = (): Fs => {
+  function readFileTask(path: FsPath): Task<Uint8Array, FsError>;
+  function readFileTask(
+    path: FsPath,
+    encoding: FsEncoding | { readonly encoding: FsEncoding },
+  ): Task<string, FsError>;
+  function readFileTask(
+    path: FsPath,
+    encoding?: FsEncoding | { readonly encoding: FsEncoding },
+  ): Task<Uint8Array | string, FsError> {
+    return async (run) => {
+      const { signal } = run;
+      const result = await tryAsync((): Promise<Uint8Array | string> =>
+        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: FsEncoding | { readonly encoding: FsEncoding },
+): { readonly encoding: FsEncoding } =>
+  typeof encoding === "string" ? { encoding } : encoding;
+
+const fsErrorReasonByCode: Readonly<Record<string, FsErrorReason>> = {
+  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: string,
+  path: FsPath,
+  error: unknown,
+  destination?: FsPath,
+): FsError => {
+  assert(error instanceof Error, "Node fs rejects with an Error.");
+  const { code, syscall } = error as NodeJS.ErrnoException;
+
+  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: Readonly<Record<number, FsEntryType>> = {
+  [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: Stats): FsMetadata => ({
+  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/src/Platform.test.ts

@@ -0,0 +1,32 @@
+import {
+  assertEqual,
+  assertSame,
+  assertType,
+  PositiveInt,
+} from "@evolu/common";
+import { mock, test } from "node:test";
+import type {
+  AvailableParallelism,
+  AvailableParallelismDep,
+} from "./Platform.ts";
+
+const nodeAvailableParallelism = mock.fn<() => number>();
+
+mock.module("node:os", {
+  // @ts-expect-error -- Node.js 24.20 replaces the deprecated namedExports option with exports, which @types/node 24.13 does not declare yet.
+  exports: { availableParallelism: nodeAvailableParallelism },
+});
+
+const { availableParallelism } = await import("./Platform.ts");
+
+test("availableParallelism returns the validated Node.js value", () => {
+  nodeAvailableParallelism.mock.mockImplementation(() => 128);
+
+  const parallelism = availableParallelism();
+  const deps = { availableParallelism } satisfies AvailableParallelismDep;
+
+  assertType<typeof availableParallelism, AvailableParallelism>();
+  assertType<typeof parallelism, PositiveInt>();
+  assertSame(deps.availableParallelism, availableParallelism);
+  assertEqual(parallelism, 128);
+});

package/src/Task.ts

@@ -7,6 +7,7 @@
 import {
   createConsole,
   createRun,
+  getOrThrow,
   isDisposable,
   ok,
   waitForAbort,
@@ -18,6 +19,7 @@ import {
   type Task,
   type Typed,
 } from "@evolu/common";
+import type { createRelay } from "./local-first/Relay.ts";
 
 /**
  * An abort requested by a Node.js termination signal.
@@ -40,8 +42,8 @@ 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"
    */
@@ -49,75 +51,90 @@ export interface RunMainOptions {
 }
 
 /**
- * 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 function runMain<T extends void | Resource>(
-  main: Task<T>,
+export function runMain<T extends void | Resource, E = never>(
+  main: Task<T, E>,
   options?: RunMainOptions,
 ): Promise<void>;
 /** With custom dependencies. */
 export function runMain<D extends object>(
   deps: RunCustomDeps<D>,
   options?: RunMainOptions,
-): <T extends void | Resource>(main: Task<T, never, D>) => Promise<void>;
-export function runMain<T extends void | Resource, D extends object>(
-  mainOrDeps: Task<T> | RunCustomDeps<D>,
+): <T extends void | Resource, E = never>(main: Task<T, E, D>) => Promise<void>;
+export function runMain<T extends void | Resource, E, D extends object>(
+  mainOrDeps: Task<T, E> | RunCustomDeps<D>,
   { mode = "service" }: RunMainOptions = {},
 ):
   | Promise<void>
-  | (<R extends void | Resource>(main: Task<R, never, D>) => Promise<void>) {
+  | (<R extends void | Resource, E = never>(
+      main: Task<R, E, D>,
+    ) => Promise<void>) {
   return typeof mainOrDeps === "function"
     ? runMainInternal(mainOrDeps, {}, mode)
     : (main) => runMainInternal(main, mainOrDeps, mode);
@@ -129,8 +146,8 @@ const commandExitCodeBySignal: Readonly<Record<NodeSignal, number>> = {
   SIGBREAK: 149,
 };
 
-const runMainInternal = async <T extends void | Resource, D extends object>(
-  main: Task<T, never, D>,
+const runMainInternal = async <T extends void | Resource, E, D extends object>(
+  main: Task<T, E, D>,
   deps: RunCustomDeps<D> & Partial<ConsoleDep & ReportDefectDep>,
   mode: RunMainMode,
 ): Promise<void> => {
@@ -175,7 +192,7 @@ const runMainInternal = async <T extends void | Resource, D extends object>(
 
   try {
     await run(async (run) => {
-      const resource = await run.ok(main);
+      const resource = getOrThrow(await run(main));
       if (!isDisposable(resource)) return ok();
 
       await using _resource = resource;

package/src/TestBundle.ts

@@ -14,18 +14,20 @@
 import {
   allSettled,
   assert,
+  assertLength,
+  assertSame,
   assertType,
   instanceOf,
   createRun,
   durationToMillis,
   escapeRegExp,
-  filterArray,
   isErr,
   mapArray,
   type NonEmptyReadonlyArray,
   type PositiveDuration,
   type ReadonlyRecord,
   type Result,
+  partitionArray,
   safelyStringifyUnknownValue,
   String as StringType,
   type Task,
@@ -301,7 +303,7 @@ export const testBundle = async ({
     ),
   );
 
-  const failures = filterArray(results, isErr);
+  const [failures, successes] = partitionArray(results, isErr);
   if (failures.length > 0) {
     const errors = mapArray(
       failures,
@@ -331,8 +333,7 @@ export const testBundle = async ({
   >();
   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}".`);
@@ -438,16 +439,11 @@ const testViteBundler: TestBundler = {
     >;
     assert(Array.isArray(output), "Vite did not return build outputs.");
     const outputs: ReadonlyArray<ViteOutput> = 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 {
@@ -582,7 +578,7 @@ interface TestBundleWorkerError {
   readonly stack: string;
 }
 
-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`

package/src/TestJSDoc.ts

@@ -31,7 +31,10 @@ import { stripVTControlCharacters } from "node:util";
 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;
@@ -219,6 +222,9 @@ export const testJSDocExamples = async ({
           noEmit: true,
           noUnusedLocals: false,
           noUnusedParameters: false,
+          paths: Object.fromEntries(
+            Object.entries(aliases).map(([name, target]) => [name, [target]]),
+          ),
           target: "es2022",
           types: ["node"],
         },