@evolu/nodejs 1.0.0-preview.0

package/LICENSE

@@ -0,0 +1,21 @@
+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/README.md

@@ -0,0 +1,13 @@
+# Evolu Relay for Node.js and SQLite
+
+## Documentation
+
+For detailed information and usage examples, please visit [evolu.dev](https://www.evolu.dev).
+
+## Community
+
+The Evolu community is on [GitHub Discussions](https://github.com/evoluhq/evolu/discussions), where you can ask questions and voice ideas.
+
+To chat with other community members, you can join the [Evolu Discord](https://discord.gg/2J8yyyyxtZ).
+
+[![Twitter URL](https://img.shields.io/twitter/url/https/twitter.com/evoluhq.svg?style=social&label=Follow%20%40evoluhq)](https://twitter.com/evoluhq)

package/dist/BetterSqliteDriver.d.ts

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

package/dist/BetterSqliteDriver.d.ts.map

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,31 @@
+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/Evolu/Relay.d.ts

@@ -0,0 +1,7 @@
+import { ConsoleDep } from "@evolu/common";
+import { Relay, RelayConfig } from "@evolu/common/evolu";
+export interface NodeJsRelayConfig extends RelayConfig {
+    readonly port?: number;
+}
+export declare const createNodeJsRelay: (deps: ConsoleDep) => (config: NodeJsRelayConfig) => Promise<Relay>;
+//# sourceMappingURL=Relay.d.ts.map

package/dist/Evolu/Relay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Relay.d.ts","sourceRoot":"","sources":["../../src/Evolu/Relay.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,UAAU,EAQX,MAAM,eAAe,CAAC;AACvB,OAAO,EAML,KAAK,EACL,WAAW,EAEZ,MAAM,qBAAqB,CAAC;AAI7B,MAAM,WAAW,iBAAkB,SAAQ,WAAW;IACpD,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,eAAO,MAAM,iBAAiB,GAC3B,MAAM,UAAU,MACV,QAAQ,iBAAiB,KAAG,OAAO,CAAC,KAAK,CA0G/C,CAAC"}

package/dist/Evolu/Relay.js

@@ -0,0 +1,80 @@
+import { createManyToManyMap, createRandom, createSqlite, getOrThrow, SimpleName, Uint8Array, } from "@evolu/common";
+import { applyProtocolMessageAsRelay, createRelayStorage, maxProtocolMessageSize, protocolVersion, } from "@evolu/common/evolu";
+import { WebSocket, WebSocketServer } from "ws";
+import { createBetterSqliteDriver } from "../BetterSqliteDriver.js";
+export const createNodeJsRelay = (deps) => async (config) => {
+    const { port = 443, name = getOrThrow(SimpleName.from("evolu-relay")), enableLogging = false, } = config;
+    deps.console.log(`Evolu Relay started on port ${port}`);
+    deps.console.enabled = enableLogging;
+    const versionedName = getOrThrow(SimpleName.from(`${name}-${protocolVersion}`));
+    const sqlite = getOrThrow(await createSqlite({
+        ...deps,
+        createSqliteDriver: createBetterSqliteDriver,
+    })(versionedName));
+    const sqliteStorageDeps = {
+        sqlite,
+        random: createRandom(),
+    };
+    const storage = getOrThrow(createRelayStorage(sqliteStorageDeps)({
+        onStorageError: (error) => {
+            deps.console.error("[relay]", "[storage]", error);
+        },
+    }));
+    const wss = new WebSocketServer({
+        maxPayload: maxProtocolMessageSize,
+        port,
+    });
+    const ownerSocketsMap = createManyToManyMap();
+    wss.on("connection", (ws) => {
+        ws.on("error", deps.console.error);
+        const options = {
+            subscribe: (ownerId) => {
+                ownerSocketsMap.add(ownerId, ws);
+            },
+            broadcast: (ownerId, message) => {
+                const sockets = ownerSocketsMap.getValues(ownerId);
+                for (const socket of sockets) {
+                    if (socket !== ws && socket.readyState === WebSocket.OPEN) {
+                        socket.send(message, { binary: true });
+                    }
+                }
+            },
+        };
+        ws.on("message", (message) => {
+            if (!Uint8Array.is(message))
+                return;
+            const response = applyProtocolMessageAsRelay({ storage })(message, options);
+            if (!response.ok) {
+                deps.console.warn(response.error.type);
+                return;
+            }
+            if (response.value) {
+                ws.send(response.value, { binary: true });
+            }
+        });
+        ws.on("close", () => {
+            ownerSocketsMap.deleteValue(ws);
+        });
+    });
+    const disposeWss = () => {
+        deps.console.log("Shutting down Evolu Relay...");
+        wss.clients.forEach((client) => {
+            if (client.readyState === WebSocket.OPEN) {
+                client.close(1000, "Evolu Relay shutting down");
+            }
+        });
+        wss.close(() => {
+            deps.console.log("Evolu Relay disposed");
+        });
+    };
+    let isDisposed = false;
+    return {
+        [Symbol.dispose]: () => {
+            if (isDisposed)
+                return;
+            isDisposed = true;
+            sqlite[Symbol.dispose]();
+            disposeWss();
+        },
+    };
+};

package/dist/index.d.ts

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

package/dist/index.d.ts.map

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

package/dist/index.js

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

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@evolu/nodejs",
+  "version": "1.0.0-preview.0",
+  "description": "Evolu for Node.js",
+  "author": "Daniel Steigerwald <daniel@steigerwald.cz>",
+  "license": "MIT",
+  "repository": "evoluhq/evolu",
+  "bugs": {
+    "url": "https://github.com/evoluhq/evolu/issues"
+  },
+  "homepage": "https://evolu.dev",
+  "type": "module",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "files": [
+    "dist/**",
+    "src/**",
+    "README.md"
+  ],
+  "dependencies": {
+    "better-sqlite3": "^11.10.0",
+    "ws": "^8.18.2"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/node": "^22.15.30",
+    "typescript": "^5.8.3",
+    "vitest": "^3.2.2",
+    "@evolu/common": "6.0.0-preview.0",
+    "@evolu/tsconfig": "0.0.2"
+  },
+  "peerDependencies": {
+    "@evolu/common": "^6.0.0-preview.0"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "dev": "tsc --watch",
+    "build": "shx rm -rf dist && tsc",
+    "clean": "shx rm -rf .turbo node_modules dist",
+    "format": "prettier --write \"src/*.{ts,tsx,md}\""
+  }
+}

package/src/BetterSqliteDriver.ts

@@ -0,0 +1,47 @@
+import {
+  constVoid,
+  createPreparedStatementsCache,
+  CreateSqliteDriver,
+  SqliteDriver,
+  SqliteRow,
+} from "@evolu/common";
+import BetterSQLite, { Statement } from "better-sqlite3";
+
+export const createBetterSqliteDriver: CreateSqliteDriver = (name, options) => {
+  const filename = options?.memory ? ":memory:" : `${name}.db`;
+  const db = new BetterSQLite(filename);
+  let isDisposed = false;
+
+  const cache = createPreparedStatementsCache<Statement>(
+    (sql) => db.prepare(sql),
+    // Not needed.
+    // https://github.com/WiseLibs/better-sqlite3/blob/master/docs/api.md#class-statement
+    constVoid,
+  );
+
+  const driver: SqliteDriver = {
+    exec: (query, isMutation) => {
+      // Always prepare is recommended for better-sqlite3
+      const prepared = cache.get(query, true);
+
+      const rows = isMutation
+        ? []
+        : (prepared.all(query.parameters) as Array<SqliteRow>);
+
+      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/src/Evolu/Relay.ts

@@ -0,0 +1,136 @@
+import {
+  ConsoleDep,
+  createManyToManyMap,
+  createRandom,
+  createSqlite,
+  getOrThrow,
+  OwnerId,
+  SimpleName,
+  Uint8Array,
+} from "@evolu/common";
+import {
+  applyProtocolMessageAsRelay,
+  ApplyProtocolMessageAsRelayOptions,
+  createRelayStorage,
+  maxProtocolMessageSize,
+  protocolVersion,
+  Relay,
+  RelayConfig,
+  SqliteStorageDeps,
+} from "@evolu/common/evolu";
+import { WebSocket, WebSocketServer } from "ws";
+import { createBetterSqliteDriver } from "../BetterSqliteDriver.js";
+
+export interface NodeJsRelayConfig extends RelayConfig {
+  readonly port?: number;
+}
+
+export const createNodeJsRelay =
+  (deps: ConsoleDep) =>
+  async (config: NodeJsRelayConfig): Promise<Relay> => {
+    const {
+      port = 443,
+      name = getOrThrow(SimpleName.from("evolu-relay")),
+      enableLogging = false,
+    } = config;
+
+    deps.console.log(`Evolu Relay started on port ${port}`);
+
+    deps.console.enabled = enableLogging;
+
+    const versionedName = getOrThrow(
+      SimpleName.from(`${name}-${protocolVersion}`),
+    );
+
+    const sqlite = getOrThrow(
+      await createSqlite({
+        ...deps,
+        createSqliteDriver: createBetterSqliteDriver,
+      })(versionedName),
+    );
+
+    const sqliteStorageDeps: SqliteStorageDeps = {
+      sqlite,
+      random: createRandom(),
+    };
+
+    const storage = getOrThrow(
+      createRelayStorage(sqliteStorageDeps)({
+        onStorageError: (error) => {
+          deps.console.error("[relay]", "[storage]", error);
+        },
+      }),
+    );
+
+    const wss = new WebSocketServer({
+      maxPayload: maxProtocolMessageSize,
+      port,
+    });
+
+    const ownerSocketsMap = createManyToManyMap<OwnerId, WebSocket>();
+
+    wss.on("connection", (ws) => {
+      ws.on("error", deps.console.error);
+
+      const options: ApplyProtocolMessageAsRelayOptions = {
+        subscribe: (ownerId) => {
+          ownerSocketsMap.add(ownerId, ws);
+        },
+        broadcast: (ownerId, message) => {
+          const sockets = ownerSocketsMap.getValues(ownerId)!;
+          for (const socket of sockets) {
+            if (socket !== ws && socket.readyState === WebSocket.OPEN) {
+              socket.send(message, { binary: true });
+            }
+          }
+        },
+      };
+
+      ws.on("message", (message) => {
+        if (!Uint8Array.is(message)) return;
+
+        const response = applyProtocolMessageAsRelay({ storage })(
+          message,
+          options,
+        );
+
+        if (!response.ok) {
+          deps.console.warn(response.error.type);
+          return;
+        }
+
+        if (response.value) {
+          ws.send(response.value, { binary: true });
+        }
+      });
+
+      ws.on("close", () => {
+        ownerSocketsMap.deleteValue(ws);
+      });
+    });
+
+    const disposeWss = () => {
+      deps.console.log("Shutting down Evolu Relay...");
+
+      wss.clients.forEach((client) => {
+        if (client.readyState === WebSocket.OPEN) {
+          client.close(1000, "Evolu Relay shutting down");
+        }
+      });
+
+      wss.close(() => {
+        deps.console.log("Evolu Relay disposed");
+      });
+    };
+
+    let isDisposed = false;
+
+    return {
+      [Symbol.dispose]: () => {
+        if (isDisposed) return;
+        isDisposed = true;
+        sqlite[Symbol.dispose]();
+        disposeWss();
+      },
+    };
+  };

package/src/index.ts

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