@powersync/web 2.4.2 → 2.6.0

package/dist/index.react_native_web.js

@@ -1,7 +1,7 @@
 import { DBAdapter, LockContext, LogLevels, queryResultWithoutRows, BaseObserver } from '@powersync/common';
 export * from '@powersync/common';
 import * as Comlink from 'comlink';
-import { Mutex, ConnectionClosedError, Semaphore, LockType, AbstractRemote, AbstractStreamingSyncImplementation, BasePowerSyncDatabase, openDatabase } from '@powersync/shared-internals';
+import { Mutex, ConnectionClosedError, Semaphore, LockType, AbstractRemote, AbstractStreamingSyncImplementation, serializeErrorForRelay, BasePowerSyncDatabase, openDatabase } from '@powersync/shared-internals';
 import { Factory, SQLITE_ROW } from '@journeyapps/wa-sqlite';
 
 /**
@@ -139,6 +139,35 @@ var WASQLiteVFS;
 function vfsRequiresDedicatedWorkers(vfs) {
     return vfs != WASQLiteVFS.IDBBatchAtomicVFS && vfs != WASQLiteVFS.InMemoryVfs;
 }
+/**
+ * Whether the VFS can keep its files in a Storage Bucket, see {@link WebSpecificOpenOptions.storageBucket}.
+ */
+function vfsSupportsStorageBuckets(vfs) {
+    return (vfs == WASQLiteVFS.OPFSCoopSyncVFS || vfs == WASQLiteVFS.OPFSWriteAheadVFS || vfs == WASQLiteVFS.AccessHandlePoolVFS);
+}
+/**
+ * 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
+ */
+function vfsOptionsForStorageBucket(storageBucket, storageBuckets = navigator.storageBuckets) {
+    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}:`
+    };
+}
 async function asyncModuleFactory(encryptionKey) {
     if (encryptionKey) {
         const { default: factory } = await import('@journeyapps/wa-sqlite/dist/mc-wa-sqlite-async.mjs');
@@ -162,7 +191,7 @@ async function syncModuleFactory(encryptionKey) {
 /**
  * @internal
  */
-async function loadModuleAndVfs({ vfs, filename, encryptionKey }) {
+async function loadModuleAndVfs({ vfs, filename, encryptionKey, storageBucket }) {
     let moduleFactory = syncModuleFactory;
     let resolveVfs;
     switch (vfs) {
@@ -178,19 +207,19 @@ async function loadModuleAndVfs({ vfs, filename, encryptionKey }) {
         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: {
@@ -439,6 +468,11 @@ function resolveAndValidateOptions(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}).`);
     }
+    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;
 }
 
@@ -530,9 +564,14 @@ class RawSqliteConnection {
         const sqlite3 = Factory(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
          */
@@ -1421,7 +1460,7 @@ class WASQLiteOpenFactory {
         return this.openAdapter();
     }
     async openConnection() {
-        const { enableMultiTabs, useWebWorker, vfs, dbFilename, encryptionKey, temporaryStorage, cacheSizeKb, preparedStatementsCache } = this.options;
+        const { enableMultiTabs, useWebWorker, vfs, dbFilename, encryptionKey, temporaryStorage, cacheSizeKb, preparedStatementsCache, additionalInitializationFunctions, storageBucket } = this.options;
         if (!enableMultiTabs) {
             this.logger.log({ level: LogLevels.warn, message: 'Multiple tabs are not enabled in this browser' });
         }
@@ -1437,7 +1476,9 @@ class WASQLiteOpenFactory {
                 temporaryStorage,
                 cacheSizeKb,
                 // TODO: Enable prepared statement cache by default?
-                preparedStatementsCache: preparedStatementsCache ?? 0
+                preparedStatementsCache: preparedStatementsCache ?? 0,
+                additionalInitializationFunctions,
+                storageBucket
             };
         }
         if (useWebWorker) {
@@ -1653,10 +1694,8 @@ function getOsInfo(nav) {
 }
 
 class WebRemote extends AbstractRemote {
-    connector;
     constructor(connector, logger) {
         super(connector, logger);
-        this.connector = connector;
     }
     fetch({ resource, request }) {
         return fetch(resource, request);
@@ -1683,10 +1722,24 @@ class WebRemote extends AbstractRemote {
 let websockets;
 
 class WebStreamingSyncImplementation extends AbstractStreamingSyncImplementation {
+    diagnosticsChannel;
     constructor(options) {
         // 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.
+     */
+    emitDiagnostics(event) {
+        this.diagnosticsChannel ??= new BroadcastChannel('powersync-diagnostics-events');
+        this.diagnosticsChannel.postMessage(event);
+    }
+    async dispose() {
+        await super.dispose();
+        this.diagnosticsChannel?.close();
+        this.diagnosticsChannel = undefined;
+    }
     get webOptions() {
         return this.options;
     }
@@ -1731,11 +1784,24 @@ class SharedSyncClientProvider extends AbstractSharedSyncClientProvider {
         const { port } = await this.webDB.shareConnection();
         return Comlink.transfer(port, [port]);
     }
+    async #relay(action) {
+        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() {
-        const credentials = await this.options.remote.getCredentials();
+        const credentials = await this.#relay(() => this.options.remote.getCredentials());
         if (credentials == null) {
             return null;
         }
@@ -1755,10 +1821,10 @@ 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());
     }
     async postCheckpointRequest(clientId, requestId) {
-        return await this.options.postCheckpointRequest(clientId, requestId);
+        return await this.#relay(async () => (await this.options.connector.postCheckpointRequest(clientId, requestId)) ?? null);
     }
     get logger() {
         return this.options.logger;
@@ -1835,9 +1901,13 @@ class SharedWebStreamingSyncImplementation extends WebStreamingSyncImplementatio
          * - The client sends the params to the shared worker after locks have been registered.
          */
         const closeSignal = await generateTabCloseSignal(this.abortOnClose.signal);
+        const { identifier, connector } = this.options;
         // Awaiting here ensures the worker is waiting for the lock
-        await this.syncManager.addLockBasedCloseSignal(closeSignal);
-        const { identifier } = this.options;
+        await this.syncManager.initialize(closeSignal, {
+            hasFetchCredentials: !!connector.fetchCredentials,
+            hasPostCheckpointRequest: !!connector.postCheckpointRequest,
+            hasUploadCrud: !!connector.uploadCrud
+        });
         await this.syncManager.setParams({
             dbParams: this.dbAdapter.getConfiguration(),
             streamOptions: {
@@ -1860,8 +1930,26 @@ class SharedWebStreamingSyncImplementation extends WebStreamingSyncImplementatio
         return this.syncManager.disconnect();
     }
     async dispose() {
-        await this.waitForReady();
-        await new Promise((resolve) => {
+        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 super.dispose();
+        this.abortOnClose.abort();
+        // Release the proxy
+        this.syncManager[Comlink.releaseProxy]();
+        this.worker.close();
+    }
+    #closeWorkerClient() {
+        return new Promise((resolve) => {
             // This will always be a message port since we use shared workers.
             const messagePort = this.worker.endpoint;
             // Listen for the close acknowledgment from the worker
@@ -1878,11 +1966,6 @@ class SharedWebStreamingSyncImplementation extends WebStreamingSyncImplementatio
             };
             messagePort.postMessage(closeMessagePayload);
         });
-        await super.dispose();
-        this.abortOnClose.abort();
-        // Release the proxy
-        this.syncManager[Comlink.releaseProxy]();
-        this.worker.close();
     }
     async waitForReady() {
         return this.isInitialized;
@@ -1963,6 +2046,34 @@ class TabLocalStreamingSyncImplementation extends WebStreamingSyncImplementation
     }
 }
 
+/**
+ * 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 {
+    databases = new Set();
+    notify() {
+        const snapshot = [...this.databases];
+        this.iterateListeners((listener) => listener.databasesChanged?.(snapshot));
+    }
+}
+const registry = new DatabaseRegistry();
+/** @internal Called by the database constructor. */
+function registerDatabase(db) {
+    registry.databases.add(db);
+    registry.notify();
+}
+/** @internal Called when the database closes. */
+function unregisterDatabase(db) {
+    if (registry.databases.delete(db)) {
+        registry.notify();
+    }
+}
+
 /**
  * @internal Use {@link PowerSyncDatabase} instead, this class is only used by other SDKs also needing web support.
  */
@@ -1975,6 +2086,11 @@ class WebPowerSyncDatabase extends BasePowerSyncDatabase {
         super(options);
         this.resolvedOpenOptions = resolvedOpenOptions;
         this.enableBroadcastLogs = options.broadcastLogs ?? true;
+        // Lets development tooling in this page find the live databases.
+        registerDatabase(this);
+    }
+    get sdkName() {
+        return '@powersync/web';
     }
     async _initialize() {
         if (this.database instanceof AsyncDbAdapter) {
@@ -2015,11 +2131,12 @@ class WebPowerSyncDatabase extends BasePowerSyncDatabase {
      * By default the sync stream client is only disconnected if
      * multiple tabs are not enabled.
      */
-    close(options) {
-        return super.close({
+    async close(options) {
+        await super.close({
             // Don't disconnect by default if multiple tabs are enabled
             disconnect: options?.disconnect ?? !this.resolvedOpenOptions.enableMultiTabs
         });
+        unregisterDatabase(this);
     }
     async loadVersion() {
         if (this.resolvedOpenOptions.ssrMode) {