@powersync/common 1.23.0 → 1.24.0

package/lib/client/AbstractPowerSyncDatabase.d.ts

@@ -141,6 +141,7 @@ export declare abstract class AbstractPowerSyncDatabase extends BaseObserver<Pow
      * Whether a connection to the PowerSync service is currently open.
      */
     get connected(): boolean;
+    get connecting(): boolean;
     /**
      * Opens the DBAdapter given open options using a default open factory
      */

package/lib/client/AbstractPowerSyncDatabase.js

@@ -114,6 +114,9 @@ export class AbstractPowerSyncDatabase extends BaseObserver {
     get connected() {
         return this.currentStatus?.connected || false;
     }
+    get connecting() {
+        return this.currentStatus?.connecting || false;
+    }
     /**
      * @returns A promise which will resolve once initialization is completed.
      */

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

@@ -9,13 +9,25 @@ import { version as POWERSYNC_JS_VERSION } from '../../../../package.json';
 const POWERSYNC_TRAILING_SLASH_MATCH = /\/+$/;
 // 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
@@ -144,7 +156,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
@@ -197,7 +210,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();
@@ -211,7 +224,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
@@ -250,10 +263,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.
      */

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

@@ -4,6 +4,7 @@ import { AbortOperation } from '../../../utils/AbortOperation.js';
 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';
 export var LockType;
 (function (LockType) {
@@ -24,6 +25,7 @@ export const DEFAULT_STREAMING_SYNC_OPTIONS = {
 };
 export const DEFAULT_STREAM_CONNECTION_OPTIONS = {
     connectionMethod: SyncStreamConnectionMethod.WEB_SOCKET,
+    fetchStrategy: FetchStrategy.Buffered,
     params: {}
 };
 export class AbstractStreamingSyncImplementation extends BaseObserver {
@@ -39,6 +41,7 @@ export class AbstractStreamingSyncImplementation extends BaseObserver {
         this.options = { ...DEFAULT_STREAMING_SYNC_OPTIONS, ...options };
         this.syncStatus = new SyncStatus({
             connected: false,
+            connecting: false,
             lastSyncedAt: undefined,
             dataFlow: {
                 uploading: false,
@@ -208,7 +211,7 @@ The next upload iteration will be delayed.`);
         }
         this.streamingSyncPromise = undefined;
         this.abortController = null;
-        this.updateSyncStatus({ connected: false });
+        this.updateSyncStatus({ connected: false, connecting: false });
     }
     /**
      * @deprecated use [connect instead]
@@ -239,6 +242,7 @@ The next upload iteration will be delayed.`);
             this.crudUpdateListener = undefined;
             this.updateSyncStatus({
                 connected: false,
+                connecting: false,
                 dataFlow: {
                     downloading: false
                 }
@@ -251,6 +255,7 @@ The next upload iteration will be delayed.`);
          *  - Close any sync stream ReadableStreams (which will also close any established network requests)
          */
         while (true) {
+            this.updateSyncStatus({ connecting: true });
             try {
                 if (signal?.aborted) {
                     break;
@@ -281,6 +286,7 @@ The next upload iteration will be delayed.`);
                 else {
                     this.logger.error(ex);
                 }
+                // On error, wait a little before retrying
                 await this.delayRetry();
             }
             finally {
@@ -289,13 +295,13 @@ The next upload iteration will be delayed.`);
                     nestedAbortController = new AbortController();
                 }
                 this.updateSyncStatus({
-                    connected: false
+                    connected: false,
+                    connecting: true // May be unnecessary
                 });
-                // On error, wait a little before retrying
             }
         }
         // Mark as disconnected if here
-        this.updateSyncStatus({ connected: false });
+        this.updateSyncStatus({ connected: false, connecting: false });
     }
     async streamingSyncIteration(signal, options) {
         return await this.obtainLock({
@@ -335,9 +341,16 @@ 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();
@@ -490,6 +503,7 @@ The next upload iteration will be delayed.`);
     updateSyncStatus(options) {
         const updatedStatus = new SyncStatus({
             connected: options.connected ?? this.syncStatus.connected,
+            connecting: !options.connected && (options.connecting ?? this.syncStatus.connecting),
             lastSyncedAt: options.lastSyncedAt ?? this.syncStatus.lastSyncedAt,
             dataFlow: {
                 ...this.syncStatus.dataFlowStatus,

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

@@ -4,6 +4,7 @@ export type SyncDataFlowStatus = Partial<{
 }>;
 export type SyncStatusOptions = {
     connected?: boolean;
+    connecting?: boolean;
     dataFlow?: SyncDataFlowStatus;
     lastSyncedAt?: Date;
     hasSynced?: boolean;
@@ -15,6 +16,7 @@ export declare class SyncStatus {
      * true if currently connected.
      */
     get connected(): boolean;
+    get connecting(): boolean;
     /**
      *  Time that a last sync has fully completed, if any.
      *  Currently this is reset to null after a restart.

package/lib/db/crud/SyncStatus.js

@@ -9,6 +9,9 @@ export class SyncStatus {
     get connected() {
         return this.options.connected ?? false;
     }
+    get connecting() {
+        return this.options.connecting ?? false;
+    }
     /**
      *  Time that a last sync has fully completed, if any.
      *  Currently this is reset to null after a restart.
@@ -44,11 +47,12 @@ export class SyncStatus {
     }
     getMessage() {
         const dataFlow = this.dataFlowStatus;
-        return `SyncStatus<connected: ${this.connected} lastSyncedAt: ${this.lastSyncedAt} hasSynced: ${this.hasSynced}. Downloading: ${dataFlow.downloading}. Uploading: ${dataFlow.uploading}`;
+        return `SyncStatus<connected: ${this.connected} connecting: ${this.connecting} lastSyncedAt: ${this.lastSyncedAt} hasSynced: ${this.hasSynced}. Downloading: ${dataFlow.downloading}. Uploading: ${dataFlow.uploading}`;
     }
     toJSON() {
         return {
             connected: this.connected,
+            connecting: this.connecting,
             dataFlow: this.dataFlowStatus,
             lastSyncedAt: this.lastSyncedAt,
             hasSynced: this.hasSynced

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@powersync/common",
-  "version": "1.23.0",
+  "version": "1.24.0",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public"