@powersync/common 0.0.0-dev-20260503073249 → 0.0.0-dev-20260630141119

package/src/client/AbstractPowerSyncOpenFactory.ts

@@ -1,39 +0,0 @@
-import Logger from 'js-logger';
-import { DBAdapter } from '../db/DBAdapter.js';
-import { Schema } from '../db/schema/Schema.js';
-import { AbstractPowerSyncDatabase, PowerSyncDatabaseOptions } from './AbstractPowerSyncDatabase.js';
-import { SQLOpenOptions } from './SQLOpenFactory.js';
-
-export interface PowerSyncOpenFactoryOptions extends Partial<PowerSyncDatabaseOptions>, SQLOpenOptions {
-  /** Schema used for the local database. */
-  schema: Schema;
-}
-
-export abstract class AbstractPowerSyncDatabaseOpenFactory {
-  constructor(protected options: PowerSyncOpenFactoryOptions) {
-    options.logger = options.logger ?? Logger.get(`PowerSync ${this.options.dbFilename}`);
-  }
-
-  /**
-   * Schema used for the local database.
-   */
-  get schema() {
-    return this.options.schema;
-  }
-
-  protected abstract openDB(): DBAdapter;
-
-  generateOptions(): PowerSyncDatabaseOptions {
-    return {
-      database: this.openDB(),
-      ...this.options
-    };
-  }
-
-  abstract generateInstance(options: PowerSyncDatabaseOptions): AbstractPowerSyncDatabase;
-
-  getInstance(): AbstractPowerSyncDatabase {
-    const options = this.generateOptions();
-    return this.generateInstance(options);
-  }
-}

package/src/client/ConnectionManager.ts

@@ -1,402 +0,0 @@
-import { ILogger } from 'js-logger';
-import { SyncStatus } from '../db/crud/SyncStatus.js';
-import { BaseListener, BaseObserver } from '../utils/BaseObserver.js';
-import { PowerSyncBackendConnector } from './connection/PowerSyncBackendConnector.js';
-import {
-  AdditionalConnectionOptions,
-  InternalConnectionOptions,
-  StreamingSyncImplementation,
-  SubscribedStream
-} from './sync/stream/AbstractStreamingSyncImplementation.js';
-import {
-  SyncStream,
-  SyncStreamDescription,
-  SyncStreamSubscribeOptions,
-  SyncStreamSubscription
-} from './sync/sync-streams.js';
-
-/**
- * @internal
- */
-export interface ConnectionManagerSyncImplementationResult {
-  sync: StreamingSyncImplementation;
-  /**
-   * Additional cleanup function which is called after the sync stream implementation
-   * is disposed.
-   */
-  onDispose: () => Promise<void> | void;
-}
-
-/**
- * The subset of {@link AbstractStreamingSyncImplementationOptions} managed by the connection manager.
- *
- * @internal
- */
-export interface CreateSyncImplementationOptions extends AdditionalConnectionOptions {
-  subscriptions: SubscribedStream[];
-}
-
-export interface InternalSubscriptionAdapter {
-  firstStatusMatching(predicate: (status: SyncStatus) => any, abort?: AbortSignal): Promise<void>;
-  resolveOfflineSyncStatus(): Promise<void>;
-  rustSubscriptionsCommand(payload: any): Promise<void>;
-}
-
-/**
- * @internal
- */
-export interface ConnectionManagerOptions {
-  createSyncImplementation(
-    connector: PowerSyncBackendConnector,
-    options: CreateSyncImplementationOptions
-  ): Promise<ConnectionManagerSyncImplementationResult>;
-
-  logger: ILogger;
-}
-
-type StoredConnectionOptions = {
-  connector: PowerSyncBackendConnector;
-  options: InternalConnectionOptions;
-};
-
-/**
- * @internal
- */
-export interface ConnectionManagerListener extends BaseListener {
-  syncStreamCreated: (sync: StreamingSyncImplementation) => void;
-}
-
-/**
- * @internal
- */
-export class ConnectionManager extends BaseObserver<ConnectionManagerListener> {
-  /**
-   * Tracks active connection attempts
-   */
-  protected connectingPromise: Promise<void> | null;
-  /**
-   * Tracks actively instantiating a streaming sync implementation.
-   */
-  protected syncStreamInitPromise: Promise<void> | null;
-  /**
-   * Active disconnect operation. Calling disconnect multiple times
-   * will resolve to the same operation.
-   */
-  protected disconnectingPromise: Promise<void> | null;
-  /**
-   * Tracks the last parameters supplied to `connect` calls.
-   * Calling `connect` multiple times in succession will result in:
-   * - 1 pending connection operation which will be aborted.
-   * - updating the last set of parameters while waiting for the pending
-   *   attempt to be aborted
-   * - internally connecting with the last set of parameters
-   */
-  protected pendingConnectionOptions: StoredConnectionOptions | null;
-
-  syncStreamImplementation: StreamingSyncImplementation | null;
-
-  /**
-   * Additional cleanup function which is called after the sync stream implementation
-   * is disposed.
-   */
-  protected syncDisposer: (() => Promise<void> | void) | null;
-
-  /**
-   * Subscriptions managed in this connection manager.
-   *
-   * On the web, these local subscriptions are merged across tabs by a shared worker.
-   */
-  private locallyActiveSubscriptions = new Map<string, ActiveSubscription>();
-
-  constructor(protected options: ConnectionManagerOptions) {
-    super();
-    this.connectingPromise = null;
-    this.syncStreamInitPromise = null;
-    this.disconnectingPromise = null;
-    this.pendingConnectionOptions = null;
-    this.syncStreamImplementation = null;
-    this.syncDisposer = null;
-  }
-
-  get connector() {
-    return this.pendingConnectionOptions?.connector ?? null;
-  }
-
-  get connectionOptions() {
-    return this.pendingConnectionOptions?.options ?? null;
-  }
-
-  get logger() {
-    return this.options.logger;
-  }
-
-  async close() {
-    await this.syncStreamImplementation?.dispose();
-    await this.syncDisposer?.();
-  }
-
-  async connect(connector: PowerSyncBackendConnector, options: InternalConnectionOptions) {
-    // Keep track if there were pending operations before this call
-    const hadPendingOptions = !!this.pendingConnectionOptions;
-
-    // Update pending options to the latest values
-    this.pendingConnectionOptions = {
-      connector,
-      options
-    };
-
-    // Disconnecting here provides aborting in progress connection attempts.
-    // The connectInternal method will clear pending options once it starts connecting (with the options).
-    // We only need to trigger a disconnect here if we have already reached the point of connecting.
-    // If we do already have pending options, a disconnect has already been performed.
-    // The connectInternal method also does a sanity disconnect to prevent straggler connections.
-    // We should also disconnect if we have already completed a connection attempt.
-    if (!hadPendingOptions || this.syncStreamImplementation) {
-      await this.disconnectInternal();
-    }
-
-    // Triggers a connect which checks if pending options are available after the connect completes.
-    // The completion can be for a successful, unsuccessful or aborted connection attempt.
-    // If pending options are available another connection will be triggered.
-    const checkConnection = async (): Promise<void> => {
-      if (this.pendingConnectionOptions) {
-        // Pending options have been placed while connecting.
-        // Need to reconnect.
-        this.connectingPromise = this.connectInternal()
-          .catch(() => {})
-          .finally(checkConnection);
-        return this.connectingPromise;
-      } else {
-        // Clear the connecting promise, done.
-        this.connectingPromise = null;
-        return;
-      }
-    };
-
-    this.connectingPromise ??= this.connectInternal()
-      .catch(() => {})
-      .finally(checkConnection);
-    return this.connectingPromise;
-  }
-
-  protected async connectInternal() {
-    let appliedOptions: InternalConnectionOptions | null = null;
-
-    // This method ensures a disconnect before any connection attempt
-    await this.disconnectInternal();
-
-    /**
-     * This portion creates a sync implementation which can be racy when disconnecting or
-     * if multiple tabs on web are in use.
-     * This is protected in an exclusive lock.
-     * The promise tracks the creation which is used to synchronize disconnect attempts.
-     */
-    this.syncStreamInitPromise = new Promise(async (resolve, reject) => {
-      try {
-        if (!this.pendingConnectionOptions) {
-          this.logger.debug('No pending connection options found, not creating sync stream implementation');
-          // A disconnect could have cleared this.
-          resolve();
-          return;
-        }
-
-        if (this.disconnectingPromise) {
-          resolve();
-          return;
-        }
-
-        const { connector, options } = this.pendingConnectionOptions;
-        appliedOptions = options;
-
-        this.pendingConnectionOptions = null;
-
-        const { sync, onDispose } = await this.options.createSyncImplementation(connector, {
-          subscriptions: this.activeStreams,
-          ...options
-        });
-        this.iterateListeners((l) => l.syncStreamCreated?.(sync));
-        this.syncStreamImplementation = sync;
-        this.syncDisposer = onDispose;
-        await this.syncStreamImplementation.waitForReady();
-        resolve();
-      } catch (error) {
-        reject(error);
-      }
-    });
-
-    await this.syncStreamInitPromise;
-    this.syncStreamInitPromise = null;
-
-    if (!appliedOptions) {
-      // A disconnect could have cleared the options which did not create a syncStreamImplementation
-      return;
-    }
-
-    // It might be possible that a disconnect triggered between the last check
-    // and this point. Awaiting here allows the sync stream to be cleared if disconnected.
-    await this.disconnectingPromise;
-
-    this.logger.debug('Attempting to connect to PowerSync instance');
-    await this.syncStreamImplementation?.connect(appliedOptions!);
-  }
-
-  /**
-   * Close the sync connection.
-   *
-   * Use {@link connect} to connect again.
-   */
-  async disconnect() {
-    // This will help abort pending connects
-    this.pendingConnectionOptions = null;
-    await this.disconnectInternal();
-  }
-
-  protected async disconnectInternal(): Promise<void> {
-    if (this.disconnectingPromise) {
-      // A disconnect is already in progress
-      return this.disconnectingPromise;
-    }
-
-    this.disconnectingPromise = this.performDisconnect();
-
-    await this.disconnectingPromise;
-    this.disconnectingPromise = null;
-  }
-
-  protected async performDisconnect() {
-    // Wait if a sync stream implementation is being created before closing it
-    // (syncStreamImplementation must be assigned before we can properly dispose it)
-    await this.syncStreamInitPromise;
-
-    // Keep reference to the sync stream implementation and disposer
-    // The class members will be cleared before we trigger the disconnect
-    // to prevent any further calls to the sync stream implementation.
-    const sync = this.syncStreamImplementation;
-    this.syncStreamImplementation = null;
-    const disposer = this.syncDisposer;
-    this.syncDisposer = null;
-
-    await sync?.disconnect();
-    await sync?.dispose();
-    await disposer?.();
-  }
-
-  stream(adapter: InternalSubscriptionAdapter, name: string, parameters: Record<string, any> | null): SyncStream {
-    const desc = { name, parameters } satisfies SyncStreamDescription;
-
-    const waitForFirstSync = (abort?: AbortSignal) => {
-      return adapter.firstStatusMatching((s) => s.forStream(desc)?.subscription.hasSynced, abort);
-    };
-
-    return {
-      ...desc,
-      subscribe: async (options?: SyncStreamSubscribeOptions) => {
-        // NOTE: We also run this command if a subscription already exists, because this increases the expiry date
-        // (relevant if the app is closed before connecting again, where the last subscribe call determines the ttl).
-        await adapter.rustSubscriptionsCommand({
-          subscribe: {
-            stream: {
-              name,
-              params: parameters
-            },
-            ttl: options?.ttl,
-            priority: options?.priority
-          }
-        });
-
-        if (!this.syncStreamImplementation) {
-          // We're not connected. So, update the offline sync status to reflect the new subscription.
-          // (With an active iteration, the sync client would include it in its state).
-          await adapter.resolveOfflineSyncStatus();
-        }
-
-        const key = `${name}|${JSON.stringify(parameters)}`;
-        let subscription = this.locallyActiveSubscriptions.get(key);
-        if (subscription == null) {
-          const clearSubscription = () => {
-            this.locallyActiveSubscriptions.delete(key);
-            this.subscriptionsMayHaveChanged();
-          };
-
-          subscription = new ActiveSubscription(name, parameters, this.logger, waitForFirstSync, clearSubscription);
-          this.locallyActiveSubscriptions.set(key, subscription);
-          this.subscriptionsMayHaveChanged();
-        }
-
-        return new SyncStreamSubscriptionHandle(subscription);
-      },
-      unsubscribeAll: async () => {
-        await adapter.rustSubscriptionsCommand({ unsubscribe: { name, params: parameters } });
-        this.subscriptionsMayHaveChanged();
-      }
-    };
-  }
-
-  /**
-   * @internal exposed for testing
-   */
-  get activeStreams() {
-    return [...this.locallyActiveSubscriptions.values()].map((a) => ({ name: a.name, params: a.parameters }));
-  }
-
-  private subscriptionsMayHaveChanged() {
-    this.syncStreamImplementation?.updateSubscriptions(this.activeStreams);
-  }
-}
-
-class ActiveSubscription {
-  refcount: number = 0;
-
-  constructor(
-    readonly name: string,
-    readonly parameters: Record<string, any> | null,
-    readonly logger: ILogger,
-    readonly waitForFirstSync: (abort?: AbortSignal) => Promise<void>,
-    private clearSubscription: () => void
-  ) {}
-
-  decrementRefCount() {
-    this.refcount--;
-    if (this.refcount == 0) {
-      this.clearSubscription();
-    }
-  }
-}
-
-class SyncStreamSubscriptionHandle implements SyncStreamSubscription {
-  private active: boolean = true;
-
-  constructor(readonly subscription: ActiveSubscription) {
-    subscription.refcount++;
-    _finalizer?.register(this, subscription);
-  }
-
-  get name() {
-    return this.subscription.name;
-  }
-
-  get parameters() {
-    return this.subscription.parameters;
-  }
-
-  waitForFirstSync(abort?: AbortSignal): Promise<void> {
-    return this.subscription.waitForFirstSync(abort);
-  }
-
-  unsubscribe(): void {
-    if (this.active) {
-      this.active = false;
-      _finalizer?.unregister(this);
-      this.subscription.decrementRefCount();
-    }
-  }
-}
-
-const _finalizer =
-  'FinalizationRegistry' in globalThis
-    ? new FinalizationRegistry<ActiveSubscription>((sub) => {
-        sub.logger.warn(
-          `A subscription to ${sub.name} with params ${JSON.stringify(sub.parameters)} leaked! Please ensure calling unsubscribe() when you don't need a subscription anymore. For global subscriptions, consider storing them in global fields to avoid this warning.`
-        );
-      })
-    : null;

package/src/client/CustomQuery.ts

@@ -1,56 +0,0 @@
-import { AbstractPowerSyncDatabase } from './AbstractPowerSyncDatabase.js';
-import { Query, StandardWatchedQueryOptions } from './Query.js';
-import { FalsyComparator } from './watched/processors/comparators.js';
-import {
-  DifferentialQueryProcessor,
-  DifferentialWatchedQueryOptions
-} from './watched/processors/DifferentialQueryProcessor.js';
-import { OnChangeQueryProcessor } from './watched/processors/OnChangeQueryProcessor.js';
-import { DEFAULT_WATCH_QUERY_OPTIONS, WatchCompatibleQuery, WatchedQueryOptions } from './watched/WatchedQuery.js';
-
-/**
- * @internal
- */
-export interface CustomQueryOptions<RowType> {
-  db: AbstractPowerSyncDatabase;
-  query: WatchCompatibleQuery<RowType[]>;
-}
-
-/**
- * @internal
- */
-export class CustomQuery<RowType> implements Query<RowType> {
-  constructor(protected options: CustomQueryOptions<RowType>) {}
-
-  protected resolveOptions(options: WatchedQueryOptions): WatchedQueryOptions {
-    return {
-      reportFetching: options?.reportFetching ?? DEFAULT_WATCH_QUERY_OPTIONS.reportFetching,
-      throttleMs: options?.throttleMs ?? DEFAULT_WATCH_QUERY_OPTIONS.throttleMs,
-      triggerOnTables: options?.triggerOnTables
-    };
-  }
-
-  watch(watchOptions: StandardWatchedQueryOptions<RowType>) {
-    return new OnChangeQueryProcessor<RowType[]>({
-      db: this.options.db,
-      comparator: watchOptions?.comparator ?? FalsyComparator,
-      placeholderData: watchOptions?.placeholderData ?? [],
-      watchOptions: {
-        ...this.resolveOptions(watchOptions),
-        query: this.options.query
-      }
-    });
-  }
-
-  differentialWatch(differentialWatchOptions: DifferentialWatchedQueryOptions<RowType>) {
-    return new DifferentialQueryProcessor<RowType>({
-      db: this.options.db,
-      rowComparator: differentialWatchOptions?.rowComparator,
-      placeholderData: differentialWatchOptions?.placeholderData ?? [],
-      watchOptions: {
-        ...this.resolveOptions(differentialWatchOptions),
-        query: this.options.query
-      }
-    });
-  }
-}

package/src/client/constants.ts

@@ -1 +0,0 @@
-export const MAX_OP_ID = '9223372036854775807';

package/src/client/sync/bucket/BucketStorageAdapter.ts

@@ -1,118 +0,0 @@
-import { BaseListener, BaseObserverInterface, Disposable } from '../../../utils/BaseObserver.js';
-import { CrudBatch } from './CrudBatch.js';
-import { CrudEntry, OpId } from './CrudEntry.js';
-import { SyncDataBatch } from './SyncDataBatch.js';
-
-export interface BucketDescription {
-  name: string;
-  priority: number;
-}
-
-export interface Checkpoint {
-  last_op_id: OpId;
-  buckets: BucketChecksum[];
-  write_checkpoint?: string;
-  streams?: any[];
-}
-
-export interface BucketState {
-  bucket: string;
-  op_id: string;
-}
-
-export interface ChecksumCache {
-  checksums: Map<string, { checksum: BucketChecksum; last_op_id: OpId }>;
-  lastOpId: OpId;
-}
-
-export interface SyncLocalDatabaseResult {
-  ready: boolean;
-  checkpointValid: boolean;
-  checkpointFailures?: string[];
-}
-
-export type SavedProgress = {
-  atLast: number;
-  sinceLast: number;
-};
-
-export type BucketOperationProgress = Record<string, SavedProgress>;
-
-export interface BucketChecksum {
-  bucket: string;
-  priority?: number;
-  /**
-   * 32-bit unsigned hash.
-   */
-  checksum: number;
-
-  /**
-   * Count of operations - informational only.
-   */
-  count?: number;
-  /**
-   * The JavaScript client does not use this field, which is why it's defined to be `any`. We rely on the structure of
-   * this interface to pass custom `BucketChecksum`s to the Rust client in unit tests, which so all fields need to be
-   * present.
-   */
-  subscriptions?: any;
-}
-
-export enum PSInternalTable {
-  DATA = 'ps_data',
-  CRUD = 'ps_crud',
-  BUCKETS = 'ps_buckets',
-  OPLOG = 'ps_oplog',
-  UNTYPED = 'ps_untyped'
-}
-
-export enum PowerSyncControlCommand {
-  PROCESS_TEXT_LINE = 'line_text',
-  PROCESS_BSON_LINE = 'line_binary',
-  STOP = 'stop',
-  START = 'start',
-  NOTIFY_TOKEN_REFRESHED = 'refreshed_token',
-  NOTIFY_CRUD_UPLOAD_COMPLETED = 'completed_upload',
-  UPDATE_SUBSCRIPTIONS = 'update_subscriptions'
-}
-
-export interface BucketStorageListener extends BaseListener {
-  crudUpdate: () => void;
-}
-
-export interface BucketStorageAdapter extends BaseObserverInterface<BucketStorageListener>, Disposable {
-  init(): Promise<void>;
-  saveSyncData(batch: SyncDataBatch, fixedKeyFormat?: boolean): Promise<void>;
-  removeBuckets(buckets: string[]): Promise<void>;
-  setTargetCheckpoint(checkpoint: Checkpoint): Promise<void>;
-
-  startSession(): void;
-
-  getBucketStates(): Promise<BucketState[]>;
-  getBucketOperationProgress(): Promise<BucketOperationProgress>;
-  hasMigratedSubkeys(): Promise<boolean>;
-  migrateToFixedSubkeys(): Promise<void>;
-
-  syncLocalDatabase(
-    checkpoint: Checkpoint,
-    priority?: number
-  ): Promise<{ checkpointValid: boolean; ready: boolean; failures?: any[] }>;
-
-  nextCrudItem(): Promise<CrudEntry | undefined>;
-  hasCrud(): Promise<boolean>;
-  getCrudBatch(limit?: number): Promise<CrudBatch | null>;
-
-  hasCompletedSync(): Promise<boolean>;
-  updateLocalTarget(cb: () => Promise<string>): Promise<boolean>;
-  getMaxOpId(): string;
-
-  /**
-   * Get an unique client id.
-   */
-  getClientId(): Promise<string>;
-
-  /**
-   * Invokes the `powersync_control` function for the sync client.
-   */
-  control(op: PowerSyncControlCommand, payload: string | Uint8Array | null): Promise<string>;
-}

package/src/client/sync/bucket/OpType.ts

@@ -1,23 +0,0 @@
-export enum OpTypeEnum {
-  CLEAR = 1,
-  MOVE = 2,
-  PUT = 3,
-  REMOVE = 4
-}
-
-export type OpTypeJSON = string;
-
-/**
- * Used internally for sync buckets.
- */
-export class OpType {
-  static fromJSON(jsonValue: OpTypeJSON) {
-    return new OpType(OpTypeEnum[jsonValue]);
-  }
-
-  constructor(public value: OpTypeEnum) {}
-
-  toJSON() {
-    return Object.entries(OpTypeEnum).find(([, value]) => value === this.value)![0];
-  }
-}

package/src/client/sync/bucket/OplogEntry.ts

@@ -1,50 +0,0 @@
-import { OpId } from './CrudEntry.js';
-import { OpType, OpTypeJSON } from './OpType.js';
-
-export interface OplogEntryJSON {
-  checksum: number;
-  data?: string;
-  object_id?: string;
-  object_type?: string;
-  op_id: string;
-  op: OpTypeJSON;
-  subkey?: string;
-}
-
-export class OplogEntry {
-  static fromRow(row: OplogEntryJSON) {
-    return new OplogEntry(
-      row.op_id,
-      OpType.fromJSON(row.op),
-      row.checksum,
-      row.subkey,
-      row.object_type,
-      row.object_id,
-      row.data
-    );
-  }
-
-  constructor(
-    public op_id: OpId,
-    public op: OpType,
-    public checksum: number,
-    public subkey?: string,
-    public object_type?: string,
-    public object_id?: string,
-    public data?: string
-  ) {}
-
-  toJSON(fixedKeyEncoding = false): OplogEntryJSON {
-    return {
-      op_id: this.op_id,
-      op: this.op.toJSON(),
-      object_type: this.object_type,
-      object_id: this.object_id,
-      checksum: this.checksum,
-      data: this.data,
-      // Older versions of the JS SDK used to always JSON.stringify here. That has always been wrong,
-      // but we need to migrate gradually to not break existing databases.
-      subkey: fixedKeyEncoding ? this.subkey : JSON.stringify(this.subkey)
-    };
-  }
-}