@powersync/web 0.0.0-dev-20260311103504 → 0.0.0-dev-20260503073249

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@powersync/web",
-  "version": "0.0.0-dev-20260311103504",
+  "version": "0.0.0-dev-20260503073249",
   "description": "PowerSync Web SDK",
   "main": "lib/src/index.js",
   "module": "lib/src/index.js",
@@ -52,21 +52,20 @@
     "real-time data stream",
     "live data"
   ],
-  "author": "JOURNEYAPPS",
+  "author": "PowerSync",
   "license": "Apache-2.0",
   "peerDependencies": {
     "@journeyapps/wa-sqlite": "^1.5.0",
-    "@powersync/common": "0.0.0-dev-20260311103504"
+    "@powersync/common": "0.0.0-dev-20260503073249"
   },
   "dependencies": {
-    "async-mutex": "^0.5.0",
     "bson": "^6.10.4",
     "comlink": "^4.4.2",
     "commander": "^12.1.0",
-    "@powersync/common": "0.0.0-dev-20260311103504"
+    "@powersync/common": "0.0.0-dev-20260503073249"
   },
   "devDependencies": {
-    "@journeyapps/wa-sqlite": "^1.5.0",
+    "@journeyapps/wa-sqlite": "^1.7.0",
     "@types/uuid": "^9.0.6",
     "crypto-browserify": "^3.12.0",
     "glob": "^11.0.0",

package/src/db/PowerSyncDatabase.ts

@@ -10,15 +10,14 @@ import {
   TriggerManagerConfig,
   isDBAdapter,
   isSQLOpenFactory,
+  Mutex,
   type BucketStorageAdapter,
   type PowerSyncBackendConnector,
   type PowerSyncCloseOptions,
   type RequiredAdditionalConnectionOptions
 } from '@powersync/common';
-import { Mutex } from 'async-mutex';
 import { getNavigatorLocks } from '../shared/navigator.js';
 import { NAVIGATOR_TRIGGER_CLAIM_MANAGER } from './NavigatorTriggerClaimManager.js';
-import { LockedAsyncDatabaseAdapter } from './adapters/LockedAsyncDatabaseAdapter.js';
 import { WebDBAdapter } from './adapters/WebDBAdapter.js';
 import { WASQLiteOpenFactory } from './adapters/wa-sqlite/WASQLiteOpenFactory.js';
 import {
@@ -35,9 +34,11 @@ import {
   WebStreamingSyncImplementation,
   WebStreamingSyncImplementationOptions
 } from './sync/WebStreamingSyncImplementation.js';
+import { AsyncDbAdapter } from './adapters/AsyncWebAdapter.js';
 
 export interface WebPowerSyncFlags extends WebSQLFlags {
   /**
+   * @deprecated This flag is no longer used. Navigator locks now handle tab detection automatically.
    * Externally unload open PowerSync database instances when the window closes.
    * Setting this to `true` requires calling `close` on all open PowerSyncDatabase
    * instances before the window unloads
@@ -127,7 +128,6 @@ function assertValidDatabaseOptions(options: WebPowerSyncDatabaseOptions): void
 export class PowerSyncDatabase extends AbstractPowerSyncDatabase {
   static SHARED_MUTEX = new Mutex();
 
-  protected unloadListener?: () => Promise<void>;
   protected resolvedFlags: WebPowerSyncFlags;
 
   constructor(options: WebPowerSyncDatabaseOptionsWithAdapter);
@@ -140,15 +140,10 @@ export class PowerSyncDatabase extends AbstractPowerSyncDatabase {
     assertValidDatabaseOptions(options);
 
     this.resolvedFlags = resolveWebPowerSyncFlags(options.flags);
-
-    if (this.resolvedFlags.enableMultiTabs && !this.resolvedFlags.externallyUnload) {
-      this.unloadListener = () => this.close({ disconnect: false });
-      window.addEventListener('unload', this.unloadListener);
-    }
   }
 
   async _initialize(): Promise<void> {
-    if (this.database instanceof LockedAsyncDatabaseAdapter) {
+    if (this.database instanceof AsyncDbAdapter) {
       /**
        * While init is done automatically,
        * LockedAsyncDatabaseAdapter only exposes config after init.
@@ -190,9 +185,6 @@ export class PowerSyncDatabase extends AbstractPowerSyncDatabase {
    * multiple tabs are not enabled.
    */
   close(options?: PowerSyncCloseOptions): Promise<void> {
-    if (this.unloadListener) {
-      window.removeEventListener('unload', this.unloadListener);
-    }
     return super.close({
       // Don't disconnect by default if multiple tabs are enabled
       disconnect: options?.disconnect ?? !this.resolvedFlags.enableMultiTabs

package/src/db/adapters/AsyncWebAdapter.ts

@@ -0,0 +1,207 @@
+import {
+  ConnectionPool,
+  DBAdapterDefaultMixin,
+  DBAdapterListener,
+  DBLockOptions,
+  LockContext,
+  Mutex,
+  Semaphore,
+  UnlockFn
+} from '@powersync/common';
+import { SharedConnectionWorker, WebDBAdapter, WebDBAdapterConfiguration } from './WebDBAdapter.js';
+import { DatabaseClient } from './wa-sqlite/DatabaseClient.js';
+
+type PendingListener = { listener: Partial<DBAdapterListener>; closeAfterRegisteredOnResolvedPool?: () => void };
+
+/**
+ * A connection pool implementation delegating to another pool opened asynchronnously.
+ */
+class AsyncConnectionPool implements ConnectionPool {
+  protected readonly state: Promise<PoolState>;
+  protected resolvedWriter?: DatabaseClient;
+
+  private readonly pendingListeners = new Set<PendingListener>();
+
+  constructor(
+    inner: Promise<PoolConnection>,
+    readonly name: string
+  ) {
+    this.state = inner.then((client) => {
+      for (const pending of this.pendingListeners) {
+        pending.closeAfterRegisteredOnResolvedPool = client.writer.registerListener(pending.listener);
+      }
+      this.pendingListeners.clear();
+
+      this.resolvedWriter = client.writer;
+      if (client.additionalReaders.length) {
+        return readWritePoolState(client.writer, client.additionalReaders);
+      }
+
+      return singleConnectionPoolState(client.writer);
+    });
+  }
+
+  async init() {
+    await this.state;
+  }
+
+  async close() {
+    const state = await this.state;
+    await state.close();
+  }
+
+  async readLock<T>(fn: (tx: LockContext) => Promise<T>, options?: DBLockOptions): Promise<T> {
+    const state = await this.state;
+    return state.withConnection(true, fn, options);
+  }
+
+  async writeLock<T>(fn: (tx: LockContext) => Promise<T>, options?: DBLockOptions): Promise<T> {
+    const state = await this.state;
+    return state.withConnection(false, fn, options);
+  }
+
+  async refreshSchema(): Promise<void> {
+    const state = await this.state;
+    await state.refreshSchema();
+  }
+
+  registerListener(listener: Partial<DBAdapterListener>): () => void {
+    if (this.resolvedWriter) {
+      return this.resolvedWriter.registerListener(listener);
+    } else {
+      const pending: PendingListener = { listener };
+      this.pendingListeners.add(pending);
+      return () => {
+        if (pending.closeAfterRegisteredOnResolvedPool) {
+          return pending.closeAfterRegisteredOnResolvedPool();
+        } else {
+          // Has not been registered yet, we can just remove the pending listener.
+          this.pendingListeners.delete(pending);
+        }
+      };
+    }
+  }
+}
+
+export interface PoolConnection {
+  writer: DatabaseClient;
+  additionalReaders: DatabaseClient[];
+}
+
+interface PoolState {
+  writer: DatabaseClient;
+  withConnection<T>(allowReadOnly: boolean, fn: (tx: LockContext) => Promise<T>, options?: DBLockOptions): Promise<T>;
+  close(): Promise<void>;
+  refreshSchema(): Promise<void>;
+}
+
+function singleConnectionPoolState(connection: DatabaseClient): PoolState {
+  return {
+    writer: connection,
+    withConnection: (allowReadOnly, fn, options) => {
+      if (allowReadOnly) {
+        return connection.readLock(fn, options);
+      } else {
+        return connection.writeLock(fn, options);
+      }
+    },
+    close: () => connection.close(),
+    refreshSchema: () => connection.refreshSchema()
+  };
+}
+
+function readWritePoolState(writer: DatabaseClient, readers: DatabaseClient[]): PoolState {
+  // DatabaseClients have locks internally, so these aren't necessary for correctness. However, our mutex and semaphore
+  // implementations are very cheap to cancel, which we use to dispatch reads to the first available connection (by
+  // simply requesting all of them and sticking with the first connection we get).
+  const writerMutex = new Mutex();
+  const readerSemaphore = new Semaphore(readers);
+
+  return {
+    writer,
+    async withConnection(allowReadOnly, fn, options) {
+      const abortController = new AbortController();
+      const abortSignal = abortController.signal;
+
+      let timeout: any = null;
+      let release: UnlockFn | undefined;
+      if (options?.timeoutMs) {
+        timeout = setTimeout(() => abortController.abort, options.timeoutMs);
+      }
+
+      try {
+        if (allowReadOnly) {
+          let connection: DatabaseClient;
+
+          // Even if we have a pool of read connections, it's typically very small and we assume that most queries are
+          // reads. So, we want to request any connection from the read pool and the dedicated write connection (which
+          // can also serve reads). We race for the first connection we can obtain this way, and then abort the other
+          // request.
+          [connection, release] = await new Promise<[DatabaseClient, UnlockFn]>((resolve, reject) => {
+            let didComplete = false;
+            function complete() {
+              didComplete = true;
+              abortController.abort();
+            }
+
+            function completeSuccess(connection: DatabaseClient, returnFn: UnlockFn) {
+              if (didComplete) {
+                // We're not going to use this connection, so return it immediately.
+                returnFn();
+              } else {
+                complete();
+                resolve([connection, returnFn]);
+              }
+            }
+
+            function completeError(error: unknown) {
+              // We either have a working connection already, or we've rejected the promise. Either way, we don't need
+              // to do either thing again.
+              if (didComplete) return;
+
+              complete();
+              reject(error);
+            }
+
+            writerMutex.acquire(abortSignal).then((unlock) => completeSuccess(writer, unlock), completeError);
+            readerSemaphore
+              .requestOne(abortSignal)
+              .then(({ item, release }) => completeSuccess(item, release), completeError);
+          });
+
+          return await connection.readLock(fn);
+        } else {
+          return await writerMutex.runExclusive(() => writer.writeLock(fn), abortSignal);
+        }
+      } finally {
+        if (timeout != null) {
+          clearTimeout(timeout);
+        }
+        release?.();
+      }
+    },
+    async close() {
+      await writer.close();
+      await Promise.all(readers.map((r) => r.close()));
+    },
+    async refreshSchema() {
+      await writer.refreshSchema();
+      await Promise.all(readers.map((r) => r.refreshSchema()));
+    }
+  };
+}
+
+export class AsyncDbAdapter extends DBAdapterDefaultMixin(AsyncConnectionPool) implements WebDBAdapter {
+  async shareConnection(): Promise<SharedConnectionWorker> {
+    const state = await this.state;
+    return state.writer.shareConnection();
+  }
+
+  getConfiguration(): WebDBAdapterConfiguration {
+    if (this.resolvedWriter) {
+      return this.resolvedWriter.getConfiguration();
+    }
+
+    throw new Error('AsyncDbAdapter.getConfiguration() can only be called after initializing it.');
+  }
+}

package/src/db/adapters/SSRDBAdapter.ts

@@ -5,11 +5,11 @@ import {
   DBLockOptions,
   LockContext,
   QueryResult,
-  Transaction
+  Transaction,
+  Mutex,
+  timeoutSignal
 } from '@powersync/common';
 
-import { Mutex } from 'async-mutex';
-
 const MOCK_QUERY_RESPONSE: QueryResult = {
   rowsAffected: 0
 };
@@ -34,19 +34,19 @@ export class SSRDBAdapter extends BaseObserver<DBAdapterListener> implements DBA
   close() {}
 
   async readLock<T>(fn: (tx: LockContext) => Promise<T>, options?: DBLockOptions) {
-    return this.readMutex.runExclusive(() => fn(this));
+    return this.readMutex.runExclusive(() => fn(this), timeoutSignal(options?.timeoutMs));
   }
 
   async readTransaction<T>(fn: (tx: Transaction) => Promise<T>, options?: DBLockOptions) {
-    return this.readLock(() => fn(this.generateMockTransactionContext()));
+    return this.readLock(() => fn(this.generateMockTransactionContext()), options);
   }
 
   async writeLock<T>(fn: (tx: LockContext) => Promise<T>, options?: DBLockOptions) {
-    return this.writeMutex.runExclusive(() => fn(this));
+    return this.writeMutex.runExclusive(() => fn(this), timeoutSignal(options?.timeoutMs));
   }
 
   async writeTransaction<T>(fn: (tx: Transaction) => Promise<T>, options?: DBLockOptions) {
-    return this.writeLock(() => fn(this.generateMockTransactionContext()));
+    return this.writeLock(() => fn(this.generateMockTransactionContext()), options);
   }
 
   async execute(query: string, params?: any[]): Promise<QueryResult> {

package/src/db/adapters/wa-sqlite/ConcurrentConnection.ts

@@ -0,0 +1,137 @@
+import { Mutex, UnlockFn } from '@powersync/common';
+import { RawSqliteConnection } from './RawSqliteConnection.js';
+import { ResolvedWASQLiteOpenFactoryOptions } from './WASQLiteOpenFactory.js';
+
+/**
+ * A wrapper around a {@link RawSqliteConnection} allowing multiple tabs to access it.
+ *
+ * To allow potentially concurrent accesses from different clients, this requires a local mutex implementation here.
+ *
+ * Note that instances of this class are not safe to proxy across context boundaries with comlink! We need to be able to
+ * rely on mutexes being returned reliably, so additional checks to detect say a client tab closing are required to
+ * avoid deadlocks.
+ */
+export class ConcurrentSqliteConnection {
+  /**
+   * An outer mutex ensuring at most one {@link ConnectionLeaseToken} can exist for this connection at a time.
+   *
+   * If null, we'll use navigator locks instead.
+   */
+  private leaseMutex: Mutex | null;
+
+  /**
+   * @param needsNavigatorLocks Whether access to the database needs an additional navigator lock guard.
+   *
+   * While {@link ConcurrentSqliteConnection} prevents concurrent access to a database _connection_, it's possible we
+   * might have multiple connections to the same physical database (e.g. if multiple tabs use dedicated workers).
+   * In those setups, we use navigator locks instead of an internal mutex to guard access..
+   */
+  constructor(
+    private readonly inner: RawSqliteConnection,
+    needsNavigatorLocks: boolean
+  ) {
+    this.leaseMutex = needsNavigatorLocks ? null : new Mutex();
+  }
+
+  get options(): ResolvedWASQLiteOpenFactoryOptions {
+    return this.inner.options;
+  }
+
+  acquireMutex(abort?: AbortSignal): Promise<UnlockFn> {
+    if (this.leaseMutex) {
+      return this.leaseMutex.acquire(abort);
+    }
+
+    return new Promise((resolve, reject) => {
+      const options: LockOptions = { signal: abort };
+
+      navigator.locks
+        .request(`db-lock-${this.options.dbFilename}`, options, (_) => {
+          return new Promise<void>((returnLock) => {
+            return resolve(() => {
+              returnLock();
+            });
+          });
+        })
+        .catch(reject);
+    });
+  }
+
+  // Unsafe, unguarded access to the SQLite connection.
+  unsafeUseInner(): RawSqliteConnection {
+    return this.inner;
+  }
+
+  /**
+   * @returns A {@link ConnectionLeaseToken}. Until that token is returned, no other client can use the database.
+   */
+  async acquireConnection(abort?: AbortSignal): Promise<ConnectionLeaseToken> {
+    const returnMutex = await this.acquireMutex(abort);
+    const token = new ConnectionLeaseToken(returnMutex, this.inner);
+
+    try {
+      // Assert that the inner connection is initialized at this point, fail early if it's not.
+      this.inner.requireSqlite();
+
+      // If a previous client was interrupted in the middle of a transaction AND this is a shared worker, it's possible
+      // for the connection to still be in a transaction. To avoid inconsistent state, we roll back connection leases
+      // that haven't been comitted.
+      if (!this.inner.isAutoCommit()) {
+        await this.inner.executeRaw('ROLLBACK');
+      }
+    } catch (e) {
+      returnMutex();
+      throw e;
+    }
+
+    return token;
+  }
+
+  async close(): Promise<void> {
+    const returnMutex = await this.acquireMutex();
+    try {
+      await this.inner.close();
+    } finally {
+      returnMutex();
+    }
+  }
+}
+
+/**
+ * An instance representing temporary exclusive access to a {@link ConcurrentSqliteConnection}.
+ */
+export class ConnectionLeaseToken {
+  /** Ensures that the client with access to this token can't run statements concurrently. */
+  private useMutex: Mutex = new Mutex();
+  private closed = false;
+
+  constructor(
+    private returnMutex: UnlockFn,
+    private connection: RawSqliteConnection
+  ) {}
+
+  /**
+   * Returns this lease, allowing another client to use the database connection.
+   */
+  async returnLease() {
+    await this.useMutex.runExclusive(async () => {
+      if (!this.closed) {
+        this.closed = true;
+        this.returnMutex();
+      }
+    });
+  }
+
+  /**
+   * This should only be used internally, since the callback must not use the raw connection after resolving.
+   */
+  async use<T>(callback: (conn: RawSqliteConnection) => Promise<T>): Promise<T> {
+    return await this.useMutex.runExclusive(async () => {
+      if (this.closed) {
+        throw new Error('lease token has already been closed');
+      }
+
+      return await callback(this.connection);
+    });
+  }
+}