@powersync/common 1.26.0 → 1.27.1

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

@@ -1,6 +1,17 @@
 export type SyncDataFlowStatus = Partial<{
     downloading: boolean;
     uploading: boolean;
+    /**
+     * Error during downloading (including connecting).
+     *
+     * Cleared on the next successful data download.
+     */
+    downloadError?: Error;
+    /**
+     * Error during uploading.
+     * Cleared on the next successful upload.
+     */
+    uploadError?: Error;
 }>;
 export interface SyncPriorityStatus {
     priority: number;
@@ -19,49 +30,101 @@ 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;
         uploading: boolean;
+        /**
+         * Error during downloading (including connecting).
+         *
+         * Cleared on the next successful data download.
+         */
+        downloadError?: Error;
+        /**
+         * Error during uploading.
+         * Cleared on the next successful upload.
+         */
+        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}`;
+        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/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.26.0",
+  "version": "1.27.1",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public"