@powersync/common 0.0.0-dev-20250210155038 → 0.0.0-dev-20250416114737

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

@@ -16,6 +16,21 @@ export type SyncStreamOptions = {
     abortSignal?: AbortSignal;
     fetchOptions?: Request;
 };
+export declare enum FetchStrategy {
+    /**
+     * Queues multiple sync events before processing, reducing round-trips.
+     * This comes at the cost of more processing overhead, which may cause ACK timeouts on older/weaker devices for big enough datasets.
+     */
+    Buffered = "buffered",
+    /**
+     * Processes each sync event immediately before requesting the next.
+     * This reduces processing overhead and improves real-time responsiveness.
+     */
+    Sequential = "sequential"
+}
+export type SocketSyncStreamOptions = SyncStreamOptions & {
+    fetchStrategy: FetchStrategy;
+};
 export type FetchImplementation = typeof fetch;
 /**
  * Class wrapper for providing a fetch implementation.
@@ -72,7 +87,7 @@ export declare abstract class AbstractRemote {
     /**
      * Connects to the sync/stream websocket endpoint
      */
-    socketStream(options: SyncStreamOptions): Promise<DataStream<StreamingSyncLine>>;
+    socketStream(options: SocketSyncStreamOptions): Promise<DataStream<StreamingSyncLine>>;
     /**
      * Connects to the sync/stream http endpoint
      */

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

@@ -10,13 +10,25 @@ 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_N = 10;
 const SYNC_QUEUE_REQUEST_LOW_WATER = 5;
 // Keep alive message is sent every period
 const KEEP_ALIVE_MS = 20_000;
 // The ACK must be received in this period
 const KEEP_ALIVE_LIFETIME_MS = 30_000;
 export const DEFAULT_REMOTE_LOGGER = Logger.get('PowerSyncRemote');
+export var FetchStrategy;
+(function (FetchStrategy) {
+    /**
+     * Queues multiple sync events before processing, reducing round-trips.
+     * This comes at the cost of more processing overhead, which may cause ACK timeouts on older/weaker devices for big enough datasets.
+     */
+    FetchStrategy["Buffered"] = "buffered";
+    /**
+     * Processes each sync event immediately before requesting the next.
+     * This reduces processing overhead and improves real-time responsiveness.
+     */
+    FetchStrategy["Sequential"] = "sequential";
+})(FetchStrategy || (FetchStrategy = {}));
 /**
  * Class wrapper for providing a fetch implementation.
  * The class wrapper is used to distinguish the fetchImplementation
@@ -145,7 +157,8 @@ export class AbstractRemote {
      * Connects to the sync/stream websocket endpoint
      */
     async socketStream(options) {
-        const { path } = options;
+        const { path, fetchStrategy = FetchStrategy.Buffered } = options;
+        const syncQueueRequestSize = fetchStrategy == FetchStrategy.Buffered ? 10 : 1;
         const request = await this.buildRequest(path);
         const bson = await this.getBSON();
         // Add the user agent in the setup payload - we can't set custom
@@ -198,7 +211,7 @@ export class AbstractRemote {
         // Helps to prevent double close scenarios
         rsocket.onClose(() => (socketIsClosed = true));
         // We initially request this amount and expect these to arrive eventually
-        let pendingEventsCount = SYNC_QUEUE_REQUEST_N;
+        let pendingEventsCount = syncQueueRequestSize;
         const disposeClosedListener = stream.registerListener({
             closed: () => {
                 closeSocket();
@@ -212,7 +225,7 @@ export class AbstractRemote {
                 metadata: Buffer.from(bson.serialize({
                     path
                 }))
-            }, SYNC_QUEUE_REQUEST_N, // The initial N amount
+            }, syncQueueRequestSize, // The initial N amount
             {
                 onError: (e) => {
                     // Don't log closed as an error
@@ -251,10 +264,10 @@ export class AbstractRemote {
         const l = stream.registerListener({
             lowWater: async () => {
                 // Request to fill up the queue
-                const required = SYNC_QUEUE_REQUEST_N - pendingEventsCount;
+                const required = syncQueueRequestSize - pendingEventsCount;
                 if (required > 0) {
-                    socket.request(SYNC_QUEUE_REQUEST_N - pendingEventsCount);
-                    pendingEventsCount = SYNC_QUEUE_REQUEST_N;
+                    socket.request(syncQueueRequestSize - pendingEventsCount);
+                    pendingEventsCount = syncQueueRequestSize;
                 }
             },
             closed: () => {

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

@@ -2,7 +2,7 @@ import Logger, { ILogger } from 'js-logger';
 import { SyncStatus, SyncStatusOptions } from '../../../db/crud/SyncStatus.js';
 import { BaseListener, BaseObserver, Disposable } from '../../../utils/BaseObserver.js';
 import { BucketStorageAdapter } from '../bucket/BucketStorageAdapter.js';
-import { AbstractRemote } from './AbstractRemote.js';
+import { AbstractRemote, FetchStrategy } from './AbstractRemote.js';
 import { StreamingSyncRequestParameterType } from './streaming-sync-types.js';
 export declare enum LockType {
     CRUD = "crud",
@@ -56,6 +56,10 @@ export interface BaseConnectionOptions {
      * Defaults to a HTTP streaming connection.
      */
     connectionMethod?: SyncStreamConnectionMethod;
+    /**
+     * The fetch strategy to use when streaming updates from the PowerSync backend instance.
+     */
+    fetchStrategy?: FetchStrategy;
     /**
      * These parameters are passed to the sync rules, and will be available under the`user_parameters` object.
      */
@@ -95,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;
@@ -111,11 +116,13 @@ 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);
     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;
@@ -130,9 +137,9 @@ export declare abstract class AbstractStreamingSyncImplementation extends BaseOb
      * @deprecated use [connect instead]
      */
     streamingSync(signal?: AbortSignal, options?: PowerSyncConnectionOptions): Promise<void>;
-    protected streamingSyncIteration(signal: AbortSignal, options?: PowerSyncConnectionOptions): Promise<{
-        retry?: boolean;
-    }>;
+    private collectLocalBucketState;
+    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,9 +2,10 @@ 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 { isStreamingKeepalive, isStreamingSyncCheckpoint, isStreamingSyncCheckpointComplete, isStreamingSyncCheckpointDiff, isStreamingSyncData } from './streaming-sync-types.js';
+import { FetchStrategy } from './AbstractRemote.js';
+import { isStreamingKeepalive, isStreamingSyncCheckpoint, isStreamingSyncCheckpointComplete, isStreamingSyncCheckpointDiff, isStreamingSyncCheckpointPartiallyComplete, isStreamingSyncData } from './streaming-sync-types.js';
 export var LockType;
 (function (LockType) {
     LockType["CRUD"] = "crud";
@@ -24,14 +25,21 @@ export const DEFAULT_STREAMING_SYNC_OPTIONS = {
 };
 export const DEFAULT_STREAM_CONNECTION_OPTIONS = {
     connectionMethod: SyncStreamConnectionMethod.WEB_SOCKET,
+    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;
     abortController;
     crudUpdateListener;
     streamingSyncPromise;
+    pendingCrudUpload;
     syncStatus;
     triggerCrudUpload;
     constructor(options) {
@@ -48,31 +56,45 @@ 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() { }
     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?.();
                     }
@@ -132,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
@@ -143,7 +170,8 @@ The next upload iteration will be delayed.`);
                         checkedCrudItem = undefined;
                         this.updateSyncStatus({
                             dataFlow: {
-                                uploading: false
+                                uploading: false,
+                                uploadError: ex
                             }
                         });
                         await this.delayRetry();
@@ -258,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) {
                 /**
@@ -284,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();
             }
@@ -301,8 +326,20 @@ 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({
+        await this.obtainLock({
             type: LockType.SYNC,
             signal,
             callback: async () => {
@@ -312,20 +349,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 = {
@@ -339,15 +367,22 @@ The next upload iteration will be delayed.`);
                         client_id: clientId
                     }
                 };
-                const stream = resolvedOptions?.connectionMethod == SyncStreamConnectionMethod.HTTP
-                    ? await this.options.remote.postStream(syncOptions)
-                    : await this.options.remote.socketStream(syncOptions);
+                let stream;
+                if (resolvedOptions?.connectionMethod == SyncStreamConnectionMethod.HTTP) {
+                    stream = await this.options.remote.postStream(syncOptions);
+                }
+                else {
+                    stream = await this.options.remote.socketStream({
+                        ...syncOptions,
+                        ...{ fetchStrategy: resolvedOptions.fetchStrategy }
+                    });
+                }
                 this.logger.debug('Stream established. Processing events');
                 while (!stream.closed) {
                     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) {
@@ -359,45 +394,61 @@ 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);
                     }
                     else if (isStreamingSyncCheckpointComplete(line)) {
-                        this.logger.debug('Checkpoint complete', targetCheckpoint);
-                        const result = await this.options.adapter.syncLocalDatabase(targetCheckpoint);
+                        const result = await this.applyCheckpoint(targetCheckpoint, signal);
+                        if (result.endIteration) {
+                            return;
+                        }
+                        else if (result.applied) {
+                            appliedCheckpoint = targetCheckpoint;
+                        }
+                        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 };
+                            return;
                         }
                         else if (!result.ready) {
-                            // Checksums valid, but need more data for a consistent checkpoint.
-                            // Continue waiting.
-                            // landing here the whole time
+                            // If we have pending uploads, we can't complete new checkpoints outside of priority 0.
+                            // We'll resolve this for a complete checkpoint.
                         }
                         else {
-                            appliedCheckpoint = targetCheckpoint;
-                            this.logger.debug('validated checkpoint', appliedCheckpoint);
+                            // 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,
-                                lastSyncedAt: new Date(),
-                                dataFlow: {
-                                    downloading: false
-                                }
+                                priorityStatusEntries: priorityStates
                             });
                         }
-                        validatedCheckpoint = targetCheckpoint;
                     }
                     else if (isStreamingSyncCheckpointDiff(line)) {
                         // TODO: It may be faster to just keep track of the diff, instead of the entire checkpoint
@@ -421,7 +472,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);
@@ -448,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();
                     }
@@ -457,40 +512,69 @@ The next upload iteration will be delayed.`);
                         if (targetCheckpoint === appliedCheckpoint) {
                             this.updateSyncStatus({
                                 connected: true,
-                                lastSyncedAt: new Date()
+                                lastSyncedAt: new Date(),
+                                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(),
-                                    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,
@@ -499,7 +583,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>;