@powersync/common 1.27.0 → 1.28.0

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

@@ -2,7 +2,7 @@ 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 { FetchStrategy } from './AbstractRemote.js';
 import { isStreamingKeepalive, isStreamingSyncCheckpoint, isStreamingSyncCheckpointComplete, isStreamingSyncCheckpointDiff, isStreamingSyncCheckpointPartiallyComplete, isStreamingSyncData } from './streaming-sync-types.js';
@@ -39,6 +39,7 @@ export class AbstractStreamingSyncImplementation extends BaseObserver {
     abortController;
     crudUpdateListener;
     streamingSyncPromise;
+    pendingCrudUpload;
     syncStatus;
     triggerCrudUpload;
     constructor(options) {
@@ -55,10 +56,15 @@ 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() { }
@@ -280,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) {
                 /**
@@ -341,7 +339,7 @@ The next upload iteration will be delayed.`);
         return [req, localDescriptions];
     }
     async streamingSyncIteration(signal, options) {
-        return await this.obtainLock({
+        await this.obtainLock({
             type: LockType.SYNC,
             signal,
             callback: async () => {
@@ -384,7 +382,7 @@ The next upload iteration will be delayed.`);
                     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) {
@@ -413,30 +411,12 @@ The next upload iteration will be delayed.`);
                         await this.options.adapter.setTargetCheckpoint(targetCheckpoint);
                     }
                     else if (isStreamingSyncCheckpointComplete(line)) {
-                        this.logger.debug('Checkpoint complete', 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: true };
-                        }
-                        else if (!result.ready) {
-                            // Checksums valid, but need more data for a consistent checkpoint.
-                            // Continue waiting.
-                            // landing here the whole time
+                        const result = await this.applyCheckpoint(targetCheckpoint, signal);
+                        if (result.endIteration) {
+                            return;
                         }
-                        else {
+                        else if (result.applied) {
                             appliedCheckpoint = targetCheckpoint;
-                            this.logger.debug('validated checkpoint', appliedCheckpoint);
-                            this.updateSyncStatus({
-                                connected: true,
-                                lastSyncedAt: new Date(),
-                                dataFlow: {
-                                    downloading: false,
-                                    downloadError: undefined
-                                }
-                            });
                         }
                         validatedCheckpoint = targetCheckpoint;
                     }
@@ -448,10 +428,11 @@ The next upload iteration will be delayed.`);
                             // 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) {
-                            // Need more data for a consistent partial sync within a priority - continue waiting.
+                            // If we have pending uploads, we can't complete new checkpoints outside of priority 0.
+                            // We'll resolve this for a complete checkpoint.
                         }
                         else {
                             // We'll keep on downloading, but can report that this priority is synced now.
@@ -522,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();
                     }
@@ -539,38 +520,61 @@ The next upload iteration will be delayed.`);
                             });
                         }
                         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(),
-                                    priorityStatusEntries: [],
-                                    dataFlow: {
-                                        downloading: false,
-                                        downloadError: undefined
-                                    }
-                                });
                             }
                         }
                     }
                 }
                 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,

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

@@ -30,22 +30,38 @@ export declare class SyncStatus {
     protected options: SyncStatusOptions;
     constructor(options: SyncStatusOptions);
     /**
-     * true if currently connected.
+     * Indicates if the client is currently connected to the PowerSync service.
+     *
+     * @returns {boolean} True if connected, false otherwise. Defaults to false if not specified.
      */
     get connected(): boolean;
+    /**
+     * Indicates if the client is in the process of establishing a connection to the PowerSync service.
+     *
+     * @returns {boolean} True if connecting, false otherwise. Defaults to false if not specified.
+     */
     get connecting(): boolean;
     /**
-     *  Time that a last sync has fully completed, if any.
-     *  Currently this is reset to null after a restart.
+     * Time that a last sync has fully completed, if any.
+     * This timestamp is reset to null after a restart of the PowerSync service.
+     *
+     * @returns {Date | undefined} The timestamp of the last successful sync, or undefined if no sync has completed.
      */
     get lastSyncedAt(): Date | undefined;
     /**
-     * Indicates whether there has been at least one full sync, if any.
-     * Is undefined when unknown, for example when state is still being loaded from the database.
+     * Indicates whether there has been at least one full sync completed since initialization.
+     *
+     * @returns {boolean | undefined} True if at least one sync has completed, false if no sync has completed,
+     * or undefined when the state is still being loaded from the database.
      */
     get hasSynced(): boolean | undefined;
     /**
-     *  Upload/download status
+     * Provides the current data flow status regarding uploads and downloads.
+     *
+     * @returns {SyncDataFlowStatus} An object containing:
+     * - downloading: True if actively downloading changes (only when connected is also true)
+     * - uploading: True if actively uploading changes
+     * Defaults to {downloading: false, uploading: false} if not specified.
      */
     get dataFlowStatus(): Partial<{
         downloading: boolean;
@@ -63,27 +79,52 @@ export declare class SyncStatus {
         uploadError?: Error;
     }>;
     /**
-     * Partial sync status for involved bucket priorities.
+     * Provides sync status information for all bucket priorities, sorted by priority (highest first).
+     *
+     * @returns {SyncPriorityStatus[]} An array of status entries for different sync priority levels,
+     * sorted with highest priorities (lower numbers) first.
      */
     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.
+     * Reports the sync status (a pair of {@link SyncStatus#hasSynced} and {@link SyncStatus#lastSyncedAt} fields)
+     * for a specific bucket priority level.
      *
      * 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
+     * syncing.
+     *
+     * This method returns the status for the requested priority or the next higher priority level that has
+     * status information available. This is because when PowerSync makes data for a given priority available,
+     * all buckets in higher-priorities are guaranteed to be consistent with that checkpoint.
+     *
+     * For example, if 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.
+     * @param {number} priority The bucket priority for which the status should be reported
+     * @returns {SyncPriorityStatus} Status information for the requested priority level or the next higher level with available status
      */
     statusForPriority(priority: number): SyncPriorityStatus;
+    /**
+     * Compares this SyncStatus instance with another to determine if they are equal.
+     * Equality is determined by comparing the serialized JSON representation of both instances.
+     *
+     * @param {SyncStatus} status The SyncStatus instance to compare against
+     * @returns {boolean} True if the instances are considered equal, false otherwise
+     */
     isEqual(status: SyncStatus): boolean;
+    /**
+     * Creates a human-readable string representation of the current sync status.
+     * Includes information about connection state, sync completion, and data flow.
+     *
+     * @returns {string} A string representation of the sync status
+     */
     getMessage(): string;
+    /**
+     * Serializes the SyncStatus instance to a plain object.
+     *
+     * @returns {SyncStatusOptions} A plain object representation of the sync status
+     */
     toJSON(): SyncStatusOptions;
     private static comparePriorities;
 }

package/lib/db/crud/SyncStatus.js

@@ -4,30 +4,46 @@ export class SyncStatus {
         this.options = options;
     }
     /**
-     * true if currently connected.
+     * Indicates if the client is currently connected to the PowerSync service.
+     *
+     * @returns {boolean} True if connected, false otherwise. Defaults to false if not specified.
      */
     get connected() {
         return this.options.connected ?? false;
     }
+    /**
+     * Indicates if the client is in the process of establishing a connection to the PowerSync service.
+     *
+     * @returns {boolean} True if connecting, false otherwise. Defaults to false if not specified.
+     */
     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.
+     * Time that a last sync has fully completed, if any.
+     * This timestamp is reset to null after a restart of the PowerSync service.
+     *
+     * @returns {Date | undefined} The timestamp of the last successful sync, or undefined if no sync has completed.
      */
     get lastSyncedAt() {
         return this.options.lastSyncedAt;
     }
     /**
-     * Indicates whether there has been at least one full sync, if any.
-     * Is undefined when unknown, for example when state is still being loaded from the database.
+     * Indicates whether there has been at least one full sync completed since initialization.
+     *
+     * @returns {boolean | undefined} True if at least one sync has completed, false if no sync has completed,
+     * or undefined when the state is still being loaded from the database.
      */
     get hasSynced() {
         return this.options.hasSynced;
     }
     /**
-     *  Upload/download status
+     * Provides the current data flow status regarding uploads and downloads.
+     *
+     * @returns {SyncDataFlowStatus} An object containing:
+     * - downloading: True if actively downloading changes (only when connected is also true)
+     * - uploading: True if actively uploading changes
+     * Defaults to {downloading: false, uploading: false} if not specified.
      */
     get dataFlowStatus() {
         return (this.options.dataFlow ?? {
@@ -43,25 +59,32 @@ export class SyncStatus {
         });
     }
     /**
-     * Partial sync status for involved bucket priorities.
+     * Provides sync status information for all bucket priorities, sorted by priority (highest first).
+     *
+     * @returns {SyncPriorityStatus[]} An array of status entries for different sync priority levels,
+     * sorted with highest priorities (lower numbers) first.
      */
     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.
+     * Reports the sync status (a pair of {@link SyncStatus#hasSynced} and {@link SyncStatus#lastSyncedAt} fields)
+     * for a specific bucket priority level.
      *
      * 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
+     * syncing.
+     *
+     * This method returns the status for the requested priority or the next higher priority level that has
+     * status information available. This is because when PowerSync makes data for a given priority available,
+     * all buckets in higher-priorities are guaranteed to be consistent with that checkpoint.
+     *
+     * For example, if 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.
+     * @param {number} priority The bucket priority for which the status should be reported
+     * @returns {SyncPriorityStatus} Status information for the requested priority level or the next higher level with available status
      */
     statusForPriority(priority) {
         // priorityStatusEntries are sorted by ascending priorities (so higher numbers to lower numbers).
@@ -78,13 +101,31 @@ export class SyncStatus {
             hasSynced: this.hasSynced
         };
     }
+    /**
+     * Compares this SyncStatus instance with another to determine if they are equal.
+     * Equality is determined by comparing the serialized JSON representation of both instances.
+     *
+     * @param {SyncStatus} status The SyncStatus instance to compare against
+     * @returns {boolean} True if the instances are considered equal, false otherwise
+     */
     isEqual(status) {
         return JSON.stringify(this.options) == JSON.stringify(status.options);
     }
+    /**
+     * Creates a human-readable string representation of the current sync status.
+     * Includes information about connection state, sync completion, and data flow.
+     *
+     * @returns {string} A string representation of the sync status
+     */
     getMessage() {
         const dataFlow = this.dataFlowStatus;
         return `SyncStatus<connected: ${this.connected} connecting: ${this.connecting} lastSyncedAt: ${this.lastSyncedAt} hasSynced: ${this.hasSynced}. Downloading: ${dataFlow.downloading}. Uploading: ${dataFlow.uploading}. UploadError: ${dataFlow.uploadError}, DownloadError?: ${dataFlow.downloadError}>`;
     }
+    /**
+     * Serializes the SyncStatus instance to a plain object.
+     *
+     * @returns {SyncStatusOptions} A plain object representation of the sync status
+     */
     toJSON() {
         return {
             connected: this.connected,

package/lib/index.d.ts

@@ -32,5 +32,6 @@ export * from './db/DBAdapter.js';
 export * from './utils/AbortOperation.js';
 export * from './utils/BaseObserver.js';
 export * from './utils/DataStream.js';
+export * from './utils/Logger.js';
 export * from './utils/parseQuery.js';
 export * from './types/types.js';

package/lib/index.js

@@ -32,5 +32,6 @@ export * from './db/DBAdapter.js';
 export * from './utils/AbortOperation.js';
 export * from './utils/BaseObserver.js';
 export * from './utils/DataStream.js';
+export * from './utils/Logger.js';
 export * from './utils/parseQuery.js';
 export * from './types/types.js';

package/lib/utils/Logger.d.ts

@@ -0,0 +1,31 @@
+import Logger, { type ILogger, type ILogLevel } from 'js-logger';
+export { GlobalLogger, ILogger, ILoggerOpts, ILogHandler, ILogLevel } from 'js-logger';
+export declare const LogLevel: {
+    TRACE: Logger.ILogLevel;
+    DEBUG: Logger.ILogLevel;
+    INFO: Logger.ILogLevel;
+    TIME: Logger.ILogLevel;
+    WARN: Logger.ILogLevel;
+    ERROR: Logger.ILogLevel;
+    OFF: Logger.ILogLevel;
+};
+export interface CreateLoggerOptions {
+    logLevel?: ILogLevel;
+}
+/**
+ * Retrieves the base (default) logger instance.
+ *
+ * This base logger controls the default logging configuration and is shared
+ * across all loggers created with `createLogger`. Adjusting settings on this
+ * base logger affects all loggers derived from it unless explicitly overridden.
+ *
+ */
+export declare function createBaseLogger(): typeof Logger;
+/**
+ * Creates and configures a new named logger based on the base logger.
+ *
+ * Named loggers allow specific modules or areas of your application to have
+ * their own logging levels and behaviors. These loggers inherit configuration
+ * from the base logger by default but can override settings independently.
+ */
+export declare function createLogger(name: string, options?: CreateLoggerOptions): ILogger;

package/lib/utils/Logger.js

@@ -0,0 +1,36 @@
+import Logger from 'js-logger';
+const TypedLogger = Logger;
+export const LogLevel = {
+    TRACE: TypedLogger.TRACE,
+    DEBUG: TypedLogger.DEBUG,
+    INFO: TypedLogger.INFO,
+    TIME: TypedLogger.TIME,
+    WARN: TypedLogger.WARN,
+    ERROR: TypedLogger.ERROR,
+    OFF: TypedLogger.OFF
+};
+/**
+ * Retrieves the base (default) logger instance.
+ *
+ * This base logger controls the default logging configuration and is shared
+ * across all loggers created with `createLogger`. Adjusting settings on this
+ * base logger affects all loggers derived from it unless explicitly overridden.
+ *
+ */
+export function createBaseLogger() {
+    return Logger;
+}
+/**
+ * Creates and configures a new named logger based on the base logger.
+ *
+ * Named loggers allow specific modules or areas of your application to have
+ * their own logging levels and behaviors. These loggers inherit configuration
+ * from the base logger by default but can override settings independently.
+ */
+export function createLogger(name, options = {}) {
+    const logger = Logger.get(name);
+    if (options.logLevel) {
+        logger.setLevel(options.logLevel);
+    }
+    return logger;
+}

package/lib/utils/{throttle.d.ts → async.d.ts}

@@ -12,3 +12,4 @@ export declare function throttleTrailing(func: () => void, wait: number): () =>
  * Roughly equivalent to lodash/throttle with {leading: true, trailing: true}
  */
 export declare function throttleLeadingTrailing(func: () => void, wait: number): () => void;
+export declare function onAbortPromise(signal: AbortSignal): Promise<void>;

package/lib/utils/{throttle.js → async.js}

@@ -43,3 +43,13 @@ export function throttleLeadingTrailing(func, wait) {
         }
     };
 }
+export function onAbortPromise(signal) {
+    return new Promise((resolve) => {
+        if (signal.aborted) {
+            resolve();
+        }
+        else {
+            signal.onabort = () => resolve();
+        }
+    });
+}

package/package.json

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