@powersync/web 2.4.2 → 2.6.0

package/src/db/adapters/options.ts

@@ -64,6 +64,17 @@ export interface WebSpecificOpenOptions {
 
   vfs: WASQLiteVFS;
 
+  /**
+   * Names of additional no-argument WebAssembly exports to call after the PowerSync core initializer and before
+   * opening each SQLite connection, in array order. Each must register a statically linked extension, return
+   * SQLITE_OK (0) on success, and be safe to call more than once for a module.
+   *
+   * Requires a custom wa-sqlite build exporting these functions and a worker bundled against its matching JavaScript.
+   * Use exported names without Emscripten's leading underscore, e.g. `decimal_init_static`.
+   * Defaults to no additional initialization functions.
+   */
+  additionalInitializationFunctions?: readonly string[];
+
   /**
    * 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.
@@ -96,6 +107,27 @@ export interface WebSpecificOpenOptions {
    * Defaults to 0 (disabling the cache).
    */
   preparedStatementsCache?: number;
+
+  /**
+   * The name of a [Storage Bucket](https://wicg.github.io/storage-buckets/) to keep the database files in,
+   * instead of the default bucket of the origin private file system.
+   *
+   * Only supported by the OPFS-based VFS implementations: {@link WASQLiteVFS.OPFSCoopSyncVFS},
+   * {@link WASQLiteVFS.OPFSWriteAheadVFS} and {@link WASQLiteVFS.AccessHandlePoolVFS}. Opening the database fails in
+   * a browser without the Storage Buckets API, so set this option only when `'storageBuckets' in navigator`.
+   *
+   * The SDK forwards the name to `navigator.storageBuckets.open()` unchanged, so the browser reports a name it does not
+   * accept. The bucket is opened by name, with the browser's default options. To configure options for the bucket,
+   * call and await `navigator.storageBuckets.open()` before opening a PowerSync database.
+   *
+   * A database in a bucket is a different database from one of the same name in the default bucket: setting this
+   * option for an existing database starts with an empty database, and the files in the default bucket are not
+   * moved. The SDK groups database resources by database name, without taking the storage bucket into account. To
+   * avoid lock contention and wrong update notifications, use unique database names even across buckets.
+   *
+   * Uses the default bucket when no option is given.
+   */
+  storageBucket?: string;
 }
 
 export interface ResolvedWebSQLOpenOptions extends SQLOpenOptions, WebSpecificOpenOptions {}

package/src/db/adapters/resolveAndValidateOptions.ts

@@ -1,6 +1,6 @@
 import { LogLevels } from '@powersync/common';
 import { TemporaryStorageOption, WebSpecificOpenOptions } from './options.js';
-import { vfsRequiresDedicatedWorkers, WASQLiteVFS } from './wa-sqlite/vfs.js';
+import { vfsRequiresDedicatedWorkers, vfsSupportsStorageBuckets, WASQLiteVFS } from './wa-sqlite/vfs.js';
 
 /**
  * The maximum length of a db filename we support.
@@ -45,5 +45,13 @@ export function resolveAndValidateOptions<And = {}>(
     );
   }
 
+  if (resolved.storageBucket != null) {
+    if (!vfsSupportsStorageBuckets(resolved.vfs)) {
+      throw new Error(
+        `Invalid configuration: The 'storageBucket' option needs an OPFS-based VFS, which ${resolved.vfs} is not.`
+      );
+    }
+  }
+
   return resolved;
 }

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

@@ -29,6 +29,11 @@ export interface RawWaSqliteDatabaseOptions {
    * The amount of prepared statements to cache, or 0 to disable caching.
    */
   preparedStatementsCache: number;
+  additionalInitializationFunctions?: readonly string[];
+  /**
+   * The name of a Storage Bucket to keep the database files in, for the OPFS-based VFS implementations.
+   */
+  storageBucket?: string;
 }
 
 /**
@@ -84,9 +89,14 @@ export class RawSqliteConnection {
     const sqlite3 = WaSqliteFactory(module);
     sqlite3.vfs_register(vfs, true);
     /**
-     * Register the PowerSync core SQLite extension
+     * Register the PowerSync core and additional statically linked extensions
      */
-    module.ccall('powersync_init_static', 'int', []);
+    for (const name of ['powersync_init_static', ...(this.options.additionalInitializationFunctions ?? [])]) {
+      const result = module.ccall(name, 'int', []);
+      if (result !== 0) {
+        throw new Error(`SQLite extension initializer ${name} failed with code ${result}`);
+      }
+    }
 
     /**
      * Create the multiple cipher vfs if an encryption key is provided

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

@@ -75,7 +75,9 @@ export class WASQLiteOpenFactory implements SQLOpenFactory {
       encryptionKey,
       temporaryStorage,
       cacheSizeKb,
-      preparedStatementsCache
+      preparedStatementsCache,
+      additionalInitializationFunctions,
+      storageBucket
     } = this.options;
 
     if (!enableMultiTabs) {
@@ -95,7 +97,9 @@ export class WASQLiteOpenFactory implements SQLOpenFactory {
         temporaryStorage,
         cacheSizeKb,
         // TODO: Enable prepared statement cache by default?
-        preparedStatementsCache: preparedStatementsCache ?? 0
+        preparedStatementsCache: preparedStatementsCache ?? 0,
+        additionalInitializationFunctions,
+        storageBucket
       };
     }
 

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

@@ -1,5 +1,6 @@
 import type * as SQLite from '@journeyapps/wa-sqlite';
 import { RawWaSqliteDatabaseOptions } from './RawSqliteConnection.js';
+import type { WebSpecificOpenOptions } from '../options.js';
 
 /**
  * List of currently tested virtual filesystems
@@ -32,6 +33,51 @@ export function vfsRequiresDedicatedWorkers(vfs: WASQLiteVFS) {
   return vfs != WASQLiteVFS.IDBBatchAtomicVFS && vfs != WASQLiteVFS.InMemoryVfs;
 }
 
+/**
+ * Whether the VFS can keep its files in a Storage Bucket, see {@link WebSpecificOpenOptions.storageBucket}.
+ */
+export function vfsSupportsStorageBuckets(vfs: WASQLiteVFS) {
+  return (
+    vfs == WASQLiteVFS.OPFSCoopSyncVFS || vfs == WASQLiteVFS.OPFSWriteAheadVFS || vfs == WASQLiteVFS.AccessHandlePoolVFS
+  );
+}
+
+/**
+ * The part of the Storage Buckets API this module uses. The API is not in the TypeScript DOM library yet.
+ */
+export interface StorageBucketManagerLike {
+  open(name: string): Promise<{ getDirectory(): Promise<FileSystemDirectoryHandle> }>;
+}
+
+/**
+ * Options for an OPFS-based VFS that keep its files in the named Storage Bucket, see
+ * {@link WebSpecificOpenOptions.storageBucket}. Without a bucket name, no options: the VFS uses the root of the
+ * origin private file system.
+ *
+ * @internal
+ */
+export function vfsOptionsForStorageBucket(
+  storageBucket: string | undefined,
+  storageBuckets: StorageBucketManagerLike | null | undefined = (navigator as any).storageBuckets
+): { getRoot?: () => Promise<FileSystemDirectoryHandle>; prefix?: string } {
+  if (storageBucket == null) {
+    return {};
+  }
+  if (storageBuckets == null) {
+    throw new Error(
+      `The 'storageBucket' option needs the Storage Buckets API (navigator.storageBuckets), which this browser does not have. Check for it before setting the option.`
+    );
+  }
+  return {
+    // Called by the VFS each time it needs its root directory. Opening the bucket again creates it when the
+    // browser deleted it with the rest of the site's data.
+    getRoot: () => storageBuckets.open(storageBucket).then((bucket) => bucket.getDirectory()),
+    // Keeps the locks and channels of a file apart from those of a file of the same name in another bucket.
+    // Bucket names cannot contain ':', so the names of two buckets never overlap.
+    prefix: `${storageBucket}:`
+  };
+}
+
 /**
  * @internal
  */
@@ -68,7 +114,8 @@ async function syncModuleFactory(encryptionKey: string | undefined): Promise<SQL
 export async function loadModuleAndVfs({
   vfs,
   filename,
-  encryptionKey
+  encryptionKey,
+  storageBucket
 }: RawWaSqliteDatabaseOptions): Promise<{ module: SQLiteModule; vfs: SQLiteVFS }> {
   let moduleFactory = syncModuleFactory;
   let resolveVfs: (module: any) => Promise<SQLiteVFS>;
@@ -86,19 +133,19 @@ export async function loadModuleAndVfs({
     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);
+      resolveVfs = (module) => AccessHandlePoolVFS.create(filename, module, vfsOptionsForStorageBucket(storageBucket));
       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);
+      resolveVfs = (module) => OPFSCoopSyncVFS.create(filename, module, vfsOptionsForStorageBucket(storageBucket));
       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, {});
+      resolveVfs = (module) => OPFSWriteAheadVFS.create(filename, module, vfsOptionsForStorageBucket(storageBucket));
       break;
     }
     case WASQLiteVFS.InMemoryVfs: {

package/src/db/sync/SharedWebStreamingSyncImplementation.ts

@@ -9,7 +9,12 @@ import {
   WebStreamingSyncImplementationOptions
 } from './WebStreamingSyncImplementation.js';
 import { generateTabCloseSignal } from '../../shared/tab_close_signal.js';
-import { SubscribedStream, SyncStatusJson, ResolvedSyncOptions } from '@powersync/shared-internals';
+import {
+  SubscribedStream,
+  SyncStatusJson,
+  ResolvedSyncOptions,
+  serializeErrorForRelay
+} from '@powersync/shared-internals';
 import { connectToExistingWorker, connectToWorker, WorkerConnection } from '../../worker/client.js';
 
 /**
@@ -30,12 +35,25 @@ class SharedSyncClientProvider extends AbstractSharedSyncClientProvider {
     return Comlink.transfer(port, [port]);
   }
 
+  async #relay<T>(action: () => Promise<T>): Promise<T> {
+    try {
+      return await action();
+    } catch (ex) {
+      /**
+       * Connector callbacks run in this tab and their rejection crosses the
+       * MessagePort to the sync worker, so serialize it here, where the error
+       * originates, before Comlink's error transfer can drop custom fields.
+       */
+      throw serializeErrorForRelay(ex);
+    }
+  }
+
   invalidateCredentials() {
     this.options.remote.invalidateCredentials();
   }
 
   async fetchCredentials(): Promise<PowerSyncCredentials | null> {
-    const credentials = await this.options.remote.getCredentials();
+    const credentials = await this.#relay(() => this.options.remote.getCredentials());
     if (credentials == null) {
       return null;
     }
@@ -56,11 +74,13 @@ class SharedSyncClientProvider extends AbstractSharedSyncClientProvider {
      * Don't return anything here, just incase something which is not
      * serializable is returned from the `uploadCrud` function.
      */
-    await this.options.uploadCrud();
+    await this.#relay(() => this.options.connector.uploadCrud!());
   }
 
   override async postCheckpointRequest(clientId: string, requestId: string): Promise<string | null> {
-    return await this.options.postCheckpointRequest(clientId, requestId);
+    return await this.#relay(
+      async () => (await this.options.connector.postCheckpointRequest!(clientId, requestId)) ?? null
+    );
   }
 
   get logger() {
@@ -159,10 +179,14 @@ export class SharedWebStreamingSyncImplementation extends WebStreamingSyncImplem
      * - The client sends the params to the shared worker after locks have been registered.
      */
     const closeSignal = await generateTabCloseSignal(this.abortOnClose.signal);
-    // Awaiting here ensures the worker is waiting for the lock
-    await this.syncManager.addLockBasedCloseSignal(closeSignal);
+    const { identifier, connector } = this.options;
 
-    const { identifier } = this.options;
+    // Awaiting here ensures the worker is waiting for the lock
+    await this.syncManager.initialize(closeSignal, {
+      hasFetchCredentials: !!connector.fetchCredentials,
+      hasPostCheckpointRequest: !!connector.postCheckpointRequest,
+      hasUploadCrud: !!connector.uploadCrud
+    });
 
     await this.syncManager.setParams(
       {
@@ -192,9 +216,30 @@ export class SharedWebStreamingSyncImplementation extends WebStreamingSyncImplem
   }
 
   async dispose(): Promise<void> {
-    await this.waitForReady();
+    let registeredWithWorker = true;
+    try {
+      await this.waitForReady();
+    } catch {
+      // The worker rejected this client (e.g. because it connects in a mode incompatible with other tabs), so it won't
+      // acknowledge a close request either.
+      registeredWithWorker = false;
+    }
+
+    if (registeredWithWorker) {
+      await this.#closeWorkerClient();
+    }
 
-    await new Promise<void>((resolve) => {
+    await super.dispose();
+
+    this.abortOnClose.abort();
+
+    // Release the proxy
+    this.syncManager[Comlink.releaseProxy]();
+    this.worker.close();
+  }
+
+  #closeWorkerClient() {
+    return new Promise<void>((resolve) => {
       // This will always be a message port since we use shared workers.
       const messagePort = this.worker.endpoint as MessagePort;
 
@@ -213,14 +258,6 @@ export class SharedWebStreamingSyncImplementation extends WebStreamingSyncImplem
       };
       messagePort.postMessage(closeMessagePayload);
     });
-
-    await super.dispose();
-
-    this.abortOnClose.abort();
-
-    // Release the proxy
-    this.syncManager[Comlink.releaseProxy]();
-    this.worker.close();
   }
 
   async waitForReady() {

package/src/db/sync/WebRemote.ts

@@ -1,14 +1,11 @@
 import { LogLevels, PowerSyncLogger } from '@powersync/common';
-import { AbstractRemote, FetchOptions, RemoteConnector } from '@powersync/shared-internals';
+import { AbstractRemote, FetchOptions, InternalConnector } from '@powersync/shared-internals';
 
 import { getUserAgentInfo } from './userAgent.js';
 import type { WebSocketSyncStreamPlatform, WebSocketSupport } from '@powersync/shared-internals/websockets';
 
 export class WebRemote extends AbstractRemote {
-  constructor(
-    protected connector: RemoteConnector,
-    logger: PowerSyncLogger
-  ) {
+  constructor(connector: InternalConnector, logger: PowerSyncLogger) {
     super(connector, logger);
   }
 

package/src/db/sync/WebStreamingSyncImplementation.ts

@@ -2,6 +2,7 @@ import { LogLevels } from '@powersync/common';
 import {
   AbstractStreamingSyncImplementation,
   AbstractStreamingSyncImplementationOptions,
+  DiagnosticsEvent,
   LockOptions,
   LockType
 } from '@powersync/shared-internals';
@@ -14,11 +15,28 @@ export interface WebStreamingSyncImplementationOptions extends AbstractStreaming
 }
 
 export class WebStreamingSyncImplementation extends AbstractStreamingSyncImplementation {
+  private diagnosticsChannel?: BroadcastChannel;
+
   constructor(options: WebStreamingSyncImplementationOptions) {
     // Super will store and provide default values for options
     super(options);
   }
 
+  /**
+   * Broadcasts a core diagnostics event on a same-origin channel for diagnostics tooling to consume.
+   * The channel reaches the page even when sync runs in a shared worker.
+   */
+  protected override emitDiagnostics(event: DiagnosticsEvent): void {
+    this.diagnosticsChannel ??= new BroadcastChannel('powersync-diagnostics-events');
+    this.diagnosticsChannel.postMessage(event);
+  }
+
+  override async dispose(): Promise<void> {
+    await super.dispose();
+    this.diagnosticsChannel?.close();
+    this.diagnosticsChannel = undefined;
+  }
+
   get webOptions(): WebStreamingSyncImplementationOptions {
     return this.options as WebStreamingSyncImplementationOptions;
   }

package/src/devtools/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Development-tooling entry point (`@powersync/web/devtools`).
+ *
+ * Kept off the main index so the public API of `@powersync/web` is unchanged; tooling imports this
+ * subpath explicitly.
+ */
+export { getRegisteredDatabases, observeRegisteredDatabases } from './registry.js';

package/src/devtools/registry.ts

@@ -0,0 +1,53 @@
+import { BaseObserver, type BaseListener } from '@powersync/common';
+import type { WebPowerSyncDatabase } from '../db/PowerSyncDatabase.js';
+
+interface RegistryListener extends BaseListener {
+  databasesChanged: (databases: readonly WebPowerSyncDatabase[]) => void;
+}
+
+/**
+ * Live database instances in this page, for development tooling.
+ *
+ * Every {@link WebPowerSyncDatabase} registers itself when constructed and leaves when closed, so a
+ * tool that runs in the same page (for example the diagnostics Vite plugin's injected agent) can find
+ * the app's databases without the app wiring anything up. The set holds only instances that already
+ * exist, so it adds nothing to a production bundle beyond the references themselves.
+ */
+class DatabaseRegistry extends BaseObserver<RegistryListener> {
+  readonly databases = new Set<WebPowerSyncDatabase>();
+
+  notify(): void {
+    const snapshot = [...this.databases];
+    this.iterateListeners((listener) => listener.databasesChanged?.(snapshot));
+  }
+}
+
+const registry = new DatabaseRegistry();
+
+/** @internal Called by the database constructor. */
+export function registerDatabase(db: WebPowerSyncDatabase): void {
+  registry.databases.add(db);
+  registry.notify();
+}
+
+/** @internal Called when the database closes. */
+export function unregisterDatabase(db: WebPowerSyncDatabase): void {
+  if (registry.databases.delete(db)) {
+    registry.notify();
+  }
+}
+
+/** The databases currently open in this page. */
+export function getRegisteredDatabases(): readonly WebPowerSyncDatabase[] {
+  return [...registry.databases];
+}
+
+/**
+ * Calls `listener` with the current databases now, and again whenever one is opened or closed.
+ * Returns a function that stops listening.
+ */
+export function observeRegisteredDatabases(listener: (databases: readonly WebPowerSyncDatabase[]) => void): () => void {
+  const stop = registry.registerListener({ databasesChanged: listener });
+  listener([...registry.databases]);
+  return stop;
+}

package/src/worker/sync/BroadcastLogger.ts

@@ -1,4 +1,5 @@
 import { PowerSyncLogger, LogLevels, CreateLoggerOptions, createConsoleLogger, LogRecord } from '@powersync/common';
+import { serializeErrorForRelay } from '@powersync/shared-internals';
 import { type WrappedSyncPort } from './SharedSyncImplementation.js';
 
 /**
@@ -8,6 +9,8 @@ export class BroadcastLogger implements PowerSyncLogger {
   private readonly inner: PowerSyncLogger & CreateLoggerOptions;
   private currentLevel: number = LogLevels.info;
 
+  private sequence = 0;
+
   sendBroadcasts = true;
 
   constructor(
@@ -48,27 +51,24 @@ export class BroadcastLogger implements PowerSyncLogger {
     }
   }
 
-  /**
-   * Guards against any logging errors.
-   * We don't want a logging exception to cause further issues upstream
-   */
   protected sanitizeRecord(record: LogRecord): LogRecord {
-    if (!record.error) {
+    // Preserve explicit undefined rejection reasons.
+    if (!('error' in record)) {
       return record;
     }
 
-    let error;
-    try {
-      // Try and clone here first. If it fails it won't be passable over a MessagePort
-      error = structuredClone(record.error);
-    } catch (ex) {
-      console.error(ex);
-      error = 'Could not serialize log params. Check shared worker logs for more details.';
-    }
-
+    const serialized = serializeErrorForRelay(record.error);
     return {
       ...record,
-      error
+      error: {
+        ...serialized,
+        relay: {
+          origin: 'shared-sync-worker',
+          sequence: this.sequence++,
+          errorState: serialized.state,
+          relayedAt: new Date().toISOString()
+        }
+      }
     };
   }
 }