@powersync/web 1.27.1 → 1.28.1

package/src/db/PowerSyncDatabase.ts

@@ -0,0 +1,224 @@
+import {
+  type BucketStorageAdapter,
+  type PowerSyncBackendConnector,
+  type PowerSyncCloseOptions,
+  type RequiredAdditionalConnectionOptions,
+  AbstractPowerSyncDatabase,
+  DBAdapter,
+  DEFAULT_POWERSYNC_CLOSE_OPTIONS,
+  isDBAdapter,
+  isSQLOpenFactory,
+  PowerSyncDatabaseOptions,
+  PowerSyncDatabaseOptionsWithDBAdapter,
+  PowerSyncDatabaseOptionsWithOpenFactory,
+  PowerSyncDatabaseOptionsWithSettings,
+  SqliteBucketStorage,
+  StreamingSyncImplementation
+} from '@powersync/common';
+import { Mutex } from 'async-mutex';
+import { getNavigatorLocks } from '../shared/navigator';
+import { WASQLiteOpenFactory } from './adapters/wa-sqlite/WASQLiteOpenFactory';
+import {
+  DEFAULT_WEB_SQL_FLAGS,
+  ResolvedWebSQLOpenOptions,
+  resolveWebSQLFlags,
+  WebSQLFlags
+} from './adapters/web-sql-flags';
+import { WebDBAdapter } from './adapters/WebDBAdapter';
+import { SharedWebStreamingSyncImplementation } from './sync/SharedWebStreamingSyncImplementation';
+import { SSRStreamingSyncImplementation } from './sync/SSRWebStreamingSyncImplementation';
+import { WebRemote } from './sync/WebRemote';
+import {
+  WebStreamingSyncImplementation,
+  WebStreamingSyncImplementationOptions
+} from './sync/WebStreamingSyncImplementation';
+
+export interface WebPowerSyncFlags extends WebSQLFlags {
+  /**
+   * Externally unload open PowerSync database instances when the window closes.
+   * Setting this to `true` requires calling `close` on all open PowerSyncDatabase
+   * instances before the window unloads
+   */
+  externallyUnload?: boolean;
+}
+
+type WithWebFlags<Base> = Base & { flags?: WebPowerSyncFlags };
+
+export interface WebSyncOptions {
+  /**
+   * Allows you to override the default sync worker.
+   *
+   * You can either provide a path to the worker script
+   * or a factory method that returns a worker.
+   */
+  worker?: string | URL | ((options: ResolvedWebSQLOpenOptions) => SharedWorker);
+}
+
+type WithWebSyncOptions<Base> = Base & {
+  sync?: WebSyncOptions;
+};
+
+export interface WebEncryptionOptions {
+  /**
+   * Encryption key for the database.
+   * If set, the database will be encrypted using Multiple Ciphers.
+   */
+  encryptionKey?: string;
+}
+
+type WithWebEncryptionOptions<Base> = Base & WebEncryptionOptions;
+
+export type WebPowerSyncDatabaseOptionsWithAdapter = WithWebSyncOptions<
+  WithWebFlags<PowerSyncDatabaseOptionsWithDBAdapter>
+>;
+export type WebPowerSyncDatabaseOptionsWithOpenFactory = WithWebSyncOptions<
+  WithWebFlags<PowerSyncDatabaseOptionsWithOpenFactory>
+>;
+export type WebPowerSyncDatabaseOptionsWithSettings = WithWebSyncOptions<
+  WithWebFlags<WithWebEncryptionOptions<PowerSyncDatabaseOptionsWithSettings>>
+>;
+
+export type WebPowerSyncDatabaseOptions = WithWebSyncOptions<WithWebFlags<PowerSyncDatabaseOptions>>;
+
+export const DEFAULT_POWERSYNC_FLAGS: Required<WebPowerSyncFlags> = {
+  ...DEFAULT_WEB_SQL_FLAGS,
+  externallyUnload: false
+};
+
+export const resolveWebPowerSyncFlags = (flags?: WebPowerSyncFlags): Required<WebPowerSyncFlags> => {
+  return {
+    ...DEFAULT_POWERSYNC_FLAGS,
+    ...flags,
+    ...resolveWebSQLFlags(flags)
+  };
+};
+
+/**
+ * Asserts that the database options are valid for custom database constructors.
+ */
+function assertValidDatabaseOptions(options: WebPowerSyncDatabaseOptions): void {
+  if ('database' in options && 'encryptionKey' in options) {
+    const { database } = options;
+    if (isSQLOpenFactory(database) || isDBAdapter(database)) {
+      throw new Error(
+        `Invalid configuration: 'encryptionKey' should only be included inside the database object when using a custom ${isSQLOpenFactory(database) ? 'WASQLiteOpenFactory' : 'WASQLiteDBAdapter'} constructor.`
+      );
+    }
+  }
+}
+
+/**
+ * A PowerSync database which provides SQLite functionality
+ * which is automatically synced.
+ *
+ * @example
+ * ```typescript
+ * export const db = new PowerSyncDatabase({
+ *  schema: AppSchema,
+ *  database: {
+ *    dbFilename: 'example.db'
+ *  }
+ * });
+ * ```
+ */
+export class PowerSyncDatabase extends AbstractPowerSyncDatabase {
+  static SHARED_MUTEX = new Mutex();
+
+  protected unloadListener?: () => Promise<void>;
+  protected resolvedFlags: WebPowerSyncFlags;
+
+  constructor(options: WebPowerSyncDatabaseOptionsWithAdapter);
+  constructor(options: WebPowerSyncDatabaseOptionsWithOpenFactory);
+  constructor(options: WebPowerSyncDatabaseOptionsWithSettings);
+  constructor(options: WebPowerSyncDatabaseOptions);
+  constructor(protected options: WebPowerSyncDatabaseOptions) {
+    super(options);
+
+    assertValidDatabaseOptions(options);
+
+    this.resolvedFlags = resolveWebPowerSyncFlags(options.flags);
+
+    if (this.resolvedFlags.enableMultiTabs && !this.resolvedFlags.externallyUnload) {
+      this.unloadListener = () => this.close({ disconnect: false });
+      window.addEventListener('unload', this.unloadListener);
+    }
+  }
+
+  async _initialize(): Promise<void> {}
+
+  protected openDBAdapter(options: WebPowerSyncDatabaseOptionsWithSettings): DBAdapter {
+    const defaultFactory = new WASQLiteOpenFactory({
+      ...options.database,
+      flags: resolveWebPowerSyncFlags(options.flags),
+      encryptionKey: options.encryptionKey
+    });
+    return defaultFactory.openDB();
+  }
+
+  /**
+   * Closes the database connection.
+   * By default the sync stream client is only disconnected if
+   * multiple tabs are not enabled.
+   */
+  close(options: PowerSyncCloseOptions = DEFAULT_POWERSYNC_CLOSE_OPTIONS): Promise<void> {
+    if (this.unloadListener) {
+      window.removeEventListener('unload', this.unloadListener);
+    }
+
+    return super.close({
+      // Don't disconnect by default if multiple tabs are enabled
+      disconnect: options.disconnect ?? !this.resolvedFlags.enableMultiTabs
+    });
+  }
+
+  protected generateBucketStorageAdapter(): BucketStorageAdapter {
+    return new SqliteBucketStorage(this.database);
+  }
+
+  protected async runExclusive<T>(cb: () => Promise<T>) {
+    if (this.resolvedFlags.ssrMode) {
+      return PowerSyncDatabase.SHARED_MUTEX.runExclusive(cb);
+    }
+    return getNavigatorLocks().request(`lock-${this.database.name}`, cb);
+  }
+
+  protected generateSyncStreamImplementation(
+    connector: PowerSyncBackendConnector,
+    options: RequiredAdditionalConnectionOptions
+  ): StreamingSyncImplementation {
+    const remote = new WebRemote(connector, this.logger);
+    const syncOptions: WebStreamingSyncImplementationOptions = {
+      ...(this.options as {}),
+      ...options,
+      flags: this.resolvedFlags,
+      adapter: this.bucketStorageAdapter,
+      remote,
+      uploadCrud: async () => {
+        await this.waitForReady();
+        await connector.uploadData(this);
+      },
+      identifier: this.database.name,
+      logger: this.logger
+    };
+
+    switch (true) {
+      case this.resolvedFlags.ssrMode:
+        return new SSRStreamingSyncImplementation(syncOptions);
+      case this.resolvedFlags.enableMultiTabs:
+        if (!this.resolvedFlags.broadcastLogs) {
+          const warning = `
+            Multiple tabs are enabled, but broadcasting of logs is disabled.
+            Logs for shared sync worker will only be available in the shared worker context
+          `;
+          const logger = this.options.logger;
+          logger ? logger.warn(warning) : console.warn(warning);
+        }
+        return new SharedWebStreamingSyncImplementation({
+          ...syncOptions,
+          db: this.database as WebDBAdapter // This should always be the case
+        });
+      default:
+        return new WebStreamingSyncImplementation(syncOptions);
+    }
+  }
+}

package/src/db/adapters/AbstractWebPowerSyncDatabaseOpenFactory.ts

@@ -0,0 +1,47 @@
+import {
+  AbstractPowerSyncDatabase,
+  AbstractPowerSyncDatabaseOpenFactory,
+  PowerSyncDatabaseOptions,
+  PowerSyncOpenFactoryOptions
+} from '@powersync/common';
+import {
+  PowerSyncDatabase,
+  WebPowerSyncDatabaseOptions,
+  WebPowerSyncFlags,
+  resolveWebPowerSyncFlags
+} from '../../db/PowerSyncDatabase';
+
+/**
+ * {@link WebPowerSyncFlags}
+ * Maintaining export for consistency with API from previous versions
+ *  */
+export interface WebPowerSyncOpenFlags extends WebPowerSyncFlags {}
+
+export interface WebPowerSyncOpenFactoryOptions extends PowerSyncOpenFactoryOptions {
+  flags?: WebPowerSyncOpenFlags;
+}
+
+/**
+ * Intermediate PowerSync Database Open factory for Web which uses a mock
+ * SSR DB Adapter if running on server side.
+ * Most SQLite DB implementations only run on client side, this will safely return
+ * empty query results in SSR which will allow for generating server partial views.
+ */
+export abstract class AbstractWebPowerSyncDatabaseOpenFactory extends AbstractPowerSyncDatabaseOpenFactory {
+  constructor(protected options: WebPowerSyncOpenFactoryOptions) {
+    super(options);
+  }
+
+  generateOptions(): WebPowerSyncDatabaseOptions {
+    return {
+      ...this.options,
+      database: this.openDB(),
+      schema: this.schema,
+      flags: resolveWebPowerSyncFlags(this.options.flags)
+    };
+  }
+
+  generateInstance(options: PowerSyncDatabaseOptions): AbstractPowerSyncDatabase {
+    return new PowerSyncDatabase(options);
+  }
+}

package/src/db/adapters/AbstractWebSQLOpenFactory.ts

@@ -0,0 +1,48 @@
+import { type ILogger, createLogger, DBAdapter, SQLOpenFactory } from '@powersync/common';
+import { SSRDBAdapter } from './SSRDBAdapter';
+import { ResolvedWebSQLFlags, WebSQLOpenFactoryOptions, isServerSide, resolveWebSQLFlags } from './web-sql-flags';
+
+export abstract class AbstractWebSQLOpenFactory implements SQLOpenFactory {
+  protected resolvedFlags: ResolvedWebSQLFlags;
+  protected logger: ILogger;
+
+  constructor(protected options: WebSQLOpenFactoryOptions) {
+    this.resolvedFlags = resolveWebSQLFlags(options.flags);
+    this.logger = options.logger ?? createLogger(`AbstractWebSQLOpenFactory - ${this.options.dbFilename}`);
+  }
+
+  /**
+   * Opens a DBAdapter if not in SSR mode
+   */
+  protected abstract openAdapter(): DBAdapter;
+
+  /**
+   * Opens a {@link DBAdapter} using resolved flags.
+   * A SSR implementation is loaded if SSR mode is detected.
+   */
+  openDB() {
+    const {
+      resolvedFlags: { disableSSRWarning, enableMultiTabs, ssrMode = isServerSide() }
+    } = this;
+    if (ssrMode && !disableSSRWarning) {
+      this.logger.warn(
+        `
+  Running PowerSync in SSR mode.
+  Only empty query results will be returned.
+  Disable this warning by setting 'disableSSRWarning: true' in options.`
+      );
+    }
+
+    if (!enableMultiTabs) {
+      this.logger.warn(
+        'Multiple tab support is not enabled. Using this site across multiple tabs may not function correctly.'
+      );
+    }
+
+    if (ssrMode) {
+      return new SSRDBAdapter();
+    }
+
+    return this.openAdapter();
+  }
+}

package/src/db/adapters/AsyncDatabaseConnection.ts

@@ -0,0 +1,40 @@
+import { BatchedUpdateNotification, QueryResult } from '@powersync/common';
+import { ResolvedWebSQLOpenOptions } from './web-sql-flags';
+
+/**
+ * @internal
+ * Proxied query result does not contain a function for accessing row values
+ */
+export type ProxiedQueryResult = Omit<QueryResult, 'rows'> & {
+  rows: {
+    _array: any[];
+    length: number;
+  };
+};
+
+/**
+ * @internal
+ */
+export type OnTableChangeCallback = (event: BatchedUpdateNotification) => void;
+
+/**
+ * @internal
+ * An async Database connection which provides basic async SQL methods.
+ * This is usually a proxied through a web worker.
+ */
+export interface AsyncDatabaseConnection<Config extends ResolvedWebSQLOpenOptions = ResolvedWebSQLOpenOptions> {
+  init(): Promise<void>;
+  close(): Promise<void>;
+  execute(sql: string, params?: any[]): Promise<ProxiedQueryResult>;
+  executeRaw(sql: string, params?: any[]): Promise<any[][]>;
+  executeBatch(sql: string, params?: any[]): Promise<ProxiedQueryResult>;
+  registerOnTableChange(callback: OnTableChangeCallback): Promise<() => void>;
+  getConfig(): Promise<Config>;
+}
+
+/**
+ * @internal
+ */
+export type OpenAsyncDatabaseConnection<Config extends ResolvedWebSQLOpenOptions = ResolvedWebSQLOpenOptions> = (
+  config: Config
+) => AsyncDatabaseConnection;