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

package/lib/src/db/adapters/web-sql-flags.d.ts

@@ -0,0 +1,87 @@
+import { type ILogger, SQLOpenOptions } from '@powersync/common';
+/**
+ * Common settings used when creating SQL connections on web.
+ */
+export interface WebSQLFlags {
+    /**
+     * Broadcast logs from shared workers, such as the shared sync worker,
+     * to individual tabs. This defaults to true.
+     */
+    broadcastLogs?: boolean;
+    /**
+     * SQLite operations are currently not supported in SSR mode.
+     * A warning will be logged if attempting to use SQLite in SSR.
+     * Setting this to `true` will disabled the warning above.
+     */
+    disableSSRWarning?: boolean;
+    /**
+     * Enables multi tab support
+     */
+    enableMultiTabs?: boolean;
+    /**
+     * The SQLite connection is often executed through a web worker
+     * in order to offload computation. This can be used to manually
+     * disable the use of web workers in environments where web workers
+     * might be unstable.
+     */
+    useWebWorker?: boolean;
+    /**
+     * Open in SSR placeholder mode. DB operations and Sync operations will be a No-op
+     */
+    ssrMode?: boolean;
+}
+export type ResolvedWebSQLFlags = Required<WebSQLFlags>;
+export interface ResolvedWebSQLOpenOptions extends SQLOpenOptions {
+    flags: ResolvedWebSQLFlags;
+    /**
+     * Where to store SQLite temporary files. Defaults to 'MEMORY'.
+     * Setting this to `FILESYSTEM` can cause issues with larger queries or datasets.
+     */
+    temporaryStorage: TemporaryStorageOption;
+    cacheSizeKb: number;
+    /**
+     * Encryption key for the database.
+     * If set, the database will be encrypted using ChaCha20.
+     */
+    encryptionKey?: string;
+}
+export declare enum TemporaryStorageOption {
+    MEMORY = "memory",
+    FILESYSTEM = "file"
+}
+export declare const DEFAULT_CACHE_SIZE_KB: number;
+/**
+ * Options for opening a Web SQL connection
+ */
+export interface WebSQLOpenFactoryOptions extends SQLOpenOptions {
+    flags?: WebSQLFlags;
+    /**
+     * Allows you to override the default wasqlite db worker.
+     *
+     * You can either provide a path to the worker script
+     * or a factory method that returns a worker.
+     */
+    worker?: string | URL | ((options: ResolvedWebSQLOpenOptions) => Worker | SharedWorker);
+    logger?: ILogger;
+    /**
+     * Where to store SQLite temporary files. Defaults to 'MEMORY'.
+     * Setting this to `FILESYSTEM` can cause issues with larger queries or datasets.
+     *
+     * For details, see: https://www.sqlite.org/pragma.html#pragma_temp_store
+     */
+    temporaryStorage?: TemporaryStorageOption;
+    /**
+     * Maximum SQLite cache size. Defaults to 50MB.
+     *
+     * For details, see: https://www.sqlite.org/pragma.html#pragma_cache_size
+     */
+    cacheSizeKb?: number;
+    /**
+     * Encryption key for the database.
+     * If set, the database will be encrypted using ChaCha20.
+     */
+    encryptionKey?: string;
+}
+export declare function isServerSide(): boolean;
+export declare const DEFAULT_WEB_SQL_FLAGS: ResolvedWebSQLFlags;
+export declare function resolveWebSQLFlags(flags?: WebSQLFlags): ResolvedWebSQLFlags;

package/lib/src/db/adapters/web-sql-flags.js

@@ -0,0 +1,36 @@
+export var TemporaryStorageOption;
+(function (TemporaryStorageOption) {
+    TemporaryStorageOption["MEMORY"] = "memory";
+    TemporaryStorageOption["FILESYSTEM"] = "file";
+})(TemporaryStorageOption || (TemporaryStorageOption = {}));
+export const DEFAULT_CACHE_SIZE_KB = 50 * 1024;
+export function isServerSide() {
+    return typeof window == 'undefined';
+}
+export const DEFAULT_WEB_SQL_FLAGS = {
+    broadcastLogs: true,
+    disableSSRWarning: false,
+    ssrMode: isServerSide(),
+    /**
+     * Multiple tabs are by default not supported on Android, iOS and Safari.
+     * Other platforms will have multiple tabs enabled by default.
+     */
+    enableMultiTabs: typeof globalThis.navigator !== 'undefined' && // For SSR purposes
+        typeof SharedWorker !== 'undefined' &&
+        !navigator.userAgent.match(/(Android|iPhone|iPod|iPad)/i) &&
+        !window.safari,
+    useWebWorker: true
+};
+export function resolveWebSQLFlags(flags) {
+    const resolvedFlags = {
+        ...DEFAULT_WEB_SQL_FLAGS,
+        ...(flags ?? {})
+    };
+    if (typeof flags?.enableMultiTabs != 'undefined') {
+        resolvedFlags.enableMultiTabs = flags.enableMultiTabs;
+    }
+    if (flags?.useWebWorker === false) {
+        resolvedFlags.enableMultiTabs = false;
+    }
+    return resolvedFlags;
+}

package/lib/src/db/sync/SSRWebStreamingSyncImplementation.d.ts

@@ -0,0 +1,48 @@
+import { AbstractStreamingSyncImplementationOptions, BaseObserver, LockOptions, PowerSyncConnectionOptions, StreamingSyncImplementation, SyncStatus, SyncStatusOptions } from '@powersync/common';
+import { Mutex } from 'async-mutex';
+export declare class SSRStreamingSyncImplementation extends BaseObserver implements StreamingSyncImplementation {
+    syncMutex: Mutex;
+    crudMutex: Mutex;
+    isConnected: boolean;
+    lastSyncedAt?: Date | undefined;
+    syncStatus: SyncStatus;
+    constructor(options: AbstractStreamingSyncImplementationOptions);
+    obtainLock<T>(lockOptions: LockOptions<T>): Promise<T>;
+    /**
+     * This is a no-op in SSR mode
+     */
+    connect(options?: PowerSyncConnectionOptions): Promise<void>;
+    dispose(): Promise<void>;
+    /**
+     * This is a no-op in SSR mode
+     */
+    disconnect(): Promise<void>;
+    /**
+     * This SSR Mode implementation is immediately ready.
+     */
+    waitForReady(): Promise<void>;
+    /**
+     * This will never resolve in SSR Mode.
+     */
+    waitForStatus(status: SyncStatusOptions): Promise<void>;
+    /**
+     * This will never resolve in SSR Mode.
+     */
+    waitUntilStatusMatches(_predicate: (status: SyncStatus) => boolean): Promise<void>;
+    /**
+     * Returns a placeholder checkpoint. This should not be used.
+     */
+    getWriteCheckpoint(): Promise<string>;
+    /**
+     * The SSR mode adapter will never complete syncing.
+     */
+    hasCompletedSync(): Promise<boolean>;
+    /**
+     * This is a no-op in SSR mode.
+     */
+    triggerCrudUpload(): void;
+    /**
+     * No-op in SSR mode.
+     */
+    updateSubscriptions(): void;
+}

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

@@ -0,0 +1,65 @@
+import { BaseObserver, LockType, SyncStatus } from '@powersync/common';
+import { Mutex } from 'async-mutex';
+export class SSRStreamingSyncImplementation extends BaseObserver {
+    syncMutex;
+    crudMutex;
+    isConnected;
+    lastSyncedAt;
+    syncStatus;
+    constructor(options) {
+        super();
+        this.syncMutex = new Mutex();
+        this.crudMutex = new Mutex();
+        this.syncStatus = new SyncStatus({});
+        this.isConnected = false;
+    }
+    obtainLock(lockOptions) {
+        const mutex = lockOptions.type == LockType.CRUD ? this.crudMutex : this.syncMutex;
+        return mutex.runExclusive(lockOptions.callback);
+    }
+    /**
+     * This is a no-op in SSR mode
+     */
+    async connect(options) { }
+    async dispose() { }
+    /**
+     * This is a no-op in SSR mode
+     */
+    async disconnect() { }
+    /**
+     * This SSR Mode implementation is immediately ready.
+     */
+    async waitForReady() { }
+    /**
+     * This will never resolve in SSR Mode.
+     */
+    async waitForStatus(status) {
+        return this.waitUntilStatusMatches(() => false);
+    }
+    /**
+     * This will never resolve in SSR Mode.
+     */
+    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.
+     */
+    triggerCrudUpload() { }
+    /**
+     * No-op in SSR mode.
+     */
+    updateSubscriptions() { }
+}

package/lib/src/db/sync/SharedWebStreamingSyncImplementation.d.ts

@@ -0,0 +1,57 @@
+import { PowerSyncConnectionOptions, PowerSyncCredentials, SubscribedStream, SyncStatusOptions } from '@powersync/common';
+import * as Comlink from 'comlink';
+import { AbstractSharedSyncClientProvider } from '../../worker/sync/AbstractSharedSyncClientProvider.js';
+import { WorkerClient } from '../../worker/sync/WorkerClient.js';
+import { WebDBAdapter } from '../adapters/WebDBAdapter.js';
+import { WebStreamingSyncImplementation, WebStreamingSyncImplementationOptions } from './WebStreamingSyncImplementation.js';
+/**
+ * The shared worker will trigger methods on this side of the message port
+ * via this client provider.
+ */
+declare class SharedSyncClientProvider extends AbstractSharedSyncClientProvider {
+    protected options: WebStreamingSyncImplementationOptions;
+    statusChanged: (status: SyncStatusOptions) => void;
+    protected webDB: WebDBAdapter;
+    constructor(options: WebStreamingSyncImplementationOptions, statusChanged: (status: SyncStatusOptions) => void, webDB: WebDBAdapter);
+    getDBWorkerPort(): Promise<MessagePort>;
+    invalidateCredentials(): void;
+    fetchCredentials(): Promise<PowerSyncCredentials | null>;
+    uploadCrud(): Promise<void>;
+    get logger(): import("@powersync/common").ILogger | undefined;
+    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;
+}
+export interface SharedWebStreamingSyncImplementationOptions extends WebStreamingSyncImplementationOptions {
+    db: WebDBAdapter;
+}
+/**
+ * The local part of the sync implementation on the web, which talks to a sync implementation hosted in a shared worker.
+ */
+export declare class SharedWebStreamingSyncImplementation extends WebStreamingSyncImplementation {
+    protected syncManager: Comlink.Remote<WorkerClient>;
+    protected clientProvider: SharedSyncClientProvider;
+    protected messagePort: MessagePort;
+    protected isInitialized: Promise<void>;
+    protected dbAdapter: WebDBAdapter;
+    private abortOnClose;
+    constructor(options: SharedWebStreamingSyncImplementationOptions);
+    protected _init(): Promise<void>;
+    /**
+     * Starts the sync process, this effectively acts as a call to
+     * `connect` if not yet connected.
+     */
+    connect(options?: PowerSyncConnectionOptions): Promise<void>;
+    disconnect(): Promise<void>;
+    getWriteCheckpoint(): Promise<string>;
+    hasCompletedSync(): Promise<boolean>;
+    dispose(): Promise<void>;
+    waitForReady(): Promise<void>;
+    updateSubscriptions(subscriptions: SubscribedStream[]): void;
+}
+export {};

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

@@ -0,0 +1,237 @@
+import * as Comlink from 'comlink';
+import { getNavigatorLocks } from '../../shared/navigator.js';
+import { AbstractSharedSyncClientProvider } from '../../worker/sync/AbstractSharedSyncClientProvider.js';
+import { SharedSyncClientEvent } from '../../worker/sync/SharedSyncImplementation.js';
+import { DEFAULT_CACHE_SIZE_KB, TemporaryStorageOption, resolveWebSQLFlags } from '../adapters/web-sql-flags.js';
+import { WebStreamingSyncImplementation } from './WebStreamingSyncImplementation.js';
+/**
+ * The shared worker will trigger methods on this side of the message port
+ * via this client provider.
+ */
+class SharedSyncClientProvider extends AbstractSharedSyncClientProvider {
+    options;
+    statusChanged;
+    webDB;
+    constructor(options, statusChanged, webDB) {
+        super();
+        this.options = options;
+        this.statusChanged = statusChanged;
+        this.webDB = webDB;
+    }
+    async getDBWorkerPort() {
+        const { port } = await this.webDB.shareConnection();
+        return Comlink.transfer(port, [port]);
+    }
+    invalidateCredentials() {
+        this.options.remote.invalidateCredentials();
+    }
+    async fetchCredentials() {
+        const credentials = await this.options.remote.getCredentials();
+        if (credentials == null) {
+            return null;
+        }
+        /**
+         * The credentials need to be serializable.
+         * Users might extend [PowerSyncCredentials] to contain
+         * items which are not serializable.
+         * This returns only the essential fields.
+         */
+        return {
+            endpoint: credentials.endpoint,
+            token: credentials.token
+        };
+    }
+    async uploadCrud() {
+        /**
+         * Don't return anything here, just incase something which is not
+         * serializable is returned from the `uploadCrud` function.
+         */
+        await this.options.uploadCrud();
+    }
+    get logger() {
+        return this.options.logger;
+    }
+    trace(...x) {
+        this.logger?.trace(...x);
+    }
+    debug(...x) {
+        this.logger?.debug(...x);
+    }
+    info(...x) {
+        this.logger?.info(...x);
+    }
+    log(...x) {
+        this.logger?.log(...x);
+    }
+    warn(...x) {
+        this.logger?.warn(...x);
+    }
+    error(...x) {
+        this.logger?.error(...x);
+    }
+    time(label) {
+        this.logger?.time(label);
+    }
+    timeEnd(label) {
+        this.logger?.timeEnd(label);
+    }
+}
+/**
+ * The local part of the sync implementation on the web, which talks to a sync implementation hosted in a shared worker.
+ */
+export class SharedWebStreamingSyncImplementation extends WebStreamingSyncImplementation {
+    syncManager;
+    clientProvider;
+    messagePort;
+    isInitialized;
+    dbAdapter;
+    abortOnClose = new AbortController();
+    constructor(options) {
+        super(options);
+        this.dbAdapter = options.db;
+        /**
+         * Configure or connect to the shared sync worker.
+         * This worker will manage all syncing operations remotely.
+         */
+        const resolvedWorkerOptions = {
+            dbFilename: this.options.identifier,
+            temporaryStorage: TemporaryStorageOption.MEMORY,
+            cacheSizeKb: DEFAULT_CACHE_SIZE_KB,
+            ...options,
+            flags: resolveWebSQLFlags(options.flags)
+        };
+        const syncWorker = options.sync?.worker;
+        if (syncWorker) {
+            if (typeof syncWorker === 'function') {
+                this.messagePort = syncWorker(resolvedWorkerOptions).port;
+            }
+            else {
+                this.messagePort = new SharedWorker(`${syncWorker}`, {
+                    /* @vite-ignore */
+                    name: `shared-sync-${this.webOptions.identifier}`
+                }).port;
+            }
+        }
+        else {
+            this.messagePort = new SharedWorker(new URL('../../worker/sync/SharedSyncImplementation.worker.js', import.meta.url), {
+                /* @vite-ignore */
+                name: `shared-sync-${this.webOptions.identifier}`,
+                type: 'module'
+            }).port;
+        }
+        /**
+         * Pass along any sync status updates to this listener
+         */
+        this.clientProvider = new SharedSyncClientProvider(this.webOptions, (status) => {
+            this.updateSyncStatus(status);
+        }, options.db);
+        this.syncManager = Comlink.wrap(this.messagePort);
+        /**
+         * The sync worker will call this client provider when it needs
+         * to fetch credentials or upload data.
+         * This performs bi-directional method calling.
+         */
+        Comlink.expose(this.clientProvider, this.messagePort);
+        this.syncManager.setLogLevel(this.logger.getLevel());
+        this.triggerCrudUpload = this.syncManager.triggerCrudUpload;
+        /**
+         * Opens MessagePort to the existing shared DB worker.
+         * The sync worker cannot initiate connections directly to the
+         * DB worker, but a port to the DB worker can be transferred to the
+         * sync worker.
+         */
+        this.isInitialized = this._init();
+    }
+    async _init() {
+        /**
+         * The general flow of initialization is:
+         *  - The client requests a unique navigator lock.
+         *    - Once the lock is acquired, we register the lock with the shared worker.
+         *    - The shared worker can then request the same lock. The client has been closed if the shared worker can acquire the lock.
+         *    - Once the shared worker knows the client's lock, we can guarentee that the shared worker will detect if the client has been closed.
+         *    - This makes the client safe for the shared worker to use.
+         *    - The client is only added to the SharedSyncImplementation once the lock has been registered.
+         *      This ensures we don't ever keep track of dead clients (tabs that closed before the lock was registered).
+         *    - The client side lock is held until the client is disposed.
+         *    - We resolve the top-level promise after the lock has been registered with the shared worker.
+         * - The client sends the params to the shared worker after locks have been registered.
+         */
+        await new Promise((resolve) => {
+            // Request a random lock until this client is disposed. The name of the lock is sent to the shared worker, which
+            // will also attempt to acquire it. Since the lock is returned when the tab is closed, this allows the share worker
+            // to free resources associated with this tab.
+            // We take hold of this lock as soon-as-possible in order to cater for potentially closed tabs.
+            getNavigatorLocks().request(`tab-close-signal-${crypto.randomUUID()}`, async (lock) => {
+                if (this.abortOnClose.signal.aborted) {
+                    return;
+                }
+                // Awaiting here ensures the worker is waiting for the lock
+                await this.syncManager.addLockBasedCloseSignal(lock.name);
+                // The lock has been registered, we can continue with the initialization
+                resolve();
+                await new Promise((r) => {
+                    this.abortOnClose.signal.onabort = () => r();
+                });
+            });
+        });
+        const { crudUploadThrottleMs, identifier, retryDelayMs } = this.options;
+        const flags = { ...this.webOptions.flags, workers: undefined };
+        await this.syncManager.setParams({
+            dbParams: this.dbAdapter.getConfiguration(),
+            streamOptions: {
+                crudUploadThrottleMs,
+                identifier,
+                retryDelayMs,
+                flags: flags
+            }
+        }, this.options.subscriptions);
+    }
+    /**
+     * Starts the sync process, this effectively acts as a call to
+     * `connect` if not yet connected.
+     */
+    async connect(options) {
+        await this.waitForReady();
+        return this.syncManager.connect(options);
+    }
+    async disconnect() {
+        await this.waitForReady();
+        return this.syncManager.disconnect();
+    }
+    async getWriteCheckpoint() {
+        await this.waitForReady();
+        return this.syncManager.getWriteCheckpoint();
+    }
+    async hasCompletedSync() {
+        return this.syncManager.hasCompletedSync();
+    }
+    async dispose() {
+        await this.waitForReady();
+        await new Promise((resolve) => {
+            // Listen for the close acknowledgment from the worker
+            this.messagePort.addEventListener('message', (event) => {
+                const payload = event.data;
+                if (payload?.event === SharedSyncClientEvent.CLOSE_ACK) {
+                    resolve();
+                }
+            });
+            // Signal the shared worker that this client is closing its connection to the worker
+            const closeMessagePayload = {
+                event: SharedSyncClientEvent.CLOSE_CLIENT,
+                data: {}
+            };
+            this.messagePort.postMessage(closeMessagePayload);
+        });
+        await super.dispose();
+        this.abortOnClose.abort();
+        // Release the proxy
+        this.syncManager[Comlink.releaseProxy]();
+        this.messagePort.close();
+    }
+    async waitForReady() {
+        return this.isInitialized;
+    }
+    updateSubscriptions(subscriptions) {
+        this.syncManager.updateSubscriptions(subscriptions);
+    }
+}

package/lib/src/db/sync/WebRemote.d.ts

@@ -0,0 +1,9 @@
+import { AbstractRemote, AbstractRemoteOptions, BSONImplementation, ILogger, RemoteConnector } from '@powersync/common';
+export declare class WebRemote extends AbstractRemote {
+    protected connector: RemoteConnector;
+    protected logger: ILogger;
+    private _bson;
+    constructor(connector: RemoteConnector, logger?: ILogger, options?: Partial<AbstractRemoteOptions>);
+    getUserAgent(): string;
+    getBSON(): Promise<BSONImplementation>;
+}

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

@@ -0,0 +1,44 @@
+import { AbstractRemote, DEFAULT_REMOTE_LOGGER, FetchImplementationProvider } from '@powersync/common';
+import { getUserAgentInfo } from './userAgent.js';
+/*
+ * Depends on browser's implementation of global fetch.
+ */
+class WebFetchProvider extends FetchImplementationProvider {
+    getFetch() {
+        return fetch.bind(globalThis);
+    }
+}
+export class WebRemote extends AbstractRemote {
+    connector;
+    logger;
+    _bson;
+    constructor(connector, logger = DEFAULT_REMOTE_LOGGER, options) {
+        super(connector, logger, {
+            ...(options ?? {}),
+            fetchImplementation: options?.fetchImplementation ?? new WebFetchProvider()
+        });
+        this.connector = connector;
+        this.logger = logger;
+    }
+    getUserAgent() {
+        let ua = [super.getUserAgent(), `powersync-web`];
+        try {
+            ua.push(...getUserAgentInfo());
+        }
+        catch (e) {
+            this.logger.warn('Failed to get user agent info', e);
+        }
+        return ua.join(' ');
+    }
+    async getBSON() {
+        if (this._bson) {
+            return this._bson;
+        }
+        /**
+         * Dynamic import to be used only when needed.
+         */
+        const { BSON } = await import('bson');
+        this._bson = BSON;
+        return this._bson;
+    }
+}

package/lib/src/db/sync/WebStreamingSyncImplementation.d.ts

@@ -0,0 +1,13 @@
+import { AbstractStreamingSyncImplementation, AbstractStreamingSyncImplementationOptions, LockOptions } from '@powersync/common';
+import { ResolvedWebSQLOpenOptions, WebSQLFlags } from '../adapters/web-sql-flags.js';
+export interface WebStreamingSyncImplementationOptions extends AbstractStreamingSyncImplementationOptions {
+    flags?: WebSQLFlags;
+    sync?: {
+        worker?: string | URL | ((options: ResolvedWebSQLOpenOptions) => SharedWorker);
+    };
+}
+export declare class WebStreamingSyncImplementation extends AbstractStreamingSyncImplementation {
+    constructor(options: WebStreamingSyncImplementationOptions);
+    get webOptions(): WebStreamingSyncImplementationOptions;
+    obtainLock<T>(lockOptions: LockOptions<T>): Promise<T>;
+}

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

@@ -0,0 +1,18 @@
+import { AbstractStreamingSyncImplementation, LockType } from '@powersync/common';
+import { getNavigatorLocks } from '../../shared/navigator.js';
+export class WebStreamingSyncImplementation extends AbstractStreamingSyncImplementation {
+    constructor(options) {
+        // Super will store and provide default values for options
+        super(options);
+    }
+    get webOptions() {
+        return this.options;
+    }
+    async obtainLock(lockOptions) {
+        const identifier = `streaming-sync-${lockOptions.type}-${this.webOptions.identifier}`;
+        if (lockOptions.type == LockType.SYNC) {
+            this.logger.debug('requesting lock for ', identifier);
+        }
+        return getNavigatorLocks().request(identifier, { signal: lockOptions.signal }, lockOptions.callback);
+    }
+}

package/lib/src/db/sync/userAgent.d.ts

@@ -0,0 +1,17 @@
+export interface NavigatorInfo {
+    userAgent: string;
+    userAgentData?: {
+        brands?: {
+            brand: string;
+            version: string;
+        }[];
+        platform?: string;
+    };
+}
+/**
+ * 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 declare function getUserAgentInfo(nav?: NavigatorInfo): string[];