@powersync/common 1.24.0 → 1.26.0

package/lib/client/AbstractPowerSyncDatabase.d.ts

@@ -10,7 +10,7 @@ import { PowerSyncBackendConnector } from './connection/PowerSyncBackendConnecto
 import { BucketStorageAdapter } from './sync/bucket/BucketStorageAdapter.js';
 import { CrudBatch } from './sync/bucket/CrudBatch.js';
 import { CrudTransaction } from './sync/bucket/CrudTransaction.js';
-import { type AdditionalConnectionOptions, type PowerSyncConnectionOptions, StreamingSyncImplementation, StreamingSyncImplementationListener, type RequiredAdditionalConnectionOptions } from './sync/stream/AbstractStreamingSyncImplementation.js';
+import { StreamingSyncImplementation, StreamingSyncImplementationListener, type AdditionalConnectionOptions, type PowerSyncConnectionOptions, type RequiredAdditionalConnectionOptions } from './sync/stream/AbstractStreamingSyncImplementation.js';
 export interface DisconnectAndClearOptions {
     /** When set to false, data in local-only tables is preserved. */
     clearLocal?: boolean;
@@ -153,9 +153,18 @@ export declare abstract class AbstractPowerSyncDatabase extends BaseObserver<Pow
      */
     waitForReady(): Promise<void>;
     /**
+     * Wait for the first sync operation to complete.
+     *
+     * @argument 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.
      * @returns A promise which will resolve once the first full sync has completed.
      */
-    waitForFirstSync(signal?: AbortSignal): Promise<void>;
+    waitForFirstSync(request?: AbortSignal | {
+        signal?: AbortSignal;
+        priority?: number;
+    }): Promise<void>;
     /**
      * Allows for extended implementations to execute custom initialization
      * logic as part of the total init process
@@ -256,6 +265,7 @@ export declare abstract class AbstractPowerSyncDatabase extends BaseObserver<Pow
      * and optionally return results.
      */
     execute(sql: string, parameters?: any[]): Promise<QueryResult>;
+    executeRaw(sql: string, parameters?: any[]): Promise<any[][]>;
     /**
      * Execute a write query (INSERT/UPDATE/DELETE) multiple times with each parameter set
      * and optionally return results.

package/lib/client/AbstractPowerSyncDatabase.js

@@ -9,12 +9,12 @@ import { ControlledExecutor } from '../utils/ControlledExecutor.js';
 import { mutexRunExclusive } from '../utils/mutex.js';
 import { throttleTrailing } from '../utils/throttle.js';
 import { isDBAdapter, isSQLOpenFactory, isSQLOpenOptions } from './SQLOpenFactory.js';
+import { runOnSchemaChange } from './runOnSchemaChange.js';
 import { PSInternalTable } from './sync/bucket/BucketStorageAdapter.js';
 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 { runOnSchemaChange } from './runOnSchemaChange.js';
 const POWERSYNC_TABLE_MATCH = /(^ps_data__|^ps_data_local__)/;
 const DEFAULT_DISCONNECT_CLEAR_OPTIONS = {
     clearLocal: true
@@ -42,6 +42,10 @@ 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;
     /**
@@ -127,16 +131,27 @@ export class AbstractPowerSyncDatabase extends BaseObserver {
         await this._isReadyPromise;
     }
     /**
+     * Wait for the first sync operation to complete.
+     *
+     * @argument 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.
      * @returns A promise which will resolve once the first full sync has completed.
      */
-    async waitForFirstSync(signal) {
-        if (this.currentStatus.hasSynced) {
+    async waitForFirstSync(request) {
+        const signal = request instanceof AbortSignal ? request : request?.signal;
+        const priority = request && 'priority' in request ? request.priority : undefined;
+        const statusMatches = priority === undefined
+            ? (status) => status.hasSynced
+            : (status) => status.statusForPriority(priority).hasSynced;
+        if (statusMatches(this.currentStatus)) {
             return;
         }
         return new Promise((resolve) => {
             const dispose = this.registerListener({
                 statusChanged: (status) => {
-                    if (status.hasSynced) {
+                    if (statusMatches(status)) {
                         dispose();
                         resolve();
                     }
@@ -177,19 +192,36 @@ export class AbstractPowerSyncDatabase extends BaseObserver {
                 .map((n) => parseInt(n));
         }
         catch (e) {
-            throw new Error(`Unsupported powersync extension version. Need >=0.2.0 <1.0.0, got: ${this.sdkVersion}. Details: ${e.message}`);
+            throw new Error(`Unsupported powersync extension version. Need >=0.3.11 <1.0.0, got: ${this.sdkVersion}. Details: ${e.message}`);
         }
-        // Validate >=0.2.0 <1.0.0
-        if (versionInts[0] != 0 || versionInts[1] < 2 || versionInts[2] < 0) {
-            throw new Error(`Unsupported powersync extension version. Need >=0.2.0 <1.0.0, got: ${this.sdkVersion}`);
+        // Validate >=0.3.11 <1.0.0
+        if (versionInts[0] != 0 || versionInts[1] < 3 || (versionInts[1] == 3 && versionInts[2] < 11)) {
+            throw new Error(`Unsupported powersync extension version. Need >=0.3.11 <1.0.0, got: ${this.sdkVersion}`);
         }
     }
     async updateHasSynced() {
-        const result = await this.database.get('SELECT powersync_last_synced_at() as synced_at');
-        const hasSynced = result.synced_at != null;
-        const syncedAt = result.synced_at != null ? new Date(result.synced_at + 'Z') : undefined;
-        if (hasSynced != this.currentStatus.hasSynced) {
-            this.currentStatus = new SyncStatus({ ...this.currentStatus.toJSON(), hasSynced, lastSyncedAt: syncedAt });
+        const result = await this.database.getAll('SELECT priority, last_synced_at FROM ps_sync_state ORDER BY priority DESC');
+        let lastCompleteSync;
+        const priorityStatusEntries = [];
+        for (const { priority, last_synced_at } of result) {
+            const parsedDate = new Date(last_synced_at + 'Z');
+            if (priority == FULL_SYNC_PRIORITY) {
+                // This lowest-possible priority represents a complete sync.
+                lastCompleteSync = parsedDate;
+            }
+            else {
+                priorityStatusEntries.push({ priority, hasSynced: true, lastSyncedAt: parsedDate });
+            }
+        }
+        const hasSynced = lastCompleteSync != null;
+        const updatedStatus = new SyncStatus({
+            ...this.currentStatus.toJSON(),
+            hasSynced,
+            priorityStatusEntries,
+            lastSyncedAt: lastCompleteSync
+        });
+        if (!updatedStatus.isEqual(this.currentStatus)) {
+            this.currentStatus = updatedStatus;
             this.iterateListeners((l) => l.statusChanged?.(this.currentStatus));
         }
     }
@@ -245,7 +277,7 @@ export class AbstractPowerSyncDatabase extends BaseObserver {
         const { retryDelayMs, crudUploadThrottleMs } = this.resolvedConnectionOptions(options);
         this.syncStreamImplementation = this.generateSyncStreamImplementation(connector, {
             retryDelayMs,
-            crudUploadThrottleMs,
+            crudUploadThrottleMs
         });
         this.syncStatusListenerDisposer = this.syncStreamImplementation.registerListener({
             statusChanged: (status) => {
@@ -302,12 +334,15 @@ export class AbstractPowerSyncDatabase extends BaseObserver {
      */
     async close(options = DEFAULT_POWERSYNC_CLOSE_OPTIONS) {
         await this.waitForReady();
+        if (this.closed) {
+            return;
+        }
         const { disconnect } = options;
         if (disconnect) {
             await this.disconnect();
         }
         await this.syncStreamImplementation?.dispose();
-        this.database.close();
+        await this.database.close();
         this.closed = true;
     }
     /**
@@ -424,6 +459,10 @@ export class AbstractPowerSyncDatabase extends BaseObserver {
         await this.waitForReady();
         return this.database.execute(sql, parameters);
     }
+    async executeRaw(sql, parameters) {
+        await this.waitForReady();
+        return this.database.executeRaw(sql, parameters);
+    }
     /**
      * Execute a write query (INSERT/UPDATE/DELETE) multiple times with each parameter set
      * and optionally return results.

package/lib/client/SQLOpenFactory.d.ts

@@ -6,6 +6,9 @@ export interface SQLOpenOptions {
     dbFilename: string;
     /**
      * Directory where the database file is located.
+     *
+     * When set, the directory must exist when the database is opened, it will
+     * not be created automatically.
      */
     dbLocation?: string;
     /**

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

@@ -2,6 +2,10 @@ import { BaseListener, BaseObserver, Disposable } from '../../../utils/BaseObser
 import { CrudBatch } from './CrudBatch.js';
 import { CrudEntry, OpId } from './CrudEntry.js';
 import { SyncDataBatch } from './SyncDataBatch.js';
+export interface BucketDescription {
+    name: string;
+    priority: number;
+}
 export interface Checkpoint {
     last_op_id: OpId;
     buckets: BucketChecksum[];
@@ -25,6 +29,7 @@ export interface SyncLocalDatabaseResult {
 }
 export interface BucketChecksum {
     bucket: string;
+    priority?: number;
     /**
      * 32-bit unsigned hash.
      */
@@ -51,7 +56,7 @@ export interface BucketStorageAdapter extends BaseObserver<BucketStorageListener
     setTargetCheckpoint(checkpoint: Checkpoint): Promise<void>;
     startSession(): void;
     getBucketStates(): Promise<BucketState[]>;
-    syncLocalDatabase(checkpoint: Checkpoint): Promise<{
+    syncLocalDatabase(checkpoint: Checkpoint, priority?: number): Promise<{
         checkpointValid: boolean;
         ready: boolean;
         failures?: any[];

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

@@ -37,14 +37,14 @@ export declare class SqliteBucketStorage extends BaseObserver<BucketStorageListe
      */
     private deleteBucket;
     hasCompletedSync(): Promise<boolean>;
-    syncLocalDatabase(checkpoint: Checkpoint): Promise<SyncLocalDatabaseResult>;
+    syncLocalDatabase(checkpoint: Checkpoint, priority?: number): Promise<SyncLocalDatabaseResult>;
     /**
      * Atomically update the local state to the current checkpoint.
      *
      * This includes creating new tables, dropping old tables, and copying data over from the oplog.
      */
     private updateObjectsFromBuckets;
-    validateChecksums(checkpoint: Checkpoint): Promise<SyncLocalDatabaseResult>;
+    validateChecksums(checkpoint: Checkpoint, priority: number | undefined): Promise<SyncLocalDatabaseResult>;
     /**
      * Force a compact, for tests.
      */

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

@@ -106,8 +106,8 @@ export class SqliteBucketStorage extends BaseObserver {
         }
         return completed;
     }
-    async syncLocalDatabase(checkpoint) {
-        const r = await this.validateChecksums(checkpoint);
+    async syncLocalDatabase(checkpoint, priority) {
+        const r = await this.validateChecksums(checkpoint, priority);
         if (!r.checkpointValid) {
             this.logger.error('Checksums failed for', r.checkpointFailures);
             for (const b of r.checkpointFailures ?? []) {
@@ -115,17 +115,21 @@ export class SqliteBucketStorage extends BaseObserver {
             }
             return { ready: false, checkpointValid: false, checkpointFailures: r.checkpointFailures };
         }
-        const bucketNames = checkpoint.buckets.map((b) => b.bucket);
+        const buckets = checkpoint.buckets;
+        if (priority !== undefined) {
+            buckets.filter((b) => hasMatchingPriority(priority, b));
+        }
+        const bucketNames = buckets.map((b) => b.bucket);
         await this.writeTransaction(async (tx) => {
             await tx.execute(`UPDATE ps_buckets SET last_op = ? WHERE name IN (SELECT json_each.value FROM json_each(?))`, [
                 checkpoint.last_op_id,
                 JSON.stringify(bucketNames)
             ]);
-            if (checkpoint.write_checkpoint) {
+            if (priority == null && checkpoint.write_checkpoint) {
                 await tx.execute("UPDATE ps_buckets SET last_op = ? WHERE name = '$local'", [checkpoint.write_checkpoint]);
             }
         });
-        const valid = await this.updateObjectsFromBuckets(checkpoint);
+        const valid = await this.updateObjectsFromBuckets(checkpoint, priority);
         if (!valid) {
             this.logger.debug('Not at a consistent checkpoint - cannot update local db');
             return { ready: false, checkpointValid: true };
@@ -141,19 +145,36 @@ export class SqliteBucketStorage extends BaseObserver {
      *
      * This includes creating new tables, dropping old tables, and copying data over from the oplog.
      */
-    async updateObjectsFromBuckets(checkpoint) {
+    async updateObjectsFromBuckets(checkpoint, priority) {
+        let arg = '';
+        if (priority !== undefined) {
+            const affectedBuckets = [];
+            for (const desc of checkpoint.buckets) {
+                if (hasMatchingPriority(priority, desc)) {
+                    affectedBuckets.push(desc.bucket);
+                }
+            }
+            arg = JSON.stringify({ priority, buckets: affectedBuckets });
+        }
         return this.writeTransaction(async (tx) => {
             const { insertId: result } = await tx.execute('INSERT INTO powersync_operations(op, data) VALUES(?, ?)', [
                 'sync_local',
-                ''
+                arg
             ]);
             return result == 1;
         });
     }
-    async validateChecksums(checkpoint) {
-        const rs = await this.db.execute('SELECT powersync_validate_checkpoint(?) as result', [JSON.stringify(checkpoint)]);
+    async validateChecksums(checkpoint, priority) {
+        if (priority !== undefined) {
+            // Only validate the buckets within the priority we care about
+            const newBuckets = checkpoint.buckets.filter((cs) => hasMatchingPriority(priority, cs));
+            checkpoint = { ...checkpoint, buckets: newBuckets };
+        }
+        const rs = await this.db.execute('SELECT powersync_validate_checkpoint(?) as result', [
+            JSON.stringify({ ...checkpoint })
+        ]);
         const resultItem = rs.rows?.item(0);
-        this.logger.debug('validateChecksums result item', resultItem);
+        this.logger.debug('validateChecksums priority, checkpoint, result item', priority, checkpoint, resultItem);
         if (!resultItem) {
             return {
                 checkpointValid: false,
@@ -304,3 +325,6 @@ export class SqliteBucketStorage extends BaseObserver {
         // No-op for now
     }
 }
+function hasMatchingPriority(priority, bucket) {
+    return bucket.priority != null && bucket.priority <= priority;
+}

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

@@ -3,10 +3,11 @@ import ndjsonStream from 'can-ndjson-stream';
 import Logger from 'js-logger';
 import { RSocketConnector } from 'rsocket-core';
 import { WebsocketClientTransport } from 'rsocket-websocket-client';
+import PACKAGE from '../../../../package.json' with { type: 'json' };
 import { AbortOperation } from '../../../utils/AbortOperation.js';
 import { DataStream } from '../../../utils/DataStream.js';
-import { version as POWERSYNC_JS_VERSION } from '../../../../package.json';
 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;

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

@@ -99,6 +99,7 @@ export interface StreamingSyncImplementation extends BaseObserver<StreamingSyncI
     triggerCrudUpload: () => void;
     waitForReady(): Promise<void>;
     waitForStatus(status: SyncStatusOptions): Promise<void>;
+    waitUntilStatusMatches(predicate: (status: SyncStatus) => boolean): Promise<void>;
 }
 export declare const DEFAULT_CRUD_UPLOAD_THROTTLE_MS = 1000;
 export declare const DEFAULT_RETRY_DELAY_MS = 5000;
@@ -120,6 +121,7 @@ export declare abstract class AbstractStreamingSyncImplementation extends BaseOb
     constructor(options: AbstractStreamingSyncImplementationOptions);
     waitForReady(): Promise<void>;
     waitForStatus(status: SyncStatusOptions): Promise<void>;
+    waitUntilStatusMatches(predicate: (status: SyncStatus) => boolean): Promise<void>;
     get lastSyncedAt(): Date | undefined;
     get isConnected(): boolean;
     protected get logger(): Logger.ILogger;
@@ -134,6 +136,7 @@ export declare abstract class AbstractStreamingSyncImplementation extends BaseOb
      * @deprecated use [connect instead]
      */
     streamingSync(signal?: AbortSignal, options?: PowerSyncConnectionOptions): Promise<void>;
+    private collectLocalBucketState;
     protected streamingSyncIteration(signal: AbortSignal, options?: PowerSyncConnectionOptions): Promise<{
         retry?: boolean;
     }>;

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

@@ -5,7 +5,7 @@ import { BaseObserver } from '../../../utils/BaseObserver.js';
 import { throttleLeadingTrailing } from '../../../utils/throttle.js';
 import { SyncDataBucket } from '../bucket/SyncDataBucket.js';
 import { FetchStrategy } from './AbstractRemote.js';
-import { isStreamingKeepalive, isStreamingSyncCheckpoint, isStreamingSyncCheckpointComplete, isStreamingSyncCheckpointDiff, isStreamingSyncData } from './streaming-sync-types.js';
+import { isStreamingKeepalive, isStreamingSyncCheckpoint, isStreamingSyncCheckpointComplete, isStreamingSyncCheckpointDiff, isStreamingSyncCheckpointPartiallyComplete, isStreamingSyncData } from './streaming-sync-types.js';
 export var LockType;
 (function (LockType) {
     LockType["CRUD"] = "crud";
@@ -28,6 +28,11 @@ export const DEFAULT_STREAM_CONNECTION_OPTIONS = {
     fetchStrategy: FetchStrategy.Buffered,
     params: {}
 };
+// The priority we assume when we receive checkpoint lines where no priority is set.
+// This is the default priority used by the sync service, but can be set to an arbitrary
+// value since sync services without priorities also won't send partial sync completion
+// messages.
+const FALLBACK_PRIORITY = 3;
 export class AbstractStreamingSyncImplementation extends BaseObserver {
     _lastSyncedAt;
     options;
@@ -58,23 +63,32 @@ export class AbstractStreamingSyncImplementation extends BaseObserver {
     }
     async waitForReady() { }
     waitForStatus(status) {
+        return this.waitUntilStatusMatches((currentStatus) => {
+            /**
+             * Match only the partial status options provided in the
+             * matching status
+             */
+            const matchPartialObject = (compA, compB) => {
+                return Object.entries(compA).every(([key, value]) => {
+                    const comparisonBValue = compB[key];
+                    if (typeof value == 'object' && typeof comparisonBValue == 'object') {
+                        return matchPartialObject(value, comparisonBValue);
+                    }
+                    return value == comparisonBValue;
+                });
+            };
+            return matchPartialObject(status, currentStatus);
+        });
+    }
+    waitUntilStatusMatches(predicate) {
         return new Promise((resolve) => {
+            if (predicate(this.syncStatus)) {
+                resolve();
+                return;
+            }
             const l = this.registerListener({
                 statusChanged: (updatedStatus) => {
-                    /**
-                     * Match only the partial status options provided in the
-                     * matching status
-                     */
-                    const matchPartialObject = (compA, compB) => {
-                        return Object.entries(compA).every(([key, value]) => {
-                            const comparisonBValue = compB[key];
-                            if (typeof value == 'object' && typeof comparisonBValue == 'object') {
-                                return matchPartialObject(value, comparisonBValue);
-                            }
-                            return value == comparisonBValue;
-                        });
-                    };
-                    if (matchPartialObject(status, updatedStatus.toJSON())) {
+                    if (predicate(updatedStatus)) {
                         resolve();
                         l?.();
                     }
@@ -303,6 +317,18 @@ The next upload iteration will be delayed.`);
         // Mark as disconnected if here
         this.updateSyncStatus({ connected: false, connecting: false });
     }
+    async collectLocalBucketState() {
+        const bucketEntries = await this.options.adapter.getBucketStates();
+        const req = bucketEntries.map((entry) => ({
+            name: entry.bucket,
+            after: entry.op_id
+        }));
+        const localDescriptions = new Map();
+        for (const entry of bucketEntries) {
+            localDescriptions.set(entry.bucket, null);
+        }
+        return [req, localDescriptions];
+    }
     async streamingSyncIteration(signal, options) {
         return await this.obtainLock({
             type: LockType.SYNC,
@@ -314,20 +340,11 @@ The next upload iteration will be delayed.`);
                 };
                 this.logger.debug('Streaming sync iteration started');
                 this.options.adapter.startSession();
-                const bucketEntries = await this.options.adapter.getBucketStates();
-                const initialBuckets = new Map();
-                bucketEntries.forEach((entry) => {
-                    initialBuckets.set(entry.bucket, entry.op_id);
-                });
-                const req = Array.from(initialBuckets.entries()).map(([bucket, after]) => ({
-                    name: bucket,
-                    after: after
-                }));
+                let [req, bucketMap] = await this.collectLocalBucketState();
                 // These are compared by reference
                 let targetCheckpoint = null;
                 let validatedCheckpoint = null;
                 let appliedCheckpoint = null;
-                let bucketSet = new Set(initialBuckets.keys());
                 const clientId = await this.options.adapter.getClientId();
                 this.logger.debug('Requesting stream from server');
                 const syncOptions = {
@@ -368,16 +385,19 @@ The next upload iteration will be delayed.`);
                     }
                     if (isStreamingSyncCheckpoint(line)) {
                         targetCheckpoint = line.checkpoint;
-                        const bucketsToDelete = new Set(bucketSet);
-                        const newBuckets = new Set();
+                        const bucketsToDelete = new Set(bucketMap.keys());
+                        const newBuckets = new Map();
                         for (const checksum of line.checkpoint.buckets) {
-                            newBuckets.add(checksum.bucket);
+                            newBuckets.set(checksum.bucket, {
+                                name: checksum.bucket,
+                                priority: checksum.priority ?? FALLBACK_PRIORITY
+                            });
                             bucketsToDelete.delete(checksum.bucket);
                         }
                         if (bucketsToDelete.size > 0) {
                             this.logger.debug('Removing buckets', [...bucketsToDelete]);
                         }
-                        bucketSet = newBuckets;
+                        bucketMap = newBuckets;
                         await this.options.adapter.removeBuckets([...bucketsToDelete]);
                         await this.options.adapter.setTargetCheckpoint(targetCheckpoint);
                     }
@@ -408,6 +428,35 @@ The next upload iteration will be delayed.`);
                         }
                         validatedCheckpoint = targetCheckpoint;
                     }
+                    else if (isStreamingSyncCheckpointPartiallyComplete(line)) {
+                        const priority = line.partial_checkpoint_complete.priority;
+                        this.logger.debug('Partial checkpoint complete', priority);
+                        const result = await this.options.adapter.syncLocalDatabase(targetCheckpoint, priority);
+                        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 };
+                        }
+                        else if (!result.ready) {
+                            // Need more data for a consistent partial sync within a priority - continue waiting.
+                        }
+                        else {
+                            // We'll keep on downloading, but can report that this priority is synced now.
+                            this.logger.debug('partial checkpoint validation succeeded');
+                            // All states with a higher priority can be deleted since this partial sync includes them.
+                            const priorityStates = this.syncStatus.priorityStatusEntries.filter((s) => s.priority <= priority);
+                            priorityStates.push({
+                                priority,
+                                lastSyncedAt: new Date(),
+                                hasSynced: true
+                            });
+                            this.updateSyncStatus({
+                                connected: true,
+                                priorityStatusEntries: priorityStates
+                            });
+                        }
+                    }
                     else if (isStreamingSyncCheckpointDiff(line)) {
                         // TODO: It may be faster to just keep track of the diff, instead of the entire checkpoint
                         if (targetCheckpoint == null) {
@@ -430,7 +479,11 @@ The next upload iteration will be delayed.`);
                             write_checkpoint: diff.write_checkpoint
                         };
                         targetCheckpoint = newCheckpoint;
-                        bucketSet = new Set(newBuckets.keys());
+                        bucketMap = new Map();
+                        newBuckets.forEach((checksum, name) => bucketMap.set(name, {
+                            name: checksum.bucket,
+                            priority: checksum.priority ?? FALLBACK_PRIORITY
+                        }));
                         const bucketsToDelete = diff.removed_buckets;
                         if (bucketsToDelete.length > 0) {
                             this.logger.debug('Remove buckets', bucketsToDelete);
@@ -466,7 +519,8 @@ The next upload iteration will be delayed.`);
                         if (targetCheckpoint === appliedCheckpoint) {
                             this.updateSyncStatus({
                                 connected: true,
-                                lastSyncedAt: new Date()
+                                lastSyncedAt: new Date(),
+                                priorityStatusEntries: []
                             });
                         }
                         else if (validatedCheckpoint === targetCheckpoint) {
@@ -486,6 +540,7 @@ The next upload iteration will be delayed.`);
                                 this.updateSyncStatus({
                                     connected: true,
                                     lastSyncedAt: new Date(),
+                                    priorityStatusEntries: [],
                                     dataFlow: {
                                         downloading: false
                                     }
@@ -508,7 +563,8 @@ The next upload iteration will be delayed.`);
             dataFlow: {
                 ...this.syncStatus.dataFlowStatus,
                 ...options.dataFlow
-            }
+            },
+            priorityStatusEntries: options.priorityStatusEntries ?? this.syncStatus.priorityStatusEntries
         });
         if (!this.syncStatus.isEqual(updatedStatus)) {
             this.syncStatus = updatedStatus;

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

@@ -90,11 +90,17 @@ export interface StreamingSyncCheckpointComplete {
         last_op_id: OpId;
     };
 }
+export interface StreamingSyncCheckpointPartiallyComplete {
+    partial_checkpoint_complete: {
+        priority: number;
+        last_op_id: OpId;
+    };
+}
 export interface StreamingSyncKeepalive {
     /** If specified, token expires in this many seconds. */
     token_expires_in: number;
 }
-export type StreamingSyncLine = StreamingSyncDataJSON | StreamingSyncCheckpoint | StreamingSyncCheckpointDiff | StreamingSyncCheckpointComplete | StreamingSyncKeepalive;
+export type StreamingSyncLine = StreamingSyncDataJSON | StreamingSyncCheckpoint | StreamingSyncCheckpointDiff | StreamingSyncCheckpointComplete | StreamingSyncCheckpointPartiallyComplete | StreamingSyncKeepalive;
 export interface BucketRequest {
     name: string;
     /**
@@ -106,6 +112,7 @@ export declare function isStreamingSyncData(line: StreamingSyncLine): line is St
 export declare function isStreamingKeepalive(line: StreamingSyncLine): line is StreamingSyncKeepalive;
 export declare function isStreamingSyncCheckpoint(line: StreamingSyncLine): line is StreamingSyncCheckpoint;
 export declare function isStreamingSyncCheckpointComplete(line: StreamingSyncLine): line is StreamingSyncCheckpointComplete;
+export declare function isStreamingSyncCheckpointPartiallyComplete(line: StreamingSyncLine): line is StreamingSyncCheckpointPartiallyComplete;
 export declare function isStreamingSyncCheckpointDiff(line: StreamingSyncLine): line is StreamingSyncCheckpointDiff;
 export declare function isContinueCheckpointRequest(request: SyncRequest): request is ContinueCheckpointRequest;
 export declare function isSyncNewCheckpointRequest(request: SyncRequest): request is SyncNewCheckpointRequest;

package/lib/client/sync/stream/streaming-sync-types.js

@@ -10,6 +10,9 @@ export function isStreamingSyncCheckpoint(line) {
 export function isStreamingSyncCheckpointComplete(line) {
     return line.checkpoint_complete != null;
 }
+export function isStreamingSyncCheckpointPartiallyComplete(line) {
+    return line.partial_checkpoint_complete != null;
+}
 export function isStreamingSyncCheckpointDiff(line) {
     return line.checkpoint_diff != null;
 }

package/lib/db/DBAdapter.d.ts

@@ -39,6 +39,21 @@ export interface DBGetUtils {
 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. */
@@ -82,8 +97,9 @@ export interface DBLockOptions {
     timeoutMs?: number;
 }
 export interface DBAdapter extends BaseObserverInterface<DBAdapterListener>, DBGetUtils {
-    close: () => void;
+    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>;