@evolu/nodejs 3.0.1 → 3.2.0

package/src/TestOverviewReporter.test.ts

@@ -0,0 +1,219 @@
+import { assertEqual, assertFalse, assertTrue } from "@evolu/common";
+import { relative, resolve } from "node:path";
+import { describe, it } from "node:test";
+import type { TestEvent } from "node:test/reporters";
+import { stripVTControlCharacters } from "node:util";
+
+import testOverviewReporter from "./TestOverviewReporter.ts";
+
+const createFileSummaryEvent = ({
+  durationMs,
+  file,
+  success,
+  tests,
+}: {
+  readonly durationMs: number;
+  readonly file: string;
+  readonly success: boolean;
+  readonly tests: number;
+}): TestEvent => ({
+  type: "test:summary",
+  data: {
+    counts: {
+      cancelled: 0,
+      passed: success ? tests : tests - 1,
+      skipped: 0,
+      suites: 0,
+      tests,
+      todo: 0,
+      topLevel: tests,
+    },
+    duration_ms: durationMs,
+    file,
+    success,
+  },
+});
+
+const collectReporterOutput = async (
+  events: ReadonlyArray<TestEvent>,
+): Promise<string> => {
+  let output = "";
+  for await (const chunk of testOverviewReporter(events)) {
+    output +=
+      typeof chunk === "string" ? chunk : new TextDecoder().decode(chunk);
+  }
+  return stripVTControlCharacters(output);
+};
+
+describe("testOverviewReporter", () => {
+  it("reports test files slowest-first", async () => {
+    const fastFile = resolve("packages/common/src/Fast.test.ts");
+    const slowFile = resolve("packages/common/src/Slow.test.ts");
+    const output = await collectReporterOutput([
+      createFileSummaryEvent({
+        durationMs: 2.4,
+        file: fastFile,
+        success: true,
+        tests: 1,
+      }),
+      createFileSummaryEvent({
+        durationMs: 312.6,
+        file: slowFile,
+        success: true,
+        tests: 2,
+      }),
+      {
+        type: "test:summary",
+        data: {
+          counts: {
+            cancelled: 0,
+            passed: 3,
+            skipped: 0,
+            suites: 0,
+            tests: 3,
+            todo: 0,
+            topLevel: 3,
+          },
+          duration_ms: 15,
+          file: undefined,
+          success: true,
+        },
+      },
+    ]);
+
+    assertEqual(
+      output,
+      `Test files:
+
+✔ ${relative(process.cwd(), slowFile)} (2 tests) 313ms
+✔ ${relative(process.cwd(), fastFile)} (1 test) 2ms
+
+`,
+    );
+  });
+
+  it("preserves Node.js failure diagnostics", async () => {
+    const cause = new Error("Expected Ada.");
+    const error = Object.assign(new Error("Test failed.", { cause }), {
+      cause,
+    });
+    const file = resolve("packages/common/src/Failing.test.ts");
+    const output = await collectReporterOutput([
+      {
+        type: "test:fail",
+        data: {
+          details: { duration_ms: 1, error, type: "test" },
+          file,
+          name: "fails",
+          nesting: 0,
+          testNumber: 1,
+        },
+      },
+      createFileSummaryEvent({
+        durationMs: 1,
+        file,
+        success: false,
+        tests: 1,
+      }),
+    ]);
+
+    assertTrue(output.includes("Failed tests:"));
+    assertTrue(output.includes("Test failed."));
+    assertTrue(output.includes(`✖ ${relative(process.cwd(), file)}`));
+  });
+
+  it("preserves failures without file summaries", async () => {
+    const cause = new Error("Module failed to load.");
+    const error = Object.assign(new Error("Test failed.", { cause }), {
+      cause,
+    });
+    const details: Extract<
+      TestEvent,
+      { readonly type: "test:fail" }
+    >["data"]["details"] = {
+      duration_ms: 1,
+      error,
+      type: "test",
+    };
+    const failure: TestEvent = {
+      type: "test:fail",
+      data: {
+        details,
+        file: resolve("packages/common/src/Failing.test.ts"),
+        name: "fails to load",
+        nesting: 0,
+        testNumber: 1,
+      },
+    };
+    const output = await collectReporterOutput([failure]);
+
+    assertTrue(output.includes("Failed tests:"));
+    assertTrue(output.includes("Module failed to load."));
+    assertFalse(output.includes("Test files:"));
+  });
+
+  it("uses Node.js summary and coverage formatting", async () => {
+    const output = await collectReporterOutput([
+      {
+        type: "test:diagnostic",
+        data: {
+          level: "info",
+          message: "skipped 1",
+          nesting: 0,
+        },
+      },
+      {
+        type: "test:diagnostic",
+        data: {
+          level: "error",
+          message: "Coverage threshold was not met.",
+          nesting: 0,
+        },
+      },
+      {
+        type: "test:coverage",
+        data: {
+          nesting: 0,
+          summary: {
+            files: [
+              {
+                branches: [],
+                coveredBranchCount: 1,
+                coveredFunctionCount: 1,
+                coveredLineCount: 1,
+                coveredBranchPercent: 100,
+                coveredFunctionPercent: 100,
+                coveredLinePercent: 100,
+                functions: [],
+                lines: [{ count: 1, line: 1 }],
+                path: resolve("packages/common/src/Foo.ts"),
+                totalBranchCount: 1,
+                totalFunctionCount: 1,
+                totalLineCount: 1,
+              },
+            ],
+            thresholds: { branch: 1, function: 1, line: 1 },
+            totals: {
+              coveredBranchCount: 1,
+              coveredFunctionCount: 1,
+              coveredLineCount: 1,
+              coveredBranchPercent: 100,
+              coveredFunctionPercent: 100,
+              coveredLinePercent: 100,
+              totalBranchCount: 1,
+              totalFunctionCount: 1,
+              totalLineCount: 1,
+            },
+            workingDirectory: process.cwd(),
+          },
+        },
+      },
+    ]);
+
+    assertTrue(output.includes("Coverage threshold was not met."));
+    assertTrue(output.includes("skipped 1"));
+    assertTrue(output.includes("start of coverage report"));
+    assertTrue(output.includes("Foo.ts"));
+    assertFalse(output.includes("Test files:"));
+  });
+});

package/src/TestOverviewReporter.ts

@@ -0,0 +1,86 @@
+/**
+ * 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, type TestEvent } 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: AsyncIterable<TestEvent> | Iterable<TestEvent>,
+): AsyncGenerator<string | Uint8Array, void> {
+  const fileSummaries: Array<
+    Extract<TestEvent, { readonly type: "test:summary" }>["data"] & {
+      readonly file: string;
+    }
+  > = [];
+  const dotOutput: Array<string> = [];
+  const specEvents: Array<TestEvent> = [];
+  let hasFailures = false;
+
+  const captureEvents = async function* (): AsyncGenerator<TestEvent, void> {
+    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/src/Time.test.ts

@@ -0,0 +1,67 @@
+import {
+  assertEqual,
+  assertThrowsInstanceOf,
+  assertType,
+  Millis,
+} from "@evolu/common";
+import { afterEach, describe, it, mock } from "node:test";
+import type { HrDuration, HrTime, NodejsTime } from "./Time.ts";
+import {
+  createNodejsTime,
+  hrDurationBetween,
+  hrDurationToMillis,
+  millisToHrDuration,
+} from "./Time.ts";
+
+describe("NodejsTime", () => {
+  afterEach(() => {
+    mock.restoreAll();
+  });
+
+  it("createNodejsTime exposes the native high-resolution clock", () => {
+    mock.method(process.hrtime, "bigint", () => 123n);
+
+    const time: NodejsTime = createNodejsTime();
+    const now: HrTime = time.hrtime();
+
+    assertEqual(now, 123n);
+  });
+});
+
+describe("hrDurationBetween", () => {
+  it("returns elapsed nanoseconds", () => {
+    const result = hrDurationBetween(100n as HrTime, 125n as HrTime);
+
+    assertType<typeof result, HrDuration>();
+    assertEqual(result, 25n);
+  });
+
+  it("rejects an end time before the start time", () => {
+    assertEqual(
+      assertThrowsInstanceOf(
+        () => hrDurationBetween(125n as HrTime, 100n as HrTime),
+        Error,
+      ).message,
+      "High-resolution end time must not precede start time",
+    );
+  });
+});
+
+describe("hrDurationToMillis", () => {
+  it("rounds to the nearest millisecond", () => {
+    const result = hrDurationToMillis(1_499_999n as HrDuration);
+
+    assertType<typeof result, Millis>();
+    assertEqual(result, 1);
+    assertEqual(hrDurationToMillis(1_500_000n as HrDuration), 2);
+  });
+});
+
+describe("millisToHrDuration", () => {
+  it("converts milliseconds to nanoseconds", () => {
+    const result = millisToHrDuration(Millis.orThrow(2));
+
+    assertType<typeof result, HrDuration>();
+    assertEqual(result, 2_000_000n);
+  });
+});

package/src/Worker.ts

@@ -14,6 +14,7 @@ export const createBroadcastChannel: CreateBroadcastChannel = <
 
   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();
   });
@@ -31,6 +32,7 @@ export const createBroadcastChannel: CreateBroadcastChannel = <
       set onMessage(fn) {
         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: MessageEvent<Output>) => {
               fn(event.data);

package/src/local-first/Relay.ts

@@ -169,12 +169,11 @@ export const createRelay =
         // 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 }) as const,
-            ),
+        daemon(async (run) =>
+          tryAsync(
+            () => isOwnerAllowed(ownerId, { signal: run.signal }),
+            (error) => ({ type: "OwnerAuthorizationError", error }) as const,
+          ),
         ),
       );
 
@@ -287,7 +286,10 @@ export const createRelay =
     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();