@evolu/nodejs 3.1.0 → 4.0.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/index.ts

@@ -5,6 +5,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/src/local-first/Relay.ts

@@ -8,6 +8,7 @@ import {
   Name,
   ok,
   OwnerId,
+  Port,
   type RandomDep,
   type Task,
   type TimingSafeEqualDep,
@@ -33,8 +34,11 @@ import { createTimingSafeEqual } from "../Crypto.ts";
 import { createBetterSqliteDriver } from "../Sqlite.ts";
 
 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;
@@ -55,37 +59,22 @@ export const createRelayDeps = (): RelayDeps => ({
  * ### 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,
+    port = Port.orThrow(443),
     name = Name.orThrow("evolu-relay"),
     isOwnerAllowed,
     isOwnerWithinQuota,