@powersync/web 1.38.7 → 2.0.0

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

@@ -1,70 +1,31 @@
-import { createLogger, DBAdapter, ILogger, SQLOpenFactory, type ILogLevel } from '@powersync/common';
+import { DBAdapter, LogLevels, PowerSyncLogger, SQLOpenFactory } from '@powersync/common';
 import * as Comlink from 'comlink';
-import { openWorkerDatabasePort, resolveWorkerDatabasePortFactory } from '../../../worker/db/open-worker-database.js';
-import {
-  DEFAULT_CACHE_SIZE_KB,
-  isServerSide,
-  ResolvedWebSQLFlags,
-  ResolvedWebSQLOpenOptions,
-  resolveWebSQLFlags,
-  TemporaryStorageOption,
-  WebSQLOpenFactoryOptions
-} from '../web-sql-flags.js';
+import { ResolvedWebSQLOpenOptions, WebSQLOpenOptions } from '../options.js';
 import { SSRDBAdapter } from '../SSRDBAdapter.js';
 import { vfsRequiresDedicatedWorkers, WASQLiteVFS } from './vfs.js';
 import { MultiDatabaseServer } from '../../../worker/db/MultiDatabaseServer.js';
 import { DatabaseClient, OpenWorkerConnection } from './DatabaseClient.js';
 import { generateTabCloseSignal } from '../../../shared/tab_close_signal.js';
 import { AsyncDbAdapter, PoolConnection } from '../AsyncWebAdapter.js';
+import { RawWaSqliteDatabaseOptions } from './RawSqliteConnection.js';
+import { resolveAndValidateOptions } from '../resolveAndValidateOptions.js';
+import { connectToExistingWorker, connectToWorker, WorkerConnection } from '../../../worker/client.js';
 
-export interface WASQLiteOpenFactoryOptions extends WebSQLOpenFactoryOptions {
-  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;
-}
-
-export interface ResolvedWASQLiteOpenFactoryOptions extends ResolvedWebSQLOpenOptions {
-  vfs: WASQLiteVFS;
-
-  /**
-   * Whether this is a read-only connection opened for the `OPFSWriteAheadVFS` file system.
-   */
-  isReadOnly: boolean;
-}
-
-export interface WorkerDBOpenerOptions extends ResolvedWASQLiteOpenFactoryOptions {
-  logLevel: ILogLevel;
-  /**
-   * A lock that is currently held by the client. When the lock is returned, we know the client is gone and that we need
-   * to clean up resources.
-   */
-  lockName: string;
+export interface WASQLiteOpenFactoryOptions {
+  open: WebSQLOpenOptions;
+  logger: PowerSyncLogger;
 }
 
 /**
  * Opens a SQLite connection using WA-SQLite.
  */
 export class WASQLiteOpenFactory implements SQLOpenFactory {
-  private resolvedFlags: ResolvedWebSQLFlags;
-  private logger: ILogger;
-
-  constructor(private options: WASQLiteOpenFactoryOptions) {
-    assertValidWASQLiteOpenFactoryOptions(options);
-    this.resolvedFlags = resolveWebSQLFlags(options.flags);
-    this.logger = options.logger ?? createLogger(`WASQLiteOpenFactory - ${this.options.dbFilename}`);
-  }
+  private options: ResolvedWebSQLOpenOptions;
+  private logger: PowerSyncLogger;
 
-  get waOptions(): WASQLiteOpenFactoryOptions {
-    // Cast to extended type
-    return this.options;
+  constructor(options: WASQLiteOpenFactoryOptions) {
+    this.options = resolveAndValidateOptions(options.open);
+    this.logger = options.logger;
   }
 
   protected openAdapter(): DBAdapter {
@@ -72,84 +33,80 @@ export class WASQLiteOpenFactory implements SQLOpenFactory {
   }
 
   openDB(): DBAdapter {
-    const {
-      resolvedFlags: { disableSSRWarning, enableMultiTabs, ssrMode = isServerSide() }
-    } = this;
+    const { disableSSRWarning, enableMultiTabs, ssrMode } = this.options;
+
     if (ssrMode) {
       if (!disableSSRWarning) {
-        this.logger.warn(
-          `
+        this.logger.log({
+          level: LogLevels.warn,
+          message: `
       Running PowerSync in SSR mode.
       Only empty query results will be returned.
       Disable this warning by setting 'disableSSRWarning: true' in options.`
-        );
+        });
       }
 
       return new SSRDBAdapter();
     }
 
     if (!enableMultiTabs) {
-      this.logger.warn(
-        'Multiple tab support is not enabled. Using this site across multiple tabs may not function correctly.'
-      );
+      this.logger.log({
+        level: LogLevels.warn,
+        message: 'Multiple tab support is not enabled. Using this site across multiple tabs may not function correctly.'
+      });
     }
 
     return this.openAdapter();
   }
 
   async openConnection(): Promise<PoolConnection> {
-    const { enableMultiTabs, useWebWorker } = this.resolvedFlags;
-    const {
-      vfs = WASQLiteVFS.IDBBatchAtomicVFS,
-      temporaryStorage = TemporaryStorageOption.MEMORY,
-      cacheSizeKb = DEFAULT_CACHE_SIZE_KB,
-      encryptionKey
-    } = this.waOptions;
+    const { enableMultiTabs, useWebWorker, vfs, dbFilename, encryptionKey, temporaryStorage, cacheSizeKb } =
+      this.options;
 
     if (!enableMultiTabs) {
-      this.logger.warn('Multiple tabs are not enabled in this browser');
+      this.logger.log({ level: LogLevels.warn, message: 'Multiple tabs are not enabled in this browser' });
     }
 
-    const resolveOptions = (isReadOnly: boolean): ResolvedWASQLiteOpenFactoryOptions => ({
-      dbFilename: this.options.dbFilename,
-      dbLocation: this.options.dbLocation,
-      debugMode: this.options.debugMode,
-      vfs,
-      temporaryStorage,
-      cacheSizeKb,
-      flags: this.resolvedFlags,
-      encryptionKey: encryptionKey,
-      isReadOnly
-    });
-
     let client: DatabaseClient;
     let additionalReaders: DatabaseClient[] = [];
     let requiresPersistentTriggers = vfsRequiresDedicatedWorkers(vfs);
 
+    function resolveRawWaSqliteDatabaseOptions(readonly: boolean): RawWaSqliteDatabaseOptions {
+      return {
+        filename: dbFilename,
+        readonly,
+        vfs,
+        encryptionKey,
+        temporaryStorage,
+        cacheSizeKb
+      };
+    }
+
     if (useWebWorker) {
       const optionsDbWorker = this.options.worker;
 
-      const openDatabaseWorker = async (
-        resolvedOptions: ResolvedWASQLiteOpenFactoryOptions
-      ): Promise<DatabaseClient> => {
-        const workerPort =
-          typeof optionsDbWorker == 'function'
-            ? resolveWorkerDatabasePortFactory(() =>
-                optionsDbWorker({
-                  ...this.options,
-                  temporaryStorage,
-                  cacheSizeKb,
-                  flags: this.resolvedFlags,
-                  encryptionKey
-                })
-              )
-            : openWorkerDatabasePort(this.options.dbFilename, enableMultiTabs, optionsDbWorker, this.waOptions.vfs);
-
-        const source = Comlink.wrap<OpenWorkerConnection>(workerPort);
+      const openDatabaseWorker = async (readonly: boolean): Promise<DatabaseClient> => {
+        let workerConnection: WorkerConnection;
+        if (typeof optionsDbWorker == 'function') {
+          const worker = optionsDbWorker(this.options);
+          workerConnection = connectToExistingWorker(worker, 'database');
+        } else {
+          const needsDedicated = vfsRequiresDedicatedWorkers(vfs);
+          const useShared = !needsDedicated && enableMultiTabs;
+
+          workerConnection = connectToWorker({
+            service: 'database',
+            databaseIdentifier: this.options.dbFilename,
+            shared: useShared,
+            customWorker: optionsDbWorker
+          });
+        }
+
+        const source = Comlink.wrap<OpenWorkerConnection>(workerConnection.endpoint);
         const closeSignal = new AbortController();
         const connection = await source.connect({
-          ...resolvedOptions,
-          logLevel: this.logger.getLevel(),
+          database: resolveRawWaSqliteDatabaseOptions(readonly),
+          logLevel: this.options.databaseWorkerLogLevel,
           lockName: await generateTabCloseSignal(closeSignal.signal)
         });
         const clientOptions = {
@@ -159,28 +116,24 @@ export class WASQLiteOpenFactory implements SQLOpenFactory {
           remoteCanCloseUnexpectedly: false,
           onClose: () => {
             closeSignal.abort();
-            if (workerPort instanceof Worker) {
-              workerPort.terminate();
-            } else {
-              workerPort.close();
-            }
+            workerConnection.close();
           }
         };
 
         return new DatabaseClient(clientOptions, {
-          ...resolvedOptions,
+          ...this.options,
           requiresPersistentTriggers
         });
       };
 
-      client = await openDatabaseWorker(resolveOptions(false));
+      client = await openDatabaseWorker(false);
 
       if (vfs == WASQLiteVFS.OPFSWriteAheadVFS) {
         // This VFS supports concurrent reads, so we can open additional workers to host read-only connections for
         // concurrent reads / writes.
         const additionalReadersCount = this.options.additionalReaders ?? 1;
         for (let i = 0; i < additionalReadersCount; i++) {
-          const reader = await openDatabaseWorker(resolveOptions(true));
+          const reader = await openDatabaseWorker(true);
           additionalReaders.push(reader);
         }
       }
@@ -189,12 +142,11 @@ export class WASQLiteOpenFactory implements SQLOpenFactory {
       const localServer = new MultiDatabaseServer(this.logger);
       requiresPersistentTriggers = true;
 
-      const resolvedOptions = resolveOptions(false);
-      const connection = await localServer.openConnectionLocally(resolvedOptions);
+      const connection = await localServer.openConnectionLocally(this.logger, resolveRawWaSqliteDatabaseOptions(false));
       client = new DatabaseClient(
         { connection, source: null, remoteCanCloseUnexpectedly: false },
         {
-          ...resolvedOptions,
+          ...this.options,
           requiresPersistentTriggers
         }
       );
@@ -206,18 +158,3 @@ export class WASQLiteOpenFactory implements SQLOpenFactory {
     };
   }
 }
-
-/**
- * Asserts that the factory options are valid.
- */
-function assertValidWASQLiteOpenFactoryOptions(options: WASQLiteOpenFactoryOptions): void {
-  // The OPFS VFS only works in dedicated web workers.
-  if ('vfs' in options && 'flags' in options) {
-    const { vfs, flags = {} } = options;
-    if (vfs && vfsRequiresDedicatedWorkers(vfs) && 'useWebWorker' in flags && !flags.useWebWorker) {
-      throw new Error(
-        `Invalid configuration: The 'useWebWorker' flag must be true when using an OPFS-based VFS (${vfs}).`
-      );
-    }
-  }
-}

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

@@ -1,4 +1,5 @@
 import type * as SQLite from '@journeyapps/wa-sqlite';
+import { RawWaSqliteDatabaseOptions } from './RawSqliteConnection.js';
 
 /**
  * List of currently tested virtual filesystems
@@ -7,11 +8,28 @@ export enum WASQLiteVFS {
   IDBBatchAtomicVFS = 'IDBBatchAtomicVFS',
   OPFSCoopSyncVFS = 'OPFSCoopSyncVFS',
   AccessHandlePoolVFS = 'AccessHandlePoolVFS',
-  OPFSWriteAheadVFS = 'OPFSWriteAheadVFS'
+  OPFSWriteAheadVFS = 'OPFSWriteAheadVFS',
+  /**
+   * A virtual file system storing data in-memory only, without persistence.
+   *
+   * This file system can be used in three configurations:
+   *
+   * 1. In shared workers (the default when available): All tabs share the same in-memory database, which is cleared
+   *    once the last tab is closed.
+   * 2. In dedicated workers (used when `enableMultiTabs` is disabled). Each tab has its own in-memory database cleared
+   *    when the tab is closed. Queries are offloaded to a dedicated worker.
+   * 3. In the context of the tab itself (used when both `enableMultiTabs` and `useWebWorker` are disabled). The per-tab
+   *    database is hosted in the tab itself, and queries run synchronously. This is _a lot_ faster than any other
+   *    single-threadedVFS, but can block JavaScript for computationally-intensive queries.
+   *
+   * This VFS primarily intended for development, but it also useful for online-first deployments not syncing large
+   * amounts of data, as it is quicker to start up.
+   */
+  InMemoryVfs = 'InMemoryVFS'
 }
 
 export function vfsRequiresDedicatedWorkers(vfs: WASQLiteVFS) {
-  return vfs != WASQLiteVFS.IDBBatchAtomicVFS;
+  return vfs != WASQLiteVFS.IDBBatchAtomicVFS && vfs != WASQLiteVFS.InMemoryVfs;
 }
 
 /**
@@ -24,14 +42,7 @@ export type WASQLiteModuleFactoryOptions = { dbFileName: string; encryptionKey?:
  */
 export type SQLiteModule = Parameters<typeof SQLite.Factory>[0];
 
-/**
- * @internal
- */
-export type WASQLiteModuleFactory = (
-  options: WASQLiteModuleFactoryOptions
-) => Promise<{ module: SQLiteModule; vfs: SQLiteVFS }>;
-
-async function asyncModuleFactory(encryptionKey: unknown) {
+async function asyncModuleFactory(encryptionKey: string | undefined): Promise<SQLiteModule> {
   if (encryptionKey) {
     const { default: factory } = await import('@journeyapps/wa-sqlite/dist/mc-wa-sqlite-async.mjs');
     return factory();
@@ -41,7 +52,7 @@ async function asyncModuleFactory(encryptionKey: unknown) {
   }
 }
 
-async function syncModuleFactory(encryptionKey: unknown) {
+async function syncModuleFactory(encryptionKey: string | undefined): Promise<SQLiteModule> {
   if (encryptionKey) {
     const { default: factory } = await import('@journeyapps/wa-sqlite/dist/mc-wa-sqlite.mjs');
     return factory();
@@ -54,43 +65,50 @@ async function syncModuleFactory(encryptionKey: unknown) {
 /**
  * @internal
  */
-export const DEFAULT_MODULE_FACTORIES = {
-  [WASQLiteVFS.IDBBatchAtomicVFS]: async (options: WASQLiteModuleFactoryOptions) => {
-    const module = await asyncModuleFactory(options.encryptionKey);
-    const { IDBBatchAtomicVFS } = await import('@journeyapps/wa-sqlite/src/examples/IDBBatchAtomicVFS.js');
-    return {
-      module,
+export async function loadModuleAndVfs({
+  vfs,
+  filename,
+  encryptionKey
+}: RawWaSqliteDatabaseOptions): Promise<{ module: SQLiteModule; vfs: SQLiteVFS }> {
+  let moduleFactory = syncModuleFactory;
+  let resolveVfs: (module: any) => Promise<SQLiteVFS>;
+
+  switch (vfs) {
+    case WASQLiteVFS.IDBBatchAtomicVFS: {
+      moduleFactory = asyncModuleFactory;
+      const { IDBBatchAtomicVFS } = await import('@journeyapps/wa-sqlite/src/examples/IDBBatchAtomicVFS.js');
+      resolveVfs = (module) => {
+        // @ts-expect-error The types for this static method are missing upstream
+        return IDBBatchAtomicVFS.create(filename, module, { lockPolicy: 'exclusive' });
+      };
+      break;
+    }
+    case WASQLiteVFS.AccessHandlePoolVFS: {
+      // @ts-expect-error The types for this import are missing upstream
+      const { AccessHandlePoolVFS } = await import('@journeyapps/wa-sqlite/src/examples/AccessHandlePoolVFS.js');
+      resolveVfs = (module) => AccessHandlePoolVFS.create(filename, module);
+      break;
+    }
+    case WASQLiteVFS.OPFSCoopSyncVFS: {
+      // @ts-expect-error The types for this import are missing upstream
+      const { OPFSCoopSyncVFS } = await import('@journeyapps/wa-sqlite/src/examples/OPFSCoopSyncVFS.js');
+      resolveVfs = (module) => OPFSCoopSyncVFS.create(filename, module);
+      break;
+    }
+    case WASQLiteVFS.OPFSWriteAheadVFS: {
+      // @ts-expect-error The types for this import are missing upstream
+      const { OPFSWriteAheadVFS } = await import('@journeyapps/wa-sqlite/src/examples/OPFSWriteAheadVFS.js');
+      resolveVfs = (module) => OPFSWriteAheadVFS.create(filename, module, {});
+      break;
+    }
+    case WASQLiteVFS.InMemoryVfs: {
+      const { MemoryVFS } = await import('@journeyapps/wa-sqlite/src/examples/MemoryVFS.js');
       // @ts-expect-error The types for this static method are missing upstream
-      vfs: await IDBBatchAtomicVFS.create(options.dbFileName, module, { lockPolicy: 'exclusive' })
-    };
-  },
-  [WASQLiteVFS.AccessHandlePoolVFS]: async (options: WASQLiteModuleFactoryOptions) => {
-    const module = await syncModuleFactory(options.encryptionKey);
-    // @ts-expect-error The types for this static method are missing upstream
-    const { AccessHandlePoolVFS } = await import('@journeyapps/wa-sqlite/src/examples/AccessHandlePoolVFS.js');
-    return {
-      module,
-      vfs: await AccessHandlePoolVFS.create(options.dbFileName, module)
-    };
-  },
-  [WASQLiteVFS.OPFSCoopSyncVFS]: async (options: WASQLiteModuleFactoryOptions) => {
-    const module = await syncModuleFactory(options.encryptionKey);
-    // @ts-expect-error The types for this static method are missing upstream
-    const { OPFSCoopSyncVFS } = await import('@journeyapps/wa-sqlite/src/examples/OPFSCoopSyncVFS.js');
-    const vfs = await OPFSCoopSyncVFS.create(options.dbFileName, module);
-    return {
-      module,
-      vfs
-    };
-  },
-  [WASQLiteVFS.OPFSWriteAheadVFS]: async (options: WASQLiteModuleFactoryOptions) => {
-    const module = await syncModuleFactory(options.encryptionKey);
-    // @ts-expect-error The types for this static method are missing upstream
-    const { OPFSWriteAheadVFS } = await import('@journeyapps/wa-sqlite/src/examples/OPFSWriteAheadVFS.js');
-    const vfs = await OPFSWriteAheadVFS.create(options.dbFileName, module, {});
-    return {
-      module,
-      vfs
-    };
+      resolveVfs = (module) => MemoryVFS.create(filename, module);
+      break;
+    }
   }
-};
+
+  const module = await moduleFactory(encryptionKey);
+  return { module, vfs: await resolveVfs(module) };
+}

package/src/db/sync/SSRWebStreamingSyncImplementation.ts

@@ -1,14 +1,5 @@
-import {
-  AbstractStreamingSyncImplementationOptions,
-  BaseObserver,
-  LockOptions,
-  LockType,
-  Mutex,
-  PowerSyncConnectionOptions,
-  StreamingSyncImplementation,
-  SyncStatus,
-  SyncStatusOptions
-} from '@powersync/common';
+import { BaseObserver, SyncStatus } from '@powersync/common';
+import { Mutex, StreamingSyncImplementation, LockOptions, LockType } from '@powersync/shared-internals';
 
 export class SSRStreamingSyncImplementation extends BaseObserver implements StreamingSyncImplementation {
   syncMutex: Mutex;
@@ -16,13 +7,11 @@ export class SSRStreamingSyncImplementation extends BaseObserver implements Stre
 
   isConnected: boolean;
   lastSyncedAt?: Date | undefined;
-  syncStatus: SyncStatus;
 
-  constructor(options: AbstractStreamingSyncImplementationOptions) {
+  constructor() {
     super();
     this.syncMutex = new Mutex();
     this.crudMutex = new Mutex();
-    this.syncStatus = new SyncStatus({});
     this.isConnected = false;
   }
 
@@ -34,7 +23,7 @@ export class SSRStreamingSyncImplementation extends BaseObserver implements Stre
   /**
    * This is a no-op in SSR mode
    */
-  async connect(options?: PowerSyncConnectionOptions): Promise<void> {}
+  async connect(): Promise<void> {}
 
   async dispose() {}
 
@@ -48,13 +37,6 @@ export class SSRStreamingSyncImplementation extends BaseObserver implements Stre
    */
   async waitForReady() {}
 
-  /**
-   * This will never resolve in SSR Mode.
-   */
-  async waitForStatus(status: SyncStatusOptions) {
-    return this.waitUntilStatusMatches(() => false);
-  }
-
   /**
    * This will never resolve in SSR Mode.
    */