Merge branch 'main' into feat/execute-raw

Author: Chriztiaan

.github/workflows/deploy-docs.yaml

@@ -54,7 +54,7 @@ jobs:
         run: pnpm build:packages
       - name: Build Docs
         run: pnpm docs:build
-      - uses: actions/upload-pages-artifact@v2
+      - uses: actions/upload-pages-artifact@v3
         with:
           path: ./docs/build
   deploy:
@@ -66,4 +66,4 @@ jobs:
     steps:
       - name: Deploy to GitHub Pages
         id: deployment
-        uses: actions/deploy-pages@v2
+        uses: actions/deploy-pages@v4

.github/workflows/test.yml

@@ -7,7 +7,7 @@ on:
 jobs:
   test:
     name: Test Packages
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-xl
     steps:
       - uses: actions/checkout@v4
         with:
@@ -40,6 +40,11 @@ jobs:
       - name: Install dependencies
         run: pnpm install
 
+      - name: Configure Playwright
+        run: |
+          pnpm exec playwright install-deps
+          pnpm exec playwright install
+
       - name: Build
         run: pnpm build:packages
 

README.md

@@ -2,7 +2,7 @@
   <a href="https://www.powersync.com" target="_blank"><img src="https://github.com/powersync-ja/.github/assets/7372448/d2538c43-c1a0-4c47-9a76-41462dba484f"/></a>
 </p>
 
-*[PowerSync](https://www.powersync.com) is a sync engine for building local-first apps with instantly-responsive UI/UX and simplified state transfer. Syncs between SQLite on the client-side and Postgres, MongoDB or MySQL on the server-side.*
+_[PowerSync](https://www.powersync.com) is a sync engine for building local-first apps with instantly-responsive UI/UX and simplified state transfer. Syncs between SQLite on the client-side and Postgres, MongoDB or MySQL on the server-side._
 
 # PowerSync JavaScript SDKs
 
@@ -18,6 +18,10 @@
 
   - 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).
@@ -100,6 +108,15 @@ Build packages
 pnpm build:packages
 ```
 
+## Tests
+
+Some packages use [Playwright](https://www.npmjs.com/package/playwright) for testing. Install Playwright dependencies with:
+
+```bash
+pnpm exec playwright install-deps
+pnpm exec playwright install
+```
+
 ## Versioning
 
 ### Development Packages

demos/angular-supabase-todolist/src/app/supabase.service.ts

@@ -8,7 +8,7 @@ import {
   type User
 } from '@supabase/supabase-js';
 import { environment } from '../environment';
-import { type AbstractPowerSyncDatabase, type CrudEntry, UpdateType, PowerSyncBackendConnector } from '@powersync/web';
+import { type AbstractPowerSyncDatabase, type CrudEntry, UpdateType, PowerSyncBackendConnector, type PowerSyncCredentials } from '@powersync/web';
 
 /// Postgres Response codes that we cannot recover from by retrying.
 const FATAL_RESPONSE_CODES = [
@@ -67,7 +67,7 @@ export class SupabaseService implements PowerSyncBackendConnector {
     return {
       endpoint: environment.powersyncUrl,
       token: session.access_token ?? ''
-    };
+    } satisfies PowerSyncCredentials;
   }
 
   authChanges(callback: (event: AuthChangeEvent, session: Session | null) => void) {

demos/django-react-native-todolist/package.json

@@ -10,7 +10,7 @@
   "dependencies": {
     "@azure/core-asynciterator-polyfill": "^1.0.2",
     "@expo/vector-icons": "^14.0.0",
-    "@journeyapps/react-native-quick-sqlite": "^2.3.0",
+    "@journeyapps/react-native-quick-sqlite": "^2.4.2",
     "@powersync/common": "workspace:*",
     "@powersync/react": "workspace:*",
     "@powersync/react-native": "workspace:*",

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'];