@powersync/common 0.0.0-dev-20250418125956 → 0.0.0-dev-20250520135616

package/lib/client/AbstractPowerSyncDatabase.d.ts

@@ -183,6 +183,7 @@ export declare abstract class AbstractPowerSyncDatabase extends BaseObserver<Pow
      * Cannot be used while connected - this should only be called before {@link AbstractPowerSyncDatabase.connect}.
      */
     updateSchema(schema: Schema): Promise<void>;
+    get logger(): Logger.ILogger;
     /**
      * Wait for initialization to complete.
      * While initializing is automatic, this helps to catch and report initialization errors.

package/lib/client/AbstractPowerSyncDatabase.js

@@ -15,6 +15,7 @@ import { CrudBatch } from './sync/bucket/CrudBatch.js';
 import { CrudEntry } from './sync/bucket/CrudEntry.js';
 import { CrudTransaction } from './sync/bucket/CrudTransaction.js';
 import { DEFAULT_CRUD_UPLOAD_THROTTLE_MS, DEFAULT_RETRY_DELAY_MS } from './sync/stream/AbstractStreamingSyncImplementation.js';
+import { FULL_SYNC_PRIORITY } from '../db/crud/SyncProgress.js';
 const POWERSYNC_TABLE_MATCH = /(^ps_data__|^ps_data_local__)/;
 const DEFAULT_DISCONNECT_CLEAR_OPTIONS = {
     clearLocal: true
@@ -42,10 +43,6 @@ export const DEFAULT_LOCK_TIMEOUT_MS = 120_000; // 2 mins
 export const isPowerSyncDatabaseOptionsWithSettings = (test) => {
     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 class AbstractPowerSyncDatabase extends BaseObserver {
     options;
     /**
@@ -250,6 +247,9 @@ export class AbstractPowerSyncDatabase extends BaseObserver {
         await this.database.refreshSchema();
         this.iterateListeners(async (cb) => cb.schemaChanged?.(schema));
     }
+    get logger() {
+        return this.options.logger;
+    }
     /**
      * Wait for initialization to complete.
      * While initializing is automatic, this helps to catch and report initialization errors.
@@ -260,6 +260,7 @@ export class AbstractPowerSyncDatabase extends BaseObserver {
     // Use the options passed in during connect, or fallback to the options set during database creation or fallback to the default options
     resolvedConnectionOptions(options) {
         return {
+            ...options,
             retryDelayMs: options?.retryDelayMs ?? this.options.retryDelayMs ?? this.options.retryDelay ?? DEFAULT_RETRY_DELAY_MS,
             crudUploadThrottleMs: options?.crudUploadThrottleMs ?? this.options.crudUploadThrottleMs ?? DEFAULT_CRUD_UPLOAD_THROTTLE_MS
         };
@@ -274,11 +275,8 @@ export class AbstractPowerSyncDatabase extends BaseObserver {
         if (this.closed) {
             throw new Error('Cannot connect using a closed client');
         }
-        const { retryDelayMs, crudUploadThrottleMs } = this.resolvedConnectionOptions(options);
-        this.syncStreamImplementation = this.generateSyncStreamImplementation(connector, {
-            retryDelayMs,
-            crudUploadThrottleMs
-        });
+        const resolvedConnectOptions = this.resolvedConnectionOptions(options);
+        this.syncStreamImplementation = this.generateSyncStreamImplementation(connector, resolvedConnectOptions);
         this.syncStatusListenerDisposer = this.syncStreamImplementation.registerListener({
             statusChanged: (status) => {
                 this.currentStatus = new SyncStatus({

package/lib/client/sync/bucket/BucketStorageAdapter.d.ts

@@ -27,6 +27,11 @@ export interface SyncLocalDatabaseResult {
     checkpointValid: boolean;
     checkpointFailures?: string[];
 }
+export type SavedProgress = {
+    atLast: number;
+    sinceLast: number;
+};
+export type BucketOperationProgress = Record<string, SavedProgress>;
 export interface BucketChecksum {
     bucket: string;
     priority?: number;
@@ -56,6 +61,7 @@ export interface BucketStorageAdapter extends BaseObserver<BucketStorageListener
     setTargetCheckpoint(checkpoint: Checkpoint): Promise<void>;
     startSession(): void;
     getBucketStates(): Promise<BucketState[]>;
+    getBucketOperationProgress(): Promise<BucketOperationProgress>;
     syncLocalDatabase(checkpoint: Checkpoint, priority?: number): Promise<{
         checkpointValid: boolean;
         ready: boolean;

package/lib/client/sync/bucket/CrudEntry.d.ts

@@ -51,6 +51,11 @@ export declare class CrudEntry {
      * Data associated with the change.
      */
     opData?: Record<string, any>;
+    /**
+     * For tables where the `trackPreviousValues` option has been enabled, this tracks previous values for
+     * `UPDATE` and `DELETE` statements.
+     */
+    previousValues?: Record<string, any>;
     /**
      * Table that contained the change.
      */
@@ -59,8 +64,15 @@ export declare class CrudEntry {
      * Auto-incrementing transaction id. This is the same for all operations within the same transaction.
      */
     transactionId?: number;
+    /**
+     * Client-side metadata attached with this write.
+     *
+     * This field is only available when the `trackMetadata` option was set to `true` when creating a table
+     * and the insert or update statement set the `_metadata` column.
+     */
+    metadata?: string;
     static fromRow(dbRow: CrudEntryJSON): CrudEntry;
-    constructor(clientId: number, op: UpdateType, table: string, id: string, transactionId?: number, opData?: Record<string, any>);
+    constructor(clientId: number, op: UpdateType, table: string, id: string, transactionId?: number, opData?: Record<string, any>, previousValues?: Record<string, any>, metadata?: string);
     /**
      * Converts the change to JSON format.
      */

package/lib/client/sync/bucket/CrudEntry.js

@@ -30,6 +30,11 @@ export class CrudEntry {
      * Data associated with the change.
      */
     opData;
+    /**
+     * For tables where the `trackPreviousValues` option has been enabled, this tracks previous values for
+     * `UPDATE` and `DELETE` statements.
+     */
+    previousValues;
     /**
      * Table that contained the change.
      */
@@ -38,17 +43,26 @@ export class CrudEntry {
      * Auto-incrementing transaction id. This is the same for all operations within the same transaction.
      */
     transactionId;
+    /**
+     * Client-side metadata attached with this write.
+     *
+     * This field is only available when the `trackMetadata` option was set to `true` when creating a table
+     * and the insert or update statement set the `_metadata` column.
+     */
+    metadata;
     static fromRow(dbRow) {
         const data = JSON.parse(dbRow.data);
-        return new CrudEntry(parseInt(dbRow.id), data.op, data.type, data.id, dbRow.tx_id, data.data);
+        return new CrudEntry(parseInt(dbRow.id), data.op, data.type, data.id, dbRow.tx_id, data.data, data.old, data.metadata);
     }
-    constructor(clientId, op, table, id, transactionId, opData) {
+    constructor(clientId, op, table, id, transactionId, opData, previousValues, metadata) {
         this.clientId = clientId;
         this.id = id;
         this.op = op;
         this.opData = opData;
         this.table = table;
         this.transactionId = transactionId;
+        this.previousValues = previousValues;
+        this.metadata = metadata;
     }
     /**
      * Converts the change to JSON format.

package/lib/client/sync/bucket/SqliteBucketStorage.d.ts

@@ -2,7 +2,7 @@ import { Mutex } from 'async-mutex';
 import { ILogger } from 'js-logger';
 import { DBAdapter, Transaction } from '../../../db/DBAdapter.js';
 import { BaseObserver } from '../../../utils/BaseObserver.js';
-import { BucketState, BucketStorageAdapter, BucketStorageListener, Checkpoint, SyncLocalDatabaseResult } from './BucketStorageAdapter.js';
+import { BucketOperationProgress, BucketState, BucketStorageAdapter, BucketStorageListener, Checkpoint, SyncLocalDatabaseResult } from './BucketStorageAdapter.js';
 import { CrudBatch } from './CrudBatch.js';
 import { CrudEntry } from './CrudEntry.js';
 import { SyncDataBatch } from './SyncDataBatch.js';
@@ -30,6 +30,7 @@ export declare class SqliteBucketStorage extends BaseObserver<BucketStorageListe
      */
     startSession(): void;
     getBucketStates(): Promise<BucketState[]>;
+    getBucketOperationProgress(): Promise<BucketOperationProgress>;
     saveSyncData(batch: SyncDataBatch): Promise<void>;
     removeBuckets(buckets: string[]): Promise<void>;
     /**

package/lib/client/sync/bucket/SqliteBucketStorage.js

@@ -66,6 +66,10 @@ export class SqliteBucketStorage extends BaseObserver {
         const result = await this.db.getAll("SELECT name as bucket, cast(last_op as TEXT) as op_id FROM ps_buckets WHERE pending_delete = 0 AND name != '$local'");
         return result;
     }
+    async getBucketOperationProgress() {
+        const rows = await this.db.getAll('SELECT name, count_at_last, count_since_last FROM ps_buckets');
+        return Object.fromEntries(rows.map((r) => [r.name, { atLast: r.count_at_last, sinceLast: r.count_since_last }]));
+    }
     async saveSyncData(batch) {
         await this.writeTransaction(async (tx) => {
             let count = 0;
@@ -115,9 +119,9 @@ export class SqliteBucketStorage extends BaseObserver {
             }
             return { ready: false, checkpointValid: false, checkpointFailures: r.checkpointFailures };
         }
-        const buckets = checkpoint.buckets;
+        let buckets = checkpoint.buckets;
         if (priority !== undefined) {
-            buckets.filter((b) => hasMatchingPriority(priority, b));
+            buckets = buckets.filter((b) => hasMatchingPriority(priority, b));
         }
         const bucketNames = buckets.map((b) => b.bucket);
         await this.writeTransaction(async (tx) => {
@@ -161,7 +165,18 @@ export class SqliteBucketStorage extends BaseObserver {
                 'sync_local',
                 arg
             ]);
-            return result == 1;
+            if (result == 1) {
+                if (priority == null) {
+                    const bucketToCount = Object.fromEntries(checkpoint.buckets.map((b) => [b.bucket, b.count]));
+                    // The two parameters could be replaced with one, but: https://github.com/powersync-ja/better-sqlite3/pull/6
+                    const jsonBucketCount = JSON.stringify(bucketToCount);
+                    await tx.execute("UPDATE ps_buckets SET count_since_last = 0, count_at_last = ?->name WHERE name != '$local' AND ?->name IS NOT NULL", [jsonBucketCount, jsonBucketCount]);
+                }
+                return true;
+            }
+            else {
+                return false;
+            }
         });
     }
     async validateChecksums(checkpoint, priority) {

package/lib/client/sync/stream/AbstractRemote.d.ts

@@ -7,6 +7,7 @@ import { StreamingSyncLine, StreamingSyncRequest } from './streaming-sync-types.
 export type BSONImplementation = typeof BSON;
 export type RemoteConnector = {
     fetchCredentials: () => Promise<PowerSyncCredentials | null>;
+    invalidateCredentials?: () => void;
 };
 export declare const DEFAULT_REMOTE_LOGGER: Logger.ILogger;
 export type SyncStreamOptions = {
@@ -74,7 +75,35 @@ export declare abstract class AbstractRemote {
      * which can be called to perform fetch requests
      */
     get fetch(): FetchImplementation;
+    /**
+     * Get credentials currently cached, or fetch new credentials if none are
+     * available.
+     *
+     * These credentials may have expired already.
+     */
     getCredentials(): Promise<PowerSyncCredentials | null>;
+    /**
+     * Fetch a new set of credentials and cache it.
+     *
+     * Until this call succeeds, `getCredentials` will still return the
+     * old credentials.
+     *
+     * This may be called before the current credentials have expired.
+     */
+    prefetchCredentials(): Promise<PowerSyncCredentials | null>;
+    /**
+     * Get credentials for PowerSync.
+     *
+     * This should always fetch a fresh set of credentials - don't use cached
+     * values.
+     */
+    fetchCredentials(): Promise<PowerSyncCredentials | null>;
+    /***
+     * Immediately invalidate credentials.
+     *
+     * This may be called when the current credentials have expired.
+     */
+    invalidateCredentials(): void;
     getUserAgent(): string;
     protected buildRequest(path: string): Promise<{
         url: string;

package/lib/client/sync/stream/AbstractRemote.js

@@ -8,8 +8,6 @@ import { AbortOperation } from '../../../utils/AbortOperation.js';
 import { DataStream } from '../../../utils/DataStream.js';
 const POWERSYNC_TRAILING_SLASH_MATCH = /\/+$/;
 const POWERSYNC_JS_VERSION = PACKAGE.version;
-// Refresh at least 30 sec before it expires
-const REFRESH_CREDENTIALS_SAFETY_PERIOD_MS = 30_000;
 const SYNC_QUEUE_REQUEST_LOW_WATER = 5;
 // Keep alive message is sent every period
 const KEEP_ALIVE_MS = 20_000;
@@ -70,17 +68,52 @@ export class AbstractRemote {
             ? fetchImplementation.getFetch()
             : fetchImplementation;
     }
+    /**
+     * Get credentials currently cached, or fetch new credentials if none are
+     * available.
+     *
+     * These credentials may have expired already.
+     */
     async getCredentials() {
-        const { expiresAt } = this.credentials ?? {};
-        if (expiresAt && expiresAt > new Date(new Date().valueOf() + REFRESH_CREDENTIALS_SAFETY_PERIOD_MS)) {
+        if (this.credentials) {
             return this.credentials;
         }
-        this.credentials = await this.connector.fetchCredentials();
-        if (this.credentials?.endpoint.match(POWERSYNC_TRAILING_SLASH_MATCH)) {
-            throw new Error(`A trailing forward slash "/" was found in the fetchCredentials endpoint: "${this.credentials.endpoint}". Remove the trailing forward slash "/" to fix this error.`);
-        }
+        return this.prefetchCredentials();
+    }
+    /**
+     * Fetch a new set of credentials and cache it.
+     *
+     * Until this call succeeds, `getCredentials` will still return the
+     * old credentials.
+     *
+     * This may be called before the current credentials have expired.
+     */
+    async prefetchCredentials() {
+        this.credentials = await this.fetchCredentials();
         return this.credentials;
     }
+    /**
+     * Get credentials for PowerSync.
+     *
+     * This should always fetch a fresh set of credentials - don't use cached
+     * values.
+     */
+    async fetchCredentials() {
+        const credentials = await this.connector.fetchCredentials();
+        if (credentials?.endpoint.match(POWERSYNC_TRAILING_SLASH_MATCH)) {
+            throw new Error(`A trailing forward slash "/" was found in the fetchCredentials endpoint: "${credentials.endpoint}". Remove the trailing forward slash "/" to fix this error.`);
+        }
+        return credentials;
+    }
+    /***
+     * Immediately invalidate credentials.
+     *
+     * This may be called when the current credentials have expired.
+     */
+    invalidateCredentials() {
+        this.credentials = null;
+        this.connector.invalidateCredentials?.();
+    }
     getUserAgent() {
         return `powersync-js/${POWERSYNC_JS_VERSION}`;
     }
@@ -114,6 +147,9 @@ export class AbstractRemote {
             },
             body: JSON.stringify(data)
         });
+        if (res.status === 401) {
+            this.invalidateCredentials();
+        }
         if (!res.ok) {
             throw new Error(`Received ${res.status} - ${res.statusText} when posting to ${path}: ${await res.text()}}`);
         }
@@ -128,6 +164,9 @@ export class AbstractRemote {
                 ...request.headers
             }
         });
+        if (res.status === 401) {
+            this.invalidateCredentials();
+        }
         if (!res.ok) {
             throw new Error(`Received ${res.status} - ${res.statusText} when getting from ${path}: ${await res.text()}}`);
         }
@@ -145,6 +184,9 @@ export class AbstractRemote {
             this.logger.error(`Caught ex when POST streaming to ${path}`, ex);
             throw ex;
         });
+        if (res.status === 401) {
+            this.invalidateCredentials();
+        }
         if (!res.ok) {
             const text = await res.text();
             this.logger.error(`Could not POST streaming to ${path} - ${res.status} - ${res.statusText}: ${text}`);
@@ -169,10 +211,18 @@ export class AbstractRemote {
         // headers with websockets on web. The browser userAgent is however added
         // automatically as a header.
         const userAgent = this.getUserAgent();
+        let socketCreationError;
         const connector = new RSocketConnector({
             transport: new WebsocketClientTransport({
                 url: this.options.socketUrlTransformer(request.url),
-                wsCreator: (url) => this.createSocket(url)
+                wsCreator: (url) => {
+                    const s = this.createSocket(url);
+                    s.addEventListener('error', (e) => {
+                        socketCreationError = new Error('Failed to create connection to websocket: ', e.target.url ?? '');
+                        this.logger.warn('Socket error', e);
+                    });
+                    return s;
+                }
             }),
             setup: {
                 keepAlive: KEEP_ALIVE_MS,
@@ -197,7 +247,7 @@ export class AbstractRemote {
              * On React native the connection exception can be `undefined` this causes issues
              * with detecting the exception inside async-mutex
              */
-            throw new Error(`Could not connect to PowerSync instance: ${JSON.stringify(ex)}`);
+            throw new Error(`Could not connect to PowerSync instance: ${JSON.stringify(ex ?? socketCreationError)}`);
         }
         const stream = new DataStream({
             logger: this.logger,
@@ -233,6 +283,9 @@ export class AbstractRemote {
             }, syncQueueRequestSize, // The initial N amount
             {
                 onError: (e) => {
+                    if (e.message.includes('Authorization failed') || e.message.includes('PSYNC_S21')) {
+                        this.invalidateCredentials();
+                    }
                     // Don't log closed as an error
                     if (e.message !== 'Closed. ') {
                         this.logger.error(e);

package/lib/client/sync/stream/AbstractStreamingSyncImplementation.d.ts

@@ -139,6 +139,7 @@ export declare abstract class AbstractStreamingSyncImplementation extends BaseOb
     streamingSync(signal?: AbortSignal, options?: PowerSyncConnectionOptions): Promise<void>;
     private collectLocalBucketState;
     protected streamingSyncIteration(signal: AbortSignal, options?: PowerSyncConnectionOptions): Promise<void>;
+    private updateSyncStatusForStartingCheckpoint;
     private applyCheckpoint;
     protected updateSyncStatus(options: SyncStatusOptions): void;
     private delayRetry;

package/lib/client/sync/stream/AbstractStreamingSyncImplementation.js

@@ -270,7 +270,8 @@ The next upload iteration will be delayed.`);
                 connected: false,
                 connecting: false,
                 dataFlow: {
-                    downloading: false
+                    downloading: false,
+                    downloadProgress: null
                 }
             });
         });
@@ -409,6 +410,7 @@ The next upload iteration will be delayed.`);
                         bucketMap = newBuckets;
                         await this.options.adapter.removeBuckets([...bucketsToDelete]);
                         await this.options.adapter.setTargetCheckpoint(targetCheckpoint);
+                        await this.updateSyncStatusForStartingCheckpoint(targetCheckpoint);
                     }
                     else if (isStreamingSyncCheckpointComplete(line)) {
                         const result = await this.applyCheckpoint(targetCheckpoint, signal);
@@ -472,6 +474,7 @@ The next upload iteration will be delayed.`);
                             write_checkpoint: diff.write_checkpoint
                         };
                         targetCheckpoint = newCheckpoint;
+                        await this.updateSyncStatusForStartingCheckpoint(targetCheckpoint);
                         bucketMap = new Map();
                         newBuckets.forEach((checksum, name) => bucketMap.set(name, {
                             name: checksum.bucket,
@@ -486,9 +489,22 @@ The next upload iteration will be delayed.`);
                     }
                     else if (isStreamingSyncData(line)) {
                         const { data } = line;
+                        const previousProgress = this.syncStatus.dataFlowStatus.downloadProgress;
+                        let updatedProgress = null;
+                        if (previousProgress) {
+                            updatedProgress = { ...previousProgress };
+                            const progressForBucket = updatedProgress[data.bucket];
+                            if (progressForBucket) {
+                                updatedProgress[data.bucket] = {
+                                    ...progressForBucket,
+                                    sinceLast: progressForBucket.sinceLast + data.data.length
+                                };
+                            }
+                        }
                         this.updateSyncStatus({
                             dataFlow: {
-                                downloading: true
+                                downloading: true,
+                                downloadProgress: updatedProgress
                             }
                         });
                         await this.options.adapter.saveSyncData({ buckets: [SyncDataBucket.fromRow(data)] });
@@ -498,6 +514,7 @@ The next upload iteration will be delayed.`);
                         if (remaining_seconds == 0) {
                             // Connection would be closed automatically right after this
                             this.logger.debug('Token expiring; reconnect');
+                            this.options.remote.invalidateCredentials();
                             /**
                              * For a rare case where the backend connector does not update the token
                              * (uses the same one), this should have some delay.
@@ -505,6 +522,12 @@ The next upload iteration will be delayed.`);
                             await this.delayRetry();
                             return;
                         }
+                        else if (remaining_seconds < 30) {
+                            this.logger.debug('Token will expire soon; reconnect');
+                            // Pre-emptively refresh the token
+                            this.options.remote.invalidateCredentials();
+                            return;
+                        }
                         this.triggerCrudUpload();
                     }
                     else {
@@ -536,6 +559,27 @@ The next upload iteration will be delayed.`);
             }
         });
     }
+    async updateSyncStatusForStartingCheckpoint(checkpoint) {
+        const localProgress = await this.options.adapter.getBucketOperationProgress();
+        const progress = {};
+        for (const bucket of checkpoint.buckets) {
+            const savedProgress = localProgress[bucket.bucket];
+            progress[bucket.bucket] = {
+                // The fallback priority doesn't matter here, but 3 is the one newer versions of the sync service
+                // will use by default.
+                priority: bucket.priority ?? 3,
+                atLast: savedProgress?.atLast ?? 0,
+                sinceLast: savedProgress?.sinceLast ?? 0,
+                targetCount: bucket.count ?? 0
+            };
+        }
+        this.updateSyncStatus({
+            dataFlow: {
+                downloading: true,
+                downloadProgress: progress
+            }
+        });
+    }
     async applyCheckpoint(checkpoint, abort) {
         let result = await this.options.adapter.syncLocalDatabase(checkpoint);
         const pending = this.pendingCrudUpload;
@@ -565,6 +609,7 @@ The next upload iteration will be delayed.`);
                 lastSyncedAt: new Date(),
                 dataFlow: {
                     downloading: false,
+                    downloadProgress: null,
                     downloadError: undefined
                 }
             });

package/lib/client/sync/stream/streaming-sync-types.d.ts

@@ -79,7 +79,7 @@ export interface StreamingSyncCheckpointDiff {
         last_op_id: OpId;
         updated_buckets: BucketChecksum[];
         removed_buckets: string[];
-        write_checkpoint: string;
+        write_checkpoint?: string;
     };
 }
 export interface StreamingSyncDataJSON {

package/lib/db/crud/SyncProgress.d.ts

@@ -0,0 +1,72 @@
+/** @internal */
+export type InternalProgressInformation = Record<string, {
+    priority: number;
+    atLast: number;
+    sinceLast: number;
+    targetCount: number;
+}>;
+/**
+ * @internal The priority used by the core extension to indicate that a full sync was completed.
+ */
+export declare 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 declare class SyncProgress implements ProgressWithOperations {
+    protected internal: InternalProgressInformation;
+    totalOperations: number;
+    downloadedOperations: number;
+    downloadedFraction: number;
+    constructor(internal: InternalProgressInformation);
+    /**
+     * 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;
+}

package/lib/db/crud/SyncProgress.js

@@ -0,0 +1,60 @@
+/**
+ * @internal The priority used by the core extension to indicate that a full sync was completed.
+ */
+export const FULL_SYNC_PRIORITY = 2147483647;
+/**
+ * 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 {
+    internal;
+    totalOperations;
+    downloadedOperations;
+    downloadedFraction;
+    constructor(internal) {
+        this.internal = internal;
+        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) {
+        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 {
+            totalOperations: total,
+            downloadedOperations: downloaded,
+            downloadedFraction: progress
+        };
+    }
+}