@powersync/web 1.27.1 → 1.28.1

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

@@ -0,0 +1,135 @@
+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 enum TemporaryStorageOption {
+  MEMORY = 'memory',
+  FILESYSTEM = 'file'
+}
+
+export const DEFAULT_CACHE_SIZE_KB = 50 * 1024;
+
+/**
+ * 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 function isServerSide() {
+  return typeof window == 'undefined';
+}
+
+export const DEFAULT_WEB_SQL_FLAGS: ResolvedWebSQLFlags = {
+  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 as any).safari,
+  useWebWorker: true
+};
+
+export function resolveWebSQLFlags(flags?: WebSQLFlags): ResolvedWebSQLFlags {
+  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/src/db/sync/SSRWebStreamingSyncImplementation.ts

@@ -0,0 +1,89 @@
+import {
+  AbstractStreamingSyncImplementationOptions,
+  BaseObserver,
+  LockOptions,
+  LockType,
+  PowerSyncConnectionOptions,
+  StreamingSyncImplementation,
+  SubscribedStream,
+  SyncStatus,
+  SyncStatusOptions
+} from '@powersync/common';
+import { Mutex } from 'async-mutex';
+
+export class SSRStreamingSyncImplementation extends BaseObserver implements StreamingSyncImplementation {
+  syncMutex: Mutex;
+  crudMutex: Mutex;
+
+  isConnected: boolean;
+  lastSyncedAt?: Date | undefined;
+  syncStatus: SyncStatus;
+
+  constructor(options: AbstractStreamingSyncImplementationOptions) {
+    super();
+    this.syncMutex = new Mutex();
+    this.crudMutex = new Mutex();
+    this.syncStatus = new SyncStatus({});
+    this.isConnected = false;
+  }
+
+  obtainLock<T>(lockOptions: LockOptions<T>): Promise<T> {
+    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?: PowerSyncConnectionOptions): Promise<void> {}
+
+  async dispose() {}
+
+  /**
+   * This is a no-op in SSR mode
+   */
+  async disconnect(): Promise<void> {}
+
+  /**
+   * This SSR Mode implementation is immediately ready.
+   */
+  async waitForReady() {}
+
+  /**
+   * This will never resolve in SSR Mode.
+   */
+  async waitForStatus(status: SyncStatusOptions) {
+    return this.waitUntilStatusMatches(() => false);
+  }
+
+  /**
+   * This will never resolve in SSR Mode.
+   */
+  waitUntilStatusMatches(_predicate: (status: SyncStatus) => boolean): Promise<void> {
+    return new Promise<void>(() => {});
+  }
+
+  /**
+   * 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(): void {}
+}

package/src/db/sync/SharedWebStreamingSyncImplementation.ts

@@ -0,0 +1,274 @@
+import {
+  PowerSyncConnectionOptions,
+  PowerSyncCredentials,
+  SubscribedStream,
+  SyncStatus,
+  SyncStatusOptions
+} from '@powersync/common';
+import * as Comlink from 'comlink';
+import { AbstractSharedSyncClientProvider } from '../../worker/sync/AbstractSharedSyncClientProvider';
+import { ManualSharedSyncPayload, SharedSyncClientEvent } from '../../worker/sync/SharedSyncImplementation';
+import { DEFAULT_CACHE_SIZE_KB, resolveWebSQLFlags, TemporaryStorageOption } from '../adapters/web-sql-flags';
+import { WebDBAdapter } from '../adapters/WebDBAdapter';
+import {
+  WebStreamingSyncImplementation,
+  WebStreamingSyncImplementationOptions
+} from './WebStreamingSyncImplementation';
+import { WorkerClient } from '../../worker/sync/WorkerClient';
+import { getNavigatorLocks } from '../../shared/navigator';
+
+/**
+ * The shared worker will trigger methods on this side of the message port
+ * via this client provider.
+ */
+class SharedSyncClientProvider extends AbstractSharedSyncClientProvider {
+  constructor(
+    protected options: WebStreamingSyncImplementationOptions,
+    public statusChanged: (status: SyncStatusOptions) => void,
+    protected webDB: WebDBAdapter
+  ) {
+    super();
+  }
+
+  async getDBWorkerPort(): Promise<MessagePort> {
+    const { port } = await this.webDB.shareConnection();
+    return Comlink.transfer(port, [port]);
+  }
+
+  invalidateCredentials() {
+    this.options.remote.invalidateCredentials();
+  }
+
+  async fetchCredentials(): Promise<PowerSyncCredentials | null> {
+    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(): Promise<void> {
+    /**
+     * 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: any[]): void {
+    this.logger?.trace(...x);
+  }
+  debug(...x: any[]): void {
+    this.logger?.debug(...x);
+  }
+  info(...x: any[]): void {
+    this.logger?.info(...x);
+  }
+  log(...x: any[]): void {
+    this.logger?.log(...x);
+  }
+  warn(...x: any[]): void {
+    this.logger?.warn(...x);
+  }
+  error(...x: any[]): void {
+    this.logger?.error(...x);
+  }
+  time(label: string): void {
+    this.logger?.time(label);
+  }
+  timeEnd(label: string): void {
+    this.logger?.timeEnd(label);
+  }
+}
+
+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 class SharedWebStreamingSyncImplementation extends WebStreamingSyncImplementation {
+  protected syncManager: Comlink.Remote<WorkerClient>;
+  protected clientProvider: SharedSyncClientProvider;
+  protected messagePort: MessagePort;
+
+  protected isInitialized: Promise<void>;
+  protected dbAdapter: WebDBAdapter;
+  private abortOnClose = new AbortController();
+
+  constructor(options: SharedWebStreamingSyncImplementationOptions) {
+    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;
+    }
+
+    this.syncManager = Comlink.wrap<WorkerClient>(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.
+     */
+    const { crudUploadThrottleMs, identifier, retryDelayMs } = this.options;
+    const flags = { ...this.webOptions.flags, workers: undefined };
+
+    this.isInitialized = this.syncManager.setParams(
+      {
+        dbParams: this.dbAdapter.getConfiguration(),
+        streamOptions: {
+          crudUploadThrottleMs,
+          identifier,
+          retryDelayMs,
+          flags: flags
+        }
+      },
+      options.subscriptions
+    );
+
+    /**
+     * Pass along any sync status updates to this listener
+     */
+    this.clientProvider = new SharedSyncClientProvider(
+      this.webOptions,
+      (status) => {
+        this.iterateListeners((l) => this.updateSyncStatus(status));
+      },
+      options.db
+    );
+
+    /**
+     * 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);
+
+    // 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.
+    getNavigatorLocks().request(`tab-close-signal-${crypto.randomUUID()}`, async (lock) => {
+      if (!this.abortOnClose.signal.aborted) {
+        this.syncManager.addLockBasedCloseSignal(lock!.name);
+
+        await new Promise<void>((r) => {
+          this.abortOnClose.signal.onabort = () => r();
+        });
+      }
+    });
+  }
+
+  /**
+   * Starts the sync process, this effectively acts as a call to
+   * `connect` if not yet connected.
+   */
+  async connect(options?: PowerSyncConnectionOptions): Promise<void> {
+    await this.waitForReady();
+    return this.syncManager.connect(options);
+  }
+
+  async disconnect(): Promise<void> {
+    await this.waitForReady();
+    return this.syncManager.disconnect();
+  }
+
+  async getWriteCheckpoint(): Promise<string> {
+    await this.waitForReady();
+    return this.syncManager.getWriteCheckpoint();
+  }
+
+  async hasCompletedSync(): Promise<boolean> {
+    return this.syncManager.hasCompletedSync();
+  }
+
+  async dispose(): Promise<void> {
+    await this.waitForReady();
+
+    await super.dispose();
+
+    await new Promise<void>((resolve) => {
+      // Listen for the close acknowledgment from the worker
+      this.messagePort.addEventListener('message', (event) => {
+        const payload = event.data as ManualSharedSyncPayload;
+        if (payload?.event === SharedSyncClientEvent.CLOSE_ACK) {
+          resolve();
+        }
+      });
+
+      // Signal the shared worker that this client is closing its connection to the worker
+      const closeMessagePayload: ManualSharedSyncPayload = {
+        event: SharedSyncClientEvent.CLOSE_CLIENT,
+        data: {}
+      };
+      this.messagePort.postMessage(closeMessagePayload);
+    });
+    this.abortOnClose.abort();
+
+    // Release the proxy
+    this.syncManager[Comlink.releaseProxy]();
+    this.messagePort.close();
+  }
+
+  async waitForReady() {
+    return this.isInitialized;
+  }
+
+  updateSubscriptions(subscriptions: SubscribedStream[]): void {
+    this.syncManager.updateSubscriptions(subscriptions);
+  }
+
+  /**
+   * Used in tests to force a connection states
+   */
+  private async _testUpdateStatus(status: SyncStatus) {
+    await this.isInitialized;
+    return this.syncManager._testUpdateAllStatuses(status.toJSON());
+  }
+}

package/src/db/sync/WebRemote.ts

@@ -0,0 +1,59 @@
+import {
+  AbstractRemote,
+  AbstractRemoteOptions,
+  BSONImplementation,
+  DEFAULT_REMOTE_LOGGER,
+  FetchImplementation,
+  FetchImplementationProvider,
+  ILogger,
+  RemoteConnector
+} from '@powersync/common';
+
+import { getUserAgentInfo } from './userAgent';
+
+/*
+ * Depends on browser's implementation of global fetch.
+ */
+class WebFetchProvider extends FetchImplementationProvider {
+  getFetch(): FetchImplementation {
+    return fetch.bind(globalThis);
+  }
+}
+
+export class WebRemote extends AbstractRemote {
+  private _bson: BSONImplementation | undefined;
+
+  constructor(
+    protected connector: RemoteConnector,
+    protected logger: ILogger = DEFAULT_REMOTE_LOGGER,
+    options?: Partial<AbstractRemoteOptions>
+  ) {
+    super(connector, logger, {
+      ...(options ?? {}),
+      fetchImplementation: options?.fetchImplementation ?? new WebFetchProvider()
+    });
+  }
+
+  getUserAgent(): string {
+    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(): Promise<BSONImplementation> {
+    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/src/db/sync/WebStreamingSyncImplementation.ts

@@ -0,0 +1,34 @@
+import {
+  AbstractStreamingSyncImplementation,
+  AbstractStreamingSyncImplementationOptions,
+  LockOptions,
+  LockType
+} from '@powersync/common';
+import { getNavigatorLocks } from '../../shared/navigator';
+import { ResolvedWebSQLOpenOptions, WebSQLFlags } from '../adapters/web-sql-flags';
+
+export interface WebStreamingSyncImplementationOptions extends AbstractStreamingSyncImplementationOptions {
+  flags?: WebSQLFlags;
+  sync?: {
+    worker?: string | URL | ((options: ResolvedWebSQLOpenOptions) => SharedWorker);
+  };
+}
+
+export class WebStreamingSyncImplementation extends AbstractStreamingSyncImplementation {
+  constructor(options: WebStreamingSyncImplementationOptions) {
+    // Super will store and provide default values for options
+    super(options);
+  }
+
+  get webOptions(): WebStreamingSyncImplementationOptions {
+    return this.options as WebStreamingSyncImplementationOptions;
+  }
+
+  async obtainLock<T>(lockOptions: LockOptions<T>): Promise<T> {
+    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/src/db/sync/userAgent.ts

@@ -0,0 +1,78 @@
+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 function getUserAgentInfo(nav?: NavigatorInfo): string[] {
+  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) as string[];
+}
+
+function getBrowserInfo(nav: NavigatorInfo): string | null {
+  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: NavigatorInfo): string | null {
+  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/src/index.ts

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

package/src/shared/navigator.ts

@@ -0,0 +1,9 @@
+export const getNavigatorLocks = (): LockManager => {
+  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.'
+  );
+};