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

package/src/db/adapters/options.ts

@@ -0,0 +1,100 @@
+import { LogLevels, SQLOpenOptions } from '@powersync/common';
+import { WASQLiteVFS } from './wa-sqlite/vfs.js';
+
+export interface WebSpecificOpenOptions {
+  /**
+   * SQLite operations are currently not supported in SSR mode.
+   * A warning will be logged if attempting to use SQLite in SSR.
+   * Setting this to `true` will disabled the warning above.
+   */
+  disableSSRWarning: boolean;
+
+  /**
+   * Enables multi tab support.
+   *
+   * Enabling multi-tab support will transparently make PowerSync manage the sync process in a shared worker collecting
+   * Sync Streams across tabs. Additionally, it enables a shared worker for IndexedDB databases.
+   *
+   * It is still valid to open multiple tabs when this option is disabled, but the experience may be degrated as only
+   * one tab can sync at the time.
+   *
+   * This is enabled by default on Desktop browsers if shared workers are enabled, except for Safari.
+   */
+  enableMultiTabs: boolean;
+
+  /**
+   * The SQLite connection is often executed through a web worker in order to offload computation and because some file
+   * system implementations (notably those based on web filesystem APIs like OPFS) are only available in workers.
+   *
+   * Manually disabling the use of web workers is not recommended, but can be useful for testing or for environments
+   * or toolchains where web workers are not supported.
+   */
+  useWebWorker: boolean;
+
+  /**
+   * Open in SSR placeholder mode. DB operations and Sync operations will be a No-op
+   */
+  ssrMode: boolean;
+
+  /**
+   * The log level for database workers.
+   *
+   * Defaults to {@link LogLevels.info}.
+   */
+  databaseWorkerLogLevel: number;
+
+  /**
+   * Where to store SQLite temporary files. Defaults to 'MEMORY'.
+   * Setting this to `FILESYSTEM` can cause issues with larger queries or datasets.
+   */
+  temporaryStorage: TemporaryStorageOption;
+
+  /**
+   * Maximum SQLite cache size. Defaults to 50MB.
+   *
+   * For details, see: https://www.sqlite.org/pragma.html#pragma_cache_size
+   */
+  cacheSizeKb: number;
+
+  /**
+   * Encryption key for the database.
+   * If set, the database will be encrypted using ChaCha20.
+   */
+  encryptionKey: string | undefined;
+
+  vfs: WASQLiteVFS;
+
+  /**
+   * If the {@link vfs} supports it, an additional amount of read-only connections to open. Using additional read
+   * connections can speed up queries by dispatching them to multiple workers running them concurrently.
+   *
+   * {@link WASQLiteVFS.OPFSWriteAheadVFS} is the only VFS with support for multiple connections, so this option is
+   * ignored for other VFS implementations.
+   *
+   * Defaults to 1.
+   */
+  additionalReaders: number;
+
+  /**
+   * Allows you to override the default wasqlite db worker.
+   *
+   * You can either provide a path to the worker script
+   * or a factory method that returns a worker.
+   */
+  worker?: string | URL | ((options: ResolvedWebSQLOpenOptions) => Worker | SharedWorker);
+
+  /**
+   * Use an existing port to an initialized worker.
+   * A worker will be initialized if none is provided
+   */
+  workerPort?: MessagePort | undefined;
+}
+
+export interface ResolvedWebSQLOpenOptions extends SQLOpenOptions, WebSpecificOpenOptions {}
+
+export interface WebSQLOpenOptions extends SQLOpenOptions, Partial<WebSpecificOpenOptions> {}
+
+export enum TemporaryStorageOption {
+  MEMORY = 'memory',
+  FILESYSTEM = 'file'
+}

package/src/db/adapters/resolveAndValidateOptions.ts

@@ -0,0 +1,40 @@
+import { LogLevels } from '@powersync/common';
+import { TemporaryStorageOption, WebSpecificOpenOptions } from './options.js';
+import { vfsRequiresDedicatedWorkers, WASQLiteVFS } from './wa-sqlite/vfs.js';
+
+/**
+ * @internal
+ */
+export function resolveAndValidateOptions<And = {}>(
+  options: Partial<WebSpecificOpenOptions> & And
+): WebSpecificOpenOptions & And {
+  const defaults: WebSpecificOpenOptions = {
+    disableSSRWarning: false,
+    ssrMode: !('window' in globalThis),
+    /**
+     * Multiple tabs are by default not supported on Android, iOS and Safari.
+     * Other platforms will have multiple tabs enabled by default.
+     */
+    enableMultiTabs:
+      typeof globalThis.navigator !== 'undefined' && // For SSR purposes
+      typeof SharedWorker !== 'undefined' &&
+      !navigator.userAgent.match(/(Android|iPhone|iPod|iPad)/i) &&
+      !(window as any).safari,
+    useWebWorker: true,
+    databaseWorkerLogLevel: LogLevels.info,
+    temporaryStorage: TemporaryStorageOption.MEMORY,
+    cacheSizeKb: 50 * 1024,
+    encryptionKey: undefined,
+    vfs: WASQLiteVFS.IDBBatchAtomicVFS,
+    additionalReaders: 1
+  };
+
+  const resolved = Object.assign(defaults, options);
+  if (vfsRequiresDedicatedWorkers(resolved.vfs) && !resolved.useWebWorker) {
+    throw new Error(
+      `Invalid configuration: The 'useWebWorker' flag must be true when using an OPFS-based VFS (${resolved.vfs}).`
+    );
+  }
+
+  return resolved;
+}

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

@@ -1,6 +1,5 @@
-import { Mutex, UnlockFn } from '@powersync/common';
-import { RawSqliteConnection } from './RawSqliteConnection.js';
-import { ResolvedWASQLiteOpenFactoryOptions } from './WASQLiteOpenFactory.js';
+import { Mutex, UnlockFn } from '@powersync/shared-internals';
+import { RawSqliteConnection, RawWaSqliteDatabaseOptions } from './RawSqliteConnection.js';
 
 /**
  * A wrapper around a {@link RawSqliteConnection} allowing multiple tabs to access it.
@@ -33,7 +32,7 @@ export class ConcurrentSqliteConnection {
     this.leaseMutex = needsNavigatorLocks ? null : new Mutex();
   }
 
-  get options(): ResolvedWASQLiteOpenFactoryOptions {
+  get options(): RawWaSqliteDatabaseOptions {
     return this.inner.options;
   }
 
@@ -46,7 +45,7 @@ export class ConcurrentSqliteConnection {
       const options: LockOptions = { signal: abort };
 
       navigator.locks
-        .request(`db-lock-${this.options.dbFilename}`, options, (_) => {
+        .request(`db-lock-${this.options.filename}`, options, (_) => {
           return new Promise<void>((returnLock) => {
             return resolve(() => {
               returnLock();

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

@@ -2,23 +2,22 @@ import {
   QueryResult,
   LockContext,
   DBLockOptions,
-  DBAdapterListener,
-  ConnectionPool,
   SqlExecutor,
-  DBGetUtilsDefaultMixin,
   BatchedUpdateNotification,
-  BaseObserver,
-  ConnectionClosedError,
-  SQLOpenOptions
+  SQLOpenOptions,
+  DBAdapter,
+  RawQueryResult,
+  queryResultWithoutRows,
+  BaseQueryResult
 } 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';
+import type { ConnectToMultiDatabaseServerOptions } from '../../../worker/db/MultiDatabaseServer.js';
+import { ConnectionClosedError } from '@powersync/shared-internals';
 
 export interface OpenWorkerConnection {
-  connect(config: WorkerDBOpenerOptions): Promise<ClientConnectionView>;
+  connect(config: ConnectToMultiDatabaseServerOptions): Promise<ClientConnectionView>;
   connectToExisting(options: { identifier: string; lockName: string }): Promise<ClientConnectionView>;
 }
 
@@ -44,10 +43,7 @@ export interface ClientOptions {
 /**
  * A single-connection {@link ConnectionPool} implementation based on a worker connection.
  */
-export class DatabaseClient<Config extends SQLOpenOptions = WebDBAdapterConfiguration>
-  extends BaseObserver<DBAdapterListener>
-  implements ConnectionPool
-{
+export class DatabaseClient<Config extends SQLOpenOptions = WebDBAdapterConfiguration> extends DBAdapter {
   #connection: ConnectionState;
   #shareConnectionAbortController = new AbortController();
   #receiveTableUpdates: MessagePort;
@@ -70,9 +66,7 @@ export class DatabaseClient<Config extends SQLOpenOptions = WebDBAdapterConfigur
     port2.onmessage = (event) => {
       const tables = event.data as string[];
       const notification: BatchedUpdateNotification = {
-        tables,
-        groupedUpdates: {},
-        rawUpdates: []
+        tables
       };
       this.iterateListeners((l) => {
         l.tablesUpdated && l.tablesUpdated(notification);
@@ -185,16 +179,17 @@ export class DatabaseClient<Config extends SQLOpenOptions = WebDBAdapterConfigur
 }
 
 /**
- * A {@link SqlExecutor} implemented by sending commands to a worker.
+ * A {@link LockContext} 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 {
+class ClientLockContext extends LockContext {
   readonly #connection: ConnectionState;
   readonly #token: string;
 
   constructor(connection: ConnectionState, token: string) {
+    super();
     this.#connection = connection;
     this.#token = token;
   }
@@ -223,37 +218,8 @@ class ClientSqlExecutor implements SqlExecutor {
     }
   }
 
-  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 executeRaw(query: string, params?: any[] | undefined): Promise<RawQueryResult> {
+    return await this.#executeOnWorker(query, params);
   }
 
   async #executeOnWorker(query: string, params: any[] | undefined): Promise<RawQueryResult> {
@@ -263,23 +229,21 @@ class ClientSqlExecutor implements SqlExecutor {
     );
   }
 
-  async executeBatch(query: string, params: any[][] = []): Promise<QueryResult> {
+  async executeBatch(query: string, params: any[][] = []): Promise<QueryResult<never>> {
     const results = await this.maybeTrace(
       (c) => c.executeBatch(this.#token, query, params),
       () => `${query} (batch of ${params.length})`
     );
-    const result: QueryResult = { insertId: undefined, rowsAffected: 0 };
+    const result: BaseQueryResult = { insertId: undefined, rowsAffected: 0 };
     for (const source of results) {
-      result.insertId = source.lastInsertRowId;
-      result.rowsAffected += source.changes;
+      result.insertId = source.insertId;
+      result.rowsAffected = (result.rowsAffected ?? 0) + source.rowsAffected;
     }
 
-    return result;
+    return queryResultWithoutRows(result);
   }
 }
 
-class ClientLockContext extends DBGetUtilsDefaultMixin(ClientSqlExecutor) implements LockContext {}
-
 interface ConnectionState {
   connection: ClientConnectionView;
   notifyRemoteClosed: AbortController | undefined;

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

@@ -1,11 +1,11 @@
-import { ILogger } from '@powersync/common';
+import { LogLevels, PowerSyncLogger } from '@powersync/common';
 import { ConcurrentSqliteConnection, ConnectionLeaseToken } from './ConcurrentConnection.js';
-import { RawQueryResult } from './RawSqliteConnection.js';
+import { RawWebResult } from './RawSqliteConnection.js';
 
 export interface DatabaseServerOptions {
   inner: ConcurrentSqliteConnection;
   onClose: () => void;
-  logger: ILogger;
+  logger: PowerSyncLogger;
 }
 
 /**
@@ -24,7 +24,7 @@ export class DatabaseServer {
   constructor(options: DatabaseServerOptions) {
     this.#options = options;
     const inner = options.inner;
-    this.#updateBroadcastChannel = new BroadcastChannel(`${inner.options.dbFilename}-table-updates`);
+    this.#updateBroadcastChannel = new BroadcastChannel(`${inner.options.filename}-table-updates`);
 
     this.#updateBroadcastChannel.onmessage = ({ data }) => {
       this.#pushTableUpdateToClients(data as string[]);
@@ -85,7 +85,7 @@ export class DatabaseServer {
 
         // If the client holds a connection lease it hasn't returned, return that now.
         for (const { lease } of connectionLeases.values()) {
-          this.#logger.debug(`Closing connection lease that hasn't been returned.`);
+          this.#logger.log({ level: LogLevels.debug, message: `Closing connection lease that hasn't been returned.` });
           await lease.returnLease();
         }
 
@@ -94,7 +94,10 @@ export class DatabaseServer {
         if (this.#activeClients.size == 0) {
           await this.forceClose();
         } else {
-          this.#logger.debug('Keeping underlying connection active since its used by other clients.');
+          this.#logger.log({
+            level: LogLevels.debug,
+            message: 'Keeping underlying connection active since its used by other clients.'
+          });
         }
       }
     };
@@ -133,9 +136,9 @@ export class DatabaseServer {
         try {
           if (lease.write) {
             // Collect update hooks invoked while the client had the write connection.
-            const { resultSet } = await lease.lease.use((conn) => conn.execute(`SELECT powersync_update_hooks('get')`));
-            if (resultSet) {
-              const updatedTables: string[] = JSON.parse(resultSet.rows[0][0] as string);
+            const { rawRows } = await lease.lease.use((conn) => conn.execute(`SELECT powersync_update_hooks('get')`));
+            if (rawRows.length) {
+              const updatedTables: string[] = JSON.parse(rawRows[0][0] as string);
               if (updatedTables.length) {
                 this.#updateBroadcastChannel.postMessage(updatedTables);
                 this.#pushTableUpdateToClients(updatedTables);
@@ -169,7 +172,7 @@ export class DatabaseServer {
   }
 
   async forceClose() {
-    this.#logger.debug(`Closing connection to ${this.#inner.options}.`);
+    this.#logger.log({ level: LogLevels.debug, message: `Closing connection to ${this.#inner.options}.` });
     const connection = this.#inner;
     this.#options.onClose();
     this.#updateBroadcastChannel.close();
@@ -190,8 +193,8 @@ export interface ClientConnectionView {
    * give other clients access to the database afterwards.
    */
   requestAccess(write: boolean, timeoutMs?: number): Promise<string>;
-  execute(token: string, sql: string, params: any[] | undefined): Promise<RawQueryResult>;
-  executeBatch(token: string, sql: string, params: any[][]): Promise<RawQueryResult[]>;
+  execute(token: string, sql: string, params: any[] | undefined): Promise<RawWebResult>;
+  executeBatch(token: string, sql: string, params: any[][]): Promise<RawWebResult[]>;
   completeAccess(token: string): Promise<void>;
 
   /**

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

@@ -1,18 +1,28 @@
 import { Factory as WaSqliteFactory, SQLITE_ROW } from '@journeyapps/wa-sqlite';
 
-import { DEFAULT_MODULE_FACTORIES, WASQLiteModuleFactory } from './vfs.js';
-import { ResolvedWASQLiteOpenFactoryOptions } from './WASQLiteOpenFactory.js';
+import { DEFAULT_MODULE_FACTORIES, WASQLiteModuleFactory, WASQLiteVFS } from './vfs.js';
+import { TemporaryStorageOption } from '../options.js';
+import { RawQueryResult, SqliteValue } from '@powersync/common';
+
+export interface RawWebResult extends Required<RawQueryResult> {
+  autocommit: boolean;
+}
 
 export interface RawResultSet {
-  columns: string[];
-  rows: SQLiteCompatibleType[][];
+  columnNames: string[];
+  rawRows: SqliteValue[][];
 }
 
-export interface RawQueryResult {
-  changes: number;
-  lastInsertRowId: number;
-  autocommit: boolean;
-  resultSet: RawResultSet | undefined;
+/**
+ * @internal
+ */
+export interface RawWaSqliteDatabaseOptions {
+  filename: string;
+  readonly: boolean;
+  vfs: WASQLiteVFS;
+  encryptionKey: string | undefined;
+  temporaryStorage: TemporaryStorageOption;
+  cacheSizeKb: number;
 }
 
 /**
@@ -29,7 +39,7 @@ export class RawSqliteConnection {
   private db: number = 0;
   private _moduleFactory: WASQLiteModuleFactory;
 
-  constructor(readonly options: ResolvedWASQLiteOpenFactoryOptions) {
+  constructor(readonly options: RawWaSqliteDatabaseOptions) {
     this._moduleFactory = DEFAULT_MODULE_FACTORIES[this.options.vfs];
   }
 
@@ -40,8 +50,8 @@ export class RawSqliteConnection {
   async init() {
     const api = (this._sqliteAPI = await this.openSQLiteAPI());
     this.db = await api.open_v2(
-      this.options.dbFilename,
-      this.options.isReadOnly ? 1 /* SQLITE_OPEN_READONLY */ : 6 /* SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE */
+      this.options.filename,
+      this.options.readonly ? 1 /* SQLITE_OPEN_READONLY */ : 6 /* SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE */
     );
     await this.executeRaw(`PRAGMA temp_store = ${this.options.temporaryStorage};`);
     if (this.options.encryptionKey) {
@@ -55,7 +65,7 @@ export class RawSqliteConnection {
 
   private async openSQLiteAPI(): Promise<SQLiteAPI> {
     const { module, vfs } = await this._moduleFactory({
-      dbFileName: this.options.dbFilename,
+      dbFileName: this.options.filename,
       encryptionKey: this.options.encryptionKey
     });
     const sqlite3 = WaSqliteFactory(module);
@@ -69,7 +79,7 @@ export class RawSqliteConnection {
      * Create the multiple cipher vfs if an encryption key is provided
      */
     if (this.options.encryptionKey) {
-      const createResult = module.ccall('sqlite3mc_vfs_create', 'int', ['string', 'int'], [this.options.dbFilename, 1]);
+      const createResult = module.ccall('sqlite3mc_vfs_create', 'int', ['string', 'int'], [this.options.filename, 1]);
       if (createResult !== 0) {
         throw new Error('Failed to create multiple cipher vfs, Database encryption will not work');
       }
@@ -93,12 +103,12 @@ export class RawSqliteConnection {
     return this.requireSqlite().get_autocommit(this.db) != 0;
   }
 
-  async execute(sql: string, bindings?: any[]): Promise<RawQueryResult> {
+  async execute(sql: string, bindings?: any[]): Promise<RawWebResult> {
     const resultSet = await this.executeSingleStatementRaw(sql, bindings);
     return this.wrapQueryResults(this.requireSqlite(), resultSet);
   }
 
-  async executeBatch(sql: string, bindings: any[][]): Promise<RawQueryResult[]> {
+  async executeBatch(sql: string, bindings: any[][]): Promise<RawWebResult[]> {
     const results = [];
     const api = this.requireSqlite();
     for await (const stmt of api.statements(this.db, sql)) {
@@ -116,21 +126,22 @@ export class RawSqliteConnection {
     return results;
   }
 
-  private wrapQueryResults(api: SQLiteAPI, rs: RawResultSet | undefined): RawQueryResult {
+  private wrapQueryResults(api: SQLiteAPI, { rawRows, columnNames }: RawResultSet): RawWebResult {
     return {
-      changes: api.changes(this.db),
-      lastInsertRowId: api.last_insert_id(this.db),
+      rowsAffected: api.changes(this.db),
+      insertId: api.last_insert_id(this.db),
       autocommit: api.get_autocommit(this.db) != 0,
-      resultSet: rs
+      rawRows,
+      columnNames
     };
   }
 
   /**
    * This executes a single statement using SQLite3 and returns the results as a {@link RawResultSet}.
    */
-  private async executeSingleStatementRaw(sql: string, bindings?: any[]): Promise<RawResultSet | undefined> {
+  private async executeSingleStatementRaw(sql: string, bindings?: any[]): Promise<RawResultSet> {
     const results = await this.executeRaw(sql, bindings);
-    return results.length ? results[0] : undefined;
+    return results.length ? results[0] : { columnNames: [], rawRows: [] };
   }
 
   async executeRaw(sql: string, bindings?: any[]): Promise<RawResultSet[]> {
@@ -140,7 +151,7 @@ export class RawSqliteConnection {
       let columns;
 
       const rs = await this.stepThroughStatement(api, stmt, bindings ?? [], columns);
-      columns = rs.columns;
+      columns = rs.columnNames;
       if (columns.length) {
         results.push(rs);
       }
@@ -182,7 +193,7 @@ export class RawSqliteConnection {
     }
 
     knownColumns ??= api.column_names(stmt);
-    return { columns: knownColumns, rows };
+    return { columnNames: knownColumns, rawRows: rows };
   }
 
   async close() {