Connect, run query, show results

Author: simolus3

demos/example-electron-node/.env.local.template

@@ -0,0 +1,4 @@
+# Copy to .env.local, and enter your PowerSync instance URL and auth token.
+# Leave blank to test local-only.
+POWERSYNC_URL=
+POWERSYNC_TOKEN=

demos/example-electron-node/.gitignore

@@ -1,3 +1,4 @@
 .webpack/
 out/
 packages/
+.env.local

demos/example-electron-node/README.md

@@ -1,4 +1,32 @@
-TODO:
+# PowerSync + Electron in main process
 
-- `electron-rebuild` needs to run.
-- Explain custom worker.
+This example shows how the [PowerSync Node.js client](https://docs.powersync.com/client-sdk-references/node#node-js-client-alpha) can be used in the main process of an Electron app.
+
+The purpose of this example is to highlight specific build configurations that enable this setup.
+In particular:
+
+1. In `src/main/index.ts`, a `PowerSyncDatabase` is created. PowerSync uses node workers to speed up database
+   queries. This worker is part of the `@powersync/node` package and wouldn't be copied into the resulting Electron
+   app by default. For this reason, this example has its own `src/main/worker.ts` loaded with `new URL('./worker.ts', import.meta.url)`.
+2. In addition to the worker, PowerSync requires access to a SQLite extension providing sync functionality.
+   This file is also part of the `@powersync/node` package and called `powersync.dll`, `libpowersync.dylib` or
+   `libpowersync.so` depending on the operating system.
+   We use the `copy-webpack-plugin` package to make sure a copy of that file is available to the main process,
+   and load it in the custom `src/main/worker.ts`.
+3. The `get()` and `getAll()` methods are exposed to the renderer process with an IPC channel.
+
+To see it in action:
+
+1. Make sure to run `pnpm install` and `pnpm build:packages` in the root directory of this repo.
+2. Copy `.env.local.template` to `.env.local`, and complete the environment variables. You can generate a [temporary development token](https://docs.powersync.com/usage/installation/authentication-setup/development-tokens), or leave blank to test with local-only data.
+   The example works with the schema from the [PowerSync + Supabase tutorial](https://docs.powersync.com/integration-guides/supabase-+-powersync#supabase-powersync).
+3. `cd` in this directory and run `pnpm start`.
+
+Apart from the build setup, this example is purposefully kept simple.
+To make sure PowerSync is working, you can run `await powersync.get('SELECT powersync_rs_version()');` in the DevTools
+console. A result from that query implies that the PowerSync was properly configured.
+
+For more details, see the documentation for [the PowerSync node package](https://docs.powersync.com/client-sdk-references/node#node-js-client-alpha) and check other examples:
+
+- [example-node](../example-node/): A Node.js CLI example that connects to PowerSync to run auto-updating queries.
+- [example-electron](../example-electron/): An Electron example that runs PowerSync in the render process instead of in the main one.

demos/example-electron-node/forge.config.ts

@@ -9,14 +9,18 @@ import { MakerDeb } from '@electron-forge/maker-deb';
 import { MakerRpm } from '@electron-forge/maker-rpm';
 import { AutoUnpackNativesPlugin } from '@electron-forge/plugin-auto-unpack-natives';
 import { WebpackPlugin } from '@electron-forge/plugin-webpack';
-import type { Configuration, ModuleOptions } from 'webpack';
+import { type Configuration, type ModuleOptions, type DefinePlugin } from 'webpack';
+import * as dotenv from 'dotenv';
 import type IForkTsCheckerWebpackPlugin from 'fork-ts-checker-webpack-plugin';
 import type ICopyPlugin from 'copy-webpack-plugin';
 
+dotenv.config({path: '.env.local'});
+
 const require = createRequire(import.meta.url);
 
 const ForkTsCheckerWebpackPlugin: typeof IForkTsCheckerWebpackPlugin = require('fork-ts-checker-webpack-plugin');
 const CopyPlugin: typeof ICopyPlugin = require('copy-webpack-plugin');
+const DefinePluginImpl: typeof DefinePlugin = require('webpack').DefinePlugin;
 
 const webpackPlugins = [
   new ForkTsCheckerWebpackPlugin({
@@ -86,6 +90,10 @@ const mainConfig: Configuration = {
         to: extensionPath,
       }],
     }),
+    new DefinePluginImpl({
+      POWERSYNC_URL: JSON.stringify(process.env.POWERSYNC_URL),
+      POWERSYNC_TOKEN: JSON.stringify(process.env.POWERSYNC_TOKEN),
+    }),
   ],
   resolve: {
     extensions: ['.js', '.ts', '.jsx', '.tsx', '.css', '.json']

demos/example-electron-node/package.json

@@ -26,6 +26,7 @@
     "@vercel/webpack-asset-relocator-loader": "1.7.3",
     "copy-webpack-plugin": "^13.0.0",
     "css-loader": "^6.11.0",
+    "dotenv": "^16.4.7",
     "electron": "30.0.2",
     "electron-rebuild": "^3.2.9",
     "fork-ts-checker-webpack-plugin": "^9.0.2",

demos/example-electron-node/src/main/index.ts

@@ -1,13 +1,19 @@
 import { Worker } from 'node:worker_threads';
 
-import { PowerSyncDatabase } from '@powersync/node';
-import { app, BrowserWindow, ipcMain } from 'electron';
-import { AppSchema } from './powersync';
+import { PowerSyncDatabase, SyncStreamConnectionMethod } from '@powersync/node';
+import { app, BrowserWindow, ipcMain, MessagePortMain } from 'electron';
+import { AppSchema, BackendConnector } from './powersync';
 import { default as Logger } from 'js-logger';
 
 const logger = Logger.get('PowerSyncDemo');
 Logger.useDefaults({ defaultLevel: logger.WARN });
 
+// This allows TypeScript to pick up the magic constants that's auto-generated by Forge's Webpack
+// plugin that tells the Electron app where to look for the Webpack-bundled app code (depending on
+// whether you're running in development or production).
+declare const MAIN_WINDOW_WEBPACK_ENTRY: string;
+declare const MAIN_WINDOW_PRELOAD_WEBPACK_ENTRY: string;
+
 // Handle creating/removing shortcuts on Windows when installing/uninstalling.
 if (require('electron-squirrel-startup')) {
   app.quit();
@@ -24,12 +30,6 @@ const database = new PowerSyncDatabase({
   logger
 });
 
-// This allows TypeScript to pick up the magic constants that's auto-generated by Forge's Webpack
-// plugin that tells the Electron app where to look for the Webpack-bundled app code (depending on
-// whether you're running in development or production).
-declare const MAIN_WINDOW_WEBPACK_ENTRY: string;
-declare const MAIN_WINDOW_PRELOAD_WEBPACK_ENTRY: string;
-
 const createWindow = (): void => {
   // Create the browser window.
   const mainWindow = new BrowserWindow({
@@ -51,6 +51,50 @@ const createWindow = (): void => {
 // initialization and is ready to create browser windows.
 // Some APIs can only be used after this event occurs.
 app.whenReady().then(() => {
+  database.connect(new BackendConnector(), { connectionMethod: SyncStreamConnectionMethod.HTTP });
+
+  const forwardSyncStatus = (port: MessagePortMain) => {
+    port.postMessage(database.currentStatus.toJSON());
+    const unregister = database.registerListener({
+      statusChanged(status) {
+        port.postMessage(status.toJSON());
+      },
+    });
+    port.once('close', unregister);
+  };
+
+  const forwardWatchResults = (sql: string, args: any[], port: MessagePortMain) => {
+    const abort = new AbortController();
+    port.once('close', () => abort.abort());
+
+    database.watchWithCallback(sql, args, {
+      onResult(results) {
+        port.postMessage(results.rows._array);
+      },
+      onError(error) {
+        console.error(`Watch ${sql} with ${args} failed`, error);
+      },
+    }, {signal: abort.signal});
+  };
+
+  ipcMain.on('port', (portEvent) => {
+    const [port] = portEvent.ports;
+    port.start();
+
+    port.on('message', (event) => {
+      const {method, payload} = event.data;
+      switch (method) {
+        case 'syncStatus':
+          forwardSyncStatus(port);
+          break;
+        case 'watch':
+          const {sql, args} = payload;
+          forwardWatchResults(sql, args, port);
+          break;
+      };
+    });
+  });
+
   ipcMain.handle('get', async (_, sql: string, args: any[]) => {
     return await database.get(sql, args);
   });

demos/example-electron-node/src/main/powersync.ts

@@ -1,49 +1,66 @@
 import { AbstractPowerSyncDatabase, column, PowerSyncBackendConnector, Schema, Table } from '@powersync/node';
 
-export class DemoConnector implements PowerSyncBackendConnector {
+declare const POWERSYNC_URL: string|null;
+declare const POWERSYNC_TOKEN: string|null;
+
+export class BackendConnector implements PowerSyncBackendConnector {
+  private powersyncUrl: string | undefined;
+  private powersyncToken: string | undefined;
+
+  constructor() {
+    this.powersyncUrl = POWERSYNC_URL;
+    // This token is for development only.
+    // For production applications, integrate with an auth provider or custom auth.
+    this.powersyncToken = POWERSYNC_TOKEN;
+  }
+
   async fetchCredentials() {
-    const response = await fetch(`${process.env.BACKEND}/api/auth/token`);
-    if (response.status != 200) {
-      throw 'Could not fetch token';
+    // TODO: Use an authentication service or custom implementation here.
+    if (this.powersyncToken == null || this.powersyncUrl == null) {
+      return null;
     }
 
-    const { token } = await response.json();
-
     return {
-      endpoint: process.env.SYNC_SERVICE!,
-      token: token
+      endpoint: this.powersyncUrl,
+      token: this.powersyncToken
     };
   }
 
-  async uploadData(database: AbstractPowerSyncDatabase) {
-    const batch = await database.getCrudBatch();
-    if (batch == null) {
+  async uploadData(database: AbstractPowerSyncDatabase): Promise<void> {
+    const transaction = await database.getNextCrudTransaction();
+
+    if (!transaction) {
       return;
     }
 
-    const entries: any[] = [];
-    for (const op of batch.crud) {
-      entries.push({
-        table: op.table,
-        op: op.op,
-        id: op.id,
-        data: op.opData
-      });
-    }
+    try {
+      // TODO: Upload here
 
-    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 transaction.complete();
+    } catch (error: any) {
+      if (shouldDiscardDataOnError(error)) {
+        // Instead of blocking the queue with these errors, discard the (rest of the) transaction.
+        //
+        // Note that these errors typically indicate a bug in the application.
+        // If protecting against data loss is important, save the failing records
+        // elsewhere instead of discarding, and/or notify the user.
+        console.error(`Data upload error - discarding`, error);
+        await transaction.complete();
+      } else {
+        // Error may be retryable - e.g. network error or temporary server error.
+        // Throwing an error here causes this call to be retried after a delay.
+        throw error;
+      }
     }
-
-    await batch?.complete();
   }
 }
 
+function shouldDiscardDataOnError(error: any) {
+  // TODO: Ignore non-retryable errors here
+  return false;
+}
+
+
 export const LIST_TABLE = 'lists';
 export const TODO_TABLE = 'todos';
 

demos/example-electron-node/src/render/index.html

@@ -12,5 +12,12 @@ <h1>PowerSync demo</h1>
       enter <code>await powersync.get('SELECT powersync_rs_version()');</code>
       in the DevTools console.
     </p>
+
+    <p>SyncStatus: <code id="sync-status"></code></p>
+    <p>
+      Results of running <code>SELECT * FROM lists</code> (updates automatically).
+
+      <li id="results"></li>
+    </p>
   </body>
 </html>

demos/example-electron-node/src/render/main.ts

@@ -1 +1,31 @@
-console.log('👋 This message is being logged by "renderer.js", included via webpack');
+import { type SyncStatus } from "@powersync/node";
+
+// Declared in preload.ts
+declare const powersync: {
+    addPort: (port: MessagePort) => void,
+    get: (sql: string, variables: any[]) => Promise<any[]>,
+    syncStatus: (cb: (status: SyncStatus) => void) => void,
+    watch: (sql: string, args: any[], cb: (rows: any[]) => void) => void,
+};
+
+const syncStatusTarget = document.getElementById('sync-status')!;
+const results = document.getElementById('results') as HTMLLIElement;
+
+// Simple query
+powersync.get('SELECT powersync_rs_version()', []).then(console.log);
+
+powersync.syncStatus((status) => {
+    syncStatusTarget.innerText = `${JSON.stringify(status)}`;    
+});
+
+powersync.watch('SELECT * FROM lists', [], (rows) => {
+    console.log(rows);
+    const newElements: HTMLUListElement[] = [];
+    for (const entry of rows) {
+        const dom = document.createElement('ul');
+        dom.textContent = JSON.stringify(entry);
+        newElements.push(dom);
+    }
+
+    results.replaceChildren(...newElements);
+});

demos/example-electron-node/src/render/preload.ts

@@ -1,5 +1,24 @@
+import { type SyncStatus } from '@powersync/node';
 import { contextBridge, ipcRenderer } from 'electron';
 
 contextBridge.exposeInMainWorld('powersync', {
-  get: (sql: string, variables: any[]) => ipcRenderer.invoke('get', sql, variables)
+  get: (sql: string, variables: any[]) => ipcRenderer.invoke('get', sql, variables),
+  getAll: (sql: string, variables: any[]) => ipcRenderer.invoke('get', sql, variables),
+  syncStatus: (cb: (status: SyncStatus) => void) => {
+    const channel = new MessageChannel();
+    channel.port1.onmessage = (event) => cb(event.data);
+
+    ipcRenderer.postMessage('port', null, [channel.port2]);
+    channel.port1.postMessage({method: 'syncStatus'});
+  },
+  watch: (sql: string, args: any[], cb: (rows: any[]) => void) => {
+    const channel = new MessageChannel();
+    channel.port1.onmessage = (event) => cb(event.data);
+
+    const message = {method: 'watch', 'payload': {sql, args}};
+    ipcRenderer.postMessage('port', null, [channel.port2]);
+    channel.port1.postMessage(message);
+
+    return () => channel.port1.close(); // Closign the port also closes resources on the main process
+  },
 });