@powersync/common 1.41.0 → 1.42.0

package/src/db/DBAdapter.ts

@@ -0,0 +1,134 @@
+/**
+ * Set of generic interfaces to allow PowerSync compatibility with
+ * different SQLite DB implementations.
+ */
+
+import { BaseListener, BaseObserverInterface } from '../utils/BaseObserver.js';
+
+/**
+ * TODO most of these types could be exported to a common `types` package
+ * which is used by the DB adapter libraries as well.
+ */
+
+/**
+ * Object returned by SQL Query executions.
+ */
+export type QueryResult = {
+  /** Represents the auto-generated row id if applicable. */
+  insertId?: number;
+  /** Number of affected rows if result of a update query. */
+  rowsAffected: number;
+  /** if status is undefined or 0 this object will contain the query results */
+  rows?: {
+    /** Raw array with all dataset */
+    _array: any[];
+    /** The length of the dataset */
+    length: number;
+    /** A convenience function to acess the index based the row object
+     * @param idx the row index
+     * @returns the row structure identified by column names
+     */
+    item: (idx: number) => any;
+  };
+};
+
+export interface DBGetUtils {
+  /** Execute a read-only query and return results. */
+  getAll<T>(sql: string, parameters?: any[]): Promise<T[]>;
+  /** Execute a read-only query and return the first result, or null if the ResultSet is empty. */
+  getOptional<T>(sql: string, parameters?: any[]): Promise<T | null>;
+  /** Execute a read-only query and return the first result, error if the ResultSet is empty. */
+  get<T>(sql: string, parameters?: any[]): Promise<T>;
+}
+
+export interface LockContext extends DBGetUtils {
+  /** Execute a single write statement. */
+  execute: (query: string, params?: any[] | undefined) => Promise<QueryResult>;
+  /**
+   * Execute a single write statement and return raw results.
+   * Unlike `execute`, which returns an object with structured key-value pairs,
+   * `executeRaw` returns a nested array of raw values, where each row is
+   * represented as an array of column values without field names.
+   *
+   * Example result:
+   *
+   * ```[ [ '1', 'list 1', '33', 'Post content', '1' ] ]```
+   *
+   * Where as `execute`'s `rows._array` would have been:
+   *
+   * ```[ { id: '33', name: 'list 1', content: 'Post content', list_id: '1' } ]```
+   */
+  executeRaw: (query: string, params?: any[] | undefined) => Promise<any[][]>;
+}
+
+export interface Transaction extends LockContext {
+  /** Commit multiple changes to the local DB using the Transaction context. */
+  commit: () => Promise<QueryResult>;
+  /** Roll back multiple attempted changes using the Transaction context. */
+  rollback: () => Promise<QueryResult>;
+}
+
+/**
+ * Update table operation numbers from SQLite
+ */
+export enum RowUpdateType {
+  SQLITE_INSERT = 18,
+  SQLITE_DELETE = 9,
+  SQLITE_UPDATE = 23
+}
+export interface TableUpdateOperation {
+  opType: RowUpdateType;
+  rowId: number;
+}
+/**
+ * Notification of an update to one or more tables, for the purpose of realtime change notifications.
+ */
+export interface UpdateNotification extends TableUpdateOperation {
+  table: string;
+}
+
+export interface BatchedUpdateNotification {
+  rawUpdates: UpdateNotification[];
+  tables: string[];
+  groupedUpdates: Record<string, TableUpdateOperation[]>;
+}
+
+export interface DBAdapterListener extends BaseListener {
+  /**
+   * Listener for table updates.
+   * Allows for single table updates in order to maintain API compatibility
+   * without the need for a major version bump
+   * The DB adapter can also batch update notifications if supported.
+   */
+  tablesUpdated: (updateNotification: BatchedUpdateNotification | UpdateNotification) => void;
+}
+
+export interface DBLockOptions {
+  timeoutMs?: number;
+}
+
+export interface DBAdapter extends BaseObserverInterface<DBAdapterListener>, DBGetUtils {
+  close: () => void | Promise<void>;
+  execute: (query: string, params?: any[]) => Promise<QueryResult>;
+  executeRaw: (query: string, params?: any[]) => Promise<any[][]>;
+  executeBatch: (query: string, params?: any[][]) => Promise<QueryResult>;
+  name: string;
+  readLock: <T>(fn: (tx: LockContext) => Promise<T>, options?: DBLockOptions) => Promise<T>;
+  readTransaction: <T>(fn: (tx: Transaction) => Promise<T>, options?: DBLockOptions) => Promise<T>;
+  writeLock: <T>(fn: (tx: LockContext) => Promise<T>, options?: DBLockOptions) => Promise<T>;
+  writeTransaction: <T>(fn: (tx: Transaction) => Promise<T>, options?: DBLockOptions) => Promise<T>;
+  /**
+   * This method refreshes the schema information across all connections. This is for advanced use cases, and should generally not be needed.
+   */
+  refreshSchema: () => Promise<void>;
+}
+
+export function isBatchedUpdateNotification(
+  update: BatchedUpdateNotification | UpdateNotification
+): update is BatchedUpdateNotification {
+  return 'tables' in update;
+}
+
+export function extractTableUpdates(update: BatchedUpdateNotification | UpdateNotification) {
+  return isBatchedUpdateNotification(update) ? update.tables : [update.table];
+}

package/src/db/crud/SyncProgress.ts

@@ -0,0 +1,100 @@
+import type { BucketProgress } from '../../client/sync/stream/core-instruction.js';
+import type { SyncStatus } from './SyncStatus.js';
+
+// (bucket, progress) pairs
+/** @internal */
+export type InternalProgressInformation = Record<string, BucketProgress>;
+
+/**
+ * @internal The priority used by the core extension to indicate that a full sync was completed.
+ */
+export const FULL_SYNC_PRIORITY = 2147483647;
+
+/**
+ * Information about a progressing download made by the PowerSync SDK.
+ *
+ * To obtain these values, use {@link SyncProgress}, available through
+ * {@link SyncStatus#downloadProgress}.
+ */
+export interface ProgressWithOperations {
+  /**
+   * The total amount of operations to download for the current sync iteration
+   * to complete.
+   */
+  totalOperations: number;
+  /**
+   * The amount of operations that have already been downloaded.
+   */
+  downloadedOperations: number;
+
+  /**
+   * Relative progress, as {@link downloadedOperations} of {@link totalOperations}.
+   *
+   * This will be a number between `0.0` and `1.0` (inclusive).
+   *
+   * When this number reaches `1.0`, all changes have been received from the sync service.
+   * Actually applying these changes happens before the `downloadProgress` field is cleared from
+   * {@link SyncStatus}, so progress can stay at `1.0` for a short while before completing.
+   */
+  downloadedFraction: number;
+}
+
+/**
+ * Provides realtime progress on how PowerSync is downloading rows.
+ *
+ * The progress until the next complete sync is available through the fields on {@link ProgressWithOperations},
+ * which this class implements.
+ * Additionally, the {@link SyncProgress.untilPriority} method can be used to otbain progress towards
+ * a specific priority (instead of the progress for the entire download).
+ *
+ * The reported progress always reflects the status towards the end of a sync iteration (after
+ * which a consistent snapshot of all buckets is available locally).
+ *
+ * In rare cases (in particular, when a [compacting](https://docs.powersync.com/usage/lifecycle-maintenance/compacting-buckets)
+ * operation takes place between syncs), it's possible for the returned numbers to be slightly
+ * inaccurate. For this reason, {@link SyncProgress} should be seen as an approximation of progress.
+ * The information returned is good enough to build progress bars, but not exact enough to track
+ * individual download counts.
+ *
+ * Also note that data is downloaded in bulk, which means that individual counters are unlikely
+ * to be updated one-by-one.
+ */
+export class SyncProgress implements ProgressWithOperations {
+  totalOperations: number;
+  downloadedOperations: number;
+  downloadedFraction: number;
+
+  constructor(protected internal: InternalProgressInformation) {
+    const untilCompletion = this.untilPriority(FULL_SYNC_PRIORITY);
+
+    this.totalOperations = untilCompletion.totalOperations;
+    this.downloadedOperations = untilCompletion.downloadedOperations;
+    this.downloadedFraction = untilCompletion.downloadedFraction;
+  }
+
+  /**
+   * Returns download progress towards all data up until the specified priority being received.
+   *
+   * The returned {@link ProgressWithOperations} tracks the target amount of operations that need
+   * to be downloaded in total and how many of them have already been received.
+   */
+  untilPriority(priority: number): ProgressWithOperations {
+    let total = 0;
+    let downloaded = 0;
+
+    for (const progress of Object.values(this.internal)) {
+      // Include higher-priority buckets, which are represented by lower numbers.
+      if (progress.priority <= priority) {
+        downloaded += progress.since_last;
+        total += progress.target_count - progress.at_last;
+      }
+    }
+
+    let progress = total == 0 ? 0.0 : downloaded / total;
+    return {
+      totalOperations: total,
+      downloadedOperations: downloaded,
+      downloadedFraction: progress
+    };
+  }
+}

package/src/db/crud/SyncStatus.ts

@@ -0,0 +1,308 @@
+import { CoreStreamSubscription } from '../../client/sync/stream/core-instruction.js';
+import { SyncClientImplementation } from '../../client/sync/stream/AbstractStreamingSyncImplementation.js';
+import { InternalProgressInformation, ProgressWithOperations, SyncProgress } from './SyncProgress.js';
+import { SyncStreamDescription, SyncSubscriptionDescription } from '../../client/sync/sync-streams.js';
+
+export type SyncDataFlowStatus = Partial<{
+  downloading: boolean;
+  uploading: boolean;
+  /**
+   * Error during downloading (including connecting).
+   *
+   * Cleared on the next successful data download.
+   */
+  downloadError?: Error;
+  /**
+   * Error during uploading.
+   * Cleared on the next successful upload.
+   */
+  uploadError?: Error;
+  /**
+   * Internal information about how far we are downloading operations in buckets.
+   *
+   * Please use the {@link SyncStatus#downloadProgress} property to track sync progress.
+   */
+  downloadProgress: InternalProgressInformation | null;
+  internalStreamSubscriptions: CoreStreamSubscription[] | null;
+}>;
+
+export interface SyncPriorityStatus {
+  priority: number;
+  lastSyncedAt?: Date;
+  hasSynced?: boolean;
+}
+
+export type SyncStatusOptions = {
+  connected?: boolean;
+  connecting?: boolean;
+  dataFlow?: SyncDataFlowStatus;
+  lastSyncedAt?: Date;
+  hasSynced?: boolean;
+  priorityStatusEntries?: SyncPriorityStatus[];
+  clientImplementation?: SyncClientImplementation;
+};
+
+export class SyncStatus {
+  constructor(protected options: SyncStatusOptions) {}
+
+  /**
+   * Returns the used sync client implementation (either the one implemented in JavaScript or the newer Rust-based
+   * implementation).
+   *
+   * This information is only available after a connection has been requested.
+   */
+  get clientImplementation() {
+    return this.options.clientImplementation;
+  }
+
+  /**
+   * Indicates if the client is currently connected to the PowerSync service.
+   *
+   * @returns {boolean} True if connected, false otherwise. Defaults to false if not specified.
+   */
+  get connected() {
+    return this.options.connected ?? false;
+  }
+
+  /**
+   * Indicates if the client is in the process of establishing a connection to the PowerSync service.
+   *
+   * @returns {boolean} True if connecting, false otherwise. Defaults to false if not specified.
+   */
+  get connecting() {
+    return this.options.connecting ?? false;
+  }
+
+  /**
+   * Time that a last sync has fully completed, if any.
+   * This timestamp is reset to null after a restart of the PowerSync service.
+   *
+   * @returns {Date | undefined} The timestamp of the last successful sync, or undefined if no sync has completed.
+   */
+  get lastSyncedAt() {
+    return this.options.lastSyncedAt;
+  }
+
+  /**
+   * Indicates whether there has been at least one full sync completed since initialization.
+   *
+   * @returns {boolean | undefined} True if at least one sync has completed, false if no sync has completed,
+   * or undefined when the state is still being loaded from the database.
+   */
+  get hasSynced() {
+    return this.options.hasSynced;
+  }
+
+  /**
+   * Provides the current data flow status regarding uploads and downloads.
+   *
+   * @returns {SyncDataFlowStatus} An object containing:
+   * - downloading: True if actively downloading changes (only when connected is also true)
+   * - uploading: True if actively uploading changes
+   * Defaults to {downloading: false, uploading: false} if not specified.
+   */
+  get dataFlowStatus() {
+    return (
+      this.options.dataFlow ?? {
+        /**
+         * true if actively downloading changes.
+         * This is only true when {@link connected} is also true.
+         */
+        downloading: false,
+        /**
+         * true if uploading changes.
+         */
+        uploading: false
+      }
+    );
+  }
+
+  /**
+   * All sync streams currently being tracked in teh database.
+   *
+   * This returns null when the database is currently being opened and we don't have reliable information about all
+   * included streams yet.
+   *
+   * @experimental Sync streams are currently in alpha.
+   */
+  get syncStreams(): SyncStreamStatus[] | undefined {
+    return this.options.dataFlow?.internalStreamSubscriptions?.map((core) => new SyncStreamStatusView(this, core));
+  }
+
+  /**
+   * If the `stream` appears in {@link syncStreams}, returns the current status for that stream.
+   *
+   * @experimental Sync streams are currently in alpha.
+   */
+  forStream(stream: SyncStreamDescription): SyncStreamStatus | undefined {
+    const asJson = JSON.stringify(stream.parameters);
+    const raw = this.options.dataFlow?.internalStreamSubscriptions?.find(
+      (r) => r.name == stream.name && asJson == JSON.stringify(r.parameters)
+    );
+
+    return raw && new SyncStreamStatusView(this, raw);
+  }
+
+  /**
+   * Provides sync status information for all bucket priorities, sorted by priority (highest first).
+   *
+   * @returns {SyncPriorityStatus[]} An array of status entries for different sync priority levels,
+   * sorted with highest priorities (lower numbers) first.
+   */
+  get priorityStatusEntries() {
+    return (this.options.priorityStatusEntries ?? []).slice().sort(SyncStatus.comparePriorities);
+  }
+
+  /**
+   * A realtime progress report on how many operations have been downloaded and
+   * how many are necessary in total to complete the next sync iteration.
+   *
+   * This field is only set when {@link SyncDataFlowStatus#downloading} is also true.
+   */
+  get downloadProgress(): SyncProgress | null {
+    const internalProgress = this.options.dataFlow?.downloadProgress;
+    if (internalProgress == null) {
+      return null;
+    }
+
+    return new SyncProgress(internalProgress);
+  }
+
+  /**
+   * Reports the sync status (a pair of {@link SyncStatus#hasSynced} and {@link SyncStatus#lastSyncedAt} fields)
+   * for a specific bucket priority level.
+   *
+   * When buckets with different priorities are declared, PowerSync may choose to synchronize higher-priority
+   * buckets first. When a consistent view over all buckets for all priorities up until the given priority is
+   * reached, PowerSync makes data from those buckets available before lower-priority buckets have finished
+   * syncing.
+   *
+   * This method returns the status for the requested priority or the next higher priority level that has
+   * status information available. This is because when PowerSync makes data for a given priority available,
+   * all buckets in higher-priorities are guaranteed to be consistent with that checkpoint.
+   *
+   * For example, if PowerSync just finished synchronizing buckets in priority level 3, calling this method
+   * with a priority of 1 may return information for priority level 3.
+   *
+   * @param {number} priority The bucket priority for which the status should be reported
+   * @returns {SyncPriorityStatus} Status information for the requested priority level or the next higher level with available status
+   */
+  statusForPriority(priority: number): SyncPriorityStatus {
+    // priorityStatusEntries are sorted by ascending priorities (so higher numbers to lower numbers).
+    for (const known of this.priorityStatusEntries) {
+      // We look for the first entry that doesn't have a higher priority.
+      if (known.priority >= priority) {
+        return known;
+      }
+    }
+
+    // If we have a complete sync, that necessarily includes all priorities.
+    return {
+      priority,
+      lastSyncedAt: this.lastSyncedAt,
+      hasSynced: this.hasSynced
+    };
+  }
+
+  /**
+   * Compares this SyncStatus instance with another to determine if they are equal.
+   * Equality is determined by comparing the serialized JSON representation of both instances.
+   *
+   * @param {SyncStatus} status The SyncStatus instance to compare against
+   * @returns {boolean} True if the instances are considered equal, false otherwise
+   */
+  isEqual(status: SyncStatus) {
+    /**
+     * By default Error object are serialized to an empty object.
+     * This replaces Errors with more useful information before serialization.
+     */
+    const replacer = (_: string, value: any) => {
+      if (value instanceof Error) {
+        return {
+          name: value.name,
+          message: value.message,
+          stack: value.stack
+        };
+      }
+      return value;
+    };
+
+    return JSON.stringify(this.options, replacer) == JSON.stringify(status.options, replacer);
+  }
+
+  /**
+   * Creates a human-readable string representation of the current sync status.
+   * Includes information about connection state, sync completion, and data flow.
+   *
+   * @returns {string} A string representation of the sync status
+   */
+  getMessage() {
+    const dataFlow = this.dataFlowStatus;
+    return `SyncStatus<connected: ${this.connected} connecting: ${this.connecting} lastSyncedAt: ${this.lastSyncedAt} hasSynced: ${this.hasSynced}. Downloading: ${dataFlow.downloading}. Uploading: ${dataFlow.uploading}. UploadError: ${dataFlow.uploadError}, DownloadError?: ${dataFlow.downloadError}>`;
+  }
+
+  /**
+   * Serializes the SyncStatus instance to a plain object.
+   *
+   * @returns {SyncStatusOptions} A plain object representation of the sync status
+   */
+  toJSON(): SyncStatusOptions {
+    return {
+      connected: this.connected,
+      connecting: this.connecting,
+      dataFlow: this.dataFlowStatus,
+      lastSyncedAt: this.lastSyncedAt,
+      hasSynced: this.hasSynced,
+      priorityStatusEntries: this.priorityStatusEntries
+    };
+  }
+
+  private static comparePriorities(a: SyncPriorityStatus, b: SyncPriorityStatus) {
+    return b.priority - a.priority; // Reverse because higher priorities have lower numbers
+  }
+}
+
+/**
+ * Information about a sync stream subscription.
+ */
+export interface SyncStreamStatus {
+  progress: ProgressWithOperations | null;
+  subscription: SyncSubscriptionDescription;
+  priority: number | null;
+}
+
+class SyncStreamStatusView implements SyncStreamStatus {
+  subscription: SyncSubscriptionDescription;
+
+  constructor(
+    private status: SyncStatus,
+    private core: CoreStreamSubscription
+  ) {
+    this.subscription = {
+      name: core.name,
+      parameters: core.parameters,
+      active: core.active,
+      isDefault: core.is_default,
+      hasExplicitSubscription: core.has_explicit_subscription,
+      expiresAt: core.expires_at != null ? new Date(core.expires_at * 1000) : null,
+      hasSynced: core.last_synced_at != null,
+      lastSyncedAt: core.last_synced_at != null ? new Date(core.last_synced_at * 1000) : null
+    };
+  }
+
+  get progress() {
+    if (this.status.dataFlowStatus.downloadProgress == null) {
+      // Don't make download progress public if we're not currently downloading.
+      return null;
+    }
+
+    const { total, downloaded } = this.core.progress;
+    const progress = total == 0 ? 0.0 : downloaded / total;
+
+    return { totalOperations: total, downloadedOperations: downloaded, downloadedFraction: progress };
+  }
+
+  get priority() {
+    return this.core.priority;
+  }
+}

package/src/db/crud/UploadQueueStatus.ts

@@ -0,0 +1,20 @@
+export class UploadQueueStats {
+  constructor(
+    /**
+     * Number of records in the upload queue.
+     */
+    public count: number,
+    /**
+     * Size of the upload queue in bytes.
+     */
+    public size: number | null = null
+  ) {}
+
+  toString() {
+    if (this.size == null) {
+      return `UploadQueueStats<count:${this.count}>`;
+    } else {
+      return `UploadQueueStats<count: $count size: ${this.size / 1024}kB>`;
+    }
+  }
+}

package/src/db/schema/Column.ts

@@ -0,0 +1,60 @@
+// https://www.sqlite.org/lang_expr.html#castexpr
+export enum ColumnType {
+  TEXT = 'TEXT',
+  INTEGER = 'INTEGER',
+  REAL = 'REAL'
+}
+
+export interface ColumnOptions {
+  name: string;
+  type?: ColumnType;
+}
+
+export type BaseColumnType<T extends number | string | null> = {
+  type: ColumnType;
+};
+
+export type ColumnsType = Record<string, BaseColumnType<any>>;
+
+export type ExtractColumnValueType<T extends BaseColumnType<any>> = T extends BaseColumnType<infer R> ? R : unknown;
+
+const text: BaseColumnType<string | null> = {
+  type: ColumnType.TEXT
+};
+
+const integer: BaseColumnType<number | null> = {
+  type: ColumnType.INTEGER
+};
+
+const real: BaseColumnType<number | null> = {
+  type: ColumnType.REAL
+};
+
+// powersync-sqlite-core limits the number of column per table to 1999, due to internal SQLite limits.
+// In earlier versions this was limited to 63.
+export const MAX_AMOUNT_OF_COLUMNS = 1999;
+
+export const column = {
+  text,
+  integer,
+  real
+};
+
+export class Column {
+  constructor(protected options: ColumnOptions) {}
+
+  get name() {
+    return this.options.name;
+  }
+
+  get type() {
+    return this.options.type;
+  }
+
+  toJSON() {
+    return {
+      name: this.name,
+      type: this.type
+    };
+  }
+}

package/src/db/schema/Index.ts

@@ -0,0 +1,39 @@
+import { IndexedColumn } from './IndexedColumn.js';
+import { Table } from './Table.js';
+
+export interface IndexOptions {
+  name: string;
+  columns?: IndexedColumn[];
+}
+
+export const DEFAULT_INDEX_OPTIONS: Partial<IndexOptions> = {
+  columns: []
+};
+
+export class Index {
+  static createAscending(options: IndexOptions, columnNames: string[]) {
+    return new Index({
+      ...options,
+      columns: columnNames.map((name) => IndexedColumn.createAscending(name))
+    });
+  }
+
+  constructor(protected options: IndexOptions) {
+    this.options = { ...DEFAULT_INDEX_OPTIONS, ...options };
+  }
+
+  get name() {
+    return this.options.name;
+  }
+
+  get columns() {
+    return this.options.columns ?? [];
+  }
+
+  toJSON(table: Table) {
+    return {
+      name: this.name,
+      columns: this.columns.map((c) => c.toJSON(table))
+    };
+  }
+}