@powersync/web 1.21.1 → 1.22.0

package/lib/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@powersync/web",
-    "version": "1.21.1",
+    "version": "1.22.0",
     "description": "PowerSync web SDK. Sync Postgres, MongoDB or MySQL with SQLite in your web app",
     "main": "lib/src/index.js",
     "types": "lib/src/index.d.ts",
@@ -61,7 +61,7 @@
     "license": "Apache-2.0",
     "peerDependencies": {
         "@journeyapps/wa-sqlite": "^1.2.4",
-        "@powersync/common": "workspace:^1.31.1"
+        "@powersync/common": "workspace:^1.32.0"
     },
     "dependencies": {
         "@powersync/common": "workspace:*",

package/lib/src/db/PowerSyncDatabase.d.ts

@@ -1,4 +1,4 @@
-import { type BucketStorageAdapter, type PowerSyncBackendConnector, type PowerSyncCloseOptions, type PowerSyncConnectionOptions, type RequiredAdditionalConnectionOptions, AbstractPowerSyncDatabase, DBAdapter, PowerSyncDatabaseOptions, PowerSyncDatabaseOptionsWithDBAdapter, PowerSyncDatabaseOptionsWithOpenFactory, PowerSyncDatabaseOptionsWithSettings, StreamingSyncImplementation } from '@powersync/common';
+import { type BucketStorageAdapter, type PowerSyncBackendConnector, type PowerSyncCloseOptions, type RequiredAdditionalConnectionOptions, AbstractPowerSyncDatabase, DBAdapter, PowerSyncDatabaseOptions, PowerSyncDatabaseOptionsWithDBAdapter, PowerSyncDatabaseOptionsWithOpenFactory, PowerSyncDatabaseOptionsWithSettings, StreamingSyncImplementation } from '@powersync/common';
 import { Mutex } from 'async-mutex';
 import { ResolvedWebSQLOpenOptions, WebSQLFlags } from './adapters/web-sql-flags';
 export interface WebPowerSyncFlags extends WebSQLFlags {
@@ -69,7 +69,6 @@ export declare class PowerSyncDatabase extends AbstractPowerSyncDatabase {
      * multiple tabs are not enabled.
      */
     close(options?: PowerSyncCloseOptions): Promise<void>;
-    connect(connector: PowerSyncBackendConnector, options?: PowerSyncConnectionOptions): Promise<void>;
     protected generateBucketStorageAdapter(): BucketStorageAdapter;
     protected runExclusive<T>(cb: () => Promise<T>): Promise<any>;
     protected generateSyncStreamImplementation(connector: PowerSyncBackendConnector, options: RequiredAdditionalConnectionOptions): StreamingSyncImplementation;

package/lib/src/db/PowerSyncDatabase.js

@@ -81,21 +81,10 @@ export class PowerSyncDatabase extends AbstractPowerSyncDatabase {
             disconnect: options.disconnect ?? !this.resolvedFlags.enableMultiTabs
         });
     }
-    connect(connector, options) {
-        /**
-         * Using React strict mode might cause calls to connect to fire multiple times
-         * Connect is wrapped inside a lock in order to prevent race conditions internally between multiple
-         * connection attempts.
-         */
-        return this.runExclusive(() => {
-            this.options.logger?.debug('Attempting to connect to PowerSync instance');
-            return super.connect(connector, options);
-        });
-    }
     generateBucketStorageAdapter() {
         return new SqliteBucketStorage(this.database, AbstractPowerSyncDatabase.transactionMutex);
     }
-    runExclusive(cb) {
+    async runExclusive(cb) {
         if (this.resolvedFlags.ssrMode) {
             return PowerSyncDatabase.SHARED_MUTEX.runExclusive(cb);
         }

package/lib/src/db/sync/SharedWebStreamingSyncImplementation.js

@@ -153,9 +153,6 @@ export class SharedWebStreamingSyncImplementation extends WebStreamingSyncImplem
      */
     async connect(options) {
         await this.waitForReady();
-        // This is needed since a new tab won't have any reference to the
-        // shared worker sync implementation since that is only created on the first call to `connect`.
-        await this.disconnect();
         return this.syncManager.connect(options);
     }
     async disconnect() {
@@ -171,12 +168,21 @@ export class SharedWebStreamingSyncImplementation extends WebStreamingSyncImplem
     }
     async dispose() {
         await this.waitForReady();
-        // Signal the shared worker that this client is closing its connection to the worker
-        const closeMessagePayload = {
-            event: SharedSyncClientEvent.CLOSE_CLIENT,
-            data: {}
-        };
-        this.messagePort.postMessage(closeMessagePayload);
+        await new Promise((resolve) => {
+            // Listen for the close acknowledgment from the worker
+            this.messagePort.addEventListener('message', (event) => {
+                const payload = event.data;
+                if (payload?.event === SharedSyncClientEvent.CLOSE_ACK) {
+                    resolve();
+                }
+            });
+            // Signal the shared worker that this client is closing its connection to the worker
+            const closeMessagePayload = {
+                event: SharedSyncClientEvent.CLOSE_CLIENT,
+                data: {}
+            };
+            this.messagePort.postMessage(closeMessagePayload);
+        });
         // Release the proxy
         this.syncManager[Comlink.releaseProxy]();
         this.messagePort.close();

package/lib/src/worker/sync/SharedSyncImplementation.d.ts

@@ -1,9 +1,11 @@
-import { type AbstractStreamingSyncImplementation, type ILogger, type ILogLevel, type LockOptions, type PowerSyncConnectionOptions, type StreamingSyncImplementation, type StreamingSyncImplementationListener, type SyncStatusOptions, BaseObserver, DBAdapter, SyncStatus } from '@powersync/common';
+import { type ILogger, type ILogLevel, type PowerSyncConnectionOptions, type StreamingSyncImplementation, type StreamingSyncImplementationListener, type SyncStatusOptions, BaseObserver, ConnectionManager, DBAdapter, SyncStatus } from '@powersync/common';
+import { Mutex } from 'async-mutex';
 import * as Comlink from 'comlink';
 import { WebStreamingSyncImplementation, WebStreamingSyncImplementationOptions } from '../../db/sync/WebStreamingSyncImplementation';
 import { ResolvedWebSQLOpenOptions } from '../../db/adapters/web-sql-flags';
 import { AbstractSharedSyncClientProvider } from './AbstractSharedSyncClientProvider';
 /**
+ * @internal
  * Manual message events for shared sync clients
  */
 export declare enum SharedSyncClientEvent {
@@ -11,8 +13,12 @@ export declare enum SharedSyncClientEvent {
      * This client requests the shared sync manager should
      * close it's connection to the client.
      */
-    CLOSE_CLIENT = "close-client"
+    CLOSE_CLIENT = "close-client",
+    CLOSE_ACK = "close-ack"
 }
+/**
+ * @internal
+ */
 export type ManualSharedSyncPayload = {
     event: SharedSyncClientEvent;
     data: any;
@@ -51,7 +57,6 @@ export type RemoteOperationAbortController = {
  */
 export declare class SharedSyncImplementation extends BaseObserver<SharedSyncImplementationListener> implements StreamingSyncImplementation {
     protected ports: WrappedSyncPort[];
-    protected syncStreamClient: AbstractStreamingSyncImplementation | null;
     protected isInitialized: Promise<void>;
     protected statusListener?: () => void;
     protected fetchCredentialsController?: RemoteOperationAbortController;
@@ -60,41 +65,43 @@ export declare class SharedSyncImplementation extends BaseObserver<SharedSyncImp
     protected syncParams: SharedSyncInitOptions | null;
     protected logger: ILogger;
     protected lastConnectOptions: PowerSyncConnectionOptions | undefined;
+    protected portMutex: Mutex;
+    protected connectionManager: ConnectionManager;
     syncStatus: SyncStatus;
     broadCastLogger: ILogger;
     constructor();
-    waitForStatus(status: SyncStatusOptions): Promise<void>;
-    waitUntilStatusMatches(predicate: (status: SyncStatus) => boolean): Promise<void>;
     get lastSyncedAt(): Date | undefined;
     get isConnected(): boolean;
+    waitForStatus(status: SyncStatusOptions): Promise<void>;
+    waitUntilStatusMatches(predicate: (status: SyncStatus) => boolean): Promise<void>;
     waitForReady(): Promise<void>;
     setLogLevel(level: ILogLevel): void;
     /**
      * Configures the DBAdapter connection and a streaming sync client.
      */
     setParams(params: SharedSyncInitOptions): Promise<void>;
-    dispose(): Promise<void | undefined>;
+    dispose(): Promise<void>;
     /**
      * Connects to the PowerSync backend instance.
      * Multiple tabs can safely call this in their initialization.
      * The connection will simply be reconnected whenever a new tab
      * connects.
      */
-    connect(options?: PowerSyncConnectionOptions): Promise<any>;
-    disconnect(): Promise<any>;
+    connect(options?: PowerSyncConnectionOptions): Promise<void>;
+    disconnect(): Promise<void>;
     /**
      * Adds a new client tab's message port to the list of connected ports
      */
-    addPort(port: MessagePort): void;
+    addPort(port: MessagePort): Promise<void>;
     /**
      * Removes a message port client from this manager's managed
      * clients.
      */
-    removePort(port: MessagePort): Promise<void>;
+    removePort(port: MessagePort): Promise<() => void>;
     triggerCrudUpload(): void;
-    obtainLock<T>(lockOptions: LockOptions<T>): Promise<T>;
     hasCompletedSync(): Promise<boolean>;
     getWriteCheckpoint(): Promise<string>;
+    protected withSyncImplementation<T>(callback: (sync: StreamingSyncImplementation) => Promise<T>): Promise<T>;
     protected generateStreamingImplementation(): WebStreamingSyncImplementation;
     protected openInternalDB(): Promise<void>;
     /**

package/lib/src/worker/sync/SharedSyncImplementation.js

@@ -1,13 +1,13 @@
-import { AbortOperation, BaseObserver, createLogger, SqliteBucketStorage, SyncStatus } from '@powersync/common';
+import { AbortOperation, BaseObserver, ConnectionManager, createLogger, SqliteBucketStorage, SyncStatus } from '@powersync/common';
 import { Mutex } from 'async-mutex';
 import * as Comlink from 'comlink';
 import { WebRemote } from '../../db/sync/WebRemote';
 import { WebStreamingSyncImplementation } from '../../db/sync/WebStreamingSyncImplementation';
 import { LockedAsyncDatabaseAdapter } from '../../db/adapters/LockedAsyncDatabaseAdapter';
 import { WorkerWrappedAsyncDatabaseConnection } from '../../db/adapters/WorkerWrappedAsyncDatabaseConnection';
-import { getNavigatorLocks } from '../../shared/navigator';
 import { BroadcastLogger } from './BroadcastLogger';
 /**
+ * @internal
  * Manual message events for shared sync clients
  */
 export var SharedSyncClientEvent;
@@ -17,14 +17,20 @@ export var SharedSyncClientEvent;
      * close it's connection to the client.
      */
     SharedSyncClientEvent["CLOSE_CLIENT"] = "close-client";
+    SharedSyncClientEvent["CLOSE_ACK"] = "close-ack";
 })(SharedSyncClientEvent || (SharedSyncClientEvent = {}));
+/**
+ * HACK: The shared implementation wraps and provides its own
+ * PowerSyncBackendConnector when generating the streaming sync implementation.
+ * We provide this unused placeholder when connecting with the ConnectionManager.
+ */
+const CONNECTOR_PLACEHOLDER = {};
 /**
  * @internal
  * Shared sync implementation which runs inside a shared webworker
  */
 export class SharedSyncImplementation extends BaseObserver {
     ports;
-    syncStreamClient;
     isInitialized;
     statusListener;
     fetchCredentialsController;
@@ -33,6 +39,8 @@ export class SharedSyncImplementation extends BaseObserver {
     syncParams;
     logger;
     lastConnectOptions;
+    portMutex;
+    connectionManager;
     syncStatus;
     broadCastLogger;
     constructor() {
@@ -40,9 +48,9 @@ export class SharedSyncImplementation extends BaseObserver {
         this.ports = [];
         this.dbAdapter = null;
         this.syncParams = null;
-        this.syncStreamClient = null;
         this.logger = createLogger('shared-sync');
         this.lastConnectOptions = undefined;
+        this.portMutex = new Mutex();
         this.isInitialized = new Promise((resolve) => {
             const callback = this.registerListener({
                 initialized: () => {
@@ -53,20 +61,43 @@ export class SharedSyncImplementation extends BaseObserver {
         });
         this.syncStatus = new SyncStatus({});
         this.broadCastLogger = new BroadcastLogger(this.ports);
-    }
-    async waitForStatus(status) {
-        await this.waitForReady();
-        return this.syncStreamClient.waitForStatus(status);
-    }
-    async waitUntilStatusMatches(predicate) {
-        await this.waitForReady();
-        return this.syncStreamClient.waitUntilStatusMatches(predicate);
+        this.connectionManager = new ConnectionManager({
+            createSyncImplementation: async () => {
+                return this.portMutex.runExclusive(async () => {
+                    await this.waitForReady();
+                    if (!this.dbAdapter) {
+                        await this.openInternalDB();
+                    }
+                    const sync = this.generateStreamingImplementation();
+                    const onDispose = sync.registerListener({
+                        statusChanged: (status) => {
+                            this.updateAllStatuses(status.toJSON());
+                        }
+                    });
+                    return {
+                        sync,
+                        onDispose
+                    };
+                });
+            },
+            logger: this.logger
+        });
     }
     get lastSyncedAt() {
-        return this.syncStreamClient?.lastSyncedAt;
+        return this.connectionManager.syncStreamImplementation?.lastSyncedAt;
     }
     get isConnected() {
-        return this.syncStreamClient?.isConnected ?? false;
+        return this.connectionManager.syncStreamImplementation?.isConnected ?? false;
+    }
+    async waitForStatus(status) {
+        return this.withSyncImplementation(async (sync) => {
+            return sync.waitForStatus(status);
+        });
+    }
+    async waitUntilStatusMatches(predicate) {
+        return this.withSyncImplementation(async (sync) => {
+            return sync.waitUntilStatusMatches(predicate);
+        });
     }
     async waitForReady() {
         return this.isInitialized;
@@ -79,25 +110,34 @@ export class SharedSyncImplementation extends BaseObserver {
      * Configures the DBAdapter connection and a streaming sync client.
      */
     async setParams(params) {
-        if (this.syncParams) {
-            // Cannot modify already existing sync implementation
-            return;
-        }
-        this.syncParams = params;
-        if (params.streamOptions?.flags?.broadcastLogs) {
-            this.logger = this.broadCastLogger;
-        }
-        self.onerror = (event) => {
-            // Share any uncaught events on the broadcast logger
-            this.logger.error('Uncaught exception in PowerSync shared sync worker', event);
-        };
-        await this.openInternalDB();
-        this.iterateListeners((l) => l.initialized?.());
+        await this.portMutex.runExclusive(async () => {
+            if (this.syncParams) {
+                // Cannot modify already existing sync implementation params
+                // But we can ask for a DB adapter, if required, at this point.
+                if (!this.dbAdapter) {
+                    await this.openInternalDB();
+                }
+                return;
+            }
+            // First time setting params
+            this.syncParams = params;
+            if (params.streamOptions?.flags?.broadcastLogs) {
+                this.logger = this.broadCastLogger;
+            }
+            self.onerror = (event) => {
+                // Share any uncaught events on the broadcast logger
+                this.logger.error('Uncaught exception in PowerSync shared sync worker', event);
+            };
+            if (!this.dbAdapter) {
+                await this.openInternalDB();
+            }
+            this.iterateListeners((l) => l.initialized?.());
+        });
     }
     async dispose() {
         await this.waitForReady();
         this.statusListener?.();
-        return this.syncStreamClient?.dispose();
+        return this.connectionManager.close();
     }
     /**
      * Connects to the PowerSync backend instance.
@@ -106,99 +146,110 @@ export class SharedSyncImplementation extends BaseObserver {
      * connects.
      */
     async connect(options) {
-        await this.waitForReady();
-        // This effectively queues connect and disconnect calls. Ensuring multiple tabs' requests are synchronized
-        return getNavigatorLocks().request('shared-sync-connect', async () => {
-            if (!this.dbAdapter) {
-                await this.openInternalDB();
-            }
-            this.syncStreamClient = this.generateStreamingImplementation();
-            this.lastConnectOptions = options;
-            this.syncStreamClient.registerListener({
-                statusChanged: (status) => {
-                    this.updateAllStatuses(status.toJSON());
-                }
-            });
-            await this.syncStreamClient.connect(options);
-        });
+        this.lastConnectOptions = options;
+        return this.connectionManager.connect(CONNECTOR_PLACEHOLDER, options);
     }
     async disconnect() {
-        await this.waitForReady();
-        // This effectively queues connect and disconnect calls. Ensuring multiple tabs' requests are synchronized
-        return getNavigatorLocks().request('shared-sync-connect', async () => {
-            await this.syncStreamClient?.disconnect();
-            await this.syncStreamClient?.dispose();
-            this.syncStreamClient = null;
-        });
+        return this.connectionManager.disconnect();
     }
     /**
      * Adds a new client tab's message port to the list of connected ports
      */
-    addPort(port) {
-        const portProvider = {
-            port,
-            clientProvider: Comlink.wrap(port)
-        };
-        this.ports.push(portProvider);
-        // Give the newly connected client the latest status
-        const status = this.syncStreamClient?.syncStatus;
-        if (status) {
-            portProvider.clientProvider.statusChanged(status.toJSON());
-        }
+    async addPort(port) {
+        await this.portMutex.runExclusive(() => {
+            const portProvider = {
+                port,
+                clientProvider: Comlink.wrap(port)
+            };
+            this.ports.push(portProvider);
+            // Give the newly connected client the latest status
+            const status = this.connectionManager.syncStreamImplementation?.syncStatus;
+            if (status) {
+                portProvider.clientProvider.statusChanged(status.toJSON());
+            }
+        });
     }
     /**
      * Removes a message port client from this manager's managed
      * clients.
      */
     async removePort(port) {
-        const index = this.ports.findIndex((p) => p.port == port);
-        if (index < 0) {
-            this.logger.warn(`Could not remove port ${port} since it is not present in active ports.`);
-            return;
-        }
-        const trackedPort = this.ports[index];
-        // Remove from the list of active ports
-        this.ports.splice(index, 1);
-        /**
-         * The port might currently be in use. Any active functions might
-         * not resolve. Abort them here.
-         */
-        [this.fetchCredentialsController, this.uploadDataController].forEach((abortController) => {
-            if (abortController?.activePort.port == port) {
-                abortController.controller.abort(new AbortOperation('Closing pending requests after client port is removed'));
+        // Remove the port within a mutex context.
+        // Warns if the port is not found. This should not happen in practice.
+        // We return early if the port is not found.
+        const { trackedPort, shouldReconnect } = await this.portMutex.runExclusive(async () => {
+            const index = this.ports.findIndex((p) => p.port == port);
+            if (index < 0) {
+                this.logger.warn(`Could not remove port ${port} since it is not present in active ports.`);
+                return {};
             }
+            const trackedPort = this.ports[index];
+            // Remove from the list of active ports
+            this.ports.splice(index, 1);
+            /**
+             * The port might currently be in use. Any active functions might
+             * not resolve. Abort them here.
+             */
+            [this.fetchCredentialsController, this.uploadDataController].forEach((abortController) => {
+                if (abortController?.activePort.port == port) {
+                    abortController.controller.abort(new AbortOperation('Closing pending requests after client port is removed'));
+                }
+            });
+            const shouldReconnect = !!this.connectionManager.syncStreamImplementation && this.ports.length > 0;
+            return {
+                shouldReconnect,
+                trackedPort
+            };
         });
-        const shouldReconnect = !!this.syncStreamClient;
+        if (!trackedPort) {
+            // We could not find the port to remove
+            return () => { };
+        }
         if (this.dbAdapter && this.dbAdapter == trackedPort.db) {
             if (shouldReconnect) {
-                await this.disconnect();
+                await this.connectionManager.disconnect();
             }
             // Clearing the adapter will result in a new one being opened in connect
             this.dbAdapter = null;
             if (shouldReconnect) {
-                await this.connect(this.lastConnectOptions);
+                await this.connectionManager.connect(CONNECTOR_PLACEHOLDER, this.lastConnectOptions);
             }
         }
         if (trackedPort.db) {
-            trackedPort.db.close();
+            await trackedPort.db.close();
         }
         // Release proxy
-        trackedPort.clientProvider[Comlink.releaseProxy]();
+        return () => trackedPort.clientProvider[Comlink.releaseProxy]();
     }
     triggerCrudUpload() {
-        this.waitForReady().then(() => this.syncStreamClient?.triggerCrudUpload());
-    }
-    async obtainLock(lockOptions) {
-        await this.waitForReady();
-        return this.syncStreamClient.obtainLock(lockOptions);
+        this.withSyncImplementation(async (sync) => {
+            sync.triggerCrudUpload();
+        });
     }
     async hasCompletedSync() {
-        await this.waitForReady();
-        return this.syncStreamClient.hasCompletedSync();
+        return this.withSyncImplementation(async (sync) => {
+            return sync.hasCompletedSync();
+        });
     }
     async getWriteCheckpoint() {
+        return this.withSyncImplementation(async (sync) => {
+            return sync.getWriteCheckpoint();
+        });
+    }
+    async withSyncImplementation(callback) {
         await this.waitForReady();
-        return this.syncStreamClient.getWriteCheckpoint();
+        if (this.connectionManager.syncStreamImplementation) {
+            return callback(this.connectionManager.syncStreamImplementation);
+        }
+        const sync = await new Promise((resolve) => {
+            const dispose = this.connectionManager.registerListener({
+                syncStreamCreated: (sync) => {
+                    resolve(sync);
+                    dispose?.();
+                }
+            });
+        });
+        return callback(sync);
     }
     generateStreamingImplementation() {
         // This should only be called after initialization has completed
@@ -301,13 +352,13 @@ export class SharedSyncImplementation extends BaseObserver {
      * A function only used for unit tests which updates the internal
      * sync stream client and all tab client's sync status
      */
-    _testUpdateAllStatuses(status) {
-        if (!this.syncStreamClient) {
+    async _testUpdateAllStatuses(status) {
+        if (!this.connectionManager.syncStreamImplementation) {
             // This is just for testing purposes
-            this.syncStreamClient = this.generateStreamingImplementation();
+            this.connectionManager.syncStreamImplementation = this.generateStreamingImplementation();
         }
         // Only assigning, don't call listeners for this test
-        this.syncStreamClient.syncStatus = new SyncStatus(status);
+        this.connectionManager.syncStreamImplementation.syncStatus = new SyncStatus(status);
         this.updateAllStatuses(status);
     }
 }

package/lib/src/worker/sync/SharedSyncImplementation.worker.js

@@ -1,22 +1,27 @@
-import * as Comlink from 'comlink';
-import { SharedSyncImplementation, SharedSyncClientEvent } from './SharedSyncImplementation';
 import { createBaseLogger } from '@powersync/common';
+import * as Comlink from 'comlink';
+import { SharedSyncClientEvent, SharedSyncImplementation } from './SharedSyncImplementation';
 const _self = self;
 const logger = createBaseLogger();
 logger.useDefaults();
 const sharedSyncImplementation = new SharedSyncImplementation();
-_self.onconnect = function (event) {
+_self.onconnect = async function (event) {
     const port = event.ports[0];
     /**
      * Adds an extra listener which can remove this port
      * from the list of monitored ports.
      */
-    port.addEventListener('message', (event) => {
+    port.addEventListener('message', async (event) => {
         const payload = event.data;
         if (payload?.event == SharedSyncClientEvent.CLOSE_CLIENT) {
-            sharedSyncImplementation.removePort(port);
+            const release = await sharedSyncImplementation.removePort(port);
+            port.postMessage({
+                event: SharedSyncClientEvent.CLOSE_ACK,
+                data: {}
+            });
+            release?.();
         }
     });
+    await sharedSyncImplementation.addPort(port);
     Comlink.expose(sharedSyncImplementation, port);
-    sharedSyncImplementation.addPort(port);
 };