@powersync/web 1.39.0 → 2.1.0

package/src/db/PowerSyncDatabase.ts

@@ -1,53 +1,50 @@
 import {
-  AbstractPowerSyncDatabase,
+  type PowerSyncBackendConnector,
+  type PowerSyncCloseOptions,
+  LogLevels,
+  BasePowerSyncDatabaseOptions,
+  DatabaseSource,
   DBAdapter,
-  PowerSyncDatabaseOptions,
-  PowerSyncDatabaseOptionsWithDBAdapter,
-  PowerSyncDatabaseOptionsWithOpenFactory,
-  PowerSyncDatabaseOptionsWithSettings,
+  PowerSyncDatabaseConstructor,
+  CommonPowerSyncDatabase
+} from '@powersync/common';
+import {
+  BasePowerSyncDatabase,
+  BucketStorageAdapter,
+  CreateSyncImplementationOptions,
+  Mutex,
   SqliteBucketStorage,
   StreamingSyncImplementation,
   TriggerManagerConfig,
-  isDBAdapter,
-  isSQLOpenFactory,
-  Mutex,
-  type BucketStorageAdapter,
-  type PowerSyncBackendConnector,
-  type PowerSyncCloseOptions,
-  type RequiredAdditionalConnectionOptions
-} from '@powersync/common';
+  openDatabase
+} from '@powersync/shared-internals';
 import { getNavigatorLocks } from '../shared/navigator.js';
 import { NAVIGATOR_TRIGGER_CLAIM_MANAGER } from './NavigatorTriggerClaimManager.js';
 import { WebDBAdapter } from './adapters/WebDBAdapter.js';
 import { WASQLiteOpenFactory } from './adapters/wa-sqlite/WASQLiteOpenFactory.js';
-import {
-  DEFAULT_WEB_SQL_FLAGS,
-  ResolvedWebSQLOpenOptions,
-  WebSQLFlags,
-  isServerSide,
-  resolveWebSQLFlags
-} from './adapters/web-sql-flags.js';
+import { WebSpecificOpenOptions, WebSQLOpenOptions } from './adapters/options.js';
 import { SSRStreamingSyncImplementation } from './sync/SSRWebStreamingSyncImplementation.js';
 import { SharedWebStreamingSyncImplementation } from './sync/SharedWebStreamingSyncImplementation.js';
 import { WebRemote } from './sync/WebRemote.js';
-import {
-  WebStreamingSyncImplementation,
-  WebStreamingSyncImplementationOptions
-} from './sync/WebStreamingSyncImplementation.js';
+import { WebStreamingSyncImplementationOptions } from './sync/WebStreamingSyncImplementation.js';
 import { AsyncDbAdapter } from './adapters/AsyncWebAdapter.js';
+import { resolveAndValidateOptions } from './adapters/resolveAndValidateOptions.js';
+import { TabLocalStreamingSyncImplementation } from './sync/TabLocalStreamingSyncImplementation.js';
+
+export type WebPowerSyncDatabaseOptions = BasePowerSyncDatabaseOptions &
+  DatabaseSource<WebSQLOpenOptions> &
+  WebSpecificOptions;
+
+export interface WebSpecificOptions {
+  sync?: WebSyncOptions;
 
-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
+   * Broadcast logs from shared workers, such as the shared sync worker,
+   * to individual tabs. This defaults to true.
    */
-  externallyUnload?: boolean;
+  broadcastLogs?: boolean;
 }
 
-type WithWebFlags<Base> = Base & { flags?: WebPowerSyncFlags };
-
 export interface WebSyncOptions {
   /**
    * Allows you to override the default sync worker.
@@ -55,91 +52,31 @@ export interface WebSyncOptions {
    * You can either provide a path to the worker script
    * or a factory method that returns a worker.
    */
-  worker?: string | URL | ((options: ResolvedWebSQLOpenOptions) => SharedWorker);
-}
-
-type WithWebSyncOptions<Base> = Base & {
-  sync?: WebSyncOptions;
-};
+  worker?: string | URL | (() => SharedWorker);
 
-export interface WebEncryptionOptions {
   /**
-   * Encryption key for the database.
-   * If set, the database will be encrypted using Multiple Ciphers.
+   * The log level for logs from the sync worker.
+   *
+   * Defaults to {@link LogLevels.info}.
    */
-  encryptionKey?: string;
+  logLevel?: number;
 }
 
-type WithWebEncryptionOptions<Base> = Base & WebEncryptionOptions;
-
-export type WebPowerSyncDatabaseOptionsWithAdapter = WithWebSyncOptions<
-  WithWebFlags<PowerSyncDatabaseOptionsWithDBAdapter>
->;
-export type WebPowerSyncDatabaseOptionsWithOpenFactory = WithWebSyncOptions<
-  WithWebFlags<PowerSyncDatabaseOptionsWithOpenFactory>
->;
-export type WebPowerSyncDatabaseOptionsWithSettings = WithWebSyncOptions<
-  WithWebFlags<WithWebEncryptionOptions<PowerSyncDatabaseOptionsWithSettings>>
->;
-
-export type WebPowerSyncDatabaseOptions = WithWebSyncOptions<WithWebFlags<PowerSyncDatabaseOptions>>;
-
-export const DEFAULT_POWERSYNC_FLAGS: Required<WebPowerSyncFlags> = {
-  ...DEFAULT_WEB_SQL_FLAGS,
-  externallyUnload: false
-};
-
-export const resolveWebPowerSyncFlags = (flags?: WebPowerSyncFlags): Required<WebPowerSyncFlags> => {
-  return {
-    ...DEFAULT_POWERSYNC_FLAGS,
-    ...flags,
-    ...resolveWebSQLFlags(flags)
-  };
-};
-
 /**
- * Asserts that the database options are valid for custom database constructors.
+ * @internal Use {@link PowerSyncDatabase} instead, this class is only used by other SDKs also needing web support.
  */
-function assertValidDatabaseOptions(options: WebPowerSyncDatabaseOptions): void {
-  if ('database' in options && 'encryptionKey' in options) {
-    const { database } = options;
-    if (isSQLOpenFactory(database) || isDBAdapter(database)) {
-      throw new Error(
-        `Invalid configuration: 'encryptionKey' should only be included inside the database object when using a custom ${isSQLOpenFactory(database) ? 'WASQLiteOpenFactory' : 'WASQLiteDBAdapter'} constructor.`
-      );
-    }
-  }
-}
-
-/**
- * A PowerSync database which provides SQLite functionality
- * which is automatically synced.
- *
- * @example
- * ```typescript
- * export const db = new PowerSyncDatabase({
- *  schema: AppSchema,
- *  database: {
- *    dbFilename: 'example.db'
- *  }
- * });
- * ```
- */
-export class PowerSyncDatabase extends AbstractPowerSyncDatabase {
+export class WebPowerSyncDatabase extends BasePowerSyncDatabase<WebPowerSyncDatabaseOptions> {
   static SHARED_MUTEX = new Mutex();
 
-  protected resolvedFlags: WebPowerSyncFlags;
+  protected resolvedOpenOptions: WebSpecificOpenOptions;
+  protected enableBroadcastLogs: boolean;
 
-  constructor(options: WebPowerSyncDatabaseOptionsWithAdapter);
-  constructor(options: WebPowerSyncDatabaseOptionsWithOpenFactory);
-  constructor(options: WebPowerSyncDatabaseOptionsWithSettings);
-  constructor(options: WebPowerSyncDatabaseOptions);
-  constructor(protected options: WebPowerSyncDatabaseOptions) {
-    super(options);
-
-    assertValidDatabaseOptions(options);
+  constructor(options: WebPowerSyncDatabaseOptions) {
+    const resolvedOpenOptions = resolveAndValidateOptions('database' in options ? options.database : {});
 
-    this.resolvedFlags = resolveWebPowerSyncFlags(options.flags);
+    super(options);
+    this.resolvedOpenOptions = resolvedOpenOptions;
+    this.enableBroadcastLogs = options.broadcastLogs ?? true;
   }
 
   async _initialize(): Promise<void> {
@@ -170,13 +107,14 @@ export class PowerSyncDatabase extends AbstractPowerSyncDatabase {
     };
   }
 
-  protected openDBAdapter(options: WebPowerSyncDatabaseOptionsWithSettings): DBAdapter {
-    const defaultFactory = new WASQLiteOpenFactory({
-      ...options.database,
-      flags: resolveWebPowerSyncFlags(options.flags),
-      encryptionKey: options.encryptionKey
+  protected override openDBAdapter(): DBAdapter {
+    return openDatabase(this.options, (options) => {
+      const defaultFactory = new WASQLiteOpenFactory({
+        logger: this.logger,
+        open: options
+      });
+      return defaultFactory.openDB();
     });
-    return defaultFactory.openDB();
   }
 
   /**
@@ -187,44 +125,43 @@ export class PowerSyncDatabase extends AbstractPowerSyncDatabase {
   close(options?: PowerSyncCloseOptions): Promise<void> {
     return super.close({
       // Don't disconnect by default if multiple tabs are enabled
-      disconnect: options?.disconnect ?? !this.resolvedFlags.enableMultiTabs
+      disconnect: options?.disconnect ?? !this.resolvedOpenOptions.enableMultiTabs
     });
   }
 
   protected async loadVersion(): Promise<void> {
-    if (isServerSide()) {
+    if (this.resolvedOpenOptions.ssrMode) {
       return;
     }
     return super.loadVersion();
   }
 
   protected async resolveOfflineSyncStatus() {
-    if (isServerSide()) {
+    if (this.resolvedOpenOptions.ssrMode) {
       return;
     }
     return super.resolveOfflineSyncStatus();
   }
 
   protected generateBucketStorageAdapter(): BucketStorageAdapter {
-    return new SqliteBucketStorage(this.database);
+    return new SqliteBucketStorage(this.database, this.logger);
   }
 
   protected async runExclusive<T>(cb: () => Promise<T>) {
-    if (this.resolvedFlags.ssrMode) {
-      return PowerSyncDatabase.SHARED_MUTEX.runExclusive(cb);
+    if (this.resolvedOpenOptions.ssrMode) {
+      return WebPowerSyncDatabase.SHARED_MUTEX.runExclusive(cb);
     }
     return getNavigatorLocks().request(`lock-${this.database.name}`, cb);
   }
 
   protected generateSyncStreamImplementation(
     connector: PowerSyncBackendConnector,
-    options: RequiredAdditionalConnectionOptions
+    options: CreateSyncImplementationOptions
   ): StreamingSyncImplementation {
     const remote = new WebRemote(connector, this.logger);
     const syncOptions: WebStreamingSyncImplementationOptions = {
       ...(this.options as {}),
       ...options,
-      flags: this.resolvedFlags,
       adapter: this.bucketStorageAdapter,
       remote,
       uploadCrud: async () => {
@@ -236,23 +173,42 @@ export class PowerSyncDatabase extends AbstractPowerSyncDatabase {
     };
 
     switch (true) {
-      case this.resolvedFlags.ssrMode:
-        return new SSRStreamingSyncImplementation(syncOptions);
-      case this.resolvedFlags.enableMultiTabs:
-        if (!this.resolvedFlags.broadcastLogs) {
+      case this.resolvedOpenOptions.ssrMode:
+        return new SSRStreamingSyncImplementation();
+      case this.resolvedOpenOptions.enableMultiTabs:
+        if (!this.enableBroadcastLogs) {
           const warning = `
             Multiple tabs are enabled, but broadcasting of logs is disabled.
             Logs for shared sync worker will only be available in the shared worker context
           `;
           const logger = this.options.logger;
-          logger ? logger.warn(warning) : console.warn(warning);
+          logger ? logger.log({ level: LogLevels.warn, message: warning }) : console.warn(warning);
         }
         return new SharedWebStreamingSyncImplementation({
           ...syncOptions,
-          db: this.database as WebDBAdapter // This should always be the case
+          db: this.database as WebDBAdapter, // This should always be the case
+          logLevel: this.options.sync?.logLevel ?? LogLevels.info,
+          enableBroadcastLogs: this.enableBroadcastLogs
         });
       default:
-        return new WebStreamingSyncImplementation(syncOptions);
+        return new TabLocalStreamingSyncImplementation(syncOptions);
     }
   }
 }
+/**
+ * A PowerSync database which provides SQLite functionality
+ * which is automatically synced.
+ *
+ * @example
+ * ```typescript
+ * export const db = new PowerSyncDatabase({
+ *  schema: AppSchema,
+ *  database: {
+ *    dbFilename: 'example.db'
+ *  }
+ * });
+ * ```
+ */
+// Typed constructor to avoid leaking AbstractPowerSyncDatabase into the public interface
+export const PowerSyncDatabase: PowerSyncDatabaseConstructor<WebPowerSyncDatabaseOptions> = WebPowerSyncDatabase;
+export interface PowerSyncDatabase extends CommonPowerSyncDatabase {}

package/src/db/adapters/AsyncWebAdapter.ts

@@ -1,13 +1,5 @@
-import {
-  ConnectionPool,
-  DBAdapterDefaultMixin,
-  DBAdapterListener,
-  DBLockOptions,
-  LockContext,
-  Mutex,
-  Semaphore,
-  UnlockFn
-} from '@powersync/common';
+import { DBAdapter, DBAdapterListener, DBLockOptions, LockContext } from '@powersync/common';
+import { Mutex, Semaphore, UnlockFn } from '@powersync/shared-internals';
 import { SharedConnectionWorker, WebDBAdapter, WebDBAdapterConfiguration } from './WebDBAdapter.js';
 import { DatabaseClient } from './wa-sqlite/DatabaseClient.js';
 
@@ -16,7 +8,7 @@ type PendingListener = { listener: Partial<DBAdapterListener>; closeAfterRegiste
 /**
  * A connection pool implementation delegating to another pool opened asynchronnously.
  */
-class AsyncConnectionPool implements ConnectionPool {
+export class AsyncDbAdapter extends DBAdapter {
   protected readonly state: Promise<PoolState>;
   protected resolvedWriter?: DatabaseClient;
 
@@ -26,6 +18,7 @@ class AsyncConnectionPool implements ConnectionPool {
     inner: Promise<PoolConnection>,
     readonly name: string
   ) {
+    super();
     this.state = inner.then((client) => {
       for (const pending of this.pendingListeners) {
         pending.closeAfterRegisteredOnResolvedPool = client.writer.registerListener(pending.listener);
@@ -81,6 +74,19 @@ class AsyncConnectionPool implements ConnectionPool {
       };
     }
   }
+
+  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.');
+  }
 }
 
 export interface PoolConnection {
@@ -126,7 +132,7 @@ function readWritePoolState(writer: DatabaseClient, readers: DatabaseClient[]):
       let timeout: any = null;
       let release: UnlockFn | undefined;
       if (options?.timeoutMs) {
-        timeout = setTimeout(() => abortController.abort, options.timeoutMs);
+        timeout = setTimeout(() => abortController.abort('requesting database timed out'), options.timeoutMs);
       }
 
       try {
@@ -190,18 +196,3 @@ function readWritePoolState(writer: DatabaseClient, readers: DatabaseClient[]):
     }
   };
 }
-
-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

@@ -1,17 +1,10 @@
-import {
-  BaseObserver,
-  DBAdapterListener,
-  DBAdapter,
-  DBLockOptions,
-  LockContext,
-  QueryResult,
-  Transaction,
-  Mutex,
-  timeoutSignal
-} from '@powersync/common';
+import { DBAdapter, DBLockOptions, LockContext, RawQueryResult } from '@powersync/common';
+import { Mutex } from '@powersync/shared-internals';
 
-const MOCK_QUERY_RESPONSE: QueryResult = {
-  rowsAffected: 0
+const MOCK_QUERY_RESPONSE: RawQueryResult = {
+  rowsAffected: 0,
+  columnNames: [],
+  rawRows: []
 };
 
 /**
@@ -19,7 +12,7 @@ const MOCK_QUERY_RESPONSE: QueryResult = {
  * 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 {
+export class SSRDBAdapter extends DBAdapter {
   name: string;
   readMutex: Mutex;
   writeMutex: Mutex;
@@ -34,61 +27,18 @@ 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), timeoutSignal(options?.timeoutMs));
-  }
-
-  async readTransaction<T>(fn: (tx: Transaction) => Promise<T>, options?: DBLockOptions) {
-    return this.readLock(() => fn(this.generateMockTransactionContext()), options);
+    return fn(new StubLockContext());
   }
 
   async writeLock<T>(fn: (tx: LockContext) => Promise<T>, options?: DBLockOptions) {
-    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()), options);
-  }
-
-  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);
+    return fn(new StubLockContext());
   }
 
-  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`);
-  }
+  async refreshSchema(): Promise<void> {}
+}
 
-  /**
-   * 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;
-      }
-    };
+class StubLockContext extends LockContext {
+  async executeRaw(): Promise<RawQueryResult> {
+    return MOCK_QUERY_RESPONSE;
   }
-
-  async refreshSchema(): Promise<void> {}
 }

package/src/db/adapters/WebDBAdapter.ts

@@ -1,5 +1,5 @@
 import { DBAdapter } from '@powersync/common';
-import { ResolvedWebSQLOpenOptions } from './web-sql-flags.js';
+import { ResolvedWebSQLOpenOptions } from './options.js';
 
 export type SharedConnectionWorker = {
   identifier: string;

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,49 @@
+import { LogLevels } from '@powersync/common';
+import { TemporaryStorageOption, WebSpecificOpenOptions } from './options.js';
+import { vfsRequiresDedicatedWorkers, WASQLiteVFS } from './wa-sqlite/vfs.js';
+
+/**
+ * The maximum length of a db filename we support.
+ *
+ * We configure the same on WA-SQLite (which otherwise defaults to a maximum length of 64). We don't want to support
+ * very long path names as Safari maps OPFS files directly to OS files, and APFS has a 255-byte filename limit. Since
+ * some VFS append additional characters for pooled file access handles, we want to stay well below that.
+ */
+export const maxPathNameLength = 128;
+
+/**
+ * @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();