@evolu/nodejs 2.4.0 → 3.0.0-next.1

package/package.json

@@ -1,50 +1,54 @@
 {
   "name": "@evolu/nodejs",
-  "version": "2.4.0",
+  "version": "3.0.0-next.1",
   "description": "Evolu for Node.js",
   "author": "Daniel Steigerwald <daniel@steigerwald.cz>",
   "license": "MIT",
-  "repository": "evoluhq/evolu",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/evoluhq/evolu.git"
+  },
   "bugs": {
     "url": "https://github.com/evoluhq/evolu/issues"
   },
   "homepage": "https://evolu.dev",
   "type": "module",
-  "types": "./dist/index.d.ts",
+  "types": "./dist/src/index.d.ts",
   "exports": {
-    ".": "./dist/index.js"
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "import": "./dist/src/index.js",
+      "default": "./dist/src/index.js"
+    }
   },
   "files": [
-    "dist/**",
+    "dist/src/**",
     "src/**",
     "README.md"
   ],
   "dependencies": {
-    "better-sqlite3": "^12.1.1",
-    "ws": "^8.18.2"
+    "better-sqlite3": "^12.6.2",
+    "ws": "^8.19.0"
   },
   "devDependencies": {
     "@types/better-sqlite3": "^7.6.13",
-    "@types/node": "^22.17.1",
+    "@types/node": "^24.10.9",
     "@types/ws": "^8.18.1",
-    "typescript": "^5.9.2",
-    "vitest": "^4.0.4",
-    "@evolu/common": "7.4.0",
-    "@evolu/tsconfig": "0.0.2"
+    "typescript": "^6",
+    "@evolu/common": "8.0.0-next.1",
+    "@evolu/typescript-config": "0.0.2"
   },
   "peerDependencies": {
-    "@evolu/common": "^7.4.0"
+    "@evolu/common": "^8.0.0-next.0"
   },
   "engines": {
-    "node": ">=22.0.0"
+    "node": ">=24.0.0"
   },
   "publishConfig": {
     "access": "public"
   },
   "scripts": {
-    "dev": "tsc --watch",
-    "build": "rimraf dist && tsc",
-    "clean": "rimraf .turbo node_modules dist",
+    "build": "tsc --build tsconfig.build.json",
     "format": "prettier --write \"src/*.{ts,tsx,md}\""
   }
 }

package/src/Crypto.ts

@@ -1,4 +1,4 @@
-import { timingSafeEqual } from "node:crypto";
 import type { TimingSafeEqual } from "@evolu/common";
+import { timingSafeEqual } from "node:crypto";
 
 export const createTimingSafeEqual = (): TimingSafeEqual => timingSafeEqual;

package/src/Sqlite.ts

@@ -0,0 +1,60 @@
+import {
+  createPreparedStatementsCache,
+  lazyVoid,
+  ok,
+  type CreateSqliteDriver,
+  type SqliteDriver,
+  type SqliteRow,
+} from "@evolu/common";
+import BetterSQLite, { type Statement } from "better-sqlite3";
+
+export const createBetterSqliteDriver: CreateSqliteDriver =
+  (name, options) => () => {
+    const filename = options?.mode === "memory" ? ":memory:" : `${name}.db`;
+    const stack = new globalThis.DisposableStack();
+    const db = stack.adopt(new BetterSQLite(filename), (db) => {
+      db.close();
+    });
+
+    const cache = stack.use(
+      createPreparedStatementsCache<Statement>(
+        (sql) => db.prepare(sql),
+        // Not needed.
+        // https://github.com/WiseLibs/better-sqlite3/blob/master/docs/api.md#class-statement
+        lazyVoid,
+      ),
+    );
+
+    const driver: SqliteDriver = {
+      exec: (query) => {
+        // Always prepare is recommended for better-sqlite3
+        const prepared = cache.get(query, true);
+
+        if (prepared.reader) {
+          const rows = prepared.all(query.parameters) as Array<SqliteRow>;
+          return { rows, changes: 0 };
+        }
+
+        const changes = prepared.run(query.parameters).changes;
+        return { rows: [], changes };
+      },
+
+      export: () => {
+        const file = db.serialize();
+        const { buffer } = file;
+
+        if (buffer instanceof ArrayBuffer) {
+          return new Uint8Array(buffer, file.byteOffset, file.byteLength);
+        }
+
+        // Ensure export uses transferable ArrayBuffer backing.
+        return new Uint8Array(file);
+      },
+
+      [Symbol.dispose]: () => {
+        stack.dispose();
+      },
+    };
+
+    return ok(driver);
+  };

package/src/Task.ts

@@ -0,0 +1,93 @@
+/**
+ * Node.js-specific Task utilities.
+ *
+ * @module
+ */
+
+import {
+  createRun as createCommonRun,
+  createUnknownError,
+  type CreateRun,
+  type Run,
+  type RunDeps,
+} from "@evolu/common";
+
+/**
+ * A promise that resolves when a termination signal is received.
+ *
+ * Resolves on `SIGINT` (Ctrl-C), `SIGTERM` (OS/k8s/Docker termination),
+ * `SIGHUP` (console close/terminal disconnect), or `SIGBREAK` (Windows
+ * Ctrl-Break).
+ *
+ * @group Node.js Run
+ */
+export type Shutdown = Promise<void>;
+
+export interface ShutdownDep {
+  readonly shutdown: Shutdown;
+}
+
+/**
+ * Creates {@link Run} for Node.js with global error handling and graceful
+ * shutdown.
+ *
+ * Registers `uncaughtException` and `unhandledRejection` handlers that log
+ * errors and initiate graceful shutdown. Adds a `shutdown` promise to deps that
+ * resolves on termination signals (`SIGINT`, `SIGTERM`, `SIGHUP`). Handlers are
+ * removed when the Run is disposed.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const deps = { ...createRelayDeps(), console };
+ *
+ * await using run = createRun(deps);
+ * await using stack = new AsyncDisposableStack();
+ *
+ * stack.use(await run.orThrow(startRelay({ port: 4000 })));
+ *
+ * await run.deps.shutdown;
+ * ```
+ *
+ * @group Node.js Run
+ */
+export const createRun: CreateRun<RunDeps & ShutdownDep> = <D>(
+  deps?: D,
+): Run<RunDeps & ShutdownDep & D> => {
+  const { promise: shutdown, resolve: resolveShutdown } =
+    Promise.withResolvers<void>();
+
+  const run = createCommonRun({ ...deps, shutdown } as D & ShutdownDep);
+
+  const console = run.deps.console.child("global");
+
+  const handleError = (source: string) => (error: unknown) => {
+    console.error(source, createUnknownError(error));
+    process.exitCode = 1;
+
+    // Resolve shutdown so `await run.deps.shutdown` unblocks
+    // and allows the stack to be disposed.
+    resolveShutdown();
+  };
+
+  const handleUncaughtException = handleError("uncaughtException");
+  const handleUnhandledRejection = handleError("unhandledRejection");
+
+  process.on("uncaughtException", handleUncaughtException);
+  process.on("unhandledRejection", handleUnhandledRejection);
+  process.on("SIGINT", resolveShutdown); // Ctrl-C (all platforms)
+  process.on("SIGTERM", resolveShutdown); // OS/k8s/Docker termination (Unix)
+  process.on("SIGHUP", resolveShutdown); // Console close (Windows), terminal disconnect (Unix)
+  process.on("SIGBREAK", resolveShutdown); // Ctrl-Break (Windows)
+
+  run.onAbort(() => {
+    process.off("uncaughtException", handleUncaughtException);
+    process.off("unhandledRejection", handleUnhandledRejection);
+    process.off("SIGINT", resolveShutdown);
+    process.off("SIGTERM", resolveShutdown);
+    process.off("SIGHUP", resolveShutdown);
+    process.off("SIGBREAK", resolveShutdown);
+  });
+
+  return run;
+};

package/src/WebSocket.ts

@@ -0,0 +1,69 @@
+import { request, type ClientRequest, type IncomingMessage } from "http";
+
+/**
+ * A raw WebSocket upgrade request prepared for tests by
+ * {@link testSetupWebSocketUpgradeRequest}.
+ */
+export interface TestSetupWebSocketUpgradeRequest extends AsyncDisposable {
+  readonly req: ClientRequest;
+}
+
+/**
+ * Creates a raw WebSocket upgrade request test setup for tests that need manual
+ * request control.
+ */
+export const testSetupWebSocketUpgradeRequest = (
+  port: number,
+  path: string,
+): TestSetupWebSocketUpgradeRequest => {
+  const req = createWebSocketUpgradeRequest(port, path);
+  req.on("error", () => undefined);
+
+  return {
+    req,
+    [Symbol.asyncDispose]: () => {
+      req.destroy();
+      return Promise.resolve();
+    },
+  };
+};
+
+/**
+ * Sends a raw WebSocket upgrade request and resolves with the rejection
+ * response.
+ */
+export const testSendWebSocketUpgradeRequest = async (
+  port: number,
+  path: string,
+): Promise<IncomingMessage> => {
+  const req = createWebSocketUpgradeRequest(port, path);
+
+  return new Promise((resolve, reject) => {
+    req.once("response", (response) => {
+      response.resume();
+      resolve(response);
+    });
+    req.once("upgrade", (_response, socket) => {
+      socket.destroy();
+      reject(new Error("Expected HTTP upgrade rejection"));
+    });
+    req.once("error", reject);
+    req.end();
+  });
+};
+
+const createWebSocketUpgradeRequest = (
+  port: number,
+  path: string,
+): ClientRequest =>
+  request({
+    host: "127.0.0.1",
+    port,
+    path,
+    headers: {
+      Connection: "Upgrade",
+      Upgrade: "websocket",
+      "Sec-WebSocket-Version": "13",
+      "Sec-WebSocket-Key": "dGhlIHNhbXBsZSBub25jZQ==",
+    },
+  });

package/src/Worker.ts

@@ -0,0 +1,11 @@
+// TODO: Implement Node.js Worker API
+//
+// This module should provide Node.js implementations of the common Worker API:
+// - createWorker
+// - createWorkerSelf (with onError hooking process.on('uncaughtException') and
+//   process.on('unhandledRejection'))
+// - createMessageChannel
+// - createMessagePort
+//
+// Node.js uses worker_threads module for Worker/MessageChannel/MessagePort.
+// Error handling uses process events instead of globalThis.onerror.

package/src/index.ts

@@ -1,2 +1,5 @@
-export * from "./BetterSqliteDriver.js";
+export * from "./Sqlite.js";
+export * from "./Crypto.js";
 export * from "./local-first/Relay.js";
+export * from "./Task.js";
+export * from "./WebSocket.js";