@powersync/web 1.27.1 → 1.28.1

package/src/db/adapters/LockedAsyncDatabaseAdapter.ts

@@ -0,0 +1,358 @@
+import {
+  type ILogger,
+  BaseObserver,
+  createLogger,
+  DBAdapter,
+  DBAdapterListener,
+  DBGetUtils,
+  DBLockOptions,
+  LockContext,
+  QueryResult,
+  Transaction
+} from '@powersync/common';
+import { getNavigatorLocks } from '../..//shared/navigator';
+import { AsyncDatabaseConnection } from './AsyncDatabaseConnection';
+import { SharedConnectionWorker, WebDBAdapter } from './WebDBAdapter';
+import { WorkerWrappedAsyncDatabaseConnection } from './WorkerWrappedAsyncDatabaseConnection';
+import { ResolvedWebSQLOpenOptions } from './web-sql-flags';
+
+/**
+ * @internal
+ */
+export interface LockedAsyncDatabaseAdapterOptions {
+  name: string;
+  openConnection: () => Promise<AsyncDatabaseConnection>;
+  debugMode?: boolean;
+  logger?: ILogger;
+}
+
+export type LockedAsyncDatabaseAdapterListener = DBAdapterListener & {
+  initialized?: () => void;
+};
+
+/**
+ * @internal
+ * Wraps a {@link AsyncDatabaseConnection} and provides exclusive locking functions in
+ * order to implement {@link DBAdapter}.
+ */
+export class LockedAsyncDatabaseAdapter
+  extends BaseObserver<LockedAsyncDatabaseAdapterListener>
+  implements WebDBAdapter
+{
+  private logger: ILogger;
+  private dbGetHelpers: DBGetUtils | null;
+  private debugMode: boolean;
+  private _dbIdentifier: string;
+  protected initPromise: Promise<void>;
+  private _db: AsyncDatabaseConnection | null = null;
+  protected _disposeTableChangeListener: (() => void) | null = null;
+  private _config: ResolvedWebSQLOpenOptions | null = null;
+  protected pendingAbortControllers: Set<AbortController>;
+
+  closing: boolean;
+  closed: boolean;
+
+  constructor(protected options: LockedAsyncDatabaseAdapterOptions) {
+    super();
+    this._dbIdentifier = options.name;
+    this.logger = options.logger ?? createLogger(`LockedAsyncDatabaseAdapter - ${this._dbIdentifier}`);
+    this.pendingAbortControllers = new Set<AbortController>();
+    this.closed = false;
+    this.closing = false;
+    // Set the name if provided. We can query for the name if not available yet
+    this.debugMode = options.debugMode ?? false;
+    if (this.debugMode) {
+      const originalExecute = this._execute.bind(this);
+      this._execute = async (sql, bindings) => {
+        const start = performance.now();
+        try {
+          const r = await originalExecute(sql, bindings);
+          performance.measure(`[SQL] ${sql}`, { start });
+          return r;
+        } catch (e: any) {
+          performance.measure(`[SQL] [ERROR: ${e.message}] ${sql}`, { start });
+          throw e;
+        }
+      };
+    }
+
+    this.dbGetHelpers = this.generateDBHelpers({
+      execute: (query, params) => this.acquireLock(() => this._execute(query, params)),
+      executeRaw: (query, params) => this.acquireLock(() => this._executeRaw(query, params))
+    });
+    this.initPromise = this._init();
+  }
+
+  protected get baseDB() {
+    if (!this._db) {
+      throw new Error(`Initialization has not completed yet. Cannot access base db`);
+    }
+    return this._db;
+  }
+
+  get name() {
+    return this._dbIdentifier;
+  }
+
+  /**
+   * Init is automatic, this helps catch errors or explicitly await initialization
+   */
+  async init() {
+    return this.initPromise;
+  }
+
+  protected async _init() {
+    this._db = await this.options.openConnection();
+    await this._db.init();
+    this._config = await this._db.getConfig();
+    await this.registerOnChangeListener(this._db);
+    this.iterateListeners((cb) => cb.initialized?.());
+  }
+
+  getConfiguration(): ResolvedWebSQLOpenOptions {
+    if (!this._config) {
+      throw new Error(`Cannot get config before initialization is completed`);
+    }
+    return this._config;
+  }
+
+  protected async waitForInitialized() {
+    // Awaiting this will expose errors on function calls like .execute etc
+    await this.initPromise;
+  }
+
+  async shareConnection(): Promise<SharedConnectionWorker> {
+    if (false == this._db instanceof WorkerWrappedAsyncDatabaseConnection) {
+      throw new Error(`Only worker connections can be shared`);
+    }
+    return this._db.shareConnection();
+  }
+
+  /**
+   * Registers a table change notification callback with the base database.
+   * This can be extended by custom implementations in order to handle proxy events.
+   */
+  protected async registerOnChangeListener(db: AsyncDatabaseConnection) {
+    this._disposeTableChangeListener = await db.registerOnTableChange((event) => {
+      this.iterateListeners((cb) => cb.tablesUpdated?.(event));
+    });
+  }
+
+  /**
+   * This is currently a no-op on web
+   */
+  async refreshSchema(): Promise<void> {}
+
+  async execute(query: string, params?: any[] | undefined): Promise<QueryResult> {
+    return this.writeLock((ctx) => ctx.execute(query, params));
+  }
+
+  async executeRaw(query: string, params?: any[] | undefined): Promise<any[][]> {
+    return this.writeLock((ctx) => ctx.executeRaw(query, params));
+  }
+
+  async executeBatch(query: string, params?: any[][]): Promise<QueryResult> {
+    return this.writeLock((ctx) => this._executeBatch(query, params));
+  }
+
+  /**
+   * Attempts to close the connection.
+   * Shared workers might not actually close the connection if other
+   * tabs are still using it.
+   */
+  async close() {
+    this.closing = true;
+    this._disposeTableChangeListener?.();
+    this.pendingAbortControllers.forEach((controller) => controller.abort('Closed'));
+    await this.baseDB?.close?.();
+    this.closed = true;
+  }
+
+  async getAll<T>(sql: string, parameters?: any[] | undefined): Promise<T[]> {
+    await this.waitForInitialized();
+    return this.dbGetHelpers!.getAll(sql, parameters);
+  }
+
+  async getOptional<T>(sql: string, parameters?: any[] | undefined): Promise<T | null> {
+    await this.waitForInitialized();
+    return this.dbGetHelpers!.getOptional(sql, parameters);
+  }
+
+  async get<T>(sql: string, parameters?: any[] | undefined): Promise<T> {
+    await this.waitForInitialized();
+    return this.dbGetHelpers!.get(sql, parameters);
+  }
+
+  async readLock<T>(fn: (tx: LockContext) => Promise<T>, options?: DBLockOptions | undefined): Promise<T> {
+    await this.waitForInitialized();
+    return this.acquireLock(
+      async () => fn(this.generateDBHelpers({ execute: this._execute, executeRaw: this._executeRaw })),
+      {
+        timeoutMs: options?.timeoutMs
+      }
+    );
+  }
+
+  async writeLock<T>(fn: (tx: LockContext) => Promise<T>, options?: DBLockOptions | undefined): Promise<T> {
+    await this.waitForInitialized();
+    return this.acquireLock(
+      async () => fn(this.generateDBHelpers({ execute: this._execute, executeRaw: this._executeRaw })),
+      {
+        timeoutMs: options?.timeoutMs
+      }
+    );
+  }
+
+  protected async acquireLock(callback: () => Promise<any>, options?: { timeoutMs?: number }): Promise<any> {
+    await this.waitForInitialized();
+
+    if (this.closing) {
+      throw new Error(`Cannot acquire lock, the database is closing`);
+    }
+
+    const abortController = new AbortController();
+    this.pendingAbortControllers.add(abortController);
+    const { timeoutMs } = options ?? {};
+
+    const timoutId = timeoutMs
+      ? setTimeout(() => {
+          abortController.abort(`Timeout after ${timeoutMs}ms`);
+          this.pendingAbortControllers.delete(abortController);
+        }, timeoutMs)
+      : null;
+
+    return getNavigatorLocks().request(`db-lock-${this._dbIdentifier}`, { signal: abortController.signal }, () => {
+      this.pendingAbortControllers.delete(abortController);
+      if (timoutId) {
+        clearTimeout(timoutId);
+      }
+      return callback();
+    });
+  }
+
+  async readTransaction<T>(fn: (tx: Transaction) => Promise<T>, options?: DBLockOptions | undefined): Promise<T> {
+    return this.readLock(this.wrapTransaction(fn));
+  }
+
+  writeTransaction<T>(fn: (tx: Transaction) => Promise<T>, options?: DBLockOptions | undefined): Promise<T> {
+    return this.writeLock(this.wrapTransaction(fn, true));
+  }
+
+  private generateDBHelpers<
+    T extends {
+      execute: (sql: string, params?: any[]) => Promise<QueryResult>;
+      executeRaw: (sql: string, params?: any[]) => Promise<any[][]>;
+    }
+  >(tx: T): T & DBGetUtils {
+    return {
+      ...tx,
+      /**
+       *  Execute a read-only query and return results
+       */
+      async getAll<T>(sql: string, parameters?: any[]): Promise<T[]> {
+        const res = await tx.execute(sql, parameters);
+        return res.rows?._array ?? [];
+      },
+
+      /**
+       * Execute a read-only query and return the first result, or null if the ResultSet is empty.
+       */
+      async getOptional<T>(sql: string, parameters?: any[]): Promise<T | null> {
+        const res = await tx.execute(sql, parameters);
+        return res.rows?.item(0) ?? null;
+      },
+
+      /**
+       * Execute a read-only query and return the first result, error if the ResultSet is empty.
+       */
+      async get<T>(sql: string, parameters?: any[]): Promise<T> {
+        const res = await tx.execute(sql, parameters);
+        const first = res.rows?.item(0);
+        if (!first) {
+          throw new Error('Result set is empty');
+        }
+        return first;
+      }
+    };
+  }
+
+  /**
+   * Wraps a lock context into a transaction context
+   */
+  private wrapTransaction<T>(cb: (tx: Transaction) => Promise<T>, write = false) {
+    return async (tx: LockContext): Promise<T> => {
+      await this._execute(write ? 'BEGIN EXCLUSIVE' : 'BEGIN');
+      let finalized = false;
+      const commit = async (): Promise<QueryResult> => {
+        if (finalized) {
+          return { rowsAffected: 0 };
+        }
+        finalized = true;
+        return this._execute('COMMIT');
+      };
+
+      const rollback = () => {
+        finalized = true;
+        return this._execute('ROLLBACK');
+      };
+
+      try {
+        const result = await cb({
+          ...tx,
+          commit,
+          rollback
+        });
+
+        if (!finalized) {
+          await commit();
+        }
+        return result;
+      } catch (ex) {
+        this.logger.debug('Caught ex in transaction', ex);
+        try {
+          await rollback();
+        } catch (ex2) {
+          // In rare cases, a rollback may fail.
+          // Safe to ignore.
+        }
+        throw ex;
+      }
+    };
+  }
+
+  /**
+   * Wraps the worker execute function, awaiting for it to be available
+   */
+  private _execute = async (sql: string, bindings?: any[]): Promise<QueryResult> => {
+    await this.waitForInitialized();
+
+    const result = await this.baseDB.execute(sql, bindings);
+    return {
+      ...result,
+      rows: {
+        ...result.rows,
+        item: (idx: number) => result.rows._array[idx]
+      }
+    };
+  };
+
+  /**
+   * Wraps the worker executeRaw function, awaiting for it to be available
+   */
+  private _executeRaw = async (sql: string, bindings?: any[]): Promise<any[][]> => {
+    await this.waitForInitialized();
+    return await this.baseDB.executeRaw(sql, bindings);
+  };
+
+  /**
+   * Wraps the worker executeBatch function, awaiting for it to be available
+   */
+  private _executeBatch = async (query: string, params?: any[]): Promise<QueryResult> => {
+    await this.waitForInitialized();
+    const result = await this.baseDB.executeBatch(query, params);
+    return {
+      ...result,
+      rows: undefined
+    };
+  };
+}

package/src/db/adapters/SSRDBAdapter.ts

@@ -0,0 +1,94 @@
+import {
+  BaseObserver,
+  DBAdapterListener,
+  DBAdapter,
+  DBLockOptions,
+  LockContext,
+  QueryResult,
+  Transaction
+} from '@powersync/common';
+
+import { Mutex } from 'async-mutex';
+
+const MOCK_QUERY_RESPONSE: QueryResult = {
+  rowsAffected: 0
+};
+
+/**
+ * Implements a Mock DB adapter for use in Server Side Rendering (SSR).
+ * This adapter will return empty results for queries, which will allow
+ * server rendered views to initially generate scaffolding components
+ */
+export class SSRDBAdapter extends BaseObserver<DBAdapterListener> implements DBAdapter {
+  name: string;
+  readMutex: Mutex;
+  writeMutex: Mutex;
+
+  constructor() {
+    super();
+    this.name = 'SSR DB';
+    this.readMutex = new Mutex();
+    this.writeMutex = new Mutex();
+  }
+
+  close() {}
+
+  async readLock<T>(fn: (tx: LockContext) => Promise<T>, options?: DBLockOptions) {
+    return this.readMutex.runExclusive(() => fn(this));
+  }
+
+  async readTransaction<T>(fn: (tx: Transaction) => Promise<T>, options?: DBLockOptions) {
+    return this.readLock(() => fn(this.generateMockTransactionContext()));
+  }
+
+  async writeLock<T>(fn: (tx: LockContext) => Promise<T>, options?: DBLockOptions) {
+    return this.writeMutex.runExclusive(() => fn(this));
+  }
+
+  async writeTransaction<T>(fn: (tx: Transaction) => Promise<T>, options?: DBLockOptions) {
+    return this.writeLock(() => fn(this.generateMockTransactionContext()));
+  }
+
+  async execute(query: string, params?: any[]): Promise<QueryResult> {
+    return this.writeMutex.runExclusive(async () => MOCK_QUERY_RESPONSE);
+  }
+
+  async executeRaw(query: string, params?: any[]): Promise<any[][]> {
+    return this.writeMutex.runExclusive(async () => []);
+  }
+
+  async executeBatch(query: string, params?: any[][]): Promise<QueryResult> {
+    return this.writeMutex.runExclusive(async () => MOCK_QUERY_RESPONSE);
+  }
+
+  async getAll<T>(sql: string, parameters?: any[]): Promise<T[]> {
+    return [];
+  }
+
+  async getOptional<T>(sql: string, parameters?: any[] | undefined): Promise<T | null> {
+    return null;
+  }
+
+  async get<T>(sql: string, parameters?: any[] | undefined): Promise<T> {
+    throw new Error(`No values are returned in SSR mode`);
+  }
+
+  /**
+   * Generates a mock context for use in read/write transactions.
+   * `this` already mocks most of the API, commit and rollback mocks
+   *  are added here
+   */
+  private generateMockTransactionContext(): Transaction {
+    return {
+      ...this,
+      commit: async () => {
+        return MOCK_QUERY_RESPONSE;
+      },
+      rollback: async () => {
+        return MOCK_QUERY_RESPONSE;
+      }
+    };
+  }
+
+  async refreshSchema(): Promise<void> {}
+}

package/src/db/adapters/WebDBAdapter.ts

@@ -0,0 +1,20 @@
+import { DBAdapter } from '@powersync/common';
+import { ResolvedWebSQLOpenOptions } from './web-sql-flags';
+
+export type SharedConnectionWorker = {
+  identifier: string;
+  port: MessagePort;
+};
+
+export interface WebDBAdapter extends DBAdapter {
+  /**
+   * Get a MessagePort which can be used to share the internals of this connection.
+   */
+  shareConnection(): Promise<SharedConnectionWorker>;
+
+  /**
+   * Get the config options used to open this connection.
+   * This is useful for sharing connections.
+   */
+  getConfiguration(): ResolvedWebSQLOpenOptions;
+}

package/src/db/adapters/WorkerWrappedAsyncDatabaseConnection.ts

@@ -0,0 +1,175 @@
+import * as Comlink from 'comlink';
+import {
+  AsyncDatabaseConnection,
+  OnTableChangeCallback,
+  OpenAsyncDatabaseConnection,
+  ProxiedQueryResult
+} from './AsyncDatabaseConnection';
+import { ResolvedWebSQLOpenOptions } from './web-sql-flags';
+
+export type SharedConnectionWorker = {
+  identifier: string;
+  port: MessagePort;
+};
+
+export type WrappedWorkerConnectionOptions<Config extends ResolvedWebSQLOpenOptions = ResolvedWebSQLOpenOptions> = {
+  baseConnection: AsyncDatabaseConnection;
+  identifier: string;
+  remoteCanCloseUnexpectedly: boolean;
+  /**
+   * Need a remote in order to keep a reference to the Proxied worker
+   */
+  remote: Comlink.Remote<OpenAsyncDatabaseConnection<Config>>;
+  onClose?: () => void;
+};
+
+/**
+ * Wraps a provided instance of {@link AsyncDatabaseConnection}, providing necessary proxy
+ * functions for worker listeners.
+ */
+export class WorkerWrappedAsyncDatabaseConnection<Config extends ResolvedWebSQLOpenOptions = ResolvedWebSQLOpenOptions>
+  implements AsyncDatabaseConnection
+{
+  protected lockAbortController = new AbortController();
+  protected notifyRemoteClosed: AbortController | undefined;
+
+  constructor(protected options: WrappedWorkerConnectionOptions<Config>) {
+    if (options.remoteCanCloseUnexpectedly) {
+      this.notifyRemoteClosed = new AbortController();
+    }
+  }
+
+  protected get baseConnection() {
+    return this.options.baseConnection;
+  }
+
+  init(): Promise<void> {
+    return this.baseConnection.init();
+  }
+
+  /**
+   * 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 methods on the {@link baseConnection} 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.notifyRemoteClosed!.abort();
+  }
+
+  private withRemote<T>(workerPromise: () => Promise<T>): Promise<T> {
+    const controller = this.notifyRemoteClosed;
+    if (controller) {
+      return new Promise((resolve, reject) => {
+        if (controller.signal.aborted) {
+          reject(new Error('Called operation on closed remote'));
+        }
+
+        function handleAbort() {
+          reject(new Error('Remote peer closed with request in flight'));
+        }
+
+        function completePromise(action: () => void) {
+          controller!.signal.removeEventListener('abort', handleAbort);
+          action();
+        }
+
+        controller.signal.addEventListener('abort', handleAbort);
+
+        workerPromise()
+          .then((data) => completePromise(() => resolve(data)))
+          .catch((e) => completePromise(() => reject(e)));
+      });
+    } else {
+      // Can't close, so just return the inner worker promise unguarded.
+      return workerPromise();
+    }
+  }
+
+  /**
+   * Get a MessagePort which can be used to share the internals of this connection.
+   */
+  async shareConnection(): Promise<SharedConnectionWorker> {
+    const { identifier, remote } = this.options;
+    /**
+     * 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.
+     */
+    await new Promise<void>((resolve, reject) =>
+      navigator.locks
+        .request(
+          `shared-connection-${this.options.identifier}-${Date.now()}-${Math.round(Math.random() * 10000)}`,
+          {
+            signal: this.lockAbortController.signal
+          },
+          async () => {
+            resolve();
+
+            // Free the lock when the connection is already closed.
+            if (this.lockAbortController.signal.aborted) {
+              return;
+            }
+
+            // Hold the lock while the shared connection is in use.
+            await new Promise<void>((releaseLock) => {
+              this.lockAbortController.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 remote[Comlink.createEndpoint]();
+    return { port: newPort, identifier };
+  }
+
+  /**
+   * Registers a table change notification callback with the base database.
+   * This can be extended by custom implementations in order to handle proxy events.
+   */
+  async registerOnTableChange(callback: OnTableChangeCallback) {
+    return this.baseConnection.registerOnTableChange(Comlink.proxy(callback));
+  }
+
+  async close(): Promise<void> {
+    // Abort any pending lock requests.
+    this.lockAbortController.abort();
+    try {
+      await this.withRemote(() => this.baseConnection.close());
+    } finally {
+      this.options.remote[Comlink.releaseProxy]();
+      this.options.onClose?.();
+    }
+  }
+
+  execute(sql: string, params?: any[]): Promise<ProxiedQueryResult> {
+    return this.withRemote(() => this.baseConnection.execute(sql, params));
+  }
+
+  executeRaw(sql: string, params?: any[]): Promise<any[][]> {
+    return this.withRemote(() => this.baseConnection.executeRaw(sql, params));
+  }
+
+  executeBatch(sql: string, params?: any[]): Promise<ProxiedQueryResult> {
+    return this.withRemote(() => this.baseConnection.executeBatch(sql, params));
+  }
+
+  getConfig(): Promise<ResolvedWebSQLOpenOptions> {
+    return this.withRemote(() => this.baseConnection.getConfig());
+  }
+}