@powersync/web 1.12.2 → 1.13.0

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

@@ -0,0 +1,39 @@
+import * as Comlink from 'comlink';
+import { AsyncDatabaseConnection, OnTableChangeCallback, OpenAsyncDatabaseConnection, ProxiedQueryResult } from './AsyncDatabaseConnection';
+import { ResolvedWebSQLOpenOptions } from './web-sql-flags';
+export type SharedConnectionWorker = {
+    identifier: string;
+    port: MessagePort;
+};
+export type WrappedWorkerConnectionOptions<Config extends ResolvedWebSQLOpenOptions = ResolvedWebSQLOpenOptions> = {
+    baseConnection: AsyncDatabaseConnection;
+    identifier: string;
+    /**
+     * Need a remote in order to keep a reference to the Proxied worker
+     */
+    remote: Comlink.Remote<OpenAsyncDatabaseConnection<Config>>;
+    onClose?: () => void;
+};
+/**
+ * Wraps a provided instance of {@link AsyncDatabaseConnection}, providing necessary proxy
+ * functions for worker listeners.
+ */
+export declare class WorkerWrappedAsyncDatabaseConnection<Config extends ResolvedWebSQLOpenOptions = ResolvedWebSQLOpenOptions> implements AsyncDatabaseConnection {
+    protected options: WrappedWorkerConnectionOptions<Config>;
+    constructor(options: WrappedWorkerConnectionOptions<Config>);
+    protected get baseConnection(): AsyncDatabaseConnection<ResolvedWebSQLOpenOptions>;
+    init(): Promise<void>;
+    /**
+     * 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>;
+    executeBatch(sql: string, params?: any[]): Promise<ProxiedQueryResult>;
+    getConfig(): Promise<ResolvedWebSQLOpenOptions>;
+}

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

@@ -0,0 +1,46 @@
+import * as Comlink from 'comlink';
+/**
+ * Wraps a provided instance of {@link AsyncDatabaseConnection}, providing necessary proxy
+ * functions for worker listeners.
+ */
+export class WorkerWrappedAsyncDatabaseConnection {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    get baseConnection() {
+        return this.options.baseConnection;
+    }
+    init() {
+        return this.baseConnection.init();
+    }
+    /**
+     * Get a MessagePort which can be used to share the internals of this connection.
+     */
+    async shareConnection() {
+        const { identifier, remote } = this.options;
+        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() {
+        await this.baseConnection.close();
+        this.options.remote[Comlink.releaseProxy]();
+        this.options.onClose?.();
+    }
+    execute(sql, params) {
+        return this.baseConnection.execute(sql, params);
+    }
+    executeBatch(sql, params) {
+        return this.baseConnection.executeBatch(sql, params);
+    }
+    getConfig() {
+        return this.baseConnection.getConfig();
+    }
+}

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

@@ -0,0 +1,127 @@
+import * as SQLite from '@journeyapps/wa-sqlite';
+import { BaseObserver, BatchedUpdateNotification } from '@powersync/common';
+import { Mutex } from 'async-mutex';
+import { AsyncDatabaseConnection, OnTableChangeCallback, ProxiedQueryResult } from '../AsyncDatabaseConnection';
+import { ResolvedWASQLiteOpenFactoryOptions } from './WASQLiteOpenFactory';
+/**
+ * List of currently tested virtual filesystems
+ */
+export declare enum WASQLiteVFS {
+    IDBBatchAtomicVFS = "IDBBatchAtomicVFS",
+    OPFSCoopSyncVFS = "OPFSCoopSyncVFS",
+    AccessHandlePoolVFS = "AccessHandlePoolVFS"
+}
+/**
+ * @internal
+ */
+export type WASQLiteBroadCastTableUpdateEvent = {
+    changedTables: Set<string>;
+    connectionId: number;
+};
+/**
+ * @internal
+ */
+export type WASQLiteConnectionListener = {
+    tablesUpdated: (event: BatchedUpdateNotification) => void;
+};
+/**
+ * @internal
+ */
+export type SQLiteModule = Parameters<typeof SQLite.Factory>[0];
+/**
+ * @internal
+ */
+export type WASQLiteModuleFactoryOptions = {
+    dbFileName: string;
+    encryptionKey?: string;
+};
+/**
+ * @internal
+ */
+export type WASQLiteModuleFactory = (options: WASQLiteModuleFactoryOptions) => Promise<{
+    module: SQLiteModule;
+    vfs: SQLiteVFS;
+}>;
+/**
+ * @internal
+ */
+export declare const AsyncWASQLiteModuleFactory: () => Promise<any>;
+/**
+ * @internal
+ */
+export declare const MultiCipherAsyncWASQLiteModuleFactory: () => Promise<any>;
+/**
+ * @internal
+ */
+export declare const SyncWASQLiteModuleFactory: () => Promise<any>;
+/**
+ * @internal
+ */
+export declare const MultiCipherSyncWASQLiteModuleFactory: () => Promise<any>;
+/**
+ * @internal
+ */
+export declare const DEFAULT_MODULE_FACTORIES: {
+    IDBBatchAtomicVFS: (options: WASQLiteModuleFactoryOptions) => Promise<{
+        module: any;
+        vfs: any;
+    }>;
+    AccessHandlePoolVFS: (options: WASQLiteModuleFactoryOptions) => Promise<{
+        module: any;
+        vfs: any;
+    }>;
+    OPFSCoopSyncVFS: (options: WASQLiteModuleFactoryOptions) => Promise<{
+        module: any;
+        vfs: any;
+    }>;
+};
+/**
+ * @internal
+ * WA-SQLite connection which directly interfaces with WA-SQLite.
+ * This is usually instantiated inside a worker.
+ */
+export declare class WASqliteConnection extends BaseObserver<WASQLiteConnectionListener> implements AsyncDatabaseConnection<ResolvedWASQLiteOpenFactoryOptions> {
+    protected options: ResolvedWASQLiteOpenFactoryOptions;
+    private _sqliteAPI;
+    private _dbP;
+    private _moduleFactory;
+    protected updatedTables: Set<string>;
+    protected updateTimer: ReturnType<typeof setTimeout> | null;
+    protected statementMutex: Mutex;
+    protected broadcastChannel: BroadcastChannel | null;
+    /**
+     * Unique id for this specific connection. This is used to prevent broadcast table change
+     * notification loops.
+     */
+    protected connectionId: number;
+    constructor(options: ResolvedWASQLiteOpenFactoryOptions);
+    protected get sqliteAPI(): SQLiteAPI;
+    protected get dbP(): number;
+    protected openDB(): Promise<number>;
+    protected executeEncryptionPragma(): Promise<void>;
+    protected openSQLiteAPI(): Promise<SQLiteAPI>;
+    protected registerBroadcastListeners(): void;
+    protected queueTableUpdate(tableNames: Set<string>, shouldBroadcast?: boolean): void;
+    init(): Promise<void>;
+    getConfig(): Promise<ResolvedWASQLiteOpenFactoryOptions>;
+    fireUpdates(shouldBroadcast?: boolean): void;
+    /**
+     * This executes SQL statements in a batch.
+     */
+    executeBatch(sql: string, bindings?: any[][]): Promise<ProxiedQueryResult>;
+    /**
+     * This executes single SQL statements inside a requested lock.
+     */
+    execute(sql: string | TemplateStringsArray, bindings?: any[]): Promise<ProxiedQueryResult>;
+    close(): Promise<void>;
+    registerOnTableChange(callback: OnTableChangeCallback): Promise<() => void>;
+    /**
+     * This requests a lock for executing statements.
+     * Should only be used internally.
+     */
+    protected acquireExecuteLock: <T>(callback: () => Promise<T>) => Promise<T>;
+    /**
+     * This executes a single statement using SQLite3.
+     */
+    protected executeSingleStatement(sql: string | TemplateStringsArray, bindings?: any[]): Promise<ProxiedQueryResult>;
+}

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

@@ -0,0 +1,343 @@
+import * as SQLite from '@journeyapps/wa-sqlite';
+import { BaseObserver } from '@powersync/common';
+import { Mutex } from 'async-mutex';
+/**
+ * List of currently tested virtual filesystems
+ */
+export var WASQLiteVFS;
+(function (WASQLiteVFS) {
+    WASQLiteVFS["IDBBatchAtomicVFS"] = "IDBBatchAtomicVFS";
+    WASQLiteVFS["OPFSCoopSyncVFS"] = "OPFSCoopSyncVFS";
+    WASQLiteVFS["AccessHandlePoolVFS"] = "AccessHandlePoolVFS";
+})(WASQLiteVFS || (WASQLiteVFS = {}));
+/**
+ * @internal
+ */
+export const AsyncWASQLiteModuleFactory = async () => {
+    const { default: factory } = await import('@journeyapps/wa-sqlite/dist/wa-sqlite-async.mjs');
+    return factory();
+};
+/**
+ * @internal
+ */
+export const MultiCipherAsyncWASQLiteModuleFactory = async () => {
+    const { default: factory } = await import('@journeyapps/wa-sqlite/dist/mc-wa-sqlite-async.mjs');
+    return factory();
+};
+/**
+ * @internal
+ */
+export const SyncWASQLiteModuleFactory = async () => {
+    const { default: factory } = await import('@journeyapps/wa-sqlite/dist/wa-sqlite.mjs');
+    return factory();
+};
+/**
+ * @internal
+ */
+export const MultiCipherSyncWASQLiteModuleFactory = async () => {
+    const { default: factory } = await import('@journeyapps/wa-sqlite/dist/mc-wa-sqlite.mjs');
+    return factory();
+};
+/**
+ * @internal
+ */
+export const DEFAULT_MODULE_FACTORIES = {
+    [WASQLiteVFS.IDBBatchAtomicVFS]: async (options) => {
+        let module;
+        if (options.encryptionKey) {
+            module = await MultiCipherAsyncWASQLiteModuleFactory();
+        }
+        else {
+            module = await AsyncWASQLiteModuleFactory();
+        }
+        const { IDBBatchAtomicVFS } = await import('@journeyapps/wa-sqlite/src/examples/IDBBatchAtomicVFS.js');
+        return {
+            module,
+            // @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) => {
+        let module;
+        if (options.encryptionKey) {
+            module = await MultiCipherSyncWASQLiteModuleFactory();
+        }
+        else {
+            module = await SyncWASQLiteModuleFactory();
+        }
+        // @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) => {
+        let module;
+        if (options.encryptionKey) {
+            module = await MultiCipherSyncWASQLiteModuleFactory();
+        }
+        else {
+            module = await SyncWASQLiteModuleFactory();
+        }
+        // @ts-expect-error The types for this static method are missing upstream
+        const { OPFSCoopSyncVFS } = await import('@journeyapps/wa-sqlite/src/examples/OPFSCoopSyncVFS.js');
+        return {
+            module,
+            vfs: await OPFSCoopSyncVFS.create(options.dbFileName, module)
+        };
+    }
+};
+/**
+ * @internal
+ * WA-SQLite connection which directly interfaces with WA-SQLite.
+ * This is usually instantiated inside a worker.
+ */
+export class WASqliteConnection extends BaseObserver {
+    options;
+    _sqliteAPI = null;
+    _dbP = null;
+    _moduleFactory;
+    updatedTables;
+    updateTimer;
+    statementMutex;
+    broadcastChannel;
+    /**
+     * Unique id for this specific connection. This is used to prevent broadcast table change
+     * notification loops.
+     */
+    connectionId;
+    constructor(options) {
+        super();
+        this.options = options;
+        this.updatedTables = new Set();
+        this.updateTimer = null;
+        this.broadcastChannel = null;
+        this.connectionId = new Date().valueOf() + Math.random();
+        this.statementMutex = new Mutex();
+        this._moduleFactory = DEFAULT_MODULE_FACTORIES[this.options.vfs];
+    }
+    get sqliteAPI() {
+        if (!this._sqliteAPI) {
+            throw new Error(`Initialization has not completed`);
+        }
+        return this._sqliteAPI;
+    }
+    get dbP() {
+        if (!this._dbP) {
+            throw new Error(`Initialization has not completed`);
+        }
+        return this._dbP;
+    }
+    async openDB() {
+        this._dbP = await this.sqliteAPI.open_v2(this.options.dbFilename);
+        return this._dbP;
+    }
+    async executeEncryptionPragma() {
+        if (this.options.encryptionKey) {
+            await this.executeSingleStatement(`PRAGMA key = "${this.options.encryptionKey}"`);
+        }
+        return;
+    }
+    async openSQLiteAPI() {
+        const { module, vfs } = await this._moduleFactory({
+            dbFileName: this.options.dbFilename,
+            encryptionKey: this.options.encryptionKey
+        });
+        const sqlite3 = SQLite.Factory(module);
+        sqlite3.vfs_register(vfs, true);
+        /**
+         * Register the PowerSync core SQLite extension
+         */
+        module.ccall('powersync_init_static', 'int', []);
+        /**
+         * Create the multiple cipher vfs if an encryption key is provided
+         */
+        if (this.options.encryptionKey) {
+            const createResult = module.ccall('sqlite3mc_vfs_create', 'int', ['string', 'int'], [this.options.dbFilename, 1]);
+            if (createResult !== 0) {
+                throw new Error('Failed to create multiple cipher vfs, Database encryption will not work');
+            }
+        }
+        return sqlite3;
+    }
+    registerBroadcastListeners() {
+        this.broadcastChannel = new BroadcastChannel(`${this.options.dbFilename}-table-updates`);
+        this.broadcastChannel.addEventListener('message', (event) => {
+            const data = event.data;
+            if (this.connectionId == data.connectionId) {
+                // Ignore messages from the same connection
+                return;
+            }
+            // Ensuring that we don't rebroadcast the same message
+            this.queueTableUpdate(data.changedTables, false);
+        });
+    }
+    queueTableUpdate(tableNames, shouldBroadcast = true) {
+        tableNames.forEach((tableName) => this.updatedTables.add(tableName));
+        if (this.updateTimer == null) {
+            this.updateTimer = setTimeout(() => this.fireUpdates(shouldBroadcast), 0);
+        }
+    }
+    async init() {
+        this._sqliteAPI = await this.openSQLiteAPI();
+        await this.openDB();
+        this.registerBroadcastListeners();
+        await this.executeSingleStatement(`PRAGMA temp_store = ${this.options.temporaryStorage};`);
+        await this.executeEncryptionPragma();
+        this.sqliteAPI.update_hook(this.dbP, (updateType, dbName, tableName) => {
+            if (!tableName) {
+                return;
+            }
+            const changedTables = new Set([tableName]);
+            this.queueTableUpdate(changedTables);
+        });
+    }
+    async getConfig() {
+        return this.options;
+    }
+    fireUpdates(shouldBroadcast = true) {
+        this.updateTimer = null;
+        const event = { tables: [...this.updatedTables], groupedUpdates: {}, rawUpdates: [] };
+        // Share to other connections
+        if (shouldBroadcast) {
+            this.broadcastChannel.postMessage({
+                changedTables: this.updatedTables,
+                connectionId: this.connectionId
+            });
+        }
+        this.updatedTables.clear();
+        this.iterateListeners((cb) => cb.tablesUpdated?.(event));
+    }
+    /**
+     * This executes SQL statements in a batch.
+     */
+    async executeBatch(sql, bindings) {
+        return this.acquireExecuteLock(async () => {
+            let affectedRows = 0;
+            try {
+                await this.executeSingleStatement('BEGIN TRANSACTION');
+                const wrappedBindings = bindings ? bindings : [];
+                for await (const stmt of this.sqliteAPI.statements(this.dbP, sql)) {
+                    if (stmt === null) {
+                        return {
+                            rowsAffected: 0,
+                            rows: { _array: [], length: 0 }
+                        };
+                    }
+                    //Prepare statement once
+                    for (const binding of wrappedBindings) {
+                        // TODO not sure why this is needed currently, but booleans break
+                        for (let i = 0; i < binding.length; i++) {
+                            const b = binding[i];
+                            if (typeof b == 'boolean') {
+                                binding[i] = b ? 1 : 0;
+                            }
+                        }
+                        if (bindings) {
+                            this.sqliteAPI.bind_collection(stmt, binding);
+                        }
+                        const result = await this.sqliteAPI.step(stmt);
+                        if (result === SQLite.SQLITE_DONE) {
+                            //The value returned by sqlite3_changes() immediately after an INSERT, UPDATE or DELETE statement run on a view is always zero.
+                            affectedRows += this.sqliteAPI.changes(this.dbP);
+                        }
+                        this.sqliteAPI.reset(stmt);
+                    }
+                }
+                await this.executeSingleStatement('COMMIT');
+            }
+            catch (err) {
+                await this.executeSingleStatement('ROLLBACK');
+                return {
+                    rowsAffected: 0,
+                    rows: { _array: [], length: 0 }
+                };
+            }
+            const result = {
+                rowsAffected: affectedRows,
+                rows: { _array: [], length: 0 }
+            };
+            return result;
+        });
+    }
+    /**
+     * This executes single SQL statements inside a requested lock.
+     */
+    async execute(sql, bindings) {
+        // Running multiple statements on the same connection concurrently should not be allowed
+        return this.acquireExecuteLock(async () => {
+            return this.executeSingleStatement(sql, bindings);
+        });
+    }
+    async close() {
+        this.broadcastChannel?.close();
+        await this.sqliteAPI.close(this.dbP);
+    }
+    async registerOnTableChange(callback) {
+        return this.registerListener({
+            tablesUpdated: (event) => callback(event)
+        });
+    }
+    /**
+     * This requests a lock for executing statements.
+     * Should only be used internally.
+     */
+    acquireExecuteLock = (callback) => {
+        return this.statementMutex.runExclusive(callback);
+    };
+    /**
+     * This executes a single statement using SQLite3.
+     */
+    async executeSingleStatement(sql, bindings) {
+        const results = [];
+        for await (const stmt of this.sqliteAPI.statements(this.dbP, sql)) {
+            let columns;
+            const wrappedBindings = bindings ? [bindings] : [[]];
+            for (const binding of wrappedBindings) {
+                // TODO not sure why this is needed currently, but booleans break
+                binding.forEach((b, index, arr) => {
+                    if (typeof b == 'boolean') {
+                        arr[index] = b ? 1 : 0;
+                    }
+                });
+                this.sqliteAPI.reset(stmt);
+                if (bindings) {
+                    this.sqliteAPI.bind_collection(stmt, binding);
+                }
+                const rows = [];
+                while ((await this.sqliteAPI.step(stmt)) === SQLite.SQLITE_ROW) {
+                    const row = this.sqliteAPI.row(stmt);
+                    rows.push(row);
+                }
+                columns = columns ?? this.sqliteAPI.column_names(stmt);
+                if (columns.length) {
+                    results.push({ columns, rows });
+                }
+            }
+            // When binding parameters, only a single statement is executed.
+            if (bindings) {
+                break;
+            }
+        }
+        const rows = [];
+        for (const resultSet of results) {
+            for (const row of resultSet.rows) {
+                const outRow = {};
+                resultSet.columns.forEach((key, index) => {
+                    outRow[key] = row[index];
+                });
+                rows.push(outRow);
+            }
+        }
+        const result = {
+            insertId: this.sqliteAPI.last_insert_id(this.dbP),
+            rowsAffected: this.sqliteAPI.changes(this.dbP),
+            rows: {
+                _array: rows,
+                length: rows.length
+            }
+        };
+        return result;
+    }
+}

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

@@ -1,5 +1,7 @@
-import { type DBAdapter, type DBAdapterListener, type DBLockOptions, type LockContext, type PowerSyncOpenFactoryOptions, type QueryResult, type Transaction, BaseObserver } from '@powersync/common';
+import { type PowerSyncOpenFactoryOptions } from '@powersync/common';
+import { LockedAsyncDatabaseAdapter } from '../LockedAsyncDatabaseAdapter';
 import { ResolvedWebSQLOpenOptions, TemporaryStorageOption, WebSQLFlags } from '../web-sql-flags';
+import { WASQLiteVFS } from './WASQLiteConnection';
 /**
  * These flags are the same as {@link WebSQLFlags}.
  * This export is maintained only for API consistency
@@ -13,51 +15,17 @@ export interface WASQLiteDBAdapterOptions extends Omit<PowerSyncOpenFactoryOptio
      */
     workerPort?: MessagePort;
     worker?: string | URL | ((options: ResolvedWebSQLOpenOptions) => Worker | SharedWorker);
+    vfs?: WASQLiteVFS;
     temporaryStorage?: TemporaryStorageOption;
+    /**
+     * Encryption key for the database.
+     * If set, the database will be encrypted using multiple-ciphers.
+     */
+    encryptionKey?: string;
 }
 /**
  * Adapter for WA-SQLite SQLite connections.
  */
-export declare class WASQLiteDBAdapter extends BaseObserver<DBAdapterListener> implements DBAdapter {
-    protected options: WASQLiteDBAdapterOptions;
-    private initialized;
-    private logger;
-    private dbGetHelpers;
-    private methods;
-    private debugMode;
+export declare class WASQLiteDBAdapter extends LockedAsyncDatabaseAdapter {
     constructor(options: WASQLiteDBAdapterOptions);
-    get name(): string;
-    protected get flags(): Required<WASQLiteFlags>;
-    getWorker(): void;
-    protected init(): Promise<void>;
-    execute(query: string, params?: any[] | undefined): Promise<QueryResult>;
-    executeBatch(query: string, params?: any[][]): Promise<QueryResult>;
-    /**
-     * Wraps the worker execute function, awaiting for it to be available
-     */
-    private _execute;
-    /**
-     * Wraps the worker executeBatch function, awaiting for it to be available
-     */
-    private _executeBatch;
-    /**
-     * Attempts to close the connection.
-     * Shared workers might not actually close the connection if other
-     * tabs are still using it.
-     */
-    close(): void;
-    getAll<T>(sql: string, parameters?: any[] | undefined): Promise<T[]>;
-    getOptional<T>(sql: string, parameters?: any[] | undefined): Promise<T | null>;
-    get<T>(sql: string, parameters?: any[] | undefined): Promise<T>;
-    readLock<T>(fn: (tx: LockContext) => Promise<T>, options?: DBLockOptions | undefined): Promise<T>;
-    writeLock<T>(fn: (tx: LockContext) => Promise<T>, options?: DBLockOptions | undefined): Promise<T>;
-    protected acquireLock(callback: () => Promise<any>): Promise<any>;
-    readTransaction<T>(fn: (tx: Transaction) => Promise<T>, options?: DBLockOptions | undefined): Promise<T>;
-    writeTransaction<T>(fn: (tx: Transaction) => Promise<T>, options?: DBLockOptions | undefined): Promise<T>;
-    /**
-     * Wraps a lock context into a transaction context
-     */
-    private wrapTransaction;
-    private generateDBHelpers;
-    refreshSchema(): Promise<void>;
 }