@powersync/web 0.0.0-dev-20260311103504 → 0.0.0-dev-20260503073249

package/lib/src/db/adapters/LockedAsyncDatabaseAdapter.js

@@ -1,401 +0,0 @@
-import { BaseObserver, ConnectionClosedError, createLogger } from '@powersync/common';
-import { getNavigatorLocks } from '../../shared/navigator.js';
-import { WorkerWrappedAsyncDatabaseConnection } from './WorkerWrappedAsyncDatabaseConnection.js';
-import { WASQLiteVFS } from './wa-sqlite/WASQLiteConnection.js';
-/**
- * @internal
- * Wraps a {@link AsyncDatabaseConnection} and provides exclusive locking functions in
- * order to implement {@link DBAdapter}.
- */
-export class LockedAsyncDatabaseAdapter extends BaseObserver {
-    options;
-    logger;
-    dbGetHelpers;
-    debugMode;
-    _dbIdentifier;
-    initPromise;
-    _db = null;
-    _disposeTableChangeListener = null;
-    _config = null;
-    pendingAbortControllers;
-    requiresHolds;
-    databaseOpenPromise = null;
-    closing;
-    closed;
-    constructor(options) {
-        super();
-        this.options = options;
-        this._dbIdentifier = options.name;
-        this.logger = options.logger ?? createLogger(`LockedAsyncDatabaseAdapter - ${this._dbIdentifier}`);
-        this.pendingAbortControllers = new Set();
-        this.closed = false;
-        this.closing = false;
-        this.requiresHolds = null;
-        // Set the name if provided. We can query for the name if not available yet
-        this.debugMode = options.debugMode ?? false;
-        if (this.debugMode) {
-            const originalExecute = this._execute.bind(this);
-            this._execute = async (sql, bindings) => {
-                const start = performance.now();
-                try {
-                    const r = await originalExecute(sql, bindings);
-                    performance.measure(`[SQL] ${sql}`, { start });
-                    return r;
-                }
-                catch (e) {
-                    performance.measure(`[SQL] [ERROR: ${e.message}] ${sql}`, { start });
-                    throw e;
-                }
-            };
-        }
-        this.dbGetHelpers = this.generateDBHelpers({
-            execute: (query, params) => this.acquireLock(() => this._execute(query, params)),
-            executeRaw: (query, params) => this.acquireLock(() => this._executeRaw(query, params))
-        });
-        this.initPromise = this._init();
-    }
-    get baseDB() {
-        if (!this._db) {
-            throw new Error(`Initialization has not completed yet. Cannot access base db`);
-        }
-        return this._db;
-    }
-    get name() {
-        return this._dbIdentifier;
-    }
-    /**
-     * Init is automatic, this helps catch errors or explicitly await initialization
-     */
-    async init() {
-        return this.initPromise;
-    }
-    async openInternalDB() {
-        /**
-         * Execute opening of the db in a lock in order not to interfere with other operations.
-         */
-        return this._acquireLock(async () => {
-            // Dispose any previous table change listener.
-            this._disposeTableChangeListener?.();
-            this._disposeTableChangeListener = null;
-            this._db?.close().catch((ex) => this.logger.warn(`Error closing database before opening new instance`, ex));
-            const isReOpen = !!this._db;
-            this._db = null;
-            this._db = await this.options.openConnection();
-            await this._db.init();
-            this._config = await this._db.getConfig();
-            await this.registerOnChangeListener(this._db);
-            if (isReOpen) {
-                this.iterateListeners((cb) => cb.databaseReOpened?.());
-            }
-            /**
-             * This is only required for the long-lived shared IndexedDB connections.
-             */
-            this.requiresHolds = this._config.vfs == WASQLiteVFS.IDBBatchAtomicVFS;
-        });
-    }
-    _reOpen() {
-        this.databaseOpenPromise = this.openInternalDB().finally(() => {
-            this.databaseOpenPromise = null;
-        });
-        return this.databaseOpenPromise;
-    }
-    /**
-     * Re-opens the underlying database.
-     * Returns a pending operation if one is already in progress.
-     */
-    async reOpenInternalDB() {
-        if (this.closing || !this.options.reOpenOnConnectionClosed) {
-            // No-op
-            return;
-        }
-        else if (this.databaseOpenPromise) {
-            // Already busy opening
-            return this.databaseOpenPromise;
-        }
-        else {
-            return this._reOpen();
-        }
-    }
-    async _init() {
-        /**
-         * For OPFS, we can see this open call sometimes fail due to NoModificationAllowedError.
-         * We should be able to recover from this by re-opening the database.
-         */
-        const maxAttempts = 3;
-        for (let count = 0; count < maxAttempts; count++) {
-            try {
-                await this.openInternalDB();
-                break;
-            }
-            catch (ex) {
-                if (count == maxAttempts - 1) {
-                    throw ex;
-                }
-                this.logger.warn(`Attempt ${count + 1} of ${maxAttempts} to open database failed, retrying in 1 second...`, ex);
-                await new Promise((resolve) => setTimeout(resolve, 1000));
-            }
-        }
-        this.iterateListeners((cb) => cb.initialized?.());
-    }
-    getConfiguration() {
-        if (!this._config) {
-            throw new Error(`Cannot get config before initialization is completed`);
-        }
-        return {
-            ...this._config,
-            // This can be overridden by the adapter later
-            requiresPersistentTriggers: false
-        };
-    }
-    async waitForInitialized() {
-        // Awaiting this will expose errors on function calls like .execute etc
-        await this.initPromise;
-    }
-    async shareConnection() {
-        if (false == this._db instanceof WorkerWrappedAsyncDatabaseConnection) {
-            throw new Error(`Only worker connections can be shared`);
-        }
-        return this._db.shareConnection();
-    }
-    /**
-     * Registers a table change notification callback with the base database.
-     * This can be extended by custom implementations in order to handle proxy events.
-     */
-    async registerOnChangeListener(db) {
-        this._disposeTableChangeListener = await db.registerOnTableChange((event) => {
-            this.iterateListeners((cb) => cb.tablesUpdated?.(event));
-        });
-    }
-    /**
-     * This is currently a no-op on web
-     */
-    async refreshSchema() { }
-    async execute(query, params) {
-        return this.writeLock((ctx) => ctx.execute(query, params));
-    }
-    async executeRaw(query, params) {
-        return this.writeLock((ctx) => ctx.executeRaw(query, params));
-    }
-    async executeBatch(query, params) {
-        return this.writeLock((ctx) => this._executeBatch(query, params));
-    }
-    /**
-     * Attempts to close the connection.
-     * Shared workers might not actually close the connection if other
-     * tabs are still using it.
-     */
-    async close() {
-        this.closing = true;
-        /**
-         * Note that we obtain a reference to the callback to avoid calling the callback with `this` as the context.
-         * This is to avoid Comlink attempting to clone `this` when calling the method.
-         */
-        const dispose = this._disposeTableChangeListener;
-        if (dispose) {
-            dispose();
-        }
-        this.pendingAbortControllers.forEach((controller) => controller.abort('Closed'));
-        await this.baseDB?.close?.();
-        this.closed = true;
-    }
-    async getAll(sql, parameters) {
-        await this.waitForInitialized();
-        return this.dbGetHelpers.getAll(sql, parameters);
-    }
-    async getOptional(sql, parameters) {
-        await this.waitForInitialized();
-        return this.dbGetHelpers.getOptional(sql, parameters);
-    }
-    async get(sql, parameters) {
-        await this.waitForInitialized();
-        return this.dbGetHelpers.get(sql, parameters);
-    }
-    async readLock(fn, options) {
-        await this.waitForInitialized();
-        return this.acquireLock(async () => fn(this.generateDBHelpers({ execute: this._execute, executeRaw: this._executeRaw })), {
-            timeoutMs: options?.timeoutMs ?? this.options.defaultLockTimeoutMs
-        });
-    }
-    async writeLock(fn, options) {
-        await this.waitForInitialized();
-        return this.acquireLock(async () => fn(this.generateDBHelpers({ execute: this._execute, executeRaw: this._executeRaw })), {
-            timeoutMs: options?.timeoutMs ?? this.options.defaultLockTimeoutMs
-        });
-    }
-    async _acquireLock(callback, options) {
-        if (this.closing) {
-            throw new Error(`Cannot acquire lock, the database is closing`);
-        }
-        const abortController = new AbortController();
-        this.pendingAbortControllers.add(abortController);
-        const { timeoutMs } = options ?? {};
-        const timeoutId = timeoutMs
-            ? setTimeout(() => {
-                abortController.abort(`Timeout after ${timeoutMs}ms`);
-                this.pendingAbortControllers.delete(abortController);
-            }, timeoutMs)
-            : null;
-        return getNavigatorLocks().request(`db-lock-${this._dbIdentifier}`, { signal: abortController.signal }, async () => {
-            this.pendingAbortControllers.delete(abortController);
-            if (timeoutId) {
-                clearTimeout(timeoutId);
-            }
-            return await callback();
-        });
-    }
-    async acquireLock(callback, options) {
-        await this.waitForInitialized();
-        // The database is being (re)opened in the background. Wait for it here.
-        if (this.databaseOpenPromise) {
-            await this.databaseOpenPromise;
-        }
-        else if (!this._db) {
-            /**
-             * The database is not open anymore, we might need to re-open it.
-             * Typically, _db, can be `null` if we tried to reOpen the database, but failed to succeed in re-opening.
-             * This can happen when disconnecting the client.
-             * Note: It is safe to re-enter this method multiple times.
-             */
-            await this.reOpenInternalDB();
-        }
-        return this._acquireLock(async () => {
-            let holdId = null;
-            try {
-                /**
-                 * We can't await this since it uses the same lock as we're in now.
-                 * If there is a pending open, this call will throw.
-                 * If there is no pending open, but there is also no database - the open
-                 * might have failed. We need to re-open the database.
-                 */
-                if (this.databaseOpenPromise || !this._db) {
-                    throw new ConnectionClosedError('Connection is busy re-opening');
-                }
-                holdId = this.requiresHolds ? await this.baseDB.markHold() : null;
-                return await callback();
-            }
-            catch (ex) {
-                if (ConnectionClosedError.MATCHES(ex)) {
-                    // Immediately re-open the database. We need to miss as little table updates as possible.
-                    // Note, don't await this since it uses the same lock as we're in now.
-                    this.reOpenInternalDB();
-                }
-                throw ex;
-            }
-            finally {
-                if (holdId) {
-                    await this.baseDB.releaseHold(holdId);
-                }
-            }
-        }, options);
-    }
-    async readTransaction(fn, options) {
-        return this.readLock(this.wrapTransaction(fn));
-    }
-    writeTransaction(fn, options) {
-        return this.writeLock(this.wrapTransaction(fn, true));
-    }
-    generateDBHelpers(tx) {
-        return {
-            ...tx,
-            /**
-             *  Execute a read-only query and return results
-             */
-            async getAll(sql, parameters) {
-                const res = await tx.execute(sql, parameters);
-                return res.rows?._array ?? [];
-            },
-            /**
-             * Execute a read-only query and return the first result, or null if the ResultSet is empty.
-             */
-            async getOptional(sql, parameters) {
-                const res = await tx.execute(sql, parameters);
-                return res.rows?.item(0) ?? null;
-            },
-            /**
-             * Execute a read-only query and return the first result, error if the ResultSet is empty.
-             */
-            async get(sql, parameters) {
-                const res = await tx.execute(sql, parameters);
-                const first = res.rows?.item(0);
-                if (!first) {
-                    throw new Error('Result set is empty');
-                }
-                return first;
-            }
-        };
-    }
-    /**
-     * Wraps a lock context into a transaction context
-     */
-    wrapTransaction(cb, write = false) {
-        return async (tx) => {
-            await this._execute(write ? 'BEGIN EXCLUSIVE' : 'BEGIN');
-            let finalized = false;
-            const commit = async () => {
-                if (finalized) {
-                    return { rowsAffected: 0 };
-                }
-                finalized = true;
-                return this._execute('COMMIT');
-            };
-            const rollback = () => {
-                finalized = true;
-                return this._execute('ROLLBACK');
-            };
-            try {
-                const result = await cb({
-                    ...tx,
-                    commit,
-                    rollback
-                });
-                if (!finalized) {
-                    await commit();
-                }
-                return result;
-            }
-            catch (ex) {
-                this.logger.debug('Caught ex in transaction', ex);
-                try {
-                    await rollback();
-                }
-                catch (ex2) {
-                    // In rare cases, a rollback may fail.
-                    // Safe to ignore.
-                }
-                throw ex;
-            }
-        };
-    }
-    /**
-     * Wraps the worker execute function, awaiting for it to be available
-     */
-    _execute = async (sql, bindings) => {
-        await this.waitForInitialized();
-        const result = await this.baseDB.execute(sql, bindings);
-        return {
-            ...result,
-            rows: {
-                ...result.rows,
-                item: (idx) => result.rows._array[idx]
-            }
-        };
-    };
-    /**
-     * Wraps the worker executeRaw function, awaiting for it to be available
-     */
-    _executeRaw = async (sql, bindings) => {
-        await this.waitForInitialized();
-        return await this.baseDB.executeRaw(sql, bindings);
-    };
-    /**
-     * Wraps the worker executeBatch function, awaiting for it to be available
-     */
-    _executeBatch = async (query, params) => {
-        await this.waitForInitialized();
-        const result = await this.baseDB.executeBatch(query, params);
-        return {
-            ...result,
-            rows: undefined
-        };
-    };
-}

package/lib/src/db/adapters/WorkerWrappedAsyncDatabaseConnection.d.ts

@@ -1,59 +0,0 @@
-import { BaseObserver } from '@powersync/common';
-import * as Comlink from 'comlink';
-import { AsyncDatabaseConnection, OnTableChangeCallback, OpenAsyncDatabaseConnection, ProxiedQueryResult } from './AsyncDatabaseConnection.js';
-import { ResolvedWebSQLOpenOptions } from './web-sql-flags.js';
-export type SharedConnectionWorker = {
-    identifier: string;
-    port: MessagePort;
-};
-export type WrappedWorkerConnectionOptions<Config extends ResolvedWebSQLOpenOptions = ResolvedWebSQLOpenOptions> = {
-    baseConnection: AsyncDatabaseConnection;
-    identifier: string;
-    remoteCanCloseUnexpectedly: boolean;
-    /**
-     * Need a remote in order to keep a reference to the Proxied worker
-     */
-    remote: Comlink.Remote<OpenAsyncDatabaseConnection<Config>>;
-    onClose?: () => void;
-};
-export type WorkerWrappedAsyncDatabaseConnectionListener = {
-    closing: () => void;
-};
-/**
- * Wraps a provided instance of {@link AsyncDatabaseConnection}, providing necessary proxy
- * functions for worker listeners.
- */
-export declare class WorkerWrappedAsyncDatabaseConnection<Config extends ResolvedWebSQLOpenOptions = ResolvedWebSQLOpenOptions> extends BaseObserver<WorkerWrappedAsyncDatabaseConnectionListener> implements AsyncDatabaseConnection {
-    protected options: WrappedWorkerConnectionOptions<Config>;
-    protected lockAbortController: AbortController;
-    protected notifyRemoteClosed: AbortController | undefined;
-    constructor(options: WrappedWorkerConnectionOptions<Config>);
-    protected get baseConnection(): AsyncDatabaseConnection<ResolvedWebSQLOpenOptions>;
-    init(): Promise<void>;
-    /**
-     * Marks the remote as closed.
-     *
-     * This can sometimes happen outside of our control, e.g. when a shared worker requests a connection from a tab. When
-     * it happens, all methods on the {@link baseConnection} would never resolve. To avoid livelocks in this scenario, we
-     * throw on all outstanding promises and forbid new calls.
-     */
-    markRemoteClosed(): void;
-    markHold(): Promise<string>;
-    releaseHold(holdId: string): Promise<void>;
-    isAutoCommit(): Promise<boolean>;
-    private withRemote;
-    /**
-     * Get a MessagePort which can be used to share the internals of this connection.
-     */
-    shareConnection(): Promise<SharedConnectionWorker>;
-    /**
-     * Registers a table change notification callback with the base database.
-     * This can be extended by custom implementations in order to handle proxy events.
-     */
-    registerOnTableChange(callback: OnTableChangeCallback): Promise<() => void>;
-    close(): Promise<void>;
-    execute(sql: string, params?: any[]): Promise<ProxiedQueryResult>;
-    executeRaw(sql: string, params?: any[]): Promise<any[][]>;
-    executeBatch(sql: string, params?: any[]): Promise<ProxiedQueryResult>;
-    getConfig(): Promise<ResolvedWebSQLOpenOptions>;
-}

package/lib/src/db/adapters/WorkerWrappedAsyncDatabaseConnection.js

@@ -1,147 +0,0 @@
-import { BaseObserver, ConnectionClosedError } from '@powersync/common';
-import * as Comlink from 'comlink';
-/**
- * Wraps a provided instance of {@link AsyncDatabaseConnection}, providing necessary proxy
- * functions for worker listeners.
- */
-export class WorkerWrappedAsyncDatabaseConnection extends BaseObserver {
-    options;
-    lockAbortController = new AbortController();
-    notifyRemoteClosed;
-    constructor(options) {
-        super();
-        this.options = options;
-        if (options.remoteCanCloseUnexpectedly) {
-            this.notifyRemoteClosed = new AbortController();
-        }
-    }
-    get baseConnection() {
-        return this.options.baseConnection;
-    }
-    init() {
-        return this.baseConnection.init();
-    }
-    /**
-     * Marks the remote as closed.
-     *
-     * This can sometimes happen outside of our control, e.g. when a shared worker requests a connection from a tab. When
-     * it happens, all methods on the {@link baseConnection} would never resolve. To avoid livelocks in this scenario, we
-     * throw on all outstanding promises and forbid new calls.
-     */
-    markRemoteClosed() {
-        // Can non-null assert here because this function is only supposed to be called when remoteCanCloseUnexpectedly was
-        // set.
-        this.notifyRemoteClosed.abort();
-    }
-    markHold() {
-        return this.withRemote(() => this.baseConnection.markHold());
-    }
-    releaseHold(holdId) {
-        return this.withRemote(() => this.baseConnection.releaseHold(holdId));
-    }
-    isAutoCommit() {
-        return this.withRemote(() => this.baseConnection.isAutoCommit());
-    }
-    withRemote(workerPromise, fireActionOnAbort = false) {
-        const controller = this.notifyRemoteClosed;
-        if (controller) {
-            return new Promise((resolve, reject) => {
-                if (controller.signal.aborted) {
-                    reject(new ConnectionClosedError('Called operation on closed remote'));
-                    if (!fireActionOnAbort) {
-                        // Don't run the operation if we're going to reject
-                        // We might want to fire-and-forget the operation in some cases (like a close operation)
-                        return;
-                    }
-                }
-                function handleAbort() {
-                    reject(new ConnectionClosedError('Remote peer closed with request in flight'));
-                }
-                function completePromise(action) {
-                    controller.signal.removeEventListener('abort', handleAbort);
-                    action();
-                }
-                controller.signal.addEventListener('abort', handleAbort);
-                workerPromise()
-                    .then((data) => completePromise(() => resolve(data)))
-                    .catch((e) => completePromise(() => reject(e)));
-            });
-        }
-        else {
-            // Can't close, so just return the inner worker promise unguarded.
-            return workerPromise();
-        }
-    }
-    /**
-     * Get a MessagePort which can be used to share the internals of this connection.
-     */
-    async shareConnection() {
-        const { identifier, remote } = this.options;
-        /**
-         * Hold a navigator lock in order to avoid features such as Chrome's frozen tabs,
-         * or Edge's sleeping tabs from pausing the thread for this connection.
-         * This promise resolves once a lock is obtained.
-         * This lock will be held as long as this connection is open.
-         * The `shareConnection` method should not be called on multiple tabs concurrently.
-         */
-        await new Promise((resolve, reject) => navigator.locks
-            .request(`shared-connection-${this.options.identifier}-${Date.now()}-${Math.round(Math.random() * 10000)}`, {
-            signal: this.lockAbortController.signal
-        }, async () => {
-            resolve();
-            // Free the lock when the connection is already closed.
-            if (this.lockAbortController.signal.aborted) {
-                return;
-            }
-            // Hold the lock while the shared connection is in use.
-            await new Promise((releaseLock) => {
-                this.lockAbortController.signal.addEventListener('abort', () => {
-                    releaseLock();
-                });
-            });
-        })
-            // We aren't concerned with abort errors here
-            .catch((ex) => {
-            if (ex.name == 'AbortError') {
-                resolve();
-            }
-            else {
-                reject(ex);
-            }
-        }));
-        const newPort = await remote[Comlink.createEndpoint]();
-        return { port: newPort, identifier };
-    }
-    /**
-     * Registers a table change notification callback with the base database.
-     * This can be extended by custom implementations in order to handle proxy events.
-     */
-    async registerOnTableChange(callback) {
-        return this.baseConnection.registerOnTableChange(Comlink.proxy(callback));
-    }
-    async close() {
-        // Abort any pending lock requests.
-        this.lockAbortController.abort();
-        try {
-            // fire and forget the close operation
-            await this.withRemote(() => this.baseConnection.close(), true);
-        }
-        finally {
-            this.options.remote[Comlink.releaseProxy]();
-            this.options.onClose?.();
-            this.iterateListeners((l) => l.closing?.());
-        }
-    }
-    execute(sql, params) {
-        return this.withRemote(() => this.baseConnection.execute(sql, params));
-    }
-    executeRaw(sql, params) {
-        return this.withRemote(() => this.baseConnection.executeRaw(sql, params));
-    }
-    executeBatch(sql, params) {
-        return this.withRemote(() => this.baseConnection.executeBatch(sql, params));
-    }
-    getConfig() {
-        return this.withRemote(() => this.baseConnection.getConfig());
-    }
-}

package/lib/src/db/adapters/wa-sqlite/InternalWASQLiteDBAdapter.d.ts

@@ -1,12 +0,0 @@
-import { LockedAsyncDatabaseAdapter } from '../LockedAsyncDatabaseAdapter.js';
-import { WebDBAdapterConfiguration } from '../WebDBAdapter.js';
-/**
- * @internal
- * An intermediary implementation of WASQLiteDBAdapter, which takes the same
- * constructor arguments as {@link LockedAsyncDatabaseAdapter}, but provides some
- * basic WA-SQLite specific functionality.
- * This base class is used to avoid requiring overloading the constructor of {@link WASQLiteDBAdapter}
- */
-export declare class InternalWASQLiteDBAdapter extends LockedAsyncDatabaseAdapter {
-    getConfiguration(): WebDBAdapterConfiguration;
-}

package/lib/src/db/adapters/wa-sqlite/InternalWASQLiteDBAdapter.js

@@ -1,19 +0,0 @@
-import { LockedAsyncDatabaseAdapter } from '../LockedAsyncDatabaseAdapter.js';
-import { WASQLiteVFS } from './WASQLiteConnection.js';
-/**
- * @internal
- * An intermediary implementation of WASQLiteDBAdapter, which takes the same
- * constructor arguments as {@link LockedAsyncDatabaseAdapter}, but provides some
- * basic WA-SQLite specific functionality.
- * This base class is used to avoid requiring overloading the constructor of {@link WASQLiteDBAdapter}
- */
-export class InternalWASQLiteDBAdapter extends LockedAsyncDatabaseAdapter {
-    getConfiguration() {
-        // This is valid since we only handle WASQLite connections
-        const baseConfig = super.getConfiguration();
-        return {
-            ...super.getConfiguration(),
-            requiresPersistentTriggers: baseConfig.vfs == WASQLiteVFS.OPFSCoopSyncVFS || baseConfig.vfs == WASQLiteVFS.AccessHandlePoolVFS
-        };
-    }
-}