@evolu/nodejs 3.1.0 → 4.0.0

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.1.0",
+  "version": "4.0.0",
   "description": "Evolu for Node.js",
   "author": "Daniel Steigerwald <daniel@steigerwald.cz>",
   "license": "MIT",
@@ -29,6 +29,11 @@
       "types": "./dist/src/TestJSDoc.d.ts",
       "import": "./dist/src/TestJSDoc.js",
       "default": "./dist/src/TestJSDoc.js"
+    },
+    "./TestOverviewReporter": {
+      "types": "./dist/src/TestOverviewReporter.d.ts",
+      "import": "./dist/src/TestOverviewReporter.js",
+      "default": "./dist/src/TestOverviewReporter.js"
     }
   },
   "typesVersions": {
@@ -38,11 +43,15 @@
       ],
       "TestJSDoc": [
         "./dist/src/TestJSDoc.d.ts"
+      ],
+      "TestOverviewReporter": [
+        "./dist/src/TestOverviewReporter.d.ts"
       ]
     }
   },
   "files": [
     "dist/src/**",
+    "!dist/**/*.test.*",
     "src/**",
     "README.md"
   ],
@@ -51,9 +60,9 @@
     "ws": "^8.21.3"
   },
   "devDependencies": {
-    "@evolu/common": "8.6.0",
-    "@evolu/oxlint-config": "0.1.0",
-    "@evolu/typescript-config": "0.1.0",
+    "@evolu/common": "8.10.0",
+    "@evolu/oxlint-config": "0.2.0",
+    "@evolu/typescript-config": "0.1.1",
     "@types/better-sqlite3": "^9.6.0",
     "@types/node": "^24.10.9",
     "@types/ws": "^8.18.1",
@@ -64,9 +73,9 @@
     "webpack": "^5.109.2"
   },
   "peerDependencies": {
-    "@evolu/common": "^8.0.0",
-    "@evolu/oxlint-config": "^0.1.0",
-    "@evolu/typescript-config": "^0.1.0",
+    "@evolu/common": "^8.10.0",
+    "@evolu/oxlint-config": "^0.2.0",
+    "@evolu/typescript-config": "^0.1.1",
     "oxlint": "^1.79.0",
     "oxlint-tsgolint": "7.0.2001",
     "typescript": ">=7.0.0",
@@ -97,7 +106,7 @@
     }
   },
   "engines": {
-    "node": ">=24.0.0"
+    "node": ">=24.20.0"
   },
   "publishConfig": {
     "access": "public"

package/src/Cli.test.ts

@@ -0,0 +1,90 @@
+import {
+  assertEqual,
+  assertErr,
+  assertOk,
+  assertTrue,
+  testAbortError,
+  testAbortReason,
+  testCreateRun,
+} from "@evolu/common";
+import { test } from "node:test";
+import { spawn } from "./Cli.ts";
+
+test("spawn succeeds with inherited stdio and a configured cwd", async () => {
+  await using run = testCreateRun();
+  const scriptsDirectory = new URL("../../../scripts/", import.meta.url);
+  const result = await run(
+    spawn(
+      process.execPath,
+      ["-e", 'process.exit(process.cwd().endsWith("scripts") ? 0 : 1)'],
+      { cwd: scriptsDirectory },
+    ),
+  );
+
+  assertOk(result);
+});
+
+test("spawn returns a start error", async () => {
+  await using run = testCreateRun();
+  const result = await run(spawn("evolu-command-that-does-not-exist", []));
+
+  assertErr(result);
+  const { message } = result.error;
+  assertTrue(
+    message.startsWith("Failed to start evolu-command-that-does-not-exist:"),
+  );
+  assertEqual(result, {
+    ok: false,
+    error: {
+      type: "SpawnError",
+      command: "evolu-command-that-does-not-exist",
+      exitCode: null,
+      signal: null,
+      message,
+    },
+  });
+});
+
+test("spawn returns a non-zero exit error", async () => {
+  await using run = testCreateRun();
+  const result = await run(spawn(process.execPath, ["-e", "process.exit(7)"]));
+  const command = `${process.execPath} -e process.exit(7)`;
+
+  assertErr(result, {
+    type: "SpawnError",
+    command,
+    exitCode: 7,
+    signal: null,
+    message: `${command} exited with code 7.`,
+  });
+});
+
+test("spawn returns a signal exit error", async () => {
+  await using run = testCreateRun();
+  const result = await run(
+    spawn(process.execPath, ["-e", 'process.kill(process.pid, "SIGTERM")']),
+  );
+  const command = `${process.execPath} -e process.kill(process.pid, "SIGTERM")`;
+
+  assertErr(result, {
+    type: "SpawnError",
+    command,
+    exitCode: null,
+    signal: "SIGTERM",
+    message: `${command} exited from SIGTERM.`,
+  });
+});
+
+test("spawn aborts its child process with the Run", async () => {
+  await using run = testCreateRun();
+  const fiber = run.abortable(
+    spawn(process.execPath, ["-e", "setInterval(() => {}, 1000)"]),
+  );
+
+  await new Promise<void>((resolve) => {
+    setImmediate(resolve);
+  });
+  fiber.abort(testAbortReason);
+
+  assertErr(await fiber, testAbortError);
+});