@powersync/common 1.24.0 → 1.26.0

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

@@ -2,12 +2,18 @@ export type SyncDataFlowStatus = Partial<{
     downloading: boolean;
     uploading: boolean;
 }>;
+export interface SyncPriorityStatus {
+    priority: number;
+    lastSyncedAt?: Date;
+    hasSynced?: boolean;
+}
 export type SyncStatusOptions = {
     connected?: boolean;
     connecting?: boolean;
     dataFlow?: SyncDataFlowStatus;
     lastSyncedAt?: Date;
     hasSynced?: boolean;
+    priorityStatusEntries?: SyncPriorityStatus[];
 };
 export declare class SyncStatus {
     protected options: SyncStatusOptions;
@@ -34,7 +40,28 @@ export declare class SyncStatus {
         downloading: boolean;
         uploading: boolean;
     }>;
+    /**
+     * Partial sync status for involved bucket priorities.
+     */
+    get priorityStatusEntries(): SyncPriorityStatus[];
+    /**
+     * Reports a pair of {@link SyncStatus#hasSynced} and {@link SyncStatus#lastSyncedAt} fields that apply
+     * to a specific bucket priority instead of the entire sync operation.
+     *
+     * When buckets with different priorities are declared, PowerSync may choose to synchronize higher-priority
+     * buckets first. When a consistent view over all buckets for all priorities up until the given priority is
+     * reached, PowerSync makes data from those buckets available before lower-priority buckets have finished
+     * synchronizing.
+     * When PowerSync makes data for a given priority available, all buckets in higher-priorities are guaranteed to
+     * be consistent with that checkpoint. For this reason, this method may also return the status for lower priorities.
+     * In a state where the PowerSync just finished synchronizing buckets in priority level 3, calling this method
+     * with a priority of 1 may return information for priority level 3.
+     *
+     * @param priority The bucket priority for which the status should be reported.
+     */
+    statusForPriority(priority: number): SyncPriorityStatus;
     isEqual(status: SyncStatus): boolean;
     getMessage(): string;
     toJSON(): SyncStatusOptions;
+    private static comparePriorities;
 }

package/lib/db/crud/SyncStatus.js

@@ -42,6 +42,42 @@ export class SyncStatus {
             uploading: false
         });
     }
+    /**
+     * Partial sync status for involved bucket priorities.
+     */
+    get priorityStatusEntries() {
+        return (this.options.priorityStatusEntries ?? []).slice().sort(SyncStatus.comparePriorities);
+    }
+    /**
+     * Reports a pair of {@link SyncStatus#hasSynced} and {@link SyncStatus#lastSyncedAt} fields that apply
+     * to a specific bucket priority instead of the entire sync operation.
+     *
+     * When buckets with different priorities are declared, PowerSync may choose to synchronize higher-priority
+     * buckets first. When a consistent view over all buckets for all priorities up until the given priority is
+     * reached, PowerSync makes data from those buckets available before lower-priority buckets have finished
+     * synchronizing.
+     * When PowerSync makes data for a given priority available, all buckets in higher-priorities are guaranteed to
+     * be consistent with that checkpoint. For this reason, this method may also return the status for lower priorities.
+     * In a state where the PowerSync just finished synchronizing buckets in priority level 3, calling this method
+     * with a priority of 1 may return information for priority level 3.
+     *
+     * @param priority The bucket priority for which the status should be reported.
+     */
+    statusForPriority(priority) {
+        // priorityStatusEntries are sorted by ascending priorities (so higher numbers to lower numbers).
+        for (const known of this.priorityStatusEntries) {
+            // We look for the first entry that doesn't have a higher priority.
+            if (known.priority >= priority) {
+                return known;
+            }
+        }
+        // If we have a complete sync, that necessarily includes all priorities.
+        return {
+            priority,
+            lastSyncedAt: this.lastSyncedAt,
+            hasSynced: this.hasSynced
+        };
+    }
     isEqual(status) {
         return JSON.stringify(this.options) == JSON.stringify(status.options);
     }
@@ -55,7 +91,11 @@ export class SyncStatus {
             connecting: this.connecting,
             dataFlow: this.dataFlowStatus,
             lastSyncedAt: this.lastSyncedAt,
-            hasSynced: this.hasSynced
+            hasSynced: this.hasSynced,
+            priorityStatusEntries: this.priorityStatusEntries
         };
     }
+    static comparePriorities(a, b) {
+        return b.priority - a.priority; // Reverse because higher priorities have lower numbers
+    }
 }

package/lib/utils/DataStream.js

@@ -63,9 +63,6 @@ export class DataStream extends BaseObserver {
      * @returns a Data payload or Null if the stream closed.
      */
     async read() {
-        if (this.dataQueue.length <= this.lowWatermark) {
-            await this.iterateAsyncErrored(async (l) => l.lowWater?.());
-        }
         if (this.closed) {
             return null;
         }
@@ -133,12 +130,14 @@ export class DataStream extends BaseObserver {
         return Array.from(this.listeners.values()).some((l) => !!l.data);
     }
     async _processQueue() {
-        if (!this.dataQueue.length || this.isClosed || !this.hasDataReader()) {
+        if (this.isClosed || !this.hasDataReader()) {
             Promise.resolve().then(() => (this.processingPromise = null));
             return;
         }
-        const data = this.dataQueue.shift();
-        await this.iterateAsyncErrored(async (l) => l.data?.(data));
+        if (this.dataQueue.length) {
+            const data = this.dataQueue.shift();
+            await this.iterateAsyncErrored(async (l) => l.data?.(data));
+        }
         if (this.dataQueue.length <= this.lowWatermark) {
             await this.iterateAsyncErrored(async (l) => l.lowWater?.());
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@powersync/common",
-  "version": "1.24.0",
+  "version": "1.26.0",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public"
@@ -52,8 +52,6 @@
     "rsocket-core": "1.0.0-alpha.3",
     "rsocket-websocket-client": "1.0.0-alpha.3",
     "text-encoding": "^0.7.0",
-    "typescript": "^5.5.3",
-    "vitest": "^2.0.5",
     "web-streams-polyfill": "3.2.1"
   },
   "scripts": {