@evolu/nodejs 2.4.0 → 3.0.0-next.0

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/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,4 @@
-export * from "./BetterSqliteDriver.js";
+export * from "./Sqlite.js";
+export * from "./Crypto.js";
 export * from "./local-first/Relay.js";
+export * from "./Task.js";

package/src/local-first/Relay.ts

@@ -1,105 +1,120 @@
 import {
-  ConsoleDep,
-  createRelation,
   createRandom,
+  createRelation,
   createSqlite,
-  CreateSqliteDriverDep,
-  isAsync,
+  type CreateSqliteDriverDep,
+  isPromiseLike,
+  Name,
   ok,
   OwnerId,
-  RandomDep,
-  Result,
-  SimpleName,
-  SqliteError,
-  TimingSafeEqualDep,
+  type RandomDep,
+  type Task,
+  type TimingSafeEqualDep,
   Uint8Array,
 } from "@evolu/common";
 import {
   applyProtocolMessageAsRelay,
-  ApplyProtocolMessageAsRelayOptions,
+  type ApplyProtocolMessageAsRelayOptions,
   createBaseSqliteStorageTables,
-  createRelayLogger,
   createRelaySqliteStorage,
   createRelayStorageTables,
   defaultProtocolMessageMaxSize,
   parseOwnerIdFromOwnerWebSocketTransportUrl,
-  Relay,
-  RelayConfig,
+  type Relay,
+  type RelayConfig,
 } from "@evolu/common/local-first";
 import { existsSync } from "fs";
 import { createServer } from "http";
 import { WebSocket, WebSocketServer } from "ws";
-import { createBetterSqliteDriver } from "../BetterSqliteDriver.js";
 import { createTimingSafeEqual } from "../Crypto.js";
+import { createBetterSqliteDriver } from "../Sqlite.js";
 
 export interface NodeJsRelayConfig extends RelayConfig {
   /** The port number for the HTTP server. */
   readonly port?: number;
 }
 
-/**
- * Creates an Evolu relay server.
- *
- * This implementation uses Node.js and better-sqlite3. Additional relay
- * implementations will be provided for other platforms (Bun, Deno, Cloudflare
- * Workers, Vercel Edge, etc.).
- */
-export const createNodeJsRelay =
-  (deps: ConsoleDep) =>
-  (config: NodeJsRelayConfig): Promise<Result<Relay, SqliteError>> =>
-    createNodeJsRelayWithSqliteDriver({
-      ...deps,
-      createSqliteDriver: createBetterSqliteDriver,
-    })(config);
+export type RelayDeps = CreateSqliteDriverDep & RandomDep & TimingSafeEqualDep;
+
+/** Dependencies for {@link startRelay} using better-sqlite3. */
+export const createRelayDeps = (): RelayDeps => ({
+  createSqliteDriver: createBetterSqliteDriver,
+  random: createRandom(),
+  timingSafeEqual: createTimingSafeEqual(),
+});
 
 /**
- * Creates an Evolu relay server with a custom SQLite driver.
+ * Starts an Evolu relay server using Node.js.
+ *
+ * Use {@link createRelayDeps} to create dependencies for better-sqlite3, or
+ * provide a custom SQLite driver implementation.
+ *
+ * ### 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",
+ *   }),
+ * });
+ *
+ * const deps = { ...createRelayDeps(), console };
  *
- * Use this when you need to provide a different SQLite driver implementation
- * (e.g., using alternative SQLite libraries).
+ * await using run = createRun(deps);
+ * await using stack = new AsyncDisposableStack();
+ *
+ * stack.use(
+ *   await run.orThrow(
+ *     startRelay({
+ *       port: 4000,
+ *
+ *       // Note: Relay requires URL in format ws://host:port/<ownerId>
+ *       // isOwnerAllowed: (_ownerId) => true,
+ *
+ *       isOwnerWithinQuota: (_ownerId, requiredBytes) => {
+ *         const maxBytes = 1024 * 1024; // 1MB
+ *         return requiredBytes <= maxBytes;
+ *       },
+ *     }),
+ *   ),
+ * );
+ *
+ * await run.deps.shutdown;
+ * ```
  */
-export const createNodeJsRelayWithSqliteDriver =
-  (deps: ConsoleDep & CreateSqliteDriverDep) =>
-  (config: NodeJsRelayConfig): Promise<Result<Relay, SqliteError>> =>
-    createNodeJsRelayWithDeps({
-      ...deps,
-      random: createRandom(),
-      timingSafeEqual: createTimingSafeEqual(),
-    })(config);
-
-const createNodeJsRelayWithDeps =
-  (deps: ConsoleDep & CreateSqliteDriverDep & RandomDep & TimingSafeEqualDep) =>
-  async ({
+export const startRelay =
+  ({
     port = 443,
-    name = SimpleName.orThrow("evolu-relay"),
-    enableLogging = false,
+    name = Name.orThrow("evolu-relay"),
     isOwnerAllowed,
     isOwnerWithinQuota,
-  }: NodeJsRelayConfig): Promise<Result<Relay, SqliteError>> => {
-    const log = createRelayLogger(deps);
-    log.started(enableLogging, port);
+  }: NodeJsRelayConfig): Task<Relay, never, RelayDeps> =>
+  async (run) => {
+    await using stack = new AsyncDisposableStack();
+    const console = run.deps.console.child("relay");
 
     const dbFileExists = existsSync(`${name}.db`);
 
-    const sqlite = await createSqlite(deps)(name);
-    if (!sqlite.ok) return sqlite;
+    const sqliteResult = await run(createSqlite(name));
+    if (!sqliteResult.ok) return sqliteResult;
+    const sqlite = stack.use(sqliteResult.value);
 
-    const depsWithSqlite = { ...deps, sqlite: sqlite.value };
+    const deps = { ...run.deps, sqlite };
 
     if (!dbFileExists) {
-      {
-        const result = createBaseSqliteStorageTables(depsWithSqlite);
-        if (!result.ok) return result;
-      }
-      {
-        const result = createRelayStorageTables(depsWithSqlite);
-        if (!result.ok) return result;
-      }
+      createBaseSqliteStorageTables(deps);
+      createRelayStorageTables(deps);
     }
 
-    const storage = createRelaySqliteStorage(depsWithSqlite)({
-      onStorageError: log.storageError,
-      isOwnerWithinQuota,
+    const relayRun = run.create().addDeps({
+      storage: createRelaySqliteStorage(deps)({
+        isOwnerWithinQuota,
+      }),
     });
 
     const server = createServer();
@@ -107,14 +122,14 @@ const createNodeJsRelayWithDeps =
       maxPayload: defaultProtocolMessageMaxSize,
       noServer: true,
     });
-
     const ownerSocketRelation = createRelation<OwnerId, WebSocket>();
 
     server.on("upgrade", (request, socket, head) => {
-      socket.on("error", log.upgradeSocketError);
+      socket.on("error", console.debug);
 
       const completeUpgrade = () => {
-        socket.removeListener("error", log.upgradeSocketError);
+        socket.removeListener("error", console.debug);
+
         wss.handleUpgrade(request, socket, head, (ws) => {
           wss.emit("connection", ws, request);
         });
@@ -130,7 +145,7 @@ const createNodeJsRelayWithDeps =
       );
 
       if (!ownerId) {
-        log.invalidOrMissingOwnerIdInUrl(request.url);
+        console.debug("invalid or missing ownerId in URL", request.url);
         socket.write("HTTP/1.1 400 Bad Request\r\n\r\n");
         socket.destroy();
         return;
@@ -138,9 +153,9 @@ const createNodeJsRelayWithDeps =
 
       void (async () => {
         const result = isOwnerAllowed(ownerId);
-        const isAllowed = isAsync(result) ? await result : result;
+        const isAllowed = isPromiseLike(result) ? await result : result;
         if (!isAllowed) {
-          log.unauthorizedOwner(ownerId);
+          console.debug("unauthorized owner", ownerId);
           socket.write("HTTP/1.1 401 Unauthorized\r\n\r\n");
           socket.destroy();
           return;
@@ -150,97 +165,96 @@ const createNodeJsRelayWithDeps =
     });
 
     wss.on("connection", (ws) => {
-      log.connectionEstablished(wss.clients.size);
-
-      ws.on("error", (error) => {
-        log.connectionWebSocketError(error);
-      });
+      console.debug("on connection", wss.clients.size);
 
       const options: ApplyProtocolMessageAsRelayOptions = {
         subscribe: (ownerId) => {
           ownerSocketRelation.add(ownerId, ws);
-          log.relayOptionSubscribe(
+          console.debug(
+            "subscribe",
             ownerId,
-            () => ownerSocketRelation.getB(ownerId)?.size ?? 0,
+            ownerSocketRelation.bCountForA(ownerId),
           );
         },
 
         unsubscribe: (ownerId) => {
           ownerSocketRelation.remove(ownerId, ws);
-          log.relayOptionUnsubscribe(
+          console.debug(
+            "unsubscribe",
             ownerId,
-            () => ownerSocketRelation.getB(ownerId)?.size ?? 0,
+            ownerSocketRelation.bCountForA(ownerId),
           );
         },
 
         broadcast: (ownerId, message) => {
-          const sockets = ownerSocketRelation.getB(ownerId);
-          if (!sockets) return;
-
-          let broadcastCount = 0;
-          for (const socket of sockets) {
+          for (const socket of ownerSocketRelation.iterateB(ownerId)) {
             if (socket !== ws && socket.readyState === WebSocket.OPEN) {
               socket.send(message, { binary: true });
-              broadcastCount++;
             }
           }
 
-          log.relayOptionBroadcast(ownerId, broadcastCount, sockets.size);
+          console.debug(
+            "broadcast",
+            ownerId,
+            ownerSocketRelation.bCountForA(ownerId),
+          );
         },
       };
 
       ws.on("message", (message) => {
         if (!Uint8Array.is(message)) return;
-        log.messageLength(message.length);
 
-        applyProtocolMessageAsRelay({ storage })(message, options)
-          .then((response) => {
-            if (!response.ok) {
-              log.applyProtocolMessageAsRelayError(response.error);
-              return;
-            }
-            ws.send(response.value.message, { binary: true });
-            log.responseLength(response.value.message.length);
-          })
-          .catch(log.applyProtocolMessageAsRelayUnknownError);
+        void (async () => {
+          const response = await relayRun(
+            applyProtocolMessageAsRelay(message, options),
+          );
+          if (!response.ok) {
+            console.error(response);
+            return;
+          }
+          ws.send(response.value.message, { binary: true });
+        })();
       });
 
       ws.on("close", () => {
-        ownerSocketRelation.deleteB(ws);
-        log.connectionClosed(wss.clients.size);
+        ownerSocketRelation.removeByB(ws);
+        console.debug("ws close", wss.clients.size);
       });
     });
 
-    server.listen(port);
-
-    const dispose = () => {
-      log.shuttingDown();
+    // Cleanup runs in LIFO order: clients → WebSocketServer → HTTP server
+    stack.defer(() => {
+      console.info("Shutdown complete");
+    });
 
-      wss.clients.forEach((client) => {
-        if (client.readyState === WebSocket.OPEN) {
-          client.close(1000, "Evolu Relay shutting down");
-        }
+    stack.defer(() => {
+      server.close(() => {
+        console.info("HTTP server closed");
       });
+    });
 
+    stack.defer(() => {
+      // wss.close() emits 'close' when all clients have disconnected
+      // https://github.com/websockets/ws/blob/master/doc/ws.md#serverclosecallback
       wss.close(() => {
-        log.webSocketServerDisposed();
+        console.info("WebSocketServer closed");
+        ok();
       });
+    });
 
-      server.close(() => {
-        log.httpServerDisposed();
-      });
-    };
+    stack.defer(() => {
+      console.info("Shutting down...");
+      for (const client of wss.clients) {
+        if (client.readyState === WebSocket.OPEN) {
+          client.close(1000, "Evolu Relay shutting down");
+        }
+      }
+    });
 
-    let isDisposed = false;
+    stack.use(relayRun);
 
-    const relay: Relay = {
-      [Symbol.dispose]: () => {
-        if (isDisposed) return;
-        isDisposed = true;
-        sqlite.value[Symbol.dispose]();
-        dispose();
-      },
-    };
+    server.listen(port);
+    console.info(`Started on port ${port}`);
 
-    return ok(relay);
+    return ok(stack.move());
   };

package/LICENSE

@@ -1,21 +0,0 @@
-The MIT License (MIT)
-
-Copyright (c) 2023 Evolu
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.

package/dist/BetterSqliteDriver.d.ts

@@ -1,3 +0,0 @@
-import { CreateSqliteDriver } from "@evolu/common";
-export declare const createBetterSqliteDriver: CreateSqliteDriver;
-//# sourceMappingURL=BetterSqliteDriver.d.ts.map

package/dist/BetterSqliteDriver.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"BetterSqliteDriver.d.ts","sourceRoot":"","sources":["../src/BetterSqliteDriver.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,kBAAkB,EAGnB,MAAM,eAAe,CAAC;AAGvB,eAAO,MAAM,wBAAwB,EAAE,kBAqCtC,CAAC"}

package/dist/BetterSqliteDriver.js

@@ -1,31 +0,0 @@
-import { constVoid, createPreparedStatementsCache, } from "@evolu/common";
-import BetterSQLite from "better-sqlite3";
-export const createBetterSqliteDriver = (name, options) => {
-    const filename = options?.memory ? ":memory:" : `${name}.db`;
-    const db = new BetterSQLite(filename);
-    let isDisposed = false;
-    const cache = createPreparedStatementsCache((sql) => db.prepare(sql), 
-    // Not needed.
-    // https://github.com/WiseLibs/better-sqlite3/blob/master/docs/api.md#class-statement
-    constVoid);
-    const driver = {
-        exec: (query, isMutation) => {
-            // Always prepare is recommended for better-sqlite3
-            const prepared = cache.get(query, true);
-            const rows = isMutation
-                ? []
-                : prepared.all(query.parameters);
-            const changes = isMutation ? prepared.run(query.parameters).changes : 0;
-            return { rows, changes };
-        },
-        export: () => db.serialize(),
-        [Symbol.dispose]: () => {
-            if (isDisposed)
-                return;
-            isDisposed = true;
-            cache[Symbol.dispose]();
-            db.close();
-        },
-    };
-    return Promise.resolve(driver);
-};

package/dist/Crypto.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"Crypto.d.ts","sourceRoot":"","sources":["../src/Crypto.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAErD,eAAO,MAAM,qBAAqB,QAAO,eAAkC,CAAC"}

package/dist/index.d.ts

@@ -1,3 +0,0 @@
-export * from "./BetterSqliteDriver.js";
-export * from "./local-first/Relay.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,yBAAyB,CAAC;AACxC,cAAc,wBAAwB,CAAC"}

package/dist/index.js

@@ -1,2 +0,0 @@
-export * from "./BetterSqliteDriver.js";
-export * from "./local-first/Relay.js";

package/dist/local-first/Relay.d.ts

@@ -1,22 +0,0 @@
-import { ConsoleDep, CreateSqliteDriverDep, Result, SqliteError } from "@evolu/common";
-import { Relay, RelayConfig } from "@evolu/common/local-first";
-export interface NodeJsRelayConfig extends RelayConfig {
-    /** The port number for the HTTP server. */
-    readonly port?: number;
-}
-/**
- * Creates an Evolu relay server.
- *
- * This implementation uses Node.js and better-sqlite3. Additional relay
- * implementations will be provided for other platforms (Bun, Deno, Cloudflare
- * Workers, Vercel Edge, etc.).
- */
-export declare const createNodeJsRelay: (deps: ConsoleDep) => (config: NodeJsRelayConfig) => Promise<Result<Relay, SqliteError>>;
-/**
- * Creates an Evolu relay server with a custom SQLite driver.
- *
- * Use this when you need to provide a different SQLite driver implementation
- * (e.g., using alternative SQLite libraries).
- */
-export declare const createNodeJsRelayWithSqliteDriver: (deps: ConsoleDep & CreateSqliteDriverDep) => (config: NodeJsRelayConfig) => Promise<Result<Relay, SqliteError>>;
-//# sourceMappingURL=Relay.d.ts.map

package/dist/local-first/Relay.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"Relay.d.ts","sourceRoot":"","sources":["../../src/local-first/Relay.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,UAAU,EAIV,qBAAqB,EAKrB,MAAM,EAEN,WAAW,EAGZ,MAAM,eAAe,CAAC;AACvB,OAAO,EASL,KAAK,EACL,WAAW,EACZ,MAAM,2BAA2B,CAAC;AAOnC,MAAM,WAAW,iBAAkB,SAAQ,WAAW;IACpD,2CAA2C;IAC3C,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,GAC3B,MAAM,UAAU,MAChB,QAAQ,iBAAiB,KAAG,OAAO,CAAC,MAAM,CAAC,KAAK,EAAE,WAAW,CAAC,CAInD,CAAC;AAEf;;;;;GAKG;AACH,eAAO,MAAM,iCAAiC,GAC3C,MAAM,UAAU,GAAG,qBAAqB,MACxC,QAAQ,iBAAiB,KAAG,OAAO,CAAC,MAAM,CAAC,KAAK,EAAE,WAAW,CAAC,CAKnD,CAAC"}