@powersync/common 1.22.2 → 1.24.0

package/lib/client/AbstractPowerSyncDatabase.d.ts

@@ -10,25 +10,18 @@ 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 { PowerSyncConnectionOptions, StreamingSyncImplementation, StreamingSyncImplementationListener } from './sync/stream/AbstractStreamingSyncImplementation.js';
+import { type AdditionalConnectionOptions, type PowerSyncConnectionOptions, StreamingSyncImplementation, StreamingSyncImplementationListener, type RequiredAdditionalConnectionOptions } from './sync/stream/AbstractStreamingSyncImplementation.js';
 export interface DisconnectAndClearOptions {
     /** When set to false, data in local-only tables is preserved. */
     clearLocal?: boolean;
 }
-export interface BasePowerSyncDatabaseOptions {
+export interface BasePowerSyncDatabaseOptions extends AdditionalConnectionOptions {
     /** Schema used for the local database. */
     schema: Schema;
     /**
-     * Delay for retrying sync streaming operations
-     * from the PowerSync backend after an error occurs.
+     * @deprecated Use {@link retryDelayMs} instead as this will be removed in future releases.
      */
     retryDelay?: number;
-    /**
-     * Backend Connector CRUD operations are throttled
-     * to occur at most every `crudUploadThrottleMs`
-     * milliseconds.
-     */
-    crudUploadThrottleMs?: number;
     logger?: ILogger;
 }
 export interface PowerSyncDatabaseOptions extends BasePowerSyncDatabaseOptions {
@@ -89,7 +82,7 @@ export interface PowerSyncCloseOptions {
 export declare const DEFAULT_POWERSYNC_CLOSE_OPTIONS: PowerSyncCloseOptions;
 export declare const DEFAULT_WATCH_THROTTLE_MS = 30;
 export declare const DEFAULT_POWERSYNC_DB_OPTIONS: {
-    retryDelay: number;
+    retryDelayMs: number;
     logger: Logger.ILogger;
     crudUploadThrottleMs: number;
 };
@@ -148,11 +141,12 @@ 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
      */
     protected abstract openDBAdapter(options: PowerSyncDatabaseOptionsWithSettings): DBAdapter;
-    protected abstract generateSyncStreamImplementation(connector: PowerSyncBackendConnector): StreamingSyncImplementation;
+    protected abstract generateSyncStreamImplementation(connector: PowerSyncBackendConnector, options: RequiredAdditionalConnectionOptions): StreamingSyncImplementation;
     protected abstract generateBucketStorageAdapter(): BucketStorageAdapter;
     /**
      * @returns A promise which will resolve once initialization is completed.
@@ -185,6 +179,7 @@ export declare abstract class AbstractPowerSyncDatabase extends BaseObserver<Pow
      * While initializing is automatic, this helps to catch and report initialization errors.
      */
     init(): Promise<void>;
+    resolvedConnectionOptions(options?: PowerSyncConnectionOptions): RequiredAdditionalConnectionOptions;
     /**
      * Connects to stream of events from the PowerSync instance.
      */

package/lib/client/AbstractPowerSyncDatabase.js

@@ -13,7 +13,7 @@ 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 } from './sync/stream/AbstractStreamingSyncImplementation.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 = {
@@ -24,7 +24,7 @@ export const DEFAULT_POWERSYNC_CLOSE_OPTIONS = {
 };
 export const DEFAULT_WATCH_THROTTLE_MS = 30;
 export const DEFAULT_POWERSYNC_DB_OPTIONS = {
-    retryDelay: 5000,
+    retryDelayMs: 5000,
     logger: Logger.get('PowerSyncDatabase'),
     crudUploadThrottleMs: DEFAULT_CRUD_UPLOAD_THROTTLE_MS
 };
@@ -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.
      */
@@ -222,6 +225,13 @@ export class AbstractPowerSyncDatabase extends BaseObserver {
     async init() {
         return this.waitForReady();
     }
+    // Use the options passed in during connect, or fallback to the options set during database creation or fallback to the default options
+    resolvedConnectionOptions(options) {
+        return {
+            retryDelayMs: options?.retryDelayMs ?? this.options.retryDelayMs ?? this.options.retryDelay ?? DEFAULT_RETRY_DELAY_MS,
+            crudUploadThrottleMs: options?.crudUploadThrottleMs ?? this.options.crudUploadThrottleMs ?? DEFAULT_CRUD_UPLOAD_THROTTLE_MS
+        };
+    }
     /**
      * Connects to stream of events from the PowerSync instance.
      */
@@ -232,7 +242,11 @@ export class AbstractPowerSyncDatabase extends BaseObserver {
         if (this.closed) {
             throw new Error('Cannot connect using a closed client');
         }
-        this.syncStreamImplementation = this.generateSyncStreamImplementation(connector);
+        const { retryDelayMs, crudUploadThrottleMs } = this.resolvedConnectionOptions(options);
+        this.syncStreamImplementation = this.generateSyncStreamImplementation(connector, {
+            retryDelayMs,
+            crudUploadThrottleMs,
+        });
         this.syncStatusListenerDisposer = this.syncStreamImplementation.registerListener({
             statusChanged: (status) => {
                 this.currentStatus = new SyncStatus({

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",
@@ -20,10 +20,9 @@ export interface LockOptions<T> {
     type: LockType;
     signal?: AbortSignal;
 }
-export interface AbstractStreamingSyncImplementationOptions {
+export interface AbstractStreamingSyncImplementationOptions extends AdditionalConnectionOptions {
     adapter: BucketStorageAdapter;
     uploadCrud: () => Promise<void>;
-    crudUploadThrottleMs?: number;
     /**
      * An identifier for which PowerSync DB this sync implementation is
      * linked to. Most commonly DB name, but not restricted to DB name.
@@ -31,7 +30,6 @@ export interface AbstractStreamingSyncImplementationOptions {
     identifier?: string;
     logger?: ILogger;
     remote: AbstractRemote;
-    retryDelayMs?: number;
 }
 export interface StreamingSyncImplementationListener extends BaseListener {
     /**
@@ -48,18 +46,41 @@ export interface StreamingSyncImplementationListener extends BaseListener {
  * Configurable options to be used when connecting to the PowerSync
  * backend instance.
  */
-export interface PowerSyncConnectionOptions {
+export interface PowerSyncConnectionOptions extends BaseConnectionOptions, AdditionalConnectionOptions {
+}
+/** @internal */
+export interface BaseConnectionOptions {
     /**
      * The connection method to use when streaming updates from
      * the PowerSync backend instance.
      * 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.
      */
     params?: Record<string, StreamingSyncRequestParameterType>;
 }
+/** @internal */
+export interface AdditionalConnectionOptions {
+    /**
+     * Delay for retrying sync streaming operations
+     * from the PowerSync backend after an error occurs.
+     */
+    retryDelayMs?: number;
+    /**
+     * Backend Connector CRUD operations are throttled
+     * to occur at most every `crudUploadThrottleMs`
+     * milliseconds.
+     */
+    crudUploadThrottleMs?: number;
+}
+/** @internal */
+export type RequiredAdditionalConnectionOptions = Required<AdditionalConnectionOptions>;
 export interface StreamingSyncImplementation extends BaseObserver<StreamingSyncImplementationListener>, Disposable {
     /**
      * Connects to the sync service
@@ -80,12 +101,14 @@ export interface StreamingSyncImplementation extends BaseObserver<StreamingSyncI
     waitForStatus(status: SyncStatusOptions): Promise<void>;
 }
 export declare const DEFAULT_CRUD_UPLOAD_THROTTLE_MS = 1000;
+export declare const DEFAULT_RETRY_DELAY_MS = 5000;
 export declare const DEFAULT_STREAMING_SYNC_OPTIONS: {
     retryDelayMs: number;
     logger: Logger.ILogger;
     crudUploadThrottleMs: number;
 };
-export declare const DEFAULT_STREAM_CONNECTION_OPTIONS: Required<PowerSyncConnectionOptions>;
+export type RequiredPowerSyncConnectionOptions = Required<BaseConnectionOptions>;
+export declare const DEFAULT_STREAM_CONNECTION_OPTIONS: RequiredPowerSyncConnectionOptions;
 export declare abstract class AbstractStreamingSyncImplementation extends BaseObserver<StreamingSyncImplementationListener> implements StreamingSyncImplementation {
     protected _lastSyncedAt: Date | null;
     protected options: AbstractStreamingSyncImplementationOptions;

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) {
@@ -16,13 +17,15 @@ export var SyncStreamConnectionMethod;
     SyncStreamConnectionMethod["WEB_SOCKET"] = "web-socket";
 })(SyncStreamConnectionMethod || (SyncStreamConnectionMethod = {}));
 export const DEFAULT_CRUD_UPLOAD_THROTTLE_MS = 1000;
+export const DEFAULT_RETRY_DELAY_MS = 5000;
 export const DEFAULT_STREAMING_SYNC_OPTIONS = {
-    retryDelayMs: 5000,
+    retryDelayMs: DEFAULT_RETRY_DELAY_MS,
     logger: Logger.get('PowerSyncStream'),
     crudUploadThrottleMs: DEFAULT_CRUD_UPLOAD_THROTTLE_MS
 };
 export const DEFAULT_STREAM_CONNECTION_OPTIONS = {
     connectionMethod: SyncStreamConnectionMethod.WEB_SOCKET,
+    fetchStrategy: FetchStrategy.Buffered,
     params: {}
 };
 export class AbstractStreamingSyncImplementation extends BaseObserver {
@@ -38,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,
@@ -207,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]
@@ -238,6 +242,7 @@ The next upload iteration will be delayed.`);
             this.crudUpdateListener = undefined;
             this.updateSyncStatus({
                 connected: false,
+                connecting: false,
                 dataFlow: {
                     downloading: false
                 }
@@ -250,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;
@@ -280,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 {
@@ -288,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({
@@ -334,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();
@@ -489,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.22.2",
+  "version": "1.24.0",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public"