@powersync/web 1.36.0 → 1.37.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@powersync/web",
-  "version": "1.36.0",
+  "version": "1.37.0",
   "description": "PowerSync Web SDK",
   "main": "lib/src/index.js",
   "module": "lib/src/index.js",
@@ -56,14 +56,13 @@
   "license": "Apache-2.0",
   "peerDependencies": {
     "@journeyapps/wa-sqlite": "^1.5.0",
-    "@powersync/common": "^1.49.0"
+    "@powersync/common": "^1.50.0"
   },
   "dependencies": {
-    "async-mutex": "^0.5.0",
     "bson": "^6.10.4",
     "comlink": "^4.4.2",
     "commander": "^12.1.0",
-    "@powersync/common": "1.49.0"
+    "@powersync/common": "1.50.0"
   },
   "devDependencies": {
     "@journeyapps/wa-sqlite": "^1.5.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,6 +34,7 @@ import {
   WebStreamingSyncImplementation,
   WebStreamingSyncImplementationOptions
 } from './sync/WebStreamingSyncImplementation.js';
+import { AsyncDbAdapter } from './adapters/AsyncWebAdapter.js';
 
 export interface WebPowerSyncFlags extends WebSQLFlags {
   /**
@@ -148,7 +148,7 @@ export class PowerSyncDatabase extends AbstractPowerSyncDatabase {
   }
 
   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.

package/src/db/adapters/AsyncWebAdapter.ts

@@ -0,0 +1,91 @@
+import {
+  ConnectionPool,
+  DBAdapterDefaultMixin,
+  DBAdapterListener,
+  DBLockOptions,
+  LockContext
+} 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 inner: Promise<DatabaseClient>;
+
+  protected resolvedClient?: DatabaseClient;
+  private readonly pendingListeners = new Set<PendingListener>();
+
+  constructor(
+    inner: Promise<DatabaseClient>,
+    readonly name: string
+  ) {
+    this.inner = inner.then((client) => {
+      for (const pending of this.pendingListeners) {
+        pending.closeAfterRegisteredOnResolvedPool = client.registerListener(pending.listener);
+      }
+      this.pendingListeners.clear();
+
+      this.resolvedClient = client;
+      return client;
+    });
+  }
+
+  async init() {
+    await this.inner;
+  }
+
+  async close() {
+    const inner = await this.inner;
+    return await inner.close();
+  }
+
+  async readLock<T>(fn: (tx: LockContext) => Promise<T>, options?: DBLockOptions): Promise<T> {
+    const inner = await this.inner;
+    return await inner.readLock(fn, options);
+  }
+
+  async writeLock<T>(fn: (tx: LockContext) => Promise<T>, options?: DBLockOptions): Promise<T> {
+    const inner = await this.inner;
+    return await inner.writeLock(fn, options);
+  }
+
+  async refreshSchema(): Promise<void> {
+    await (await this.inner).refreshSchema();
+  }
+
+  registerListener(listener: Partial<DBAdapterListener>): () => void {
+    if (this.resolvedClient) {
+      return this.resolvedClient.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 class AsyncDbAdapter extends DBAdapterDefaultMixin(AsyncConnectionPool) implements WebDBAdapter {
+  async shareConnection(): Promise<SharedConnectionWorker> {
+    const inner = await this.inner;
+    return inner.shareConnection();
+  }
+
+  getConfiguration(): WebDBAdapterConfiguration {
+    if (this.resolvedClient) {
+      return this.resolvedClient.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);
+    });
+  }
+}

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

@@ -0,0 +1,325 @@
+import {
+  QueryResult,
+  LockContext,
+  DBLockOptions,
+  DBAdapterListener,
+  ConnectionPool,
+  SqlExecutor,
+  DBGetUtilsDefaultMixin,
+  BatchedUpdateNotification,
+  BaseObserver,
+  ConnectionClosedError,
+  SQLOpenOptions
+} from '@powersync/common';
+import { SharedConnectionWorker, WebDBAdapterConfiguration } from '../WebDBAdapter.js';
+import { ClientConnectionView } from './DatabaseServer.js';
+import { RawQueryResult } from './RawSqliteConnection.js';
+import * as Comlink from 'comlink';
+import { WorkerDBOpenerOptions } from './WASQLiteOpenFactory.js';
+
+export interface OpenWorkerConnection {
+  connect(config: WorkerDBOpenerOptions): Promise<ClientConnectionView>;
+  connectToExisting(options: { identifier: string; lockName: string }): Promise<ClientConnectionView>;
+}
+
+export interface ClientOptions {
+  connection: ClientConnectionView;
+  /**
+   * The remote from which the {@link connection} has been obtained.
+   *
+   * We use this to be able to expose this port to other clients wanting to connect to the database (e.g. the shared
+   * sync worker).
+   *
+   * For sources not based on workers, returns null.
+   */
+  source: Comlink.Remote<OpenWorkerConnection> | null;
+  /**
+   * Whether the remote we're connecting to can close unexpectedly (e.g. because we're a shared worker connecting to a
+   * dedicated worker handle we've received from a tab).
+   */
+  remoteCanCloseUnexpectedly: boolean;
+  onClose?: () => void;
+}
+
+/**
+ * A single-connection {@link ConnectionPool} implementation based on a worker connection.
+ */
+export class DatabaseClient<Config extends SQLOpenOptions = WebDBAdapterConfiguration>
+  extends BaseObserver<DBAdapterListener>
+  implements ConnectionPool
+{
+  #connection: ConnectionState;
+  #shareConnectionAbortController = new AbortController();
+  #receiveTableUpdates: MessagePort;
+
+  constructor(
+    private readonly options: ClientOptions,
+    private readonly config: Config
+  ) {
+    super();
+    this.#connection = {
+      connection: options.connection,
+      notifyRemoteClosed: options.remoteCanCloseUnexpectedly ? new AbortController() : undefined,
+      traceQueries: config.debugMode === true
+    };
+
+    const { port1, port2 } = new MessageChannel();
+    options.connection.setUpdateListener(Comlink.transfer(port1, [port1]));
+
+    this.#receiveTableUpdates = port2;
+    port2.onmessage = (event) => {
+      const tables = event.data as string[];
+      const notification: BatchedUpdateNotification = {
+        tables,
+        groupedUpdates: {},
+        rawUpdates: []
+      };
+      this.iterateListeners((l) => {
+        l.tablesUpdated && l.tablesUpdated(notification);
+      });
+    };
+  }
+
+  get name(): string {
+    return this.config.dbFilename;
+  }
+
+  /**
+   * Marks the remote as closed.
+   *
+   * This can sometimes happen outside of our control, e.g. when a shared worker requests a connection from a tab. When
+   * it happens, all outstanding requests on this pool would never resolve. To avoid livelocks in this scenario, we
+   * throw on all outstanding promises and forbid new calls.
+   */
+  markRemoteClosed() {
+    // Can non-null assert here because this function is only supposed to be called when remoteCanCloseUnexpectedly was
+    // set.
+    this.#connection.notifyRemoteClosed!.abort();
+  }
+
+  async close(): Promise<void> {
+    // This connection is no longer shared, so we can close locks held for shareConnection calls.
+    this.#shareConnectionAbortController.abort();
+    this.#receiveTableUpdates.close();
+
+    await useConnectionState(this.#connection, (c) => c.close(), true);
+    this.options.onClose?.();
+    this.options.source?.[Comlink.releaseProxy]();
+  }
+
+  readLock<T>(fn: (tx: LockContext) => Promise<T>, options?: DBLockOptions): Promise<T> {
+    return this.#lock(false, fn, options);
+  }
+
+  writeLock<T>(fn: (tx: LockContext) => Promise<T>, options?: DBLockOptions): Promise<T> {
+    return this.#lock(true, fn, options);
+  }
+
+  async #lock<T>(write: boolean, fn: (tx: LockContext) => Promise<T>, options?: DBLockOptions): Promise<T> {
+    const token = await useConnectionState(this.#connection, (c) => c.requestAccess(write, options?.timeoutMs));
+    try {
+      return await fn(new ClientLockContext(this.#connection, token));
+    } finally {
+      await useConnectionState(this.#connection, (c) => c.completeAccess(token));
+    }
+  }
+
+  async refreshSchema(): Promise<void> {
+    // Currently a no-op on the web.
+  }
+
+  async shareConnection(): Promise<SharedConnectionWorker> {
+    /**
+     * Hold a navigator lock in order to avoid features such as Chrome's frozen tabs,
+     * or Edge's sleeping tabs from pausing the thread for this connection.
+     * This promise resolves once a lock is obtained.
+     * This lock will be held as long as this connection is open.
+     * The `shareConnection` method should not be called on multiple tabs concurrently.
+     */
+    const abort = this.#shareConnectionAbortController;
+    const source = this.options.source;
+    if (source == null) {
+      throw new Error(`shareConnection() is only available for connections based by workers.`);
+    }
+
+    await new Promise<void>((resolve, reject) =>
+      navigator.locks
+        .request(
+          `shared-connection-${this.name}-${Date.now()}-${Math.round(Math.random() * 10000)}`,
+          {
+            signal: abort.signal
+          },
+          async () => {
+            resolve();
+
+            // Free the lock when the connection is already closed.
+            if (abort.signal.aborted) {
+              return;
+            }
+
+            // Hold the lock while the shared connection is in use.
+            await new Promise<void>((releaseLock) => {
+              abort.signal.addEventListener('abort', () => {
+                releaseLock();
+              });
+            });
+          }
+        )
+        // We aren't concerned with abort errors here
+        .catch((ex) => {
+          if (ex.name == 'AbortError') {
+            resolve();
+          } else {
+            reject(ex);
+          }
+        })
+    );
+
+    const newPort = await source[Comlink.createEndpoint]();
+    return { port: newPort, identifier: this.name };
+  }
+
+  getConfiguration(): Config {
+    return this.config;
+  }
+}
+
+/**
+ * A {@link SqlExecutor} implemented by sending commands to a worker.
+ *
+ * While an instance is active, it has exclusive access to the underlying database connection (as represented by its
+ * token).
+ */
+class ClientSqlExecutor implements SqlExecutor {
+  readonly #connection: ConnectionState;
+  readonly #token: string;
+
+  constructor(connection: ConnectionState, token: string) {
+    this.#connection = connection;
+    this.#token = token;
+  }
+
+  /**
+   * Requests an operation from the worker, potentially tracing it if that option has been enabled.
+   */
+  private async maybeTrace<T>(
+    fn: (connection: ClientConnectionView) => Promise<T>,
+    describeForTrace: () => string
+  ): Promise<T> {
+    if (this.#connection.traceQueries) {
+      const start = performance.now();
+      const description = describeForTrace();
+
+      try {
+        const r = await useConnectionState(this.#connection, fn);
+        performance.measure(`[SQL] ${description}`, { start });
+        return r;
+      } catch (e: any) {
+        performance.measure(`[SQL] [ERROR: ${e.message}] ${description}`, { start });
+        throw e;
+      }
+    } else {
+      return useConnectionState(this.#connection, fn);
+    }
+  }
+
+  async execute(query: string, params?: any[] | undefined): Promise<QueryResult> {
+    const rs = await this.#executeOnWorker(query, params);
+    let rows: QueryResult['rows'] | undefined;
+    if (rs.resultSet) {
+      const resultSet = rs.resultSet;
+
+      function rowToJavaScriptObject(row: any[]): Record<string, any> {
+        const obj: Record<string, any> = {};
+        resultSet.columns.forEach((key, idx) => (obj[key] = row[idx]));
+        return obj;
+      }
+
+      const mapped = resultSet.rows.map(rowToJavaScriptObject);
+
+      rows = {
+        _array: mapped,
+        length: mapped.length,
+        item: (idx: number) => mapped[idx]
+      };
+    }
+
+    return {
+      rowsAffected: rs.changes,
+      insertId: rs.lastInsertRowId,
+      rows
+    };
+  }
+
+  async executeRaw(query: string, params?: any[] | undefined): Promise<any[][]> {
+    const rs = await this.#executeOnWorker(query, params);
+    return rs.resultSet?.rows ?? [];
+  }
+
+  async #executeOnWorker(query: string, params: any[] | undefined): Promise<RawQueryResult> {
+    return this.maybeTrace(
+      (c) => c.execute(this.#token, query, params),
+      () => query
+    );
+  }
+
+  async executeBatch(query: string, params: any[][] = []): Promise<QueryResult> {
+    const results = await this.maybeTrace(
+      (c) => c.executeBatch(this.#token, query, params),
+      () => `${query} (batch of ${params.length})`
+    );
+    const result: QueryResult = { insertId: undefined, rowsAffected: 0 };
+    for (const source of results) {
+      result.insertId = source.lastInsertRowId;
+      result.rowsAffected += source.changes;
+    }
+
+    return result;
+  }
+}
+
+class ClientLockContext extends DBGetUtilsDefaultMixin(ClientSqlExecutor) implements LockContext {}
+
+interface ConnectionState {
+  connection: ClientConnectionView;
+  notifyRemoteClosed: AbortController | undefined;
+  traceQueries: boolean;
+}
+
+async function useConnectionState<T>(
+  state: ConnectionState,
+  workerPromise: (connection: ClientConnectionView) => Promise<T>,
+  fireActionOnAbort = false
+): Promise<T> {
+  const controller = state.notifyRemoteClosed;
+  if (controller) {
+    return new Promise((resolve, reject) => {
+      if (controller.signal.aborted) {
+        reject(new ConnectionClosedError('Called operation on closed remote'));
+        if (!fireActionOnAbort) {
+          // Don't run the operation if we're going to reject
+          // We might want to fire-and-forget the operation in some cases (like a close operation)
+          return;
+        }
+      }
+
+      function handleAbort() {
+        reject(new ConnectionClosedError('Remote peer closed with request in flight'));
+      }
+
+      function completePromise(action: () => void) {
+        controller!.signal.removeEventListener('abort', handleAbort);
+        action();
+      }
+
+      controller.signal.addEventListener('abort', handleAbort);
+
+      workerPromise(state.connection)
+        .then((data) => completePromise(() => resolve(data)))
+        .catch((e) => completePromise(() => reject(e)));
+    });
+  } else {
+    // Can't close, so just return the inner worker promise unguarded.
+    return workerPromise(state.connection);
+  }
+}