@powersync/common 0.0.0-dev-20250210155038 → 0.0.0-dev-20250416114737

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

@@ -1,40 +1,130 @@
 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;
+    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;
     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;
     }>;
+    /**
+     * 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 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
+     * 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 {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 ?? {
@@ -42,20 +58,85 @@ export class SyncStatus {
             uploading: false
         });
     }
+    /**
+     * 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 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
+     * 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 {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).
+        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
+        };
+    }
+    /**
+     * 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,
             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/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/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/lib/utils/Logger.d.ts

@@ -0,0 +1,16 @@
+import Logger, { ILogger, ILogLevel } from 'js-logger';
+export { GlobalLogger, ILogger, ILoggerOpts, ILogHandler, ILogLevel } from 'js-logger';
+export declare const LogLevels: {
+    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;
+}
+export declare function createBaseLogger(): typeof Logger;
+export declare function createLogger(name: string, options?: CreateLoggerOptions): ILogger;

package/lib/utils/Logger.js

@@ -0,0 +1,21 @@
+import Logger from 'js-logger';
+const TypedLogger = Logger;
+export const LogLevels = {
+    TRACE: TypedLogger.TRACE,
+    DEBUG: TypedLogger.DEBUG,
+    INFO: TypedLogger.INFO,
+    TIME: TypedLogger.TIME,
+    WARN: TypedLogger.WARN,
+    ERROR: TypedLogger.ERROR,
+    OFF: TypedLogger.OFF
+};
+export function createBaseLogger() {
+    return Logger;
+}
+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": "0.0.0-dev-20250210155038",
+  "version": "0.0.0-dev-20250416114737",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public"