@powersync/web 0.0.0-dev-20260202162549 → 0.0.0-dev-20260216124709

package/lib/src/db/sync/userAgent.js

@@ -0,0 +1,64 @@
+/**
+ * Get a minimal representation of browser, version and operating system.
+ *
+ * The goal is to get enough environemnt info to reproduce issues, but no
+ * more.
+ */
+export function getUserAgentInfo(nav) {
+    nav ??= navigator;
+    const browser = getBrowserInfo(nav);
+    const os = getOsInfo(nav);
+    // The cast below is to cater for TypeScript < 5.5.0
+    return [browser, os].filter((v) => v != null);
+}
+function getBrowserInfo(nav) {
+    const brands = nav.userAgentData?.brands;
+    if (brands != null) {
+        const tests = [
+            { name: 'Google Chrome', value: 'Chrome' },
+            { name: 'Opera', value: 'Opera' },
+            { name: 'Edge', value: 'Edge' },
+            { name: 'Chromium', value: 'Chromium' }
+        ];
+        for (let { name, value } of tests) {
+            const brand = brands.find((b) => b.brand == name);
+            if (brand != null) {
+                return `${value}/${brand.version}`;
+            }
+        }
+    }
+    const ua = nav.userAgent;
+    const regexps = [
+        { re: /(?:firefox|fxios)\/(\d+)/i, value: 'Firefox' },
+        { re: /(?:edg|edge|edga|edgios)\/(\d+)/i, value: 'Edge' },
+        { re: /opr\/(\d+)/i, value: 'Opera' },
+        { re: /(?:chrome|chromium|crios)\/(\d+)/i, value: 'Chrome' },
+        { re: /version\/(\d+).*safari/i, value: 'Safari' }
+    ];
+    for (let { re, value } of regexps) {
+        const match = re.exec(ua);
+        if (match != null) {
+            return `${value}/${match[1]}`;
+        }
+    }
+    return null;
+}
+function getOsInfo(nav) {
+    if (nav.userAgentData?.platform != null) {
+        return nav.userAgentData.platform.toLowerCase();
+    }
+    const ua = nav.userAgent;
+    const regexps = [
+        { re: /windows/i, value: 'windows' },
+        { re: /android/i, value: 'android' },
+        { re: /linux/i, value: 'linux' },
+        { re: /iphone|ipad|ipod/i, value: 'ios' },
+        { re: /macintosh|mac os x/i, value: 'macos' }
+    ];
+    for (let { re, value } of regexps) {
+        if (re.test(ua)) {
+            return value;
+        }
+    }
+    return null;
+}

package/lib/src/index.d.ts

@@ -0,0 +1,15 @@
+export * from '@powersync/common';
+export * from './attachments/IndexDBFileSystemAdapter.js';
+export * from './db/adapters/AbstractWebPowerSyncDatabaseOpenFactory.js';
+export * from './db/adapters/AbstractWebSQLOpenFactory.js';
+export * from './db/adapters/AsyncDatabaseConnection.js';
+export * from './db/adapters/wa-sqlite/WASQLiteConnection.js';
+export * from './db/adapters/wa-sqlite/WASQLiteDBAdapter.js';
+export * from './db/adapters/wa-sqlite/WASQLiteOpenFactory.js';
+export * from './db/adapters/wa-sqlite/WASQLitePowerSyncDatabaseOpenFactory.js';
+export * from './db/adapters/web-sql-flags.js';
+export * from './db/PowerSyncDatabase.js';
+export * from './db/sync/SharedWebStreamingSyncImplementation.js';
+export * from './db/sync/WebRemote.js';
+export * from './db/sync/WebStreamingSyncImplementation.js';
+export * from './db/adapters/WebDBAdapter.js';

package/lib/src/index.js

@@ -0,0 +1,15 @@
+export * from '@powersync/common';
+export * from './attachments/IndexDBFileSystemAdapter.js';
+export * from './db/adapters/AbstractWebPowerSyncDatabaseOpenFactory.js';
+export * from './db/adapters/AbstractWebSQLOpenFactory.js';
+export * from './db/adapters/AsyncDatabaseConnection.js';
+export * from './db/adapters/wa-sqlite/WASQLiteConnection.js';
+export * from './db/adapters/wa-sqlite/WASQLiteDBAdapter.js';
+export * from './db/adapters/wa-sqlite/WASQLiteOpenFactory.js';
+export * from './db/adapters/wa-sqlite/WASQLitePowerSyncDatabaseOpenFactory.js';
+export * from './db/adapters/web-sql-flags.js';
+export * from './db/PowerSyncDatabase.js';
+export * from './db/sync/SharedWebStreamingSyncImplementation.js';
+export * from './db/sync/WebRemote.js';
+export * from './db/sync/WebStreamingSyncImplementation.js';
+export * from './db/adapters/WebDBAdapter.js';

package/lib/src/shared/navigator.d.ts

@@ -0,0 +1 @@
+export declare const getNavigatorLocks: () => LockManager;

package/lib/src/shared/navigator.js

@@ -0,0 +1,6 @@
+export const getNavigatorLocks = () => {
+    if ('locks' in navigator && navigator.locks) {
+        return navigator.locks;
+    }
+    throw new Error('Navigator locks are not available in an insecure context. Use a secure context such as HTTPS or http://localhost.');
+};

package/lib/src/worker/db/SharedWASQLiteConnection.d.ts

@@ -0,0 +1,42 @@
+import { ILogger } from '@powersync/common';
+import { AsyncDatabaseConnection, OnTableChangeCallback, ProxiedQueryResult } from '../../db/adapters/AsyncDatabaseConnection.js';
+import { ResolvedWebSQLOpenOptions } from '../../db/adapters/web-sql-flags.js';
+/**
+ * Keeps track of open DB connections and the clients which
+ * are using it.
+ */
+export type SharedDBWorkerConnection = {
+    clientIds: Set<number>;
+    db: AsyncDatabaseConnection;
+};
+export type SharedWASQLiteConnectionOptions = {
+    dbMap: Map<string, SharedDBWorkerConnection>;
+    dbFilename: string;
+    clientId: number;
+    logger: ILogger;
+};
+export declare class SharedWASQLiteConnection implements AsyncDatabaseConnection {
+    protected options: SharedWASQLiteConnectionOptions;
+    protected isClosing: boolean;
+    protected activeHoldId: string | null;
+    constructor(options: SharedWASQLiteConnectionOptions);
+    protected get logger(): ILogger;
+    protected get dbEntry(): SharedDBWorkerConnection;
+    protected get connection(): AsyncDatabaseConnection<ResolvedWebSQLOpenOptions>;
+    protected get clientIds(): Set<number>;
+    init(): Promise<void>;
+    markHold(): Promise<string>;
+    releaseHold(id: string): Promise<void>;
+    isAutoCommit(): Promise<boolean>;
+    /**
+     * Handles closing of a shared connection.
+     * The connection is only closed if there are no active clients using it.
+     */
+    close(): Promise<void>;
+    protected withClosing<T>(action: () => Promise<T>): Promise<T>;
+    execute(sql: string, params?: any[]): Promise<ProxiedQueryResult>;
+    executeRaw(sql: string, params?: any[]): Promise<any[][]>;
+    executeBatch(sql: string, params?: any[] | undefined): Promise<ProxiedQueryResult>;
+    registerOnTableChange(callback: OnTableChangeCallback): Promise<() => void>;
+    getConfig(): Promise<ResolvedWebSQLOpenOptions>;
+}

package/lib/src/worker/db/SharedWASQLiteConnection.js

@@ -0,0 +1,90 @@
+export class SharedWASQLiteConnection {
+    options;
+    isClosing;
+    // Keeps track if this current hold if the shared connection has a hold
+    activeHoldId;
+    constructor(options) {
+        this.options = options;
+        // Add this client ID to the set of known clients
+        this.clientIds.add(options.clientId);
+        this.isClosing = false;
+        this.activeHoldId = null;
+    }
+    get logger() {
+        return this.options.logger;
+    }
+    get dbEntry() {
+        return this.options.dbMap.get(this.options.dbFilename);
+    }
+    get connection() {
+        return this.dbEntry.db;
+    }
+    get clientIds() {
+        return this.dbEntry.clientIds;
+    }
+    async init() {
+        // No-op since the connection is already initialized when it was created
+    }
+    async markHold() {
+        this.activeHoldId = await this.connection.markHold();
+        return this.activeHoldId;
+    }
+    async releaseHold(id) {
+        try {
+            await this.connection.releaseHold(id);
+        }
+        finally {
+            this.activeHoldId = null;
+        }
+    }
+    async isAutoCommit() {
+        return this.connection.isAutoCommit();
+    }
+    /**
+     * Handles closing of a shared connection.
+     * The connection is only closed if there are no active clients using it.
+     */
+    async close() {
+        // This prevents further statements on this connection from being executed
+        this.isClosing = true;
+        const { clientIds, logger } = this;
+        const { clientId, dbFilename, dbMap } = this.options;
+        logger.debug(`Close requested from client ${clientId} of ${[...clientIds]}`);
+        clientIds.delete(clientId);
+        if (this.activeHoldId) {
+            // We can't cleanup here since we're not in a lock context.
+            // The cleanup will occur once a new hold is acquired.
+            this.logger.info(`Hold ${this.activeHoldId} was still active when the connection was closed. Cleanup will occur once a new hold is acquired.`);
+        }
+        if (clientIds.size == 0) {
+            logger.debug(`Closing connection to ${this.options}.`);
+            const connection = this.connection;
+            dbMap.delete(dbFilename);
+            await connection.close();
+            return;
+        }
+        logger.debug(`Connection to ${dbFilename} not closed yet due to active clients.`);
+        return;
+    }
+    async withClosing(action) {
+        if (this.isClosing) {
+            throw new Error('Connection is closing');
+        }
+        return action();
+    }
+    async execute(sql, params) {
+        return this.withClosing(() => this.connection.execute(sql, params));
+    }
+    async executeRaw(sql, params) {
+        return this.withClosing(() => this.connection.executeRaw(sql, params));
+    }
+    executeBatch(sql, params) {
+        return this.withClosing(() => this.connection.executeBatch(sql, params));
+    }
+    registerOnTableChange(callback) {
+        return this.connection.registerOnTableChange(callback);
+    }
+    getConfig() {
+        return this.connection.getConfig();
+    }
+}

package/lib/src/worker/db/WASQLiteDB.worker.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Supports both shared and dedicated workers, based on how the worker is constructed (new SharedWorker vs new Worker()).
+ */
+import '@journeyapps/wa-sqlite';

package/lib/src/worker/db/WASQLiteDB.worker.js

@@ -0,0 +1,69 @@
+/**
+ * Supports both shared and dedicated workers, based on how the worker is constructed (new SharedWorker vs new Worker()).
+ */
+import '@journeyapps/wa-sqlite';
+import { createBaseLogger, createLogger } from '@powersync/common';
+import * as Comlink from 'comlink';
+import { getNavigatorLocks } from '../../shared/navigator.js';
+import { SharedWASQLiteConnection } from './SharedWASQLiteConnection.js';
+import { WorkerWASQLiteConnection } from './WorkerWASQLiteConnection.js';
+const baseLogger = createBaseLogger();
+baseLogger.useDefaults();
+const logger = createLogger('db-worker');
+const DBMap = new Map();
+const OPEN_DB_LOCK = 'open-wasqlite-db';
+let nextClientId = 1;
+const openDBShared = async (options) => {
+    // Prevent multiple simultaneous opens from causing race conditions
+    return getNavigatorLocks().request(OPEN_DB_LOCK, async () => {
+        const clientId = nextClientId++;
+        const { dbFilename, logLevel } = options;
+        logger.setLevel(logLevel);
+        if (!DBMap.has(dbFilename)) {
+            const clientIds = new Set();
+            // This format returns proxy objects for function callbacks
+            const connection = new WorkerWASQLiteConnection(options);
+            await connection.init();
+            connection.registerListener({
+                holdOverwritten: async () => {
+                    /**
+                     * The previous hold has been overwritten, without being released.
+                     * we need to cleanup any resources associated with it.
+                     * We can perform a rollback to release any potential transactions that were started.
+                     */
+                    await connection.execute('ROLLBACK').catch(() => { });
+                }
+            });
+            DBMap.set(dbFilename, {
+                clientIds,
+                db: connection
+            });
+        }
+        // Associates this clientId with the shared connection entry
+        const sharedConnection = new SharedWASQLiteConnection({
+            dbMap: DBMap,
+            dbFilename,
+            clientId,
+            logger
+        });
+        return Comlink.proxy(sharedConnection);
+    });
+};
+// Check if we're in a SharedWorker context
+if (typeof SharedWorkerGlobalScope !== 'undefined') {
+    const _self = self;
+    _self.onconnect = function (event) {
+        const port = event.ports[0];
+        Comlink.expose(openDBShared, port);
+    };
+}
+else {
+    // A dedicated worker can be shared externally
+    Comlink.expose(openDBShared);
+}
+addEventListener('unload', () => {
+    Array.from(DBMap.values()).forEach(async (dbConnection) => {
+        const { db } = dbConnection;
+        db.close?.();
+    });
+});

package/lib/src/worker/db/WorkerWASQLiteConnection.d.ts

@@ -0,0 +1,9 @@
+import { OnTableChangeCallback } from '../../db/adapters/AsyncDatabaseConnection.js';
+import { WASqliteConnection } from '../../db/adapters/wa-sqlite/WASQLiteConnection.js';
+/**
+ * A Small proxy wrapper around the WASqliteConnection.
+ * This ensures that certain return types are properly proxied.
+ */
+export declare class WorkerWASQLiteConnection extends WASqliteConnection {
+    registerOnTableChange(callback: OnTableChangeCallback): Promise<() => void>;
+}

package/lib/src/worker/db/WorkerWASQLiteConnection.js

@@ -0,0 +1,12 @@
+import * as Comlink from 'comlink';
+import { WASqliteConnection } from '../../db/adapters/wa-sqlite/WASQLiteConnection.js';
+/**
+ * A Small proxy wrapper around the WASqliteConnection.
+ * This ensures that certain return types are properly proxied.
+ */
+export class WorkerWASQLiteConnection extends WASqliteConnection {
+    async registerOnTableChange(callback) {
+        // Proxy the callback remove function
+        return Comlink.proxy(await super.registerOnTableChange(callback));
+    }
+}

package/lib/src/worker/db/open-worker-database.d.ts

@@ -0,0 +1,14 @@
+import * as Comlink from 'comlink';
+import { OpenAsyncDatabaseConnection } from '../../db/adapters/AsyncDatabaseConnection.js';
+import { WASQLiteVFS } from '../../db/adapters/wa-sqlite/WASQLiteConnection.js';
+/**
+ * Opens a shared or dedicated worker which exposes opening of database connections
+ */
+export declare function openWorkerDatabasePort(workerIdentifier: string, multipleTabs?: boolean, worker?: string | URL, vfs?: WASQLiteVFS): Worker | MessagePort;
+/**
+ * @returns A function which allows for opening database connections inside
+ * a worker.
+ */
+export declare function getWorkerDatabaseOpener(workerIdentifier: string, multipleTabs?: boolean, worker?: string | URL): Comlink.Remote<OpenAsyncDatabaseConnection>;
+export declare function resolveWorkerDatabasePortFactory(worker: () => Worker | SharedWorker): Worker | MessagePort;
+export declare function isSharedWorker(worker: Worker | SharedWorker): worker is SharedWorker;

package/lib/src/worker/db/open-worker-database.js

@@ -0,0 +1,52 @@
+import * as Comlink from 'comlink';
+import { WASQLiteVFS } from '../../db/adapters/wa-sqlite/WASQLiteConnection.js';
+/**
+ * Opens a shared or dedicated worker which exposes opening of database connections
+ */
+export function openWorkerDatabasePort(workerIdentifier, multipleTabs = true, worker = '', vfs) {
+    const needsDedicated = vfs == WASQLiteVFS.AccessHandlePoolVFS || vfs == WASQLiteVFS.OPFSCoopSyncVFS;
+    if (worker) {
+        return !needsDedicated && multipleTabs
+            ? new SharedWorker(`${worker}`, {
+                /* @vite-ignore */
+                name: `shared-DB-worker-${workerIdentifier}`
+            }).port
+            : new Worker(`${worker}`, {
+                /* @vite-ignore */
+                name: `DB-worker-${workerIdentifier}`
+            });
+    }
+    else {
+        /**
+         *  Webpack V5 can bundle the worker automatically if the full Worker constructor syntax is used
+         *  https://webpack.js.org/guides/web-workers/
+         *  This enables multi tab support by default, but falls back if SharedWorker is not available
+         *  (in the case of Android)
+         */
+        return !needsDedicated && multipleTabs
+            ? new SharedWorker(new URL('./WASQLiteDB.worker.js', import.meta.url), {
+                /* @vite-ignore */
+                name: `shared-DB-worker-${workerIdentifier}`,
+                type: 'module'
+            }).port
+            : new Worker(new URL('./WASQLiteDB.worker.js', import.meta.url), {
+                /* @vite-ignore */
+                name: `DB-worker-${workerIdentifier}`,
+                type: 'module'
+            });
+    }
+}
+/**
+ * @returns A function which allows for opening database connections inside
+ * a worker.
+ */
+export function getWorkerDatabaseOpener(workerIdentifier, multipleTabs = true, worker = '') {
+    return Comlink.wrap(openWorkerDatabasePort(workerIdentifier, multipleTabs, worker));
+}
+export function resolveWorkerDatabasePortFactory(worker) {
+    const workerInstance = worker();
+    return isSharedWorker(workerInstance) ? workerInstance.port : workerInstance;
+}
+export function isSharedWorker(worker) {
+    return 'port' in worker;
+}

package/lib/src/worker/sync/AbstractSharedSyncClientProvider.d.ts

@@ -0,0 +1,19 @@
+import type { PowerSyncCredentials, SyncStatusOptions } from '@powersync/common';
+/**
+ * The client side port should provide these methods.
+ */
+export declare abstract class AbstractSharedSyncClientProvider {
+    abstract fetchCredentials(): Promise<PowerSyncCredentials | null>;
+    abstract invalidateCredentials(): void;
+    abstract uploadCrud(): Promise<void>;
+    abstract statusChanged(status: SyncStatusOptions): void;
+    abstract getDBWorkerPort(): Promise<MessagePort>;
+    abstract trace(...x: any[]): void;
+    abstract debug(...x: any[]): void;
+    abstract info(...x: any[]): void;
+    abstract log(...x: any[]): void;
+    abstract warn(...x: any[]): void;
+    abstract error(...x: any[]): void;
+    abstract time(label: string): void;
+    abstract timeEnd(label: string): void;
+}

package/lib/src/worker/sync/AbstractSharedSyncClientProvider.js

@@ -0,0 +1,5 @@
+/**
+ * The client side port should provide these methods.
+ */
+export class AbstractSharedSyncClientProvider {
+}

package/lib/src/worker/sync/BroadcastLogger.d.ts

@@ -0,0 +1,47 @@
+import { type ILogger, type ILogLevel } from '@powersync/common';
+import { type WrappedSyncPort } from './SharedSyncImplementation.js';
+/**
+ * Broadcasts logs to all clients
+ */
+export declare class BroadcastLogger implements ILogger {
+    protected clients: WrappedSyncPort[];
+    TRACE: ILogLevel;
+    DEBUG: ILogLevel;
+    INFO: ILogLevel;
+    TIME: ILogLevel;
+    WARN: ILogLevel;
+    ERROR: ILogLevel;
+    OFF: ILogLevel;
+    private currentLevel;
+    constructor(clients: WrappedSyncPort[]);
+    trace(...x: any[]): void;
+    debug(...x: any[]): void;
+    info(...x: any[]): void;
+    log(...x: any[]): void;
+    warn(...x: any[]): void;
+    error(...x: any[]): void;
+    time(label: string): void;
+    timeEnd(label: string): void;
+    /**
+     * Set the global log level.
+     */
+    setLevel(level: ILogLevel): void;
+    /**
+     * Get the current log level.
+     */
+    getLevel(): ILogLevel;
+    /**
+     * Returns true if the given level is enabled.
+     */
+    enabledFor(level: ILogLevel): boolean;
+    /**
+     * Iterates all clients, catches individual client exceptions
+     * and proceeds to execute for all clients.
+     */
+    protected iterateClients(callback: (client: WrappedSyncPort) => Promise<void>): Promise<void>;
+    /**
+     * Guards against any logging errors.
+     * We don't want a logging exception to cause further issues upstream
+     */
+    protected sanitizeArgs(x: any[]): any[];
+}

package/lib/src/worker/sync/BroadcastLogger.js

@@ -0,0 +1,128 @@
+import { LogLevel } from '@powersync/common';
+/**
+ * Broadcasts logs to all clients
+ */
+export class BroadcastLogger {
+    clients;
+    TRACE;
+    DEBUG;
+    INFO;
+    TIME;
+    WARN;
+    ERROR;
+    OFF;
+    currentLevel = LogLevel.INFO;
+    constructor(clients) {
+        this.clients = clients;
+        this.TRACE = LogLevel.TRACE;
+        this.DEBUG = LogLevel.DEBUG;
+        this.INFO = LogLevel.INFO;
+        this.TIME = LogLevel.TIME;
+        this.WARN = LogLevel.WARN;
+        this.ERROR = LogLevel.ERROR;
+        this.OFF = LogLevel.OFF;
+    }
+    trace(...x) {
+        if (!this.enabledFor(this.TRACE))
+            return;
+        console.trace(...x);
+        const sanitized = this.sanitizeArgs(x);
+        this.iterateClients((client) => client.clientProvider.trace(...sanitized));
+    }
+    debug(...x) {
+        if (!this.enabledFor(this.DEBUG))
+            return;
+        console.debug(...x);
+        const sanitized = this.sanitizeArgs(x);
+        this.iterateClients((client) => client.clientProvider.debug(...sanitized));
+    }
+    info(...x) {
+        if (!this.enabledFor(this.INFO))
+            return;
+        console.info(...x);
+        const sanitized = this.sanitizeArgs(x);
+        this.iterateClients((client) => client.clientProvider.info(...sanitized));
+    }
+    log(...x) {
+        if (!this.enabledFor(this.INFO))
+            return;
+        console.log(...x);
+        const sanitized = this.sanitizeArgs(x);
+        this.iterateClients((client) => client.clientProvider.log(...sanitized));
+    }
+    warn(...x) {
+        if (!this.enabledFor(this.WARN))
+            return;
+        console.warn(...x);
+        const sanitized = this.sanitizeArgs(x);
+        this.iterateClients((client) => client.clientProvider.warn(...sanitized));
+    }
+    error(...x) {
+        if (!this.enabledFor(this.ERROR))
+            return;
+        console.error(...x);
+        const sanitized = this.sanitizeArgs(x);
+        this.iterateClients((client) => client.clientProvider.error(...sanitized));
+    }
+    time(label) {
+        if (!this.enabledFor(this.TIME))
+            return;
+        console.time(label);
+        this.iterateClients((client) => client.clientProvider.time(label));
+    }
+    timeEnd(label) {
+        if (!this.enabledFor(this.TIME))
+            return;
+        console.timeEnd(label);
+        this.iterateClients((client) => client.clientProvider.timeEnd(label));
+    }
+    /**
+     * Set the global log level.
+     */
+    setLevel(level) {
+        this.currentLevel = level;
+    }
+    /**
+     * Get the current log level.
+     */
+    getLevel() {
+        return this.currentLevel;
+    }
+    /**
+     * Returns true if the given level is enabled.
+     */
+    enabledFor(level) {
+        return level.value >= this.currentLevel.value;
+    }
+    /**
+     * Iterates all clients, catches individual client exceptions
+     * and proceeds to execute for all clients.
+     */
+    async iterateClients(callback) {
+        for (const client of this.clients) {
+            try {
+                await callback(client);
+            }
+            catch (ex) {
+                console.error('Caught exception when iterating client', ex);
+            }
+        }
+    }
+    /**
+     * Guards against any logging errors.
+     * We don't want a logging exception to cause further issues upstream
+     */
+    sanitizeArgs(x) {
+        const sanitizedParams = x.map((param) => {
+            try {
+                // Try and clone here first. If it fails it won't be passable over a MessagePort
+                return structuredClone(param);
+            }
+            catch (ex) {
+                console.error(ex);
+                return 'Could not serialize log params. Check shared worker logs for more details.';
+            }
+        });
+        return sanitizedParams;
+    }
+}