@powersync/web 2.1.1 → 2.3.0

package/README.md

@@ -4,7 +4,7 @@
 
 # PowerSync SDK for Web
 
-_[PowerSync](https://www.powersync.com) is a sync engine for building local-first apps with instantly-responsive UI/UX and simplified state transfer. Syncs between SQLite on the client-side and Postgres, MongoDB, MySQL or SQL Server on the server-side._
+_[PowerSync](https://www.powersync.com) keeps a client-side SQLite database in sync with your backend database. Changes appear across users and devices in real-time, user interactions feel instant and your app continues to work even when offline. Supports Postgres, MongoDB, MySQL, and SQL Server. Client SDKs are available for a wide range of environments including web, mobile, desktop, headless and embedded._
 
 This package (`packages/web`) is the PowerSync SDK for JavaScript Web clients. It is an extension of `packages/common`.
 

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, SqliteBucketStorage } from '@powersync/shared-internals';
+import { Mutex, ConnectionClosedError, Semaphore, LockType, AbstractRemote, AbstractStreamingSyncImplementation, BasePowerSyncDatabase, openDatabase } from '@powersync/shared-internals';
 import { Factory, SQLITE_ROW } from '@journeyapps/wa-sqlite';
 
 /**
@@ -442,6 +442,50 @@ function resolveAndValidateOptions(options) {
     return resolved;
 }
 
+class PreparedStatementCache {
+    #size;
+    // Note that Map preserves insertion order, which allows using it as an LRU
+    // cache (with the first element being the first element to evict).
+    #statements = new Map();
+    constructor(size) {
+        this.#size = size;
+    }
+    /**
+     * Attempts to look up the cached sql statement, if it's currently cached.
+     */
+    lookup(sql) {
+        const foundStatement = this.#statements.get(sql);
+        if (foundStatement != null) {
+            // Delete and re-insert to move to the end (most-recently-used position).
+            this.#statements.delete(sql);
+            this.#statements.set(sql, foundStatement);
+            return foundStatement;
+        }
+        return null;
+    }
+    /**
+     * Adds a new statement into the cache.
+     *
+     * If that exceeds the target size of the statement cache, returns an old statement to evict.
+     * The caller is responsible for freeing that statement.
+     */
+    addStatement(sql, statement) {
+        this.#statements.set(sql, statement);
+        if (this.#statements.size > this.#size) {
+            for (const [k, v] of this.#statements.entries()) {
+                this.#statements.delete(k);
+                return v;
+            }
+        }
+        return null;
+    }
+    drain() {
+        const values = [...this.#statements.values()];
+        this.#statements.clear();
+        return values;
+    }
+}
+
 /**
  * A small wrapper around WA-sqlite to help with opening databases and running statements by preparing them internally.
  *
@@ -451,18 +495,26 @@ function resolveAndValidateOptions(options) {
 class RawSqliteConnection {
     options;
     _sqliteAPI = null;
+    sqlite3_stmt_isexplain;
     /**
      * The `sqlite3*` connection pointer.
      */
     db = 0;
+    statementCache;
     constructor(options) {
         this.options = options;
+        this.statementCache =
+            options.preparedStatementsCache > 0 ? new PreparedStatementCache(options.preparedStatementsCache) : null;
     }
     get isOpen() {
         return this.db != 0;
     }
     async init() {
-        const api = (this._sqliteAPI = await this.openSQLiteAPI());
+        const { module, vfs } = await loadModuleAndVfs(this.options);
+        await this.initWithModule(module, vfs);
+    }
+    async initWithModule(module, vfs) {
+        const api = (this._sqliteAPI = await this.openSQLiteAPI(module, vfs));
         this.db = await api.open_v2(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) {
@@ -472,9 +524,9 @@ class RawSqliteConnection {
         await this.executeRaw(`PRAGMA cache_size = -${this.options.cacheSizeKb};`);
         await this.executeRaw(`SELECT powersync_update_hooks('install');`);
     }
-    async openSQLiteAPI() {
-        const { module, vfs } = await loadModuleAndVfs(this.options);
+    async openSQLiteAPI(module, vfs) {
         vfs.mxPathname = maxPathNameLength;
+        this.sqlite3_stmt_isexplain = module.cwrap('sqlite3_stmt_isexplain', 'int', ['int']);
         const sqlite3 = Factory(module);
         sqlite3.vfs_register(vfs, true);
         /**
@@ -542,7 +594,7 @@ class RawSqliteConnection {
     async executeRaw(sql, bindings) {
         const results = [];
         const api = this.requireSqlite();
-        for await (const stmt of api.statements(this.db, sql)) {
+        for await (const stmt of this.cachedStatements(api, sql)) {
             let columns;
             const rs = await this.stepThroughStatement(api, stmt, bindings ?? [], columns);
             columns = rs.columnNames;
@@ -579,10 +631,52 @@ class RawSqliteConnection {
     }
     async close() {
         if (this.isOpen) {
-            await this.requireSqlite().close(this.db);
+            const api = this.requireSqlite();
+            if (this.statementCache) {
+                for (const stmt of this.statementCache.drain()) {
+                    await api.finalize(stmt);
+                }
+            }
+            await api.close(this.db);
             this.db = 0;
         }
     }
+    async *cachedStatements(api, sql) {
+        {
+            const existing = this.statementCache?.lookup(sql);
+            if (existing != null) {
+                yield existing;
+                return;
+            }
+        }
+        const inner = api.statements(this.db, sql, { unscoped: true });
+        const preparedStatements = [];
+        try {
+            for await (const stmt of inner) {
+                preparedStatements.push(stmt);
+                yield stmt;
+            }
+        }
+        finally {
+            // We can only cache statements if the sql text corresponds to a single statement, otherwise it's not clear what
+            // portion of the original sql text to use as a key.
+            if (preparedStatements.length === 1 && this.statementCache) {
+                const stmt = preparedStatements[0];
+                // Don't cache EXPLAIN statements, their result becomes invalid after schema changes.
+                if (this.sqlite3_stmt_isexplain(stmt) == 0) {
+                    const evicted = this.statementCache.addStatement(sql, stmt);
+                    if (evicted != null) {
+                        await api.finalize(evicted);
+                    }
+                    return;
+                }
+            }
+            // We're not caching statements, so finalize them.
+            for (const stmt of preparedStatements) {
+                await api.finalize(stmt);
+            }
+        }
+    }
 }
 
 /**
@@ -712,7 +806,8 @@ const OPEN_DB_LOCK = 'open-wasqlite-db';
  */
 class MultiDatabaseServer {
     logger;
-    activeDatabases = new Map();
+    #activeDatabases = new Map();
+    #localOpenLock = new Mutex();
     constructor(logger) {
         this.logger = logger;
     }
@@ -727,7 +822,7 @@ class MultiDatabaseServer {
     }
     async connectToExisting(name, lockName) {
         return getNavigatorLocks().request(OPEN_DB_LOCK, async () => {
-            const server = this.activeDatabases.get(name);
+            const server = this.#activeDatabases.get(name);
             if (server == null) {
                 throw new Error(`connectToExisting(${name}) failed because the worker doesn't own a database with that name.`);
             }
@@ -741,7 +836,7 @@ class MultiDatabaseServer {
         let server;
         for (let count = 0; count < maxAttempts - 1; count++) {
             try {
-                server = await this.databaseOpenAttempt(logger, options);
+                server = await this.#databaseOpenAttempt(logger, options);
             }
             catch (error) {
                 this.logger.log({
@@ -753,19 +848,20 @@ class MultiDatabaseServer {
             }
         }
         // Final attempt if we haven't been able to open the server - rethrow errors if we still can't open.
-        server ??= await this.databaseOpenAttempt(logger, options);
+        server ??= await this.#databaseOpenAttempt(logger, options);
         return server.connect(lockName);
     }
-    async databaseOpenAttempt(logger, options) {
-        return getNavigatorLocks().request(OPEN_DB_LOCK, async () => {
-            const { filename, readonly, vfs } = options;
-            let server = this.activeDatabases.get(filename);
+    async #databaseOpenAttempt(logger, options) {
+        const { filename, readonly, vfs } = options;
+        // We don't need navigator locks for shared workers because all queries run in this shared worker exclusively.
+        // For read-only connections, we use a VFS that supports concurrent reads (so a single lock on the connection is
+        // fine). In-memory databases either run in a shared worker or aren't shared across tabs at all, so the internal
+        // lock is enough.
+        const needsNavigatorLocks = !(isSharedWorker$1 || readonly || vfs == WASQLiteVFS.InMemoryVfs);
+        const activeDatabases = this.#activeDatabases;
+        async function openDatabase() {
+            let server = activeDatabases.get(filename);
             if (server == null) {
-                // We don't need navigator locks for shared workers because all queries run in this shared worker exclusively.
-                // For read-only connections, we use a VFS that supports concurrent reads (so a single lock on the connection is
-                // fine). In-memory databases either run in a shared worker or aren't shared across tabs at all, so the internal
-                // lock is enough.
-                const needsNavigatorLocks = !(isSharedWorker$1 || readonly || vfs == WASQLiteVFS.InMemoryVfs);
                 const connection = new RawSqliteConnection(options);
                 const withSafeConcurrency = new ConcurrentSqliteConnection(connection, needsNavigatorLocks);
                 // Initializing the RawSqliteConnection will run some pragmas that might write to the database file, so we want
@@ -781,19 +877,27 @@ class MultiDatabaseServer {
                     throw e;
                 }
                 returnLease();
-                const onClose = () => this.activeDatabases.delete(filename);
+                const onClose = () => activeDatabases.delete(filename);
                 server = new DatabaseServer({
                     inner: withSafeConcurrency,
                     logger,
                     onClose
                 });
-                this.activeDatabases.set(filename, server);
+                activeDatabases.set(filename, server);
             }
             return server;
-        });
+        }
+        if (needsNavigatorLocks) {
+            return getNavigatorLocks().request(OPEN_DB_LOCK, openDatabase);
+        }
+        else {
+            // Even if we don't need navigator locks, this avoids a race between the activeDatabases.get() call, the async
+            // open logic and the final activeDatabases.set() step.
+            return this.#localOpenLock.runExclusive(openDatabase);
+        }
     }
     closeAll() {
-        const existingDatabases = [...this.activeDatabases.values()];
+        const existingDatabases = [...this.#activeDatabases.values()];
         return Promise.all(existingDatabases.map((db) => {
             db.forceClose();
         }));
@@ -1026,6 +1130,66 @@ function generateTabCloseSignal(abort) {
     });
 }
 
+/**
+ * Internal helper function to acquire a connection from a pool that has a designated writer, additional readers, and
+ * also allows dispatching reads to the writer.
+ */
+async function acquireFromPool(writerMutex, writer, readers, callback, options, allowReadOnly) {
+    const abortController = new AbortController();
+    const abortSignal = abortController.signal;
+    let timeout = null;
+    let release;
+    if (options?.timeoutMs) {
+        timeout = setTimeout(() => abortController.abort('requesting database timed out'), options.timeoutMs);
+    }
+    try {
+        if (allowReadOnly) {
+            let connection;
+            // Even if we have a pool of read connections, it's typically very small and we assume that most queries are
+            // reads. So, we want to request any connection from the read pool and the dedicated write connection (which
+            // can also serve reads). We race for the first connection we can obtain this way, and then abort the other
+            // request.
+            [connection, release] = await new Promise((resolve, reject) => {
+                let didComplete = false;
+                function complete() {
+                    didComplete = true;
+                    abortController.abort();
+                }
+                function completeSuccess(connection, returnFn) {
+                    if (didComplete) {
+                        // We're not going to use this connection, so return it immediately.
+                        returnFn();
+                    }
+                    else {
+                        complete();
+                        resolve([connection, returnFn]);
+                    }
+                }
+                function completeError(error) {
+                    // We either have a working connection already, or we've rejected the promise. Either way, we don't need
+                    // to do either thing again.
+                    if (didComplete)
+                        return;
+                    complete();
+                    reject(error);
+                }
+                writerMutex.acquire(abortSignal).then((unlock) => completeSuccess(writer, unlock), completeError);
+                readers?.requestOne(abortSignal).then(({ item, release }) => completeSuccess(item, release), completeError);
+            });
+            return await callback(connection);
+        }
+        else {
+            return await writerMutex.runExclusive(() => callback(writer), abortSignal);
+        }
+    }
+    finally {
+        if (timeout != null) {
+            clearTimeout(timeout);
+        }
+        release?.();
+    }
+}
+
 /**
  * A connection pool implementation delegating to another pool opened asynchronnously.
  */
@@ -1121,61 +1285,9 @@ function readWritePoolState(writer, readers) {
     return {
         writer,
         async withConnection(allowReadOnly, fn, options) {
-            const abortController = new AbortController();
-            const abortSignal = abortController.signal;
-            let timeout = null;
-            let release;
-            if (options?.timeoutMs) {
-                timeout = setTimeout(() => abortController.abort('requesting database timed out'), options.timeoutMs);
-            }
-            try {
-                if (allowReadOnly) {
-                    let connection;
-                    // Even if we have a pool of read connections, it's typically very small and we assume that most queries are
-                    // reads. So, we want to request any connection from the read pool and the dedicated write connection (which
-                    // can also serve reads). We race for the first connection we can obtain this way, and then abort the other
-                    // request.
-                    [connection, release] = await new Promise((resolve, reject) => {
-                        let didComplete = false;
-                        function complete() {
-                            didComplete = true;
-                            abortController.abort();
-                        }
-                        function completeSuccess(connection, returnFn) {
-                            if (didComplete) {
-                                // We're not going to use this connection, so return it immediately.
-                                returnFn();
-                            }
-                            else {
-                                complete();
-                                resolve([connection, returnFn]);
-                            }
-                        }
-                        function completeError(error) {
-                            // We either have a working connection already, or we've rejected the promise. Either way, we don't need
-                            // to do either thing again.
-                            if (didComplete)
-                                return;
-                            complete();
-                            reject(error);
-                        }
-                        writerMutex.acquire(abortSignal).then((unlock) => completeSuccess(writer, unlock), completeError);
-                        readerSemaphore
-                            .requestOne(abortSignal)
-                            .then(({ item, release }) => completeSuccess(item, release), completeError);
-                    });
-                    return await connection.readLock(fn);
-                }
-                else {
-                    return await writerMutex.runExclusive(() => writer.writeLock(fn), abortSignal);
-                }
-            }
-            finally {
-                if (timeout != null) {
-                    clearTimeout(timeout);
-                }
-                release?.();
-            }
+            return acquireFromPool(writerMutex, writer, readerSemaphore, (connection) => {
+                return allowReadOnly ? connection.readLock(fn) : connection.writeLock(fn);
+            }, options, allowReadOnly);
         },
         async close() {
             await writer.close();
@@ -1309,7 +1421,7 @@ class WASQLiteOpenFactory {
         return this.openAdapter();
     }
     async openConnection() {
-        const { enableMultiTabs, useWebWorker, vfs, dbFilename, encryptionKey, temporaryStorage, cacheSizeKb } = this.options;
+        const { enableMultiTabs, useWebWorker, vfs, dbFilename, encryptionKey, temporaryStorage, cacheSizeKb, preparedStatementsCache } = this.options;
         if (!enableMultiTabs) {
             this.logger.log({ level: LogLevels.warn, message: 'Multiple tabs are not enabled in this browser' });
         }
@@ -1323,7 +1435,9 @@ class WASQLiteOpenFactory {
                 vfs,
                 encryptionKey,
                 temporaryStorage,
-                cacheSizeKb
+                cacheSizeKb,
+                // TODO: Enable prepared statement cache by default?
+                preparedStatementsCache: preparedStatementsCache ?? 0
             };
         }
         if (useWebWorker) {
@@ -1372,10 +1486,11 @@ class WASQLiteOpenFactory {
                 // 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;
+                const additionalReaderPromises = [];
                 for (let i = 0; i < additionalReadersCount; i++) {
-                    const reader = await openDatabaseWorker(true);
-                    additionalReaders.push(reader);
+                    additionalReaderPromises.push(openDatabaseWorker(true));
                 }
+                additionalReaders.push(...(await Promise.all(additionalReaderPromises)));
             }
         }
         else {
@@ -1449,18 +1564,6 @@ class SSRStreamingSyncImplementation extends BaseObserver {
     waitUntilStatusMatches(_predicate) {
         return new Promise(() => { });
     }
-    /**
-     * Returns a placeholder checkpoint. This should not be used.
-     */
-    async getWriteCheckpoint() {
-        return '1';
-    }
-    /**
-     * The SSR mode adapter will never complete syncing.
-     */
-    async hasCompletedSync() {
-        return false;
-    }
     /**
      * This is a no-op in SSR mode.
      */
@@ -1473,6 +1576,9 @@ class SSRStreamingSyncImplementation extends BaseObserver {
      * No-op in SSR mode.
      */
     markConnectionMayHaveChanged() { }
+    requestCheckpoint() {
+        throw new Error('Sub sync implementation does not support request checkpoints');
+    }
 }
 
 /**
@@ -1651,6 +1757,9 @@ class SharedSyncClientProvider extends AbstractSharedSyncClientProvider {
          */
         await this.options.uploadCrud();
     }
+    async postCheckpointRequest(clientId, requestId) {
+        return await this.options.postCheckpointRequest(clientId, requestId);
+    }
     get logger() {
         return this.options.logger;
     }
@@ -1750,10 +1859,6 @@ class SharedWebStreamingSyncImplementation extends WebStreamingSyncImplementatio
         await this.waitForReady();
         return this.syncManager.disconnect();
     }
-    async getWriteCheckpoint() {
-        await this.waitForReady();
-        return this.syncManager.getWriteCheckpoint();
-    }
     async dispose() {
         await this.waitForReady();
         await new Promise((resolve) => {
@@ -1782,6 +1887,9 @@ class SharedWebStreamingSyncImplementation extends WebStreamingSyncImplementatio
     async waitForReady() {
         return this.isInitialized;
     }
+    requestCheckpoint() {
+        return this.syncManager.requestCheckpoint();
+    }
     updateSubscriptions(subscriptions) {
         this.syncManager.updateSubscriptions(subscriptions);
     }
@@ -1925,9 +2033,6 @@ class WebPowerSyncDatabase extends BasePowerSyncDatabase {
         }
         return super.resolveOfflineSyncStatus();
     }
-    generateBucketStorageAdapter() {
-        return new SqliteBucketStorage(this.database, this.logger);
-    }
     async runExclusive(cb) {
         if (this.resolvedOpenOptions.ssrMode) {
             return WebPowerSyncDatabase.SHARED_MUTEX.runExclusive(cb);
@@ -1938,37 +2043,35 @@ class WebPowerSyncDatabase extends BasePowerSyncDatabase {
         const remote = new WebRemote(connector, this.logger);
         const syncOptions = {
             ...this.options,
-            ...options,
-            adapter: this.bucketStorageAdapter,
-            remote,
-            uploadCrud: async () => {
-                await this.waitForReady();
-                await connector.uploadData(this);
-            },
-            identifier: this.database.name,
-            logger: this.logger
+            ...this.commonSyncOptions(connector, options),
+            remote
         };
-        switch (true) {
-            case this.resolvedOpenOptions.ssrMode:
-                return new SSRStreamingSyncImplementation();
-            case this.resolvedOpenOptions.enableMultiTabs:
-                if (!this.enableBroadcastLogs) {
-                    const warning = `
+        if (this.resolvedOpenOptions.ssrMode) {
+            return new SSRStreamingSyncImplementation();
+        }
+        else if (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.log({ level: LogLevels.warn, message: warning }) : console.warn(warning);
-                }
+                const logger = this.options.logger;
+                logger ? logger.log({ level: LogLevels.warn, message: warning }) : console.warn(warning);
+            }
+            if ('shareConnection' in this.database) {
                 return new SharedWebStreamingSyncImplementation({
                     ...syncOptions,
                     db: this.database, // This should always be the case
                     logLevel: this.options.sync?.logLevel ?? LogLevels.info,
                     enableBroadcastLogs: this.enableBroadcastLogs
                 });
-            default:
-                return new TabLocalStreamingSyncImplementation(syncOptions);
+            }
+            this.logger.log({
+                level: LogLevels.warn,
+                message: "Not using a shared sync worker because the database adapter doesn't support it."
+            });
         }
+        return new TabLocalStreamingSyncImplementation(syncOptions);
     }
 }
 /**