@powersync/common 1.26.0 → 1.27.1

package/lib/client/AbstractPowerSyncDatabase.d.ts

@@ -155,7 +155,7 @@ export declare abstract class AbstractPowerSyncDatabase extends BaseObserver<Pow
     /**
      * Wait for the first sync operation to complete.
      *
-     * @argument request Either an abort signal (after which the promise will complete regardless of
+     * @param request Either an abort signal (after which the promise will complete regardless of
      * whether a full sync was completed) or an object providing an abort signal and a priority target.
      * When a priority target is set, the promise may complete when all buckets with the given (or higher)
      * priorities have been synchronized. This can be earlier than a complete sync.
@@ -222,7 +222,7 @@ export declare abstract class AbstractPowerSyncDatabase extends BaseObserver<Pow
      */
     getUploadQueueStats(includeSize?: boolean): Promise<UploadQueueStats>;
     /**
-     * Get a batch of crud data to upload.
+     * Get a batch of CRUD data to upload.
      *
      * Returns null if there is no data to upload.
      *
@@ -237,6 +237,9 @@ export declare abstract class AbstractPowerSyncDatabase extends BaseObserver<Pow
      * This method does include transaction ids in the result, but does not group
      * data by transaction. One batch may contain data from multiple transactions,
      * and a single transaction may be split over multiple batches.
+     *
+     * @param limit Maximum number of CRUD entries to include in the batch
+     * @returns A batch of CRUD operations to upload, or null if there are none
      */
     getCrudBatch(limit?: number): Promise<CrudBatch | null>;
     /**
@@ -251,37 +254,71 @@ export declare abstract class AbstractPowerSyncDatabase extends BaseObserver<Pow
      *
      * Unlike {@link getCrudBatch}, this only returns data from a single transaction at a time.
      * All data for the transaction is loaded into memory.
+     *
+     * @returns A transaction of CRUD operations to upload, or null if there are none
      */
     getNextCrudTransaction(): Promise<CrudTransaction | null>;
     /**
      * Get an unique client id for this database.
      *
      * The id is not reset when the database is cleared, only when the database is deleted.
+     *
+     * @returns A unique identifier for the database instance
      */
     getClientId(): Promise<string>;
     private handleCrudCheckpoint;
     /**
-     * Execute a write (INSERT/UPDATE/DELETE) query
+     * Execute a SQL write (INSERT/UPDATE/DELETE) query
      * and optionally return results.
+     *
+     * @param sql The SQL query to execute
+     * @param parameters Optional array of parameters to bind to the query
+     * @returns The query result as an object with structured key-value pairs
      */
     execute(sql: string, parameters?: any[]): Promise<QueryResult>;
+    /**
+     * Execute a SQL write (INSERT/UPDATE/DELETE) query directly on the database without any PowerSync processing.
+     * This bypasses certain PowerSync abstractions and is useful for accessing the raw database results.
+     *
+     * @param sql The SQL query to execute
+     * @param parameters Optional array of parameters to bind to the query
+     * @returns The raw query result from the underlying database as a nested array of raw values, where each row is
+     * represented as an array of column values without field names.
+     */
     executeRaw(sql: string, parameters?: any[]): Promise<any[][]>;
     /**
      * Execute a write query (INSERT/UPDATE/DELETE) multiple times with each parameter set
      * and optionally return results.
      * This is faster than executing separately with each parameter set.
+     *
+     * @param sql The SQL query to execute
+     * @param parameters Optional 2D array of parameter sets, where each inner array is a set of parameters for one execution
+     * @returns The query result
      */
     executeBatch(sql: string, parameters?: any[][]): Promise<QueryResult>;
     /**
      *  Execute a read-only query and return results.
+     *
+     * @param sql The SQL query to execute
+     * @param parameters Optional array of parameters to bind to the query
+     * @returns An array of 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.
+     *
+     * @param sql The SQL query to execute
+     * @param parameters Optional array of parameters to bind to the query
+     * @returns The first result if found, or null if no results are returned
      */
     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.
+     *
+     * @param sql The SQL query to execute
+     * @param parameters Optional array of parameters to bind to the query
+     * @returns The first result matching the query
+     * @throws Error if no rows are returned
      */
     get<T>(sql: string, parameters?: any[]): Promise<T>;
     /**
@@ -298,12 +335,22 @@ export declare abstract class AbstractPowerSyncDatabase extends BaseObserver<Pow
      * Open a read-only transaction.
      * Read transactions can run concurrently to a write transaction.
      * Changes from any write transaction are not visible to read transactions started before it.
+     *
+     * @param callback Function to execute within the transaction
+     * @param lockTimeout Time in milliseconds to wait for a lock before throwing an error
+     * @returns The result of the callback
+     * @throws Error if the lock cannot be obtained within the timeout period
      */
     readTransaction<T>(callback: (tx: Transaction) => Promise<T>, lockTimeout?: number): Promise<T>;
     /**
      * Open a read-write transaction.
      * This takes a global lock - only one write transaction can execute against the database at a time.
      * Statements within the transaction must be done on the provided {@link Transaction} interface.
+     *
+     * @param callback Function to execute within the transaction
+     * @param lockTimeout Time in milliseconds to wait for a lock before throwing an error
+     * @returns The result of the callback
+     * @throws Error if the lock cannot be obtained within the timeout period
      */
     writeTransaction<T>(callback: (tx: Transaction) => Promise<T>, lockTimeout?: number): Promise<T>;
     /**
@@ -346,14 +393,34 @@ export declare abstract class AbstractPowerSyncDatabase extends BaseObserver<Pow
      * Source tables are automatically detected using `EXPLAIN QUERY PLAN`.
      *
      * Note that the `onChange` callback member of the handler is required.
+     *
+     * @param sql The SQL query to execute
+     * @param parameters Optional array of parameters to bind to the query
+     * @param handler Callbacks for handling results and errors
+     * @param options Options for configuring watch behavior
      */
     watchWithCallback(sql: string, parameters?: any[], handler?: WatchHandler, options?: SQLWatchOptions): void;
     /**
      * Execute a read query every time the source tables are modified.
      * Use {@link SQLWatchOptions.throttleMs} to specify the minimum interval between queries.
      * Source tables are automatically detected using `EXPLAIN QUERY PLAN`.
+     *
+     * @param sql The SQL query to execute
+     * @param parameters Optional array of parameters to bind to the query
+     * @param options Options for configuring watch behavior
+     * @returns An AsyncIterable that yields QueryResults whenever the data changes
      */
     watchWithAsyncGenerator(sql: string, parameters?: any[], options?: SQLWatchOptions): AsyncIterable<QueryResult>;
+    /**
+     * Resolves the list of tables that are used in a SQL query.
+     * If tables are specified in the options, those are used directly.
+     * Otherwise, analyzes the query using EXPLAIN to determine which tables are accessed.
+     *
+     * @param sql The SQL query to analyze
+     * @param parameters Optional parameters for the SQL query
+     * @param options Optional watch options that may contain explicit table list
+     * @returns Array of table names that the query depends on
+     */
     resolveTables(sql: string, parameters?: any[], options?: SQLWatchOptions): Promise<string[]>;
     /**
      * This version of `onChange` uses {@link AsyncGenerator}, for documentation see {@link onChangeWithAsyncGenerator}.
@@ -392,7 +459,9 @@ export declare abstract class AbstractPowerSyncDatabase extends BaseObserver<Pow
      *
      * Note that the `onChange` callback member of the handler is required.
      *
-     * Returns dispose function to stop watching.
+     * @param handler Callbacks for handling change events and errors
+     * @param options Options for configuring watch behavior
+     * @returns A dispose function to stop watching for changes
      */
     onChangeWithCallback(handler?: WatchOnChangeHandler, options?: SQLWatchOptions): () => void;
     /**
@@ -401,7 +470,10 @@ export declare abstract class AbstractPowerSyncDatabase extends BaseObserver<Pow
      * This is preferred over {@link watchWithAsyncGenerator} when multiple queries need to be performed
      * together when data is changed.
      *
-     * Note, do not declare this as `async *onChange` as it will not work in React Native
+     * Note: do not declare this as `async *onChange` as it will not work in React Native.
+     *
+     * @param options Options for configuring watch behavior
+     * @returns An AsyncIterable that yields change events whenever the specified tables change
      */
     onChangeWithAsyncGenerator(options?: SQLWatchOptions): AsyncIterable<WatchOnChangeEvent>;
     private handleTableChanges;

package/lib/client/AbstractPowerSyncDatabase.js

@@ -7,7 +7,7 @@ import { UploadQueueStats } from '../db/crud/UploadQueueStatus.js';
 import { BaseObserver } from '../utils/BaseObserver.js';
 import { ControlledExecutor } from '../utils/ControlledExecutor.js';
 import { mutexRunExclusive } from '../utils/mutex.js';
-import { throttleTrailing } from '../utils/throttle.js';
+import { throttleTrailing } from '../utils/async.js';
 import { isDBAdapter, isSQLOpenFactory, isSQLOpenOptions } from './SQLOpenFactory.js';
 import { runOnSchemaChange } from './runOnSchemaChange.js';
 import { PSInternalTable } from './sync/bucket/BucketStorageAdapter.js';
@@ -133,7 +133,7 @@ export class AbstractPowerSyncDatabase extends BaseObserver {
     /**
      * Wait for the first sync operation to complete.
      *
-     * @argument request Either an abort signal (after which the promise will complete regardless of
+     * @param request Either an abort signal (after which the promise will complete regardless of
      * whether a full sync was completed) or an object providing an abort signal and a priority target.
      * When a priority target is set, the promise may complete when all buckets with the given (or higher)
      * priorities have been synchronized. This can be earlier than a complete sync.
@@ -363,7 +363,7 @@ export class AbstractPowerSyncDatabase extends BaseObserver {
         });
     }
     /**
-     * Get a batch of crud data to upload.
+     * Get a batch of CRUD data to upload.
      *
      * Returns null if there is no data to upload.
      *
@@ -378,6 +378,9 @@ export class AbstractPowerSyncDatabase extends BaseObserver {
      * This method does include transaction ids in the result, but does not group
      * data by transaction. One batch may contain data from multiple transactions,
      * and a single transaction may be split over multiple batches.
+     *
+     * @param limit Maximum number of CRUD entries to include in the batch
+     * @returns A batch of CRUD operations to upload, or null if there are none
      */
     async getCrudBatch(limit = DEFAULT_CRUD_BATCH_LIMIT) {
         const result = await this.getAll(`SELECT id, tx_id, data FROM ${PSInternalTable.CRUD} ORDER BY id ASC LIMIT ?`, [limit + 1]);
@@ -405,6 +408,8 @@ export class AbstractPowerSyncDatabase extends BaseObserver {
      *
      * Unlike {@link getCrudBatch}, this only returns data from a single transaction at a time.
      * All data for the transaction is loaded into memory.
+     *
+     * @returns A transaction of CRUD operations to upload, or null if there are none
      */
     async getNextCrudTransaction() {
         return await this.readTransaction(async (tx) => {
@@ -429,6 +434,8 @@ export class AbstractPowerSyncDatabase extends BaseObserver {
      * Get an unique client id for this database.
      *
      * The id is not reset when the database is cleared, only when the database is deleted.
+     *
+     * @returns A unique identifier for the database instance
      */
     async getClientId() {
         return this.bucketStorageAdapter.getClientId();
@@ -452,13 +459,26 @@ export class AbstractPowerSyncDatabase extends BaseObserver {
         });
     }
     /**
-     * Execute a write (INSERT/UPDATE/DELETE) query
+     * Execute a SQL write (INSERT/UPDATE/DELETE) query
      * and optionally return results.
+     *
+     * @param sql The SQL query to execute
+     * @param parameters Optional array of parameters to bind to the query
+     * @returns The query result as an object with structured key-value pairs
      */
     async execute(sql, parameters) {
         await this.waitForReady();
         return this.database.execute(sql, parameters);
     }
+    /**
+     * Execute a SQL write (INSERT/UPDATE/DELETE) query directly on the database without any PowerSync processing.
+     * This bypasses certain PowerSync abstractions and is useful for accessing the raw database results.
+     *
+     * @param sql The SQL query to execute
+     * @param parameters Optional array of parameters to bind to the query
+     * @returns The raw query result from the underlying database as a nested array of raw values, where each row is
+     * represented as an array of column values without field names.
+     */
     async executeRaw(sql, parameters) {
         await this.waitForReady();
         return this.database.executeRaw(sql, parameters);
@@ -467,6 +487,10 @@ export class AbstractPowerSyncDatabase extends BaseObserver {
      * Execute a write query (INSERT/UPDATE/DELETE) multiple times with each parameter set
      * and optionally return results.
      * This is faster than executing separately with each parameter set.
+     *
+     * @param sql The SQL query to execute
+     * @param parameters Optional 2D array of parameter sets, where each inner array is a set of parameters for one execution
+     * @returns The query result
      */
     async executeBatch(sql, parameters) {
         await this.waitForReady();
@@ -474,6 +498,10 @@ export class AbstractPowerSyncDatabase extends BaseObserver {
     }
     /**
      *  Execute a read-only query and return results.
+     *
+     * @param sql The SQL query to execute
+     * @param parameters Optional array of parameters to bind to the query
+     * @returns An array of results
      */
     async getAll(sql, parameters) {
         await this.waitForReady();
@@ -481,6 +509,10 @@ export class AbstractPowerSyncDatabase extends BaseObserver {
     }
     /**
      * Execute a read-only query and return the first result, or null if the ResultSet is empty.
+     *
+     * @param sql The SQL query to execute
+     * @param parameters Optional array of parameters to bind to the query
+     * @returns The first result if found, or null if no results are returned
      */
     async getOptional(sql, parameters) {
         await this.waitForReady();
@@ -488,6 +520,11 @@ export class AbstractPowerSyncDatabase extends BaseObserver {
     }
     /**
      * Execute a read-only query and return the first result, error if the ResultSet is empty.
+     *
+     * @param sql The SQL query to execute
+     * @param parameters Optional array of parameters to bind to the query
+     * @returns The first result matching the query
+     * @throws Error if no rows are returned
      */
     async get(sql, parameters) {
         await this.waitForReady();
@@ -516,6 +553,11 @@ export class AbstractPowerSyncDatabase extends BaseObserver {
      * Open a read-only transaction.
      * Read transactions can run concurrently to a write transaction.
      * Changes from any write transaction are not visible to read transactions started before it.
+     *
+     * @param callback Function to execute within the transaction
+     * @param lockTimeout Time in milliseconds to wait for a lock before throwing an error
+     * @returns The result of the callback
+     * @throws Error if the lock cannot be obtained within the timeout period
      */
     async readTransaction(callback, lockTimeout = DEFAULT_LOCK_TIMEOUT_MS) {
         await this.waitForReady();
@@ -529,6 +571,11 @@ export class AbstractPowerSyncDatabase extends BaseObserver {
      * Open a read-write transaction.
      * This takes a global lock - only one write transaction can execute against the database at a time.
      * Statements within the transaction must be done on the provided {@link Transaction} interface.
+     *
+     * @param callback Function to execute within the transaction
+     * @param lockTimeout Time in milliseconds to wait for a lock before throwing an error
+     * @returns The result of the callback
+     * @throws Error if the lock cannot be obtained within the timeout period
      */
     async writeTransaction(callback, lockTimeout = DEFAULT_LOCK_TIMEOUT_MS) {
         await this.waitForReady();
@@ -553,6 +600,11 @@ export class AbstractPowerSyncDatabase extends BaseObserver {
      * Source tables are automatically detected using `EXPLAIN QUERY PLAN`.
      *
      * Note that the `onChange` callback member of the handler is required.
+     *
+     * @param sql The SQL query to execute
+     * @param parameters Optional array of parameters to bind to the query
+     * @param handler Callbacks for handling results and errors
+     * @param options Options for configuring watch behavior
      */
     watchWithCallback(sql, parameters, handler, options) {
         const { onResult, onError = (e) => this.options.logger?.error(e) } = handler ?? {};
@@ -593,6 +645,11 @@ export class AbstractPowerSyncDatabase extends BaseObserver {
      * Execute a read query every time the source tables are modified.
      * Use {@link SQLWatchOptions.throttleMs} to specify the minimum interval between queries.
      * Source tables are automatically detected using `EXPLAIN QUERY PLAN`.
+     *
+     * @param sql The SQL query to execute
+     * @param parameters Optional array of parameters to bind to the query
+     * @param options Options for configuring watch behavior
+     * @returns An AsyncIterable that yields QueryResults whenever the data changes
      */
     watchWithAsyncGenerator(sql, parameters, options) {
         return new EventIterator((eventOptions) => {
@@ -610,6 +667,16 @@ export class AbstractPowerSyncDatabase extends BaseObserver {
             });
         });
     }
+    /**
+     * Resolves the list of tables that are used in a SQL query.
+     * If tables are specified in the options, those are used directly.
+     * Otherwise, analyzes the query using EXPLAIN to determine which tables are accessed.
+     *
+     * @param sql The SQL query to analyze
+     * @param parameters Optional parameters for the SQL query
+     * @param options Optional watch options that may contain explicit table list
+     * @returns Array of table names that the query depends on
+     */
     async resolveTables(sql, parameters, options) {
         const resolvedTables = options?.tables ? [...options.tables] : [];
         if (!options?.tables) {
@@ -641,7 +708,9 @@ export class AbstractPowerSyncDatabase extends BaseObserver {
      *
      * Note that the `onChange` callback member of the handler is required.
      *
-     * Returns dispose function to stop watching.
+     * @param handler Callbacks for handling change events and errors
+     * @param options Options for configuring watch behavior
+     * @returns A dispose function to stop watching for changes
      */
     onChangeWithCallback(handler, options) {
         const { onChange, onError = (e) => this.options.logger?.error(e) } = handler ?? {};
@@ -683,7 +752,10 @@ export class AbstractPowerSyncDatabase extends BaseObserver {
      * This is preferred over {@link watchWithAsyncGenerator} when multiple queries need to be performed
      * together when data is changed.
      *
-     * Note, do not declare this as `async *onChange` as it will not work in React Native
+     * Note: do not declare this as `async *onChange` as it will not work in React Native.
+     *
+     * @param options Options for configuring watch behavior
+     * @returns An AsyncIterable that yields change events whenever the specified tables change
      */
     onChangeWithAsyncGenerator(options) {
         const resolvedOptions = options ?? {};

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

@@ -116,6 +116,7 @@ export declare abstract class AbstractStreamingSyncImplementation extends BaseOb
     protected abortController: AbortController | null;
     protected crudUpdateListener?: () => void;
     protected streamingSyncPromise?: Promise<void>;
+    private pendingCrudUpload?;
     syncStatus: SyncStatus;
     triggerCrudUpload: () => void;
     constructor(options: AbstractStreamingSyncImplementationOptions);
@@ -137,9 +138,8 @@ export declare abstract class AbstractStreamingSyncImplementation extends BaseOb
      */
     streamingSync(signal?: AbortSignal, options?: PowerSyncConnectionOptions): Promise<void>;
     private collectLocalBucketState;
-    protected streamingSyncIteration(signal: AbortSignal, options?: PowerSyncConnectionOptions): Promise<{
-        retry?: boolean;
-    }>;
+    protected streamingSyncIteration(signal: AbortSignal, options?: PowerSyncConnectionOptions): Promise<void>;
+    private applyCheckpoint;
     protected updateSyncStatus(options: SyncStatusOptions): void;
     private delayRetry;
 }

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

@@ -2,7 +2,7 @@ import Logger from 'js-logger';
 import { SyncStatus } from '../../../db/crud/SyncStatus.js';
 import { AbortOperation } from '../../../utils/AbortOperation.js';
 import { BaseObserver } from '../../../utils/BaseObserver.js';
-import { throttleLeadingTrailing } from '../../../utils/throttle.js';
+import { onAbortPromise, throttleLeadingTrailing } from '../../../utils/async.js';
 import { SyncDataBucket } from '../bucket/SyncDataBucket.js';
 import { FetchStrategy } from './AbstractRemote.js';
 import { isStreamingKeepalive, isStreamingSyncCheckpoint, isStreamingSyncCheckpointComplete, isStreamingSyncCheckpointDiff, isStreamingSyncCheckpointPartiallyComplete, isStreamingSyncData } from './streaming-sync-types.js';
@@ -39,6 +39,7 @@ export class AbstractStreamingSyncImplementation extends BaseObserver {
     abortController;
     crudUpdateListener;
     streamingSyncPromise;
+    pendingCrudUpload;
     syncStatus;
     triggerCrudUpload;
     constructor(options) {
@@ -55,10 +56,15 @@ export class AbstractStreamingSyncImplementation extends BaseObserver {
         });
         this.abortController = null;
         this.triggerCrudUpload = throttleLeadingTrailing(() => {
-            if (!this.syncStatus.connected || this.syncStatus.dataFlowStatus.uploading) {
+            if (!this.syncStatus.connected || this.pendingCrudUpload != null) {
                 return;
             }
-            this._uploadAllCrud();
+            this.pendingCrudUpload = new Promise((resolve) => {
+                this._uploadAllCrud().finally(() => {
+                    this.pendingCrudUpload = undefined;
+                    resolve();
+                });
+            });
         }, this.options.crudUploadThrottleMs);
     }
     async waitForReady() { }
@@ -148,6 +154,11 @@ The next upload iteration will be delayed.`);
                             }
                             checkedCrudItem = nextCrudItem;
                             await this.options.uploadCrud();
+                            this.updateSyncStatus({
+                                dataFlow: {
+                                    uploadError: undefined
+                                }
+                            });
                         }
                         else {
                             // Uploading is completed
@@ -159,7 +170,8 @@ The next upload iteration will be delayed.`);
                         checkedCrudItem = undefined;
                         this.updateSyncStatus({
                             dataFlow: {
-                                uploading: false
+                                uploading: false,
+                                uploadError: ex
                             }
                         });
                         await this.delayRetry();
@@ -274,16 +286,8 @@ The next upload iteration will be delayed.`);
                 if (signal?.aborted) {
                     break;
                 }
-                const { retry } = await this.streamingSyncIteration(nestedAbortController.signal, options);
-                if (!retry) {
-                    /**
-                     * A sync error ocurred that we cannot recover from here.
-                     * This loop must terminate.
-                     * The nestedAbortController will close any open network requests and streams below.
-                     */
-                    break;
-                }
-                // Continue immediately
+                await this.streamingSyncIteration(nestedAbortController.signal, options);
+                // Continue immediately, streamingSyncIteration will wait before completing if necessary.
             }
             catch (ex) {
                 /**
@@ -300,6 +304,11 @@ The next upload iteration will be delayed.`);
                 else {
                     this.logger.error(ex);
                 }
+                this.updateSyncStatus({
+                    dataFlow: {
+                        downloadError: ex
+                    }
+                });
                 // On error, wait a little before retrying
                 await this.delayRetry();
             }
@@ -330,7 +339,7 @@ The next upload iteration will be delayed.`);
         return [req, localDescriptions];
     }
     async streamingSyncIteration(signal, options) {
-        return await this.obtainLock({
+        await this.obtainLock({
             type: LockType.SYNC,
             signal,
             callback: async () => {
@@ -373,7 +382,7 @@ The next upload iteration will be delayed.`);
                     const line = await stream.read();
                     if (!line) {
                         // The stream has closed while waiting
-                        return { retry: true };
+                        return;
                     }
                     // A connection is active and messages are being received
                     if (!this.syncStatus.connected) {
@@ -402,29 +411,12 @@ The next upload iteration will be delayed.`);
                         await this.options.adapter.setTargetCheckpoint(targetCheckpoint);
                     }
                     else if (isStreamingSyncCheckpointComplete(line)) {
-                        this.logger.debug('Checkpoint complete', targetCheckpoint);
-                        const result = await this.options.adapter.syncLocalDatabase(targetCheckpoint);
-                        if (!result.checkpointValid) {
-                            // This means checksums failed. Start again with a new checkpoint.
-                            // TODO: better back-off
-                            await new Promise((resolve) => setTimeout(resolve, 50));
-                            return { retry: true };
+                        const result = await this.applyCheckpoint(targetCheckpoint, signal);
+                        if (result.endIteration) {
+                            return;
                         }
-                        else if (!result.ready) {
-                            // Checksums valid, but need more data for a consistent checkpoint.
-                            // Continue waiting.
-                            // landing here the whole time
-                        }
-                        else {
+                        else if (result.applied) {
                             appliedCheckpoint = targetCheckpoint;
-                            this.logger.debug('validated checkpoint', appliedCheckpoint);
-                            this.updateSyncStatus({
-                                connected: true,
-                                lastSyncedAt: new Date(),
-                                dataFlow: {
-                                    downloading: false
-                                }
-                            });
                         }
                         validatedCheckpoint = targetCheckpoint;
                     }
@@ -436,10 +428,11 @@ The next upload iteration will be delayed.`);
                             // This means checksums failed. Start again with a new checkpoint.
                             // TODO: better back-off
                             await new Promise((resolve) => setTimeout(resolve, 50));
-                            return { retry: true };
+                            return;
                         }
                         else if (!result.ready) {
-                            // Need more data for a consistent partial sync within a priority - continue waiting.
+                            // If we have pending uploads, we can't complete new checkpoints outside of priority 0.
+                            // We'll resolve this for a complete checkpoint.
                         }
                         else {
                             // We'll keep on downloading, but can report that this priority is synced now.
@@ -510,7 +503,7 @@ The next upload iteration will be delayed.`);
                              * (uses the same one), this should have some delay.
                              */
                             await this.delayRetry();
-                            return { retry: true };
+                            return;
                         }
                         this.triggerCrudUpload();
                     }
@@ -520,41 +513,68 @@ The next upload iteration will be delayed.`);
                             this.updateSyncStatus({
                                 connected: true,
                                 lastSyncedAt: new Date(),
-                                priorityStatusEntries: []
+                                priorityStatusEntries: [],
+                                dataFlow: {
+                                    downloadError: undefined
+                                }
                             });
                         }
                         else if (validatedCheckpoint === targetCheckpoint) {
-                            const result = await this.options.adapter.syncLocalDatabase(targetCheckpoint);
-                            if (!result.checkpointValid) {
-                                // This means checksums failed. Start again with a new checkpoint.
-                                // TODO: better back-off
-                                await new Promise((resolve) => setTimeout(resolve, 50));
-                                return { retry: false };
+                            const result = await this.applyCheckpoint(targetCheckpoint, signal);
+                            if (result.endIteration) {
+                                return;
                             }
-                            else if (!result.ready) {
-                                // Checksums valid, but need more data for a consistent checkpoint.
-                                // Continue waiting.
-                            }
-                            else {
+                            else if (result.applied) {
                                 appliedCheckpoint = targetCheckpoint;
-                                this.updateSyncStatus({
-                                    connected: true,
-                                    lastSyncedAt: new Date(),
-                                    priorityStatusEntries: [],
-                                    dataFlow: {
-                                        downloading: false
-                                    }
-                                });
                             }
                         }
                     }
                 }
                 this.logger.debug('Stream input empty');
                 // Connection closed. Likely due to auth issue.
-                return { retry: true };
+                return;
             }
         });
     }
+    async applyCheckpoint(checkpoint, abort) {
+        let result = await this.options.adapter.syncLocalDatabase(checkpoint);
+        const pending = this.pendingCrudUpload;
+        if (!result.checkpointValid) {
+            this.logger.debug('Checksum mismatch in checkpoint, will reconnect');
+            // This means checksums failed. Start again with a new checkpoint.
+            // TODO: better back-off
+            await new Promise((resolve) => setTimeout(resolve, 50));
+            return { applied: false, endIteration: true };
+        }
+        else if (!result.ready && pending != null) {
+            // We have pending entries in the local upload queue or are waiting to confirm a write
+            // checkpoint, which prevented this checkpoint from applying. Wait for that to complete and
+            // try again.
+            this.logger.debug('Could not apply checkpoint due to local data. Waiting for in-progress upload before retrying.');
+            await Promise.race([pending, onAbortPromise(abort)]);
+            if (abort.aborted) {
+                return { applied: false, endIteration: true };
+            }
+            // Try again now that uploads have completed.
+            result = await this.options.adapter.syncLocalDatabase(checkpoint);
+        }
+        if (result.checkpointValid && result.ready) {
+            this.logger.debug('validated checkpoint', checkpoint);
+            this.updateSyncStatus({
+                connected: true,
+                lastSyncedAt: new Date(),
+                dataFlow: {
+                    downloading: false,
+                    downloadError: undefined
+                }
+            });
+            return { applied: true, endIteration: false };
+        }
+        else {
+            this.logger.debug('Could not apply checkpoint. Waiting for next sync complete line.');
+            return { applied: false, endIteration: false };
+        }
+    }
     updateSyncStatus(options) {
         const updatedStatus = new SyncStatus({
             connected: options.connected ?? this.syncStatus.connected,