Add sync progress APIs

Author: simolus3

packages/common/src/client/AbstractPowerSyncDatabase.ts

@@ -32,6 +32,7 @@ import {
   type PowerSyncConnectionOptions,
   type RequiredAdditionalConnectionOptions
 } from './sync/stream/AbstractStreamingSyncImplementation.js';
+import { FULL_SYNC_PRIORITY } from 'src/db/crud/SyncProgress.js';
 
 export interface DisconnectAndClearOptions {
   /** When set to false, data in local-only tables is preserved. */
@@ -146,11 +147,6 @@ export const isPowerSyncDatabaseOptionsWithSettings = (test: any): test is Power
   return typeof test == 'object' && isSQLOpenOptions(test.database);
 };
 
-/**
- * The priority used by the core extension to indicate that a full sync was completed.
- */
-const FULL_SYNC_PRIORITY = 2147483647;
-
 export abstract class AbstractPowerSyncDatabase extends BaseObserver<PowerSyncDBListener> {
   /**
    * Transactions should be queued in the DBAdapter, but we also want to prevent

packages/common/src/db/crud/SyncProgress.ts

@@ -0,0 +1,81 @@
+import type { SyncStatus } from "./SyncStatus.js";
+
+// (bucket, progress) pairs
+export type InternalProgressInformation = Record<string, {
+    priority: number, // Priority of the associated buckets
+    atLast: number, // Total ops at last completed sync, or 0
+    sinceLast: number, // Total ops _since_ the last completed sync.
+    targetCount: number, // Total opcount for next checkpoint as indicated by service.
+  }>;
+
+/**
+ * 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.
+     */
+    total: number;
+    /**
+     * The amount of operations that have already been downloaded.
+     */
+    completed: number;
+
+    /**
+     * Relative progress, as {@link completed} of {@link total}. This will be a number
+     * between `0.0` and `1.0`.
+     */
+    fraction: number;
+};
+
+/**
+ * Provides realtime progress on how PowerSync is downloading rows.
+ * 
+ * The reported progress always reflects the status towards th 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 {
+    constructor(protected internal: InternalProgressInformation) {}
+
+    get untilCompletion(): ProgressWithOperations {
+        return this.untilPriority(FULL_SYNC_PRIORITY);
+    }
+
+    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.sinceLast;
+                total += progress.targetCount - progress.atLast;
+            }
+        }
+
+        let progress = total == 0 ? 0.0 : downloaded / total;
+        return {
+            total,
+            completed: downloaded,
+            fraction: progress,
+        }
+    }
+}

packages/common/src/db/crud/SyncStatus.ts

@@ -1,6 +1,14 @@
+import { InternalProgressInformation, SyncProgress } from "./SyncProgress.js";
+
 export type SyncDataFlowStatus = Partial<{
   downloading: boolean;
   uploading: boolean;
+  /**
+   * Internal information about how far we are downloading operations in buckets.
+   * 
+   * Please use the {@link SyncStatus#downloadProgress} property to track sync progress.
+   */
+  downloadProgress: InternalProgressInformation,
 }>;
 
 export interface SyncPriorityStatus {
@@ -74,6 +82,21 @@ export class SyncStatus {
     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 a pair of {@link SyncStatus#hasSynced} and {@link SyncStatus#lastSyncedAt} fields that apply
    * to a specific bucket priority instead of the entire sync operation.

packages/common/src/index.ts

@@ -19,6 +19,7 @@ export * from './client/sync/stream/AbstractStreamingSyncImplementation.js';
 export * from './client/sync/stream/streaming-sync-types.js';
 export { MAX_OP_ID } from './client/constants.js';
 
+export { ProgressWithOperations, SyncProgress } from './db/crud/SyncProgress.js';
 export * from './db/crud/SyncStatus.js';
 export * from './db/crud/UploadQueueStatus.js';
 export * from './db/schema/Schema.js';