@powersync/common 0.0.0-dev-20250915110424 → 0.0.0-dev-20250922104723

package/lib/client/sync/stream/core-instruction.js

@@ -1 +1,26 @@
-export {};
+import { FULL_SYNC_PRIORITY } from '../../../db/crud/SyncProgress.js';
+function priorityToJs(status) {
+    return {
+        priority: status.priority,
+        hasSynced: status.has_synced ?? undefined,
+        lastSyncedAt: status.last_synced_at != null ? new Date(status.last_synced_at * 1000) : undefined
+    };
+}
+export function coreStatusToJs(status) {
+    const coreCompleteSync = status.priority_status.find((s) => s.priority == FULL_SYNC_PRIORITY);
+    const completeSync = coreCompleteSync != null ? priorityToJs(coreCompleteSync) : null;
+    return {
+        connected: status.connected,
+        connecting: status.connecting,
+        dataFlow: {
+            // We expose downloading as a boolean field, the core extension reports download information as a nullable
+            // download status. When that status is non-null, a download is in progress.
+            downloading: status.downloading != null,
+            downloadProgress: status.downloading?.buckets,
+            internalStreamSubscriptions: status.streams
+        },
+        lastSyncedAt: completeSync?.lastSyncedAt,
+        hasSynced: completeSync?.hasSynced,
+        priorityStatusEntries: status.priority_status.map(priorityToJs)
+    };
+}

package/lib/client/sync/sync-streams.d.ts

@@ -0,0 +1,98 @@
+/**
+ * A description of a sync stream, consisting of its {@link name} and the {@link parameters} used when subscribing.
+ */
+export interface SyncStreamDescription {
+    /**
+     * The name of the stream as it appears in the stream definition for the PowerSync service.
+     */
+    name: string;
+    /**
+     * The parameters used to subscribe to the stream, if any.
+     *
+     * The same stream can be subscribed to multiple times with different parameters.
+     */
+    parameters: Record<string, any> | null;
+}
+/**
+ * Information about a subscribed sync stream.
+ *
+ * This includes the {@link SyncStreamDescription}, along with information about the current sync status.
+ */
+export interface SyncSubscriptionDescription extends SyncStreamDescription {
+    active: boolean;
+    /**
+     * Whether this stream subscription is included by default, regardless of whether the stream has explicitly been
+     * subscribed to or not.
+     *
+     * It's possible for both {@link isDefault} and {@link hasExplicitSubscription} to be true at the same time - this
+     * happens when a default stream was subscribed explicitly.
+     */
+    isDefault: boolean;
+    /**
+     * Whether this stream has been subscribed to explicitly.
+     *
+     * It's possible for both {@link isDefault} and {@link hasExplicitSubscription} to be true at the same time - this
+     * happens when a default stream was subscribed explicitly.
+     */
+    hasExplicitSubscription: boolean;
+    /**
+     * For sync streams that have a time-to-live, the current time at which the stream would expire if not subscribed to
+     * again.
+     */
+    expiresAt: Date | null;
+    /**
+     * Whether this stream subscription has been synced at least once.
+     */
+    hasSynced: boolean;
+    /**
+     * If {@link hasSynced} is true, the last time data from this stream has been synced.
+     */
+    lastSyncedAt: Date | null;
+}
+export interface SyncStreamSubscribeOptions {
+    /**
+     * A "time to live" for this stream subscription, in seconds.
+     *
+     * The TTL control when a stream gets evicted after not having an active {@link SyncStreamSubscription} object
+     * attached to it.
+     */
+    ttl?: number;
+    /**
+     * A priority to assign to this subscription. This overrides the default priority that may have been set on streams.
+     *
+     * For details on priorities, see [priotized sync](https://docs.powersync.com/usage/use-case-examples/prioritized-sync).
+     */
+    priority?: 0 | 1 | 2 | 3;
+}
+/**
+ * A handle to a {@link SyncStreamDescription} that allows subscribing to the stream.
+ *
+ * To obtain an instance of {@link SyncStream}, call {@link AbstractPowerSyncDatabase.syncStream}.
+ */
+export interface SyncStream extends SyncStreamDescription {
+    /**
+     * Adds a subscription to this stream, requesting it to be included when connecting to the sync service.
+     *
+     * You should keep a reference to the returned {@link SyncStreamSubscription} object along as you need data for that
+     * stream. As soon as {@link SyncStreamSubscription.unsubscribe} is called for all subscriptions on this stream
+     * (including subscriptions created on other tabs), the {@link SyncStreamSubscribeOptions.ttl} starts ticking and will
+     * eventually evict the stream (unless {@link subscribe} is called again).
+     */
+    subscribe(options?: SyncStreamSubscribeOptions): Promise<SyncStreamSubscription>;
+    /**
+     * Clears all subscriptions attached to this stream and resets the TTL for the stream.
+     *
+     * This is a potentially dangerous operations, as it interferes with other stream subscriptions.
+     */
+    unsubscribeAll(): Promise<void>;
+}
+export interface SyncStreamSubscription extends SyncStreamDescription {
+    /**
+     * A promise that resolves once data from in this sync stream has been synced and applied.
+     */
+    waitForFirstSync(abort?: AbortSignal): Promise<void>;
+    /**
+     * Removes this stream subscription.
+     */
+    unsubscribe(): void;
+}

package/lib/client/sync/sync-streams.js

@@ -0,0 +1 @@
+export {};

package/lib/client/watched/WatchedQuery.d.ts

@@ -65,12 +65,14 @@ export declare enum WatchedQueryListenerEvent {
     ON_DATA = "onData",
     ON_ERROR = "onError",
     ON_STATE_CHANGE = "onStateChange",
+    SETTINGS_WILL_UPDATE = "settingsWillUpdate",
     CLOSED = "closed"
 }
 export interface WatchedQueryListener<Data> extends BaseListener {
     [WatchedQueryListenerEvent.ON_DATA]?: (data: Data) => void | Promise<void>;
     [WatchedQueryListenerEvent.ON_ERROR]?: (error: Error) => void | Promise<void>;
     [WatchedQueryListenerEvent.ON_STATE_CHANGE]?: (state: WatchedQueryState<Data>) => void | Promise<void>;
+    [WatchedQueryListenerEvent.SETTINGS_WILL_UPDATE]?: () => void;
     [WatchedQueryListenerEvent.CLOSED]?: () => void | Promise<void>;
 }
 export declare const DEFAULT_WATCH_THROTTLE_MS = 30;

package/lib/client/watched/WatchedQuery.js

@@ -3,6 +3,7 @@ export var WatchedQueryListenerEvent;
     WatchedQueryListenerEvent["ON_DATA"] = "onData";
     WatchedQueryListenerEvent["ON_ERROR"] = "onError";
     WatchedQueryListenerEvent["ON_STATE_CHANGE"] = "onStateChange";
+    WatchedQueryListenerEvent["SETTINGS_WILL_UPDATE"] = "settingsWillUpdate";
     WatchedQueryListenerEvent["CLOSED"] = "closed";
 })(WatchedQueryListenerEvent || (WatchedQueryListenerEvent = {}));
 export const DEFAULT_WATCH_THROTTLE_MS = 30;

package/lib/client/watched/processors/AbstractQueryProcessor.d.ts

@@ -54,7 +54,7 @@ export declare abstract class AbstractQueryProcessor<Data = unknown[], Settings
     /**
      * Configures base DB listeners and links the query to listeners.
      */
-    protected init(): Promise<void>;
+    protected init(signal: AbortSignal): Promise<void>;
     close(): Promise<void>;
     /**
      * Runs a callback and reports errors to the error listeners.

package/lib/client/watched/processors/AbstractQueryProcessor.js

@@ -1,4 +1,5 @@
 import { MetaBaseObserver } from '../../../utils/MetaBaseObserver.js';
+import { WatchedQueryListenerEvent } from '../WatchedQuery.js';
 /**
  * Performs underlying watching and yields a stream of results.
  * @internal
@@ -20,7 +21,7 @@ export class AbstractQueryProcessor extends MetaBaseObserver {
         this._closed = false;
         this.state = this.constructInitialState();
         this.disposeListeners = null;
-        this.initialized = this.init();
+        this.initialized = this.init(this.abortController.signal);
     }
     constructInitialState() {
         return {
@@ -36,10 +37,11 @@ export class AbstractQueryProcessor extends MetaBaseObserver {
     }
     async updateSettingsInternal(settings, signal) {
         // This may have been aborted while awaiting or if multiple calls to `updateSettings` were made
-        if (signal.aborted) {
+        if (this._closed || signal.aborted) {
             return;
         }
         this.options.watchOptions = settings;
+        this.iterateListeners((l) => l[WatchedQueryListenerEvent.SETTINGS_WILL_UPDATE]?.());
         if (!this.state.isFetching && this.reportFetching) {
             await this.updateState({
                 isFetching: true
@@ -54,7 +56,7 @@ export class AbstractQueryProcessor extends MetaBaseObserver {
      * Updates the underlying query.
      */
     async updateSettings(settings) {
-        // Abort any previous requests
+        // Abort the previous request
         this.abortController.abort();
         // Keep track of this controller's abort status
         const abortController = new AbortController();
@@ -64,6 +66,9 @@ export class AbstractQueryProcessor extends MetaBaseObserver {
         return this.updateSettingsInternal(settings, abortController.signal);
     }
     async updateState(update) {
+        if (this._closed) {
+            return;
+        }
         if (typeof update.error !== 'undefined') {
             await this.iterateAsyncListenersWithError(async (l) => l.onError?.(update.error));
             // An error always stops for the current fetching state
@@ -79,7 +84,7 @@ export class AbstractQueryProcessor extends MetaBaseObserver {
     /**
      * Configures base DB listeners and links the query to listeners.
      */
-    async init() {
+    async init(signal) {
         const { db } = this.options;
         const disposeCloseListener = db.registerListener({
             closing: async () => {
@@ -101,15 +106,14 @@ export class AbstractQueryProcessor extends MetaBaseObserver {
         };
         // Initial setup
         await this.runWithReporting(async () => {
-            await this.updateSettingsInternal(this.options.watchOptions, this.abortController.signal);
+            await this.updateSettingsInternal(this.options.watchOptions, signal);
         });
     }
     async close() {
-        await this.initialized;
+        this._closed = true;
         this.abortController.abort();
         this.disposeListeners?.();
         this.disposeListeners = null;
-        this._closed = true;
         this.iterateListeners((l) => l.closed?.());
         this.listeners.clear();
     }

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

@@ -1,5 +1,7 @@
+import { CoreStreamSubscription } from '../../client/sync/stream/core-instruction.js';
 import { SyncClientImplementation } from '../../client/sync/stream/AbstractStreamingSyncImplementation.js';
-import { InternalProgressInformation, SyncProgress } from './SyncProgress.js';
+import { InternalProgressInformation, ProgressWithOperations, SyncProgress } from './SyncProgress.js';
+import { SyncStreamDescription, SyncSubscriptionDescription } from '../../client/sync/sync-streams.js';
 export type SyncDataFlowStatus = Partial<{
     downloading: boolean;
     uploading: boolean;
@@ -20,6 +22,7 @@ export type SyncDataFlowStatus = Partial<{
      * Please use the {@link SyncStatus#downloadProgress} property to track sync progress.
      */
     downloadProgress: InternalProgressInformation | null;
+    internalStreamSubscriptions: CoreStreamSubscription[] | null;
 }>;
 export interface SyncPriorityStatus {
     priority: number;
@@ -99,7 +102,23 @@ export declare class SyncStatus {
          * Please use the {@link SyncStatus#downloadProgress} property to track sync progress.
          */
         downloadProgress: InternalProgressInformation | null;
+        internalStreamSubscriptions: CoreStreamSubscription[] | null;
     }>;
+    /**
+     * All sync streams currently being tracked in teh database.
+     *
+     * This returns null when the database is currently being opened and we don't have reliable information about all
+     * included streams yet.
+     *
+     * @experimental Sync streams are currently in alpha.
+     */
+    get syncStreams(): SyncStreamStatus[] | undefined;
+    /**
+     * If the `stream` appears in {@link syncStreams}, returns the current status for that stream.
+     *
+     * @experimental Sync streams are currently in alpha.
+     */
+    forStream(stream: SyncStreamDescription): SyncStreamStatus | undefined;
     /**
      * Provides sync status information for all bucket priorities, sorted by priority (highest first).
      *
@@ -157,3 +176,11 @@ export declare class SyncStatus {
     toJSON(): SyncStatusOptions;
     private static comparePriorities;
 }
+/**
+ * Information about a sync stream subscription.
+ */
+export interface SyncStreamStatus {
+    progress: ProgressWithOperations | null;
+    subscription: SyncSubscriptionDescription;
+    priority: number | null;
+}

package/lib/db/crud/SyncStatus.js

@@ -68,6 +68,27 @@ export class SyncStatus {
             uploading: false
         });
     }
+    /**
+     * All sync streams currently being tracked in teh database.
+     *
+     * This returns null when the database is currently being opened and we don't have reliable information about all
+     * included streams yet.
+     *
+     * @experimental Sync streams are currently in alpha.
+     */
+    get syncStreams() {
+        return this.options.dataFlow?.internalStreamSubscriptions?.map((core) => new SyncStreamStatusView(this, core));
+    }
+    /**
+     * If the `stream` appears in {@link syncStreams}, returns the current status for that stream.
+     *
+     * @experimental Sync streams are currently in alpha.
+     */
+    forStream(stream) {
+        const asJson = JSON.stringify(stream.parameters);
+        const raw = this.options.dataFlow?.internalStreamSubscriptions?.find((r) => r.name == stream.name && asJson == JSON.stringify(r.parameters));
+        return raw && new SyncStreamStatusView(this, raw);
+    }
     /**
      * Provides sync status information for all bucket priorities, sorted by priority (highest first).
      *
@@ -177,3 +198,34 @@ export class SyncStatus {
         return b.priority - a.priority; // Reverse because higher priorities have lower numbers
     }
 }
+class SyncStreamStatusView {
+    status;
+    core;
+    subscription;
+    constructor(status, core) {
+        this.status = status;
+        this.core = core;
+        this.subscription = {
+            name: core.name,
+            parameters: core.parameters,
+            active: core.active,
+            isDefault: core.is_default,
+            hasExplicitSubscription: core.has_explicit_subscription,
+            expiresAt: core.expires_at != null ? new Date(core.expires_at * 1000) : null,
+            hasSynced: core.last_synced_at != null,
+            lastSyncedAt: core.last_synced_at != null ? new Date(core.last_synced_at * 1000) : null
+        };
+    }
+    get progress() {
+        if (this.status.dataFlowStatus.downloadProgress == null) {
+            // Don't make download progress public if we're not currently downloading.
+            return null;
+        }
+        const { total, downloaded } = this.core.progress;
+        const progress = total == 0 ? 0.0 : downloaded / total;
+        return { totalOperations: total, downloadedOperations: downloaded, downloadedFraction: progress };
+    }
+    get priority() {
+        return this.core.priority;
+    }
+}

package/lib/index.d.ts

@@ -18,6 +18,7 @@ export * from './client/sync/bucket/SyncDataBucket.js';
 export * from './client/sync/stream/AbstractRemote.js';
 export * from './client/sync/stream/AbstractStreamingSyncImplementation.js';
 export * from './client/sync/stream/streaming-sync-types.js';
+export * from './client/sync/sync-streams.js';
 export * from './client/ConnectionManager.js';
 export { ProgressWithOperations, SyncProgress } from './db/crud/SyncProgress.js';
 export * from './db/crud/SyncStatus.js';

package/lib/index.js

@@ -18,6 +18,7 @@ export * from './client/sync/bucket/SyncDataBucket.js';
 export * from './client/sync/stream/AbstractRemote.js';
 export * from './client/sync/stream/AbstractStreamingSyncImplementation.js';
 export * from './client/sync/stream/streaming-sync-types.js';
+export * from './client/sync/sync-streams.js';
 export * from './client/ConnectionManager.js';
 export { SyncProgress } from './db/crud/SyncProgress.js';
 export * from './db/crud/SyncStatus.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@powersync/common",
-  "version": "0.0.0-dev-20250915110424",
+  "version": "0.0.0-dev-20250922104723",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public"