@powersync/web 0.0.0-dev-20251111122755 → 0.0.0-dev-20251119142638

package/lib/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@powersync/web",
-    "version": "1.28.0",
+    "version": "1.28.2",
     "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",
@@ -62,7 +62,7 @@
     "license": "Apache-2.0",
     "peerDependencies": {
         "@journeyapps/wa-sqlite": "^1.3.2",
-        "@powersync/common": "workspace:^1.41.0"
+        "@powersync/common": "workspace:^1.42.0"
     },
     "dependencies": {
         "@powersync/common": "workspace:*",

package/lib/src/db/adapters/AsyncDatabaseConnection.d.ts

@@ -22,6 +22,8 @@ export type OnTableChangeCallback = (event: BatchedUpdateNotification) => void;
 export interface AsyncDatabaseConnection<Config extends ResolvedWebSQLOpenOptions = ResolvedWebSQLOpenOptions> {
     init(): Promise<void>;
     close(): Promise<void>;
+    markHold(): Promise<string>;
+    releaseHold(holdId: string): Promise<void>;
     execute(sql: string, params?: any[]): Promise<ProxiedQueryResult>;
     executeRaw(sql: string, params?: any[]): Promise<any[][]>;
     executeBatch(sql: string, params?: any[]): Promise<ProxiedQueryResult>;

package/lib/src/db/adapters/LockedAsyncDatabaseAdapter.d.ts

@@ -1,4 +1,4 @@
-import { type ILogger, BaseObserver, DBAdapterListener, DBLockOptions, LockContext, QueryResult, Transaction } from '@powersync/common';
+import { BaseObserver, DBAdapterListener, DBLockOptions, LockContext, QueryResult, Transaction, type ILogger } from '@powersync/common';
 import { AsyncDatabaseConnection } from './AsyncDatabaseConnection';
 import { SharedConnectionWorker, WebDBAdapter } from './WebDBAdapter';
 import { ResolvedWebSQLOpenOptions } from './web-sql-flags';

package/lib/src/db/adapters/LockedAsyncDatabaseAdapter.js

@@ -160,12 +160,18 @@ export class LockedAsyncDatabaseAdapter extends BaseObserver {
                 this.pendingAbortControllers.delete(abortController);
             }, timeoutMs)
             : null;
-        return getNavigatorLocks().request(`db-lock-${this._dbIdentifier}`, { signal: abortController.signal }, () => {
+        return getNavigatorLocks().request(`db-lock-${this._dbIdentifier}`, { signal: abortController.signal }, async () => {
             this.pendingAbortControllers.delete(abortController);
             if (timoutId) {
                 clearTimeout(timoutId);
             }
-            return callback();
+            const holdId = await this.baseDB.markHold();
+            try {
+                return await callback();
+            }
+            finally {
+                await this.baseDB.releaseHold(holdId);
+            }
         });
     }
     async readTransaction(fn, options) {

package/lib/src/db/adapters/WorkerWrappedAsyncDatabaseConnection.d.ts

@@ -34,6 +34,8 @@ export declare class WorkerWrappedAsyncDatabaseConnection<Config extends Resolve
      * throw on all outstanding promises and forbid new calls.
      */
     markRemoteClosed(): void;
+    markHold(): Promise<string>;
+    releaseHold(holdId: string): Promise<void>;
     private withRemote;
     /**
      * Get a MessagePort which can be used to share the internals of this connection.

package/lib/src/db/adapters/WorkerWrappedAsyncDatabaseConnection.js

@@ -31,6 +31,12 @@ export class WorkerWrappedAsyncDatabaseConnection {
         // set.
         this.notifyRemoteClosed.abort();
     }
+    markHold() {
+        return this.baseConnection.markHold();
+    }
+    releaseHold(holdId) {
+        return this.baseConnection.releaseHold(holdId);
+    }
     withRemote(workerPromise) {
         const controller = this.notifyRemoteClosed;
         if (controller) {

package/lib/src/db/adapters/wa-sqlite/WASQLiteConnection.d.ts

@@ -23,6 +23,14 @@ export type WASQLiteBroadCastTableUpdateEvent = {
  */
 export type WASQLiteConnectionListener = {
     tablesUpdated: (event: BatchedUpdateNotification) => void;
+    /**
+     * Triggered when an active hold is overwritten by a new hold.
+     * This is most likely to happen when a shared connection has been closed
+     * without releasing the hold.
+     * This listener can be used to cleanup any resources associated with the previous hold.
+     * @param holdId - The id of the hold that has been overwritten.
+     */
+    holdOverwritten: (holdId: string) => Promise<void>;
 };
 /**
  * @internal
@@ -94,9 +102,18 @@ export declare class WASqliteConnection extends BaseObserver<WASQLiteConnectionL
      * notification loops.
      */
     protected connectionId: number;
+    protected _holdCounter: number;
+    protected _holdId: string | null;
     constructor(options: ResolvedWASQLiteOpenFactoryOptions);
+    /**
+     * Gets the id for the current hold.
+     * This can be used to check for invalid states.
+     */
+    get currentHoldId(): string | null;
     protected get sqliteAPI(): SQLiteAPI;
     protected get dbP(): number;
+    markHold(): Promise<string>;
+    releaseHold(holdId: string): Promise<void>;
     protected openDB(): Promise<number>;
     protected executeEncryptionPragma(): Promise<void>;
     protected openSQLiteAPI(): Promise<SQLiteAPI>;

package/lib/src/db/adapters/wa-sqlite/WASQLiteConnection.js

@@ -107,6 +107,8 @@ export class WASqliteConnection extends BaseObserver {
      * notification loops.
      */
     connectionId;
+    _holdCounter;
+    _holdId;
     constructor(options) {
         super();
         this.options = options;
@@ -116,6 +118,15 @@ export class WASqliteConnection extends BaseObserver {
         this.connectionId = new Date().valueOf() + Math.random();
         this.statementMutex = new Mutex();
         this._moduleFactory = DEFAULT_MODULE_FACTORIES[this.options.vfs];
+        this._holdCounter = 0;
+        this._holdId = null;
+    }
+    /**
+     * Gets the id for the current hold.
+     * This can be used to check for invalid states.
+     */
+    get currentHoldId() {
+        return this._holdId;
     }
     get sqliteAPI() {
         if (!this._sqliteAPI) {
@@ -129,6 +140,20 @@ export class WASqliteConnection extends BaseObserver {
         }
         return this._dbP;
     }
+    async markHold() {
+        const previousHoldId = this._holdId;
+        this._holdId = `${++this._holdCounter}`;
+        if (previousHoldId) {
+            await this.iterateAsyncListeners(async (cb) => cb.holdOverwritten?.(previousHoldId));
+        }
+        return this._holdId;
+    }
+    async releaseHold(holdId) {
+        if (holdId != this._holdId) {
+            throw new Error(`Invalid hold state, expected ${this._holdId} but got ${holdId}`);
+        }
+        this._holdId = null;
+    }
     async openDB() {
         this._dbP = await this.sqliteAPI.open_v2(this.options.dbFilename);
         return this._dbP;

package/lib/src/worker/db/SharedWASQLiteConnection.d.ts

@@ -0,0 +1,41 @@
+import { ILogger } from '@powersync/common';
+import { AsyncDatabaseConnection, OnTableChangeCallback, ProxiedQueryResult } from '../../db/adapters/AsyncDatabaseConnection';
+import { ResolvedWebSQLOpenOptions } from '../../db/adapters/web-sql-flags';
+/**
+ * Keeps track of open DB connections and the clients which
+ * are using it.
+ */
+export type SharedDBWorkerConnection = {
+    clientIds: Set<number>;
+    db: AsyncDatabaseConnection;
+};
+export type SharedWASQLiteConnectionOptions = {
+    dbMap: Map<string, SharedDBWorkerConnection>;
+    dbFilename: string;
+    clientId: number;
+    logger: ILogger;
+};
+export declare class SharedWASQLiteConnection implements AsyncDatabaseConnection {
+    protected options: SharedWASQLiteConnectionOptions;
+    protected isClosing: boolean;
+    protected activeHoldId: string | null;
+    constructor(options: SharedWASQLiteConnectionOptions);
+    init(): Promise<void>;
+    markHold(): Promise<string>;
+    releaseHold(id: string): Promise<void>;
+    protected get logger(): ILogger;
+    protected get dbEntry(): SharedDBWorkerConnection;
+    protected get connection(): AsyncDatabaseConnection<ResolvedWebSQLOpenOptions>;
+    protected get clientIds(): Set<number>;
+    /**
+     * Handles closing of a shared connection.
+     * The connection is only closed if there are no active clients using it.
+     */
+    close(): Promise<void>;
+    protected withClosing<T>(action: () => Promise<T>): Promise<T>;
+    execute(sql: string, params?: any[]): Promise<ProxiedQueryResult>;
+    executeRaw(sql: string, params?: any[]): Promise<any[][]>;
+    executeBatch(sql: string, params?: any[] | undefined): Promise<ProxiedQueryResult>;
+    registerOnTableChange(callback: OnTableChangeCallback): Promise<() => void>;
+    getConfig(): Promise<ResolvedWebSQLOpenOptions>;
+}

package/lib/src/worker/db/SharedWASQLiteConnection.js

@@ -0,0 +1,89 @@
+export class SharedWASQLiteConnection {
+    options;
+    isClosing;
+    // Keeps track if this current hold if the shared connection has a hold
+    activeHoldId;
+    constructor(options) {
+        this.options = options;
+        // Add this client ID to the set of known clients
+        this.clientIds.add(options.clientId);
+        this.isClosing = false;
+        this.activeHoldId = null;
+    }
+    async init() {
+        // No-op since the connection is already initialized when it was created
+    }
+    async markHold() {
+        this.activeHoldId = await this.connection.markHold();
+        return this.activeHoldId;
+    }
+    async releaseHold(id) {
+        try {
+            await this.connection.releaseHold(id);
+        }
+        finally {
+            this.activeHoldId = null;
+        }
+    }
+    get logger() {
+        return this.options.logger;
+    }
+    get dbEntry() {
+        return this.options.dbMap.get(this.options.dbFilename);
+    }
+    get connection() {
+        return this.dbEntry.db;
+    }
+    get clientIds() {
+        return this.dbEntry.clientIds;
+    }
+    /**
+     * Handles closing of a shared connection.
+     * The connection is only closed if there are no active clients using it.
+     */
+    async close() {
+        // This prevents further statements on this connection from being executed
+        this.isClosing = true;
+        const { clientIds, logger } = this;
+        const { clientId, dbFilename, dbMap } = this.options;
+        logger.debug(`Close requested from client ${clientId} of ${[...clientIds]}`);
+        clientIds.delete(clientId);
+        if (this.activeHoldId) {
+            /**
+             * The hold hasn't been released, but we're closing now.
+             * We can proactively cleanup and release the hold.
+             */
+            await this.connection.execute('ROLLBACK').catch(() => { });
+            await this.connection.releaseHold(this.activeHoldId).catch(() => { });
+        }
+        if (clientIds.size == 0) {
+            logger.debug(`Closing connection to ${this.options}.`);
+            const connection = this.connection;
+            dbMap.delete(dbFilename);
+            await connection.close();
+        }
+        logger.debug(`Connection to ${dbFilename} not closed yet due to active clients.`);
+        return;
+    }
+    async withClosing(action) {
+        if (this.isClosing) {
+            throw new Error('Connection is closing');
+        }
+        return action();
+    }
+    async execute(sql, params) {
+        return this.withClosing(() => this.connection.execute(sql, params));
+    }
+    async executeRaw(sql, params) {
+        return this.withClosing(() => this.connection.executeRaw(sql, params));
+    }
+    executeBatch(sql, params) {
+        return this.withClosing(() => this.connection.executeBatch(sql, params));
+    }
+    registerOnTableChange(callback) {
+        return this.connection.registerOnTableChange(callback);
+    }
+    getConfig() {
+        return this.connection.getConfig();
+    }
+}

package/lib/src/worker/db/WASQLiteDB.worker.js

@@ -4,29 +4,15 @@
 import '@journeyapps/wa-sqlite';
 import { createBaseLogger, createLogger } from '@powersync/common';
 import * as Comlink from 'comlink';
-import { WASqliteConnection } from '../../db/adapters/wa-sqlite/WASQLiteConnection';
 import { getNavigatorLocks } from '../../shared/navigator';
+import { SharedWASQLiteConnection } from './SharedWASQLiteConnection';
+import { WorkerWASQLiteConnection, proxyWASQLiteConnection } from './WorkerWASQLiteConnection';
 const baseLogger = createBaseLogger();
 baseLogger.useDefaults();
 const logger = createLogger('db-worker');
 const DBMap = new Map();
 const OPEN_DB_LOCK = 'open-wasqlite-db';
 let nextClientId = 1;
-const openWorkerConnection = async (options) => {
-    const connection = new WASqliteConnection(options);
-    return {
-        init: Comlink.proxy(() => connection.init()),
-        getConfig: Comlink.proxy(() => connection.getConfig()),
-        close: Comlink.proxy(() => connection.close()),
-        execute: Comlink.proxy(async (sql, params) => connection.execute(sql, params)),
-        executeRaw: Comlink.proxy(async (sql, params) => connection.executeRaw(sql, params)),
-        executeBatch: Comlink.proxy(async (sql, params) => connection.executeBatch(sql, params)),
-        registerOnTableChange: Comlink.proxy(async (callback) => {
-            // Proxy the callback remove function
-            return Comlink.proxy(await connection.registerOnTableChange(callback));
-        })
-    };
-};
 const openDBShared = async (options) => {
     // Prevent multiple simultaneous opens from causing race conditions
     return getNavigatorLocks().request(OPEN_DB_LOCK, async () => {
@@ -35,35 +21,32 @@ const openDBShared = async (options) => {
         logger.setLevel(logLevel);
         if (!DBMap.has(dbFilename)) {
             const clientIds = new Set();
-            const connection = await openWorkerConnection(options);
+            // This format returns proxy objects for function callbacks
+            const connection = new WorkerWASQLiteConnection(options);
             await connection.init();
+            connection.registerListener({
+                holdOverwritten: async () => {
+                    /**
+                     * The previous hold has been overwritten, without being released.
+                     * we need to cleanup any resources associated with it.
+                     * We can perform a rollback to release any potential transactions that were started.
+                     */
+                    await connection.execute('ROLLBACK').catch(() => { });
+                }
+            });
             DBMap.set(dbFilename, {
                 clientIds,
                 db: connection
             });
         }
-        const dbEntry = DBMap.get(dbFilename);
-        dbEntry.clientIds.add(clientId);
-        const { db } = dbEntry;
-        const wrappedConnection = {
-            ...db,
-            init: Comlink.proxy(async () => {
-                // the init has been done automatically
-            }),
-            close: Comlink.proxy(async () => {
-                const { clientIds } = dbEntry;
-                logger.debug(`Close requested from client ${clientId} of ${[...clientIds]}`);
-                clientIds.delete(clientId);
-                if (clientIds.size == 0) {
-                    logger.debug(`Closing connection to ${dbFilename}.`);
-                    DBMap.delete(dbFilename);
-                    return db.close?.();
-                }
-                logger.debug(`Connection to ${dbFilename} not closed yet due to active clients.`);
-                return;
-            })
-        };
-        return Comlink.proxy(wrappedConnection);
+        // Associates this clientId with the shared connection entry
+        const sharedConnection = new SharedWASQLiteConnection({
+            dbMap: DBMap,
+            dbFilename,
+            clientId,
+            logger
+        });
+        return proxyWASQLiteConnection(sharedConnection);
     });
 };
 // Check if we're in a SharedWorker context

package/lib/src/worker/db/WorkerWASQLiteConnection.d.ts

@@ -0,0 +1,9 @@
+import { AsyncDatabaseConnection, OnTableChangeCallback } from '../../db/adapters/AsyncDatabaseConnection';
+import { WASqliteConnection } from '../../db/adapters/wa-sqlite/WASQLiteConnection';
+/**
+ * Fully proxies a WASQLiteConnection to be used as an AsyncDatabaseConnection.
+ */
+export declare function proxyWASQLiteConnection(connection: AsyncDatabaseConnection): AsyncDatabaseConnection;
+export declare class WorkerWASQLiteConnection extends WASqliteConnection {
+    registerOnTableChange(callback: OnTableChangeCallback): Promise<() => void>;
+}

package/lib/src/worker/db/WorkerWASQLiteConnection.js

@@ -0,0 +1,24 @@
+import * as Comlink from 'comlink';
+import { WASqliteConnection } from '../../db/adapters/wa-sqlite/WASQLiteConnection';
+/**
+ * Fully proxies a WASQLiteConnection to be used as an AsyncDatabaseConnection.
+ */
+export function proxyWASQLiteConnection(connection) {
+    return Comlink.proxy({
+        init: Comlink.proxy(() => connection.init()),
+        close: Comlink.proxy(() => connection.close()),
+        markHold: Comlink.proxy(() => connection.markHold()),
+        releaseHold: Comlink.proxy((holdId) => connection.releaseHold(holdId)),
+        execute: Comlink.proxy((sql, params) => connection.execute(sql, params)),
+        executeRaw: Comlink.proxy((sql, params) => connection.executeRaw(sql, params)),
+        executeBatch: Comlink.proxy((sql, params) => connection.executeBatch(sql, params)),
+        registerOnTableChange: Comlink.proxy((callback) => connection.registerOnTableChange(callback)),
+        getConfig: Comlink.proxy(() => connection.getConfig())
+    });
+}
+export class WorkerWASQLiteConnection extends WASqliteConnection {
+    async registerOnTableChange(callback) {
+        // Proxy the callback remove function
+        return Comlink.proxy(await super.registerOnTableChange(callback));
+    }
+}