Merge pull request #516 from powersync-ja/node

Add NodeJS implementation

Author: simolus3

.changeset/serious-rice-buy.md

@@ -0,0 +1,5 @@
+---
+'@powersync/node': minor
+---
+
+Initial version

README.md

@@ -18,6 +18,10 @@ _[PowerSync](https://www.powersync.com) is a sync engine for building local-firs
 
   - JS Web SDK implementation (extension of `packages/common`)
 
+- [packages/node](./packages/node/README.md)
+
+  - Node.js client implementation (extension of `packages/common`)
+
 - [packages/react](./packages/react/README.md)
 
   - React integration for PowerSync.
@@ -80,6 +84,10 @@ Demo applications are located in the [`demos/`](./demos/) directory. Also see ou
 
 - [demos/example-capacitor](./demos/example-capacitor/README.md) A Capacitor example app using the PowerSync Web SDK.
 
+### Node
+
+- [demos/example-node](./demos/example-node/README.md) A small CLI example built using the PowerSync SDK for Node.js.
+
 ## Tools
 
 - [tools/diagnostics-app](./tools/diagnostics-app): A standalone web app that presents stats about a user's local database (incl. tables and sync buckets).

demos/example-node/.env

@@ -0,0 +1,2 @@
+BACKEND=http://localhost:6060
+SYNC_SERVICE=http://localhost:8080

demos/example-node/README.md

@@ -0,0 +1,16 @@
+## Node.js Demo
+
+This demonstrates a small Node.js client opening a database and connecting PowerSync.
+
+This demo is configured to talk to an example backend [you can host yourself](https://github.com/powersync-ja/self-host-demo). To get started:
+
+1. Start one of the Node.js backend examples from [the self-host-demo repository](https://github.com/powersync-ja/self-host-demo).
+2. If necessary, change `.env` to point to the started backend and sync service.
+3. Run `pnpm install` and `pnpm build:packages` in the root of this repo.
+4. In this directory, run `pnpm run start`.
+
+This opens the local database, connects to PowerSync, waits for a first sync and then runs a simple query.
+Results from the query are printed every time it changes. Try:
+
+1. Updating a row in the backend database and see changes reflected in the running client.
+2. Enter `add('my list')` and see the new list show up in the backend database.

demos/example-node/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "example-node",
+  "version": "1.0.0",
+  "description": "",
+  "type": "module",
+  "private": true,
+  "scripts": {
+    "build": "tsc -b",
+    "watch": "tsc -b -w",
+    "start": "node --loader ts-node/esm -r dotenv/config src/main.ts"
+  },
+  "dependencies": {
+    "@powersync/node": "workspace:*",
+    "dotenv": "^16.4.7"
+  },
+  "devDependencies": {
+    "ts-node": "^10.9.2",
+    "typescript": "^5.8.2"
+  }
+}

demos/example-node/src/main.ts

@@ -0,0 +1,65 @@
+import repl_factory from 'node:repl';
+import { once } from 'node:events';
+
+import { PowerSyncDatabase, SyncStreamConnectionMethod } from '@powersync/node';
+import Logger from 'js-logger';
+import { AppSchema, DemoConnector } from './powersync.js';
+import { exit } from 'node:process';
+
+const main = async () => {
+  Logger.useDefaults({ defaultLevel: Logger.WARN });
+
+  if (!('BACKEND' in process.env) || !('SYNC_SERVICE' in process.env)) {
+    console.warn(
+      'Set the BACKEND and SYNC_SERVICE environment variables to point to a sync service and a running demo backend.'
+    );
+    return;
+  }
+
+  const db = new PowerSyncDatabase({
+    schema: AppSchema,
+    database: {
+      dbFilename: 'test.db'
+    },
+    logger: Logger
+  });
+  console.log(await db.get('SELECT powersync_rs_version();'));
+
+  await db.connect(new DemoConnector(), { connectionMethod: SyncStreamConnectionMethod.HTTP });
+  await db.waitForFirstSync();
+  console.log('First sync complete!');
+
+  let hasFirstRow: ((value: any) => void) | null = null;
+  const firstRow = new Promise((resolve) => (hasFirstRow = resolve));
+  const watchLists = async () => {
+    for await (const rows of db.watch('SELECT * FROM lists')) {
+      if (hasFirstRow) {
+        hasFirstRow(null);
+        hasFirstRow = null;
+      }
+      console.log('Has todo lists', rows.rows?._array);
+    }
+  };
+
+  watchLists();
+  await firstRow;
+
+  console.log('Connected to PowerSync. Try updating the lists in the database and see it reflected here.');
+  console.log("To upload a list here, enter `await add('name of new list');`");
+
+  const repl = repl_factory.start();
+  repl.context.add = async (name: string) => {
+    await db.execute(
+      "INSERT INTO lists (id, created_at, name, owner_id) VALUEs (uuid(), datetime('now'), ?, uuid());",
+      [name]
+    );
+  };
+
+  await once(repl, 'exit');
+  console.log('shutting down');
+  await db.disconnect();
+  await db.close();
+  exit(0);
+};
+
+await main();

demos/example-node/src/powersync.ts

@@ -0,0 +1,77 @@
+import { AbstractPowerSyncDatabase, column, PowerSyncBackendConnector, Schema, Table } from '@powersync/node';
+
+export class DemoConnector implements PowerSyncBackendConnector {
+  async fetchCredentials() {
+    const response = await fetch(`${process.env.BACKEND}/api/auth/token`);
+    if (response.status != 200) {
+      throw 'Could not fetch token';
+    }
+
+    const { token } = await response.json();
+
+    return {
+      endpoint: process.env.SYNC_SERVICE!,
+      token: token
+    };
+  }
+
+  async uploadData(database: AbstractPowerSyncDatabase) {
+    const batch = await database.getCrudBatch();
+    if (batch == null) {
+      return;
+    }
+
+    const entries: any[] = [];
+    for (const op of batch.crud) {
+      entries.push({
+        table: op.table,
+        op: op.op,
+        id: op.id,
+        data: op.opData
+      });
+    }
+
+    const response = await fetch(`${process.env.BACKEND}/api/data/`, {
+      method: 'POST',
+      headers: {'Content-Type': 'application/json'},
+      body: JSON.stringify({batch: entries}),
+    });
+    if (response.status !== 200) {
+      throw new Error(`Server returned HTTP ${response.status}: ${await response.text()}`);
+    }
+
+    await batch?.complete();
+  }
+}
+
+export const LIST_TABLE = 'lists';
+export const TODO_TABLE = 'todos';
+
+const todos = new Table(
+  {
+    list_id: column.text,
+    created_at: column.text,
+    completed_at: column.text,
+    description: column.text,
+    created_by: column.text,
+    completed_by: column.text,
+    completed: column.integer,
+    photo_id: column.text
+  },
+  { indexes: { list: ['list_id'] } }
+);
+
+const lists = new Table({
+  created_at: column.text,
+  name: column.text,
+  owner_id: column.text
+});
+
+export const AppSchema = new Schema({
+  lists,
+  todos
+});
+
+export type Database = (typeof AppSchema)['types'];
+export type TodoRecord = Database['todos'];
+export type ListRecord = Database['lists'];

demos/example-node/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "extends": "../../tsconfig.base",
+  "compilerOptions": {
+    "baseUrl": ".",
+    "rootDir": "src",
+    "outDir": "lib",
+    "strictNullChecks": true
+  },
+  "references": [
+    {
+      "path": "../../packages/node"
+    }
+  ]
+}

docs/utils/packageMap.ts

@@ -6,7 +6,8 @@ enum Packages {
   VueSdk = 'vue-sdk',
   AttachmentsSdk = 'attachments-sdk',
   WebSdk = 'web-sdk',
-  TanstackReactQuerySdk = 'tanstack-react-query-sdk'
+  TanstackReactQuerySdk = 'tanstack-react-query-sdk',
+  NodeSdk = 'node-sdk',
 }
 
 interface Package {
@@ -63,5 +64,12 @@ export const packageMap: PackageMap = {
     entryPoints: ['../packages/attachments/src/index.ts'],
     tsconfig: '../packages/attachments/tsconfig.json',
     id: Packages.AttachmentsSdk
-  }
+  },
+  [Packages.NodeSdk]: {
+    name: 'Node SDK',
+    dirName: Packages.NodeSdk,
+    entryPoints: ['../packages/node/src/index.ts'],
+    tsconfig: '../packages/node/tsconfig.json',
+    id: Packages.NodeSdk
+  },
 };

packages/node/CHANGELOG.md

@@ -0,0 +1 @@
+# @powersync/node