@evolu/nodejs 3.0.1 → 3.2.0

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/Worker.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Worker.d.ts","sourceRoot":"","sources":["../../src/Worker.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAoB,sBAAsB,EAAE,MAAM,eAAe,CAAC;AAG9E,0EAA0E;AAC1E,eAAO,MAAM,sBAAsB,EAAE,sBAsCpC,CAAC"}
+{"version":3,"file":"Worker.d.ts","sourceRoot":"","sources":["../../src/Worker.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAoB,sBAAsB,EAAE,MAAM,eAAe,CAAC;AAG9E,0EAA0E;AAC1E,eAAO,MAAM,sBAAsB,EAAE,sBAwCpC,CAAC"}

package/dist/src/Worker.js

@@ -60,6 +60,7 @@ export const createBroadcastChannel = (name) => {
         let disposed = false;
         disposer.defer(() => {
             disposed = true;
+            // oxlint-disable-next-line unicorn/prefer-add-event-listener -- This adapter owns and clears one handler.
             nativeBroadcastChannel.onmessage = null;
             nativeBroadcastChannel.close();
         });
@@ -75,6 +76,7 @@ export const createBroadcastChannel = (name) => {
                 if (disposed)
                     return;
                 onMessageHandler = fn;
+                // oxlint-disable-next-line unicorn/prefer-add-event-listener -- This adapter owns and clears one handler.
                 nativeBroadcastChannel.onmessage = fn
                     ? (event) => {
                         fn(event.data);

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,CAgNlD,CAAC"}
+{"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"}

package/dist/src/local-first/Relay.js

@@ -161,7 +161,7 @@ export const createRelay = ({ port = 443, name = Name.orThrow("evolu-relay"), is
             // ignores abort. The daemon runs in the root Run, so aborting the
             // current Run does not make its Fiber wait for the service Promise to
             // settle.
-            daemon(async (run) => await tryAsync(() => isOwnerAllowed(ownerId, { signal: run.signal }), (error) => ({ type: "OwnerAuthorizationError", error }))));
+            daemon(async (run) => tryAsync(() => isOwnerAllowed(ownerId, { signal: run.signal }), (error) => ({ type: "OwnerAuthorizationError", error }))));
             const abortAuthorization = () => {
                 authorizationFiber.abort({
                     type: "WebSocketUpgradeSocketClosed",
@@ -239,7 +239,7 @@ export const createRelay = ({ port = 443, name = Name.orThrow("evolu-relay"), is
         server.listen(port);
         await once(server, "listening");
         const address = server.address();
-        assert(address && typeof address !== "string", "Expected TCP address");
+        assert(address !== null && typeof address !== "string", "Expected TCP address");
         const disposables = disposer.move();
         console.info(`Started on port ${address.port}`);
         return ok({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evolu/nodejs",
-  "version": "3.0.1",
+  "version": "3.2.0",
   "description": "Evolu for Node.js",
   "author": "Daniel Steigerwald <daniel@steigerwald.cz>",
   "license": "MIT",
@@ -24,40 +24,80 @@
       "types": "./dist/src/TestBundle.d.ts",
       "import": "./dist/src/TestBundle.js",
       "default": "./dist/src/TestBundle.js"
+    },
+    "./TestJSDoc": {
+      "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": {
     "*": {
       "TestBundle": [
         "./dist/src/TestBundle.d.ts"
+      ],
+      "TestJSDoc": [
+        "./dist/src/TestJSDoc.d.ts"
+      ],
+      "TestOverviewReporter": [
+        "./dist/src/TestOverviewReporter.d.ts"
       ]
     }
   },
   "files": [
     "dist/src/**",
+    "!dist/**/*.test.*",
     "src/**",
     "README.md"
   ],
   "dependencies": {
     "better-sqlite3": "^12.11.1",
-    "ws": "^8.19.0"
+    "ws": "^8.21.3"
   },
   "devDependencies": {
+    "@evolu/common": "8.8.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",
     "@typescript/native": "npm:typescript@^7.0.2",
-    "vite": "^8.2.0",
-    "webpack": "^5.109.2",
-    "@evolu/common": "8.1.0",
-    "@evolu/typescript-config": "0.0.2"
+    "oxlint": "^1.79.0",
+    "oxlint-tsgolint": "7.0.2001",
+    "vite": "^8.2.2",
+    "webpack": "^5.109.2"
   },
   "peerDependencies": {
     "@evolu/common": "^8.0.0",
+    "@evolu/oxlint-config": "^0.2.0",
+    "@evolu/typescript-config": "^0.1.0",
+    "oxlint": "^1.79.0",
+    "oxlint-tsgolint": "7.0.2001",
+    "typescript": ">=7.0.0",
     "vite": ">=8.0.0",
     "webpack": ">=5.108.4"
   },
   "peerDependenciesMeta": {
+    "@evolu/oxlint-config": {
+      "optional": true
+    },
+    "@evolu/typescript-config": {
+      "optional": true
+    },
+    "oxlint": {
+      "optional": true
+    },
+    "oxlint-tsgolint": {
+      "optional": true
+    },
+    "typescript": {
+      "optional": true
+    },
     "vite": {
       "optional": true
     },
@@ -66,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);
+});

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/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}".`);
@@ -408,11 +409,11 @@ const testViteBundler: TestBundler = {
     const output = await vite.build({
       root: dirname(entryPath),
       configFile: false,
-      envFile: false,
+      envDir: false,
       logLevel: "silent",
       resolve: {
         alias: Object.entries(aliases).map(([name, replacement]) => ({
-          find: new RegExp(`^${escapeRegExp(name)}$`),
+          find: new RegExp(`^${escapeRegExp(name)}$`, "u"),
           replacement,
         })),
       },
@@ -438,15 +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.");
+    assertLength(outputs, 1);
     const viteOutput = outputs[0];
-    assert(viteOutput, "Vite did not return a build output.");
-    assert(
-      viteOutput.output.length === 1,
-      "Vite did not emit one JavaScript chunk.",
-    );
+    assertLength(viteOutput.output, 1);
     const chunk = viteOutput.output[0];
-    assert(chunk, "Vite did not emit a JavaScript chunk.");
+    assertSame(chunk.type, "chunk");
     assertType(StringType, chunk.code);
 
     return {
@@ -581,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`