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

package/dist/index.d.cts

@@ -357,6 +357,7 @@ interface Checkpoint {
     last_op_id: OpId;
     buckets: BucketChecksum[];
     write_checkpoint?: string;
+    streams?: any[];
 }
 interface BucketState {
     bucket: string;
@@ -390,6 +391,12 @@ interface BucketChecksum {
      * Count of operations - informational only.
      */
     count?: number;
+    /**
+     * The JavaScript client does not use this field, which is why it's defined to be `any`. We rely on the structure of
+     * this interface to pass custom `BucketChecksum`s to the Rust client in unit tests, which so all fields need to be
+     * present.
+     */
+    subscriptions?: any;
 }
 declare enum PSInternalTable {
     DATA = "ps_data",
@@ -404,7 +411,8 @@ declare enum PowerSyncControlCommand {
     STOP = "stop",
     START = "start",
     NOTIFY_TOKEN_REFRESHED = "refreshed_token",
-    NOTIFY_CRUD_UPLOAD_COMPLETED = "completed_upload"
+    NOTIFY_CRUD_UPLOAD_COMPLETED = "completed_upload",
+    UPDATE_SUBSCRIPTIONS = "update_subscriptions"
 }
 interface BucketStorageListener extends BaseListener {
     crudUpdate: () => void;
@@ -440,73 +448,6 @@ interface BucketStorageAdapter extends BaseObserverInterface<BucketStorageListen
     control(op: PowerSyncControlCommand, payload: string | Uint8Array | null): Promise<string>;
 }
 
-type DataStreamOptions<ParsedData, SourceData> = {
-    mapLine?: (line: SourceData) => ParsedData;
-    /**
-     * Close the stream if any consumer throws an error
-     */
-    closeOnError?: boolean;
-    pressure?: {
-        highWaterMark?: number;
-        lowWaterMark?: number;
-    };
-    logger?: ILogger;
-};
-type DataStreamCallback<Data extends any = any> = (data: Data) => Promise<void>;
-interface DataStreamListener<Data extends any = any> extends BaseListener {
-    data: (data: Data) => Promise<void>;
-    closed: () => void;
-    error: (error: Error) => void;
-    highWater: () => Promise<void>;
-    lowWater: () => Promise<void>;
-}
-declare const DEFAULT_PRESSURE_LIMITS: {
-    highWater: number;
-    lowWater: number;
-};
-/**
- * A very basic implementation of a data stream with backpressure support which does not use
- * native JS streams or async iterators.
- * This is handy for environments such as React Native which need polyfills for the above.
- */
-declare class DataStream<ParsedData, SourceData = any> extends BaseObserver<DataStreamListener<ParsedData>> {
-    protected options?: DataStreamOptions<ParsedData, SourceData> | undefined;
-    dataQueue: SourceData[];
-    protected isClosed: boolean;
-    protected processingPromise: Promise<void> | null;
-    protected notifyDataAdded: (() => void) | null;
-    protected logger: ILogger;
-    protected mapLine: (line: SourceData) => ParsedData;
-    constructor(options?: DataStreamOptions<ParsedData, SourceData> | undefined);
-    get highWatermark(): number;
-    get lowWatermark(): number;
-    get closed(): boolean;
-    close(): Promise<void>;
-    /**
-     * Enqueues data for the consumers to read
-     */
-    enqueueData(data: SourceData): void;
-    /**
-     * Reads data once from the data stream
-     * @returns a Data payload or Null if the stream closed.
-     */
-    read(): Promise<ParsedData | null>;
-    /**
-     * Executes a callback for each data item in the stream
-     */
-    forEach(callback: DataStreamCallback<ParsedData>): () => void;
-    protected processQueue(): Promise<void> | undefined;
-    protected hasDataReader(): boolean;
-    protected _processQueue(): Promise<void>;
-    protected iterateAsyncErrored(cb: (l: Partial<DataStreamListener<ParsedData>>) => Promise<void>): Promise<void>;
-}
-
-interface PowerSyncCredentials {
-    endpoint: string;
-    token: string;
-    expiresAt?: Date;
-}
-
 /**
  * For sync2.json
  */
@@ -643,6 +584,94 @@ interface CrudResponse {
     checkpoint?: OpId;
 }
 
+interface CoreStreamSubscription {
+    progress: {
+        total: number;
+        downloaded: number;
+    };
+    name: string;
+    parameters: any;
+    priority: number | null;
+    active: boolean;
+    is_default: boolean;
+    has_explicit_subscription: boolean;
+    expires_at: number | null;
+    last_synced_at: number | null;
+}
+interface BucketProgress {
+    priority: number;
+    at_last: number;
+    since_last: number;
+    target_count: number;
+}
+
+type DataStreamOptions<ParsedData, SourceData> = {
+    mapLine?: (line: SourceData) => ParsedData;
+    /**
+     * Close the stream if any consumer throws an error
+     */
+    closeOnError?: boolean;
+    pressure?: {
+        highWaterMark?: number;
+        lowWaterMark?: number;
+    };
+    logger?: ILogger;
+};
+type DataStreamCallback<Data extends any = any> = (data: Data) => Promise<void>;
+interface DataStreamListener<Data extends any = any> extends BaseListener {
+    data: (data: Data) => Promise<void>;
+    closed: () => void;
+    error: (error: Error) => void;
+    highWater: () => Promise<void>;
+    lowWater: () => Promise<void>;
+}
+declare const DEFAULT_PRESSURE_LIMITS: {
+    highWater: number;
+    lowWater: number;
+};
+/**
+ * A very basic implementation of a data stream with backpressure support which does not use
+ * native JS streams or async iterators.
+ * This is handy for environments such as React Native which need polyfills for the above.
+ */
+declare class DataStream<ParsedData, SourceData = any> extends BaseObserver<DataStreamListener<ParsedData>> {
+    protected options?: DataStreamOptions<ParsedData, SourceData> | undefined;
+    dataQueue: SourceData[];
+    protected isClosed: boolean;
+    protected processingPromise: Promise<void> | null;
+    protected notifyDataAdded: (() => void) | null;
+    protected logger: ILogger;
+    protected mapLine: (line: SourceData) => ParsedData;
+    constructor(options?: DataStreamOptions<ParsedData, SourceData> | undefined);
+    get highWatermark(): number;
+    get lowWatermark(): number;
+    get closed(): boolean;
+    close(): Promise<void>;
+    /**
+     * Enqueues data for the consumers to read
+     */
+    enqueueData(data: SourceData): void;
+    /**
+     * Reads data once from the data stream
+     * @returns a Data payload or Null if the stream closed.
+     */
+    read(): Promise<ParsedData | null>;
+    /**
+     * Executes a callback for each data item in the stream
+     */
+    forEach(callback: DataStreamCallback<ParsedData>): () => void;
+    protected processQueue(): Promise<void> | undefined;
+    protected hasDataReader(): boolean;
+    protected _processQueue(): Promise<void>;
+    protected iterateAsyncErrored(cb: (l: Partial<DataStreamListener<ParsedData>>) => Promise<void>): Promise<void>;
+}
+
+interface PowerSyncCredentials {
+    endpoint: string;
+    token: string;
+    expiresAt?: Date;
+}
+
 type BSONImplementation = typeof BSON;
 type RemoteConnector = {
     fetchCredentials: () => Promise<PowerSyncCredentials | null>;
@@ -831,8 +860,9 @@ interface LockOptions<T> {
     type: LockType;
     signal?: AbortSignal;
 }
-interface AbstractStreamingSyncImplementationOptions extends AdditionalConnectionOptions {
+interface AbstractStreamingSyncImplementationOptions extends RequiredAdditionalConnectionOptions {
     adapter: BucketStorageAdapter;
+    subscriptions: SubscribedStream[];
     uploadCrud: () => Promise<void>;
     /**
      * An identifier for which PowerSync DB this sync implementation is
@@ -884,6 +914,12 @@ interface BaseConnectionOptions {
      * These parameters are passed to the sync rules, and will be available under the`user_parameters` object.
      */
     params?: Record<string, StreamingSyncRequestParameterType>;
+    /**
+     * Whether to include streams that have `auto_subscribe: true` in their definition.
+     *
+     * This defaults to `true`.
+     */
+    includeDefaultStreams?: boolean;
     /**
      * The serialized schema - mainly used to forward information about raw tables to the sync client.
      */
@@ -904,7 +940,9 @@ interface AdditionalConnectionOptions {
     crudUploadThrottleMs?: number;
 }
 /** @internal */
-type RequiredAdditionalConnectionOptions = Required<AdditionalConnectionOptions>;
+interface RequiredAdditionalConnectionOptions extends Required<AdditionalConnectionOptions> {
+    subscriptions: SubscribedStream[];
+}
 interface StreamingSyncImplementation extends BaseObserverInterface<StreamingSyncImplementationListener>, Disposable {
     /**
      * Connects to the sync service
@@ -924,6 +962,7 @@ interface StreamingSyncImplementation extends BaseObserverInterface<StreamingSyn
     waitForReady(): Promise<void>;
     waitForStatus(status: SyncStatusOptions): Promise<void>;
     waitUntilStatusMatches(predicate: (status: SyncStatus) => boolean): Promise<void>;
+    updateSubscriptions(subscriptions: SubscribedStream[]): void;
 }
 declare const DEFAULT_CRUD_UPLOAD_THROTTLE_MS = 1000;
 declare const DEFAULT_RETRY_DELAY_MS = 5000;
@@ -933,6 +972,10 @@ declare const DEFAULT_STREAMING_SYNC_OPTIONS: {
 };
 type RequiredPowerSyncConnectionOptions = Required<BaseConnectionOptions>;
 declare const DEFAULT_STREAM_CONNECTION_OPTIONS: RequiredPowerSyncConnectionOptions;
+type SubscribedStream = {
+    name: string;
+    params: Record<string, any> | null;
+};
 declare abstract class AbstractStreamingSyncImplementation extends BaseObserver<StreamingSyncImplementationListener> implements StreamingSyncImplementation {
     protected _lastSyncedAt: Date | null;
     protected options: AbstractStreamingSyncImplementationOptions;
@@ -941,8 +984,10 @@ declare abstract class AbstractStreamingSyncImplementation extends BaseObserver<
     protected crudUpdateListener?: () => void;
     protected streamingSyncPromise?: Promise<void>;
     protected logger: ILogger;
+    private activeStreams;
     private isUploadingCrud;
     private notifyCompletedUploads?;
+    private handleActiveStreamsChange?;
     syncStatus: SyncStatus;
     triggerCrudUpload: () => void;
     constructor(options: AbstractStreamingSyncImplementationOptions);
@@ -979,20 +1024,17 @@ declare abstract class AbstractStreamingSyncImplementation extends BaseObserver<
      * @returns Whether the database is now using the new, fixed subkey format.
      */
     private requireKeyFormat;
-    protected streamingSyncIteration(signal: AbortSignal, options?: PowerSyncConnectionOptions): Promise<void>;
+    protected streamingSyncIteration(signal: AbortSignal, options?: PowerSyncConnectionOptions): Promise<RustIterationResult | null>;
     private legacyStreamingSyncIteration;
     private rustSyncIteration;
     private updateSyncStatusForStartingCheckpoint;
     private applyCheckpoint;
     protected updateSyncStatus(options: SyncStatusOptions): void;
     private delayRetry;
+    updateSubscriptions(subscriptions: SubscribedStream[]): void;
 }
-
-interface BucketProgress {
-    priority: number;
-    at_last: number;
-    since_last: number;
-    target_count: number;
+interface RustIterationResult {
+    immediateRestart: boolean;
 }
 
 /** @internal */
@@ -1059,6 +1101,105 @@ declare class SyncProgress implements ProgressWithOperations {
     untilPriority(priority: number): ProgressWithOperations;
 }
 
+/**
+ * A description of a sync stream, consisting of its {@link name} and the {@link parameters} used when subscribing.
+ */
+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.
+ */
+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;
+}
+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}.
+ */
+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>;
+}
+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;
+}
+
 type SyncDataFlowStatus = Partial<{
     downloading: boolean;
     uploading: boolean;
@@ -1079,6 +1220,7 @@ type SyncDataFlowStatus = Partial<{
      * Please use the {@link SyncStatus#downloadProgress} property to track sync progress.
      */
     downloadProgress: InternalProgressInformation | null;
+    internalStreamSubscriptions: CoreStreamSubscription[] | null;
 }>;
 interface SyncPriorityStatus {
     priority: number;
@@ -1158,7 +1300,23 @@ 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).
      *
@@ -1216,6 +1374,14 @@ declare class SyncStatus {
     toJSON(): SyncStatusOptions;
     private static comparePriorities;
 }
+/**
+ * Information about a sync stream subscription.
+ */
+interface SyncStreamStatus {
+    progress: ProgressWithOperations | null;
+    subscription: SyncSubscriptionDescription;
+    priority: number | null;
+}
 
 declare class UploadQueueStats {
     /**
@@ -1618,11 +1784,24 @@ interface ConnectionManagerSyncImplementationResult {
      */
     onDispose: () => Promise<void> | void;
 }
+/**
+ * The subset of {@link AbstractStreamingSyncImplementationOptions} managed by the connection manager.
+ *
+ * @internal
+ */
+interface CreateSyncImplementationOptions extends AdditionalConnectionOptions {
+    subscriptions: SubscribedStream[];
+}
+interface InternalSubscriptionAdapter {
+    firstStatusMatching(predicate: (status: SyncStatus) => any, abort?: AbortSignal): Promise<void>;
+    resolveOfflineSyncStatus(): Promise<void>;
+    rustSubscriptionsCommand(payload: any): Promise<void>;
+}
 /**
  * @internal
  */
 interface ConnectionManagerOptions {
-    createSyncImplementation(connector: PowerSyncBackendConnector, options: InternalConnectionOptions): Promise<ConnectionManagerSyncImplementationResult>;
+    createSyncImplementation(connector: PowerSyncBackendConnector, options: CreateSyncImplementationOptions): Promise<ConnectionManagerSyncImplementationResult>;
     logger: ILogger;
 }
 type StoredConnectionOptions = {
@@ -1668,6 +1847,12 @@ declare class ConnectionManager extends BaseObserver<ConnectionManagerListener>
      * is disposed.
      */
     protected syncDisposer: (() => Promise<void> | void) | null;
+    /**
+     * Subscriptions managed in this connection manager.
+     *
+     * On the web, these local subscriptions are merged across tabs by a shared worker.
+     */
+    private locallyActiveSubscriptions;
     constructor(options: ConnectionManagerOptions);
     get logger(): ILogger;
     close(): Promise<void>;
@@ -1681,6 +1866,9 @@ declare class ConnectionManager extends BaseObserver<ConnectionManagerListener>
     disconnect(): Promise<void>;
     protected disconnectInternal(): Promise<void>;
     protected performDisconnect(): Promise<void>;
+    stream(adapter: InternalSubscriptionAdapter, name: string, parameters: Record<string, any> | null): SyncStream;
+    private get activeStreams();
+    private subscriptionsMayHaveChanged;
 }
 
 /**
@@ -1815,12 +2003,14 @@ declare enum WatchedQueryListenerEvent {
     ON_DATA = "onData",
     ON_ERROR = "onError",
     ON_STATE_CHANGE = "onStateChange",
+    SETTINGS_WILL_UPDATE = "settingsWillUpdate",
     CLOSED = "closed"
 }
 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>;
 }
 declare const DEFAULT_WATCH_THROTTLE_MS = 30;
@@ -1900,7 +2090,7 @@ declare abstract class AbstractQueryProcessor<Data = unknown[], Settings extends
     /**
      * 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.
@@ -2701,6 +2891,7 @@ declare abstract class AbstractPowerSyncDatabase extends BaseObserver<PowerSyncD
     protected bucketStorageAdapter: BucketStorageAdapter;
     protected _isReadyPromise: Promise<void>;
     protected connectionManager: ConnectionManager;
+    private subscriptions;
     get syncStreamImplementation(): StreamingSyncImplementation | null;
     protected _schema: Schema;
     private _database;
@@ -2736,7 +2927,7 @@ declare abstract class AbstractPowerSyncDatabase extends BaseObserver<PowerSyncD
      * Opens the DBAdapter given open options using a default open factory
      */
     protected abstract openDBAdapter(options: PowerSyncDatabaseOptionsWithSettings): DBAdapter;
-    protected abstract generateSyncStreamImplementation(connector: PowerSyncBackendConnector, options: RequiredAdditionalConnectionOptions): StreamingSyncImplementation;
+    protected abstract generateSyncStreamImplementation(connector: PowerSyncBackendConnector, options: CreateSyncImplementationOptions & RequiredAdditionalConnectionOptions): StreamingSyncImplementation;
     protected abstract generateBucketStorageAdapter(): BucketStorageAdapter;
     /**
      * @returns A promise which will resolve once initialization is completed.
@@ -2755,6 +2946,7 @@ declare abstract class AbstractPowerSyncDatabase extends BaseObserver<PowerSyncD
         signal?: AbortSignal;
         priority?: number;
     }): Promise<void>;
+    private waitForStatus;
     /**
      * Allows for extended implementations to execute custom initialization
      * logic as part of the total init process
@@ -2766,7 +2958,7 @@ declare abstract class AbstractPowerSyncDatabase extends BaseObserver<PowerSyncD
      */
     protected initialize(): Promise<void>;
     private _loadVersion;
-    protected updateHasSynced(): Promise<void>;
+    protected resolveOfflineSyncStatus(): Promise<void>;
     /**
      * Replace the schema with a new version. This is for advanced use cases - typically the schema should just be specified once in the constructor.
      *
@@ -2778,7 +2970,7 @@ declare abstract class AbstractPowerSyncDatabase extends BaseObserver<PowerSyncD
      * While initializing is automatic, this helps to catch and report initialization errors.
      */
     init(): Promise<void>;
-    resolvedConnectionOptions(options?: PowerSyncConnectionOptions): RequiredAdditionalConnectionOptions;
+    protected resolvedConnectionOptions(options: CreateSyncImplementationOptions): CreateSyncImplementationOptions & RequiredAdditionalConnectionOptions;
     /**
      * @deprecated Use {@link AbstractPowerSyncDatabase#close} instead.
      * Clears all listeners registered by {@link AbstractPowerSyncDatabase#registerListener}.
@@ -2808,6 +3000,15 @@ declare abstract class AbstractPowerSyncDatabase extends BaseObserver<PowerSyncD
      * To preserve data in local-only tables, set clearLocal to false.
      */
     disconnectAndClear(options?: DisconnectAndClearOptions): Promise<void>;
+    /**
+     * Create a sync stream to query its status or to subscribe to it.
+     *
+     * @param name The name of the stream to subscribe to.
+     * @param params Optional parameters for the stream subscription.
+     * @returns A {@link SyncStream} instance that can be subscribed to.
+     * @experimental Sync streams are currently in alpha.
+     */
+    syncStream(name: string, params?: Record<string, any>): SyncStream;
     /**
      * Close the database, releasing resources.
      *
@@ -3374,4 +3575,4 @@ interface ParsedQuery {
 declare const parseQuery: <T>(query: string | CompilableQuery<T>, parameters: any[]) => ParsedQuery;
 
 export { AbortOperation, AbstractPowerSyncDatabase, AbstractPowerSyncDatabaseOpenFactory, AbstractQueryProcessor, AbstractRemote, AbstractStreamingSyncImplementation, ArrayComparator, BaseObserver, Column, ColumnType, ConnectionManager, ControlledExecutor, CrudBatch, CrudEntry, CrudTransaction, DEFAULT_CRUD_BATCH_LIMIT, DEFAULT_CRUD_UPLOAD_THROTTLE_MS, DEFAULT_INDEX_COLUMN_OPTIONS, DEFAULT_INDEX_OPTIONS, DEFAULT_LOCK_TIMEOUT_MS, DEFAULT_POWERSYNC_CLOSE_OPTIONS, DEFAULT_POWERSYNC_DB_OPTIONS, DEFAULT_PRESSURE_LIMITS, DEFAULT_REMOTE_LOGGER, DEFAULT_REMOTE_OPTIONS, DEFAULT_RETRY_DELAY_MS, DEFAULT_ROW_COMPARATOR, DEFAULT_STREAMING_SYNC_OPTIONS, DEFAULT_STREAM_CONNECTION_OPTIONS, DEFAULT_SYNC_CLIENT_IMPLEMENTATION, DEFAULT_TABLE_OPTIONS, DEFAULT_WATCH_QUERY_OPTIONS, DEFAULT_WATCH_THROTTLE_MS, DataStream, DiffTriggerOperation, DifferentialQueryProcessor, EMPTY_DIFFERENTIAL, FalsyComparator, FetchImplementationProvider, FetchStrategy, GetAllQuery, Index, IndexedColumn, InvalidSQLCharacters, LockType, LogLevel, MAX_AMOUNT_OF_COLUMNS, MAX_OP_ID, OnChangeQueryProcessor, OpType, OpTypeEnum, OplogEntry, PSInternalTable, PowerSyncControlCommand, RowUpdateType, Schema, SqliteBucketStorage, SyncClientImplementation, SyncDataBatch, SyncDataBucket, SyncProgress, SyncStatus, SyncStreamConnectionMethod, Table, TableV2, UpdateType, UploadQueueStats, WatchedQueryListenerEvent, column, compilableQueryWatch, createBaseLogger, createLogger, extractTableUpdates, isBatchedUpdateNotification, isContinueCheckpointRequest, isDBAdapter, isPowerSyncDatabaseOptionsWithSettings, isSQLOpenFactory, isSQLOpenOptions, isStreamingKeepalive, isStreamingSyncCheckpoint, isStreamingSyncCheckpointComplete, isStreamingSyncCheckpointDiff, isStreamingSyncCheckpointPartiallyComplete, isStreamingSyncData, isSyncNewCheckpointRequest, parseQuery, runOnSchemaChange, sanitizeSQL, sanitizeUUID };
-export type { AbstractQueryProcessorOptions, AbstractRemoteOptions, AbstractStreamingSyncImplementationOptions, AdditionalConnectionOptions, ArrayComparatorOptions, ArrayQueryDefinition, BSONImplementation, BaseColumnType, BaseConnectionOptions, BaseListener, BaseObserverInterface, BasePowerSyncDatabaseOptions, BaseTriggerDiffRecord, BatchedUpdateNotification, BucketChecksum, BucketDescription, BucketOperationProgress, BucketRequest, BucketState, BucketStorageAdapter, BucketStorageListener, Checkpoint, ChecksumCache, ColumnOptions, ColumnsType, CompilableQuery, CompilableQueryWatchHandler, CompiledQuery, ConnectionManagerListener, ConnectionManagerOptions, ConnectionManagerSyncImplementationResult, ContinueCheckpointRequest, ControlledExecutorOptions, CreateDiffTriggerOptions, CreateLoggerOptions, CrudRequest, CrudResponse, CrudUploadNotification, DBAdapter, DBAdapterListener, DBGetUtils, DBLockOptions, DataStreamCallback, DataStreamListener, DataStreamOptions, DifferentialQueryProcessorOptions, DifferentialWatchedQuery, DifferentialWatchedQueryComparator, DifferentialWatchedQueryListener, DifferentialWatchedQueryOptions, DifferentialWatchedQuerySettings, DisconnectAndClearOptions, Disposable, ExtractColumnValueType, ExtractedTriggerDiffRecord, FetchImplementation, GetAllQueryOptions, IndexColumnOptions, IndexOptions, IndexShorthand, InternalConnectionOptions, LinkQueryOptions, LockContext, LockOptions, MutableWatchedQueryState, OnChangeQueryProcessorOptions, OpId, OpTypeJSON, OplogEntryJSON, ParsedQuery, PowerSyncBackendConnector, PowerSyncCloseOptions, PowerSyncConnectionOptions, PowerSyncCredentials, PowerSyncDBListener, PowerSyncDatabaseOptions, PowerSyncDatabaseOptionsWithDBAdapter, PowerSyncDatabaseOptionsWithOpenFactory, PowerSyncDatabaseOptionsWithSettings, PowerSyncOpenFactoryOptions, ProgressWithOperations, Query, QueryParam, QueryResult, RemoteConnector, RequiredAdditionalConnectionOptions, RequiredPowerSyncConnectionOptions, RowType, SQLOnChangeOptions, SQLOpenFactory, SQLOpenOptions, SQLWatchOptions, SavedProgress, SchemaTableType, SocketSyncStreamOptions, StandardWatchedQuery, StandardWatchedQueryOptions, StreamingSyncCheckpoint, StreamingSyncCheckpointComplete, StreamingSyncCheckpointDiff, StreamingSyncCheckpointPartiallyComplete, StreamingSyncDataJSON, StreamingSyncImplementation, StreamingSyncImplementationListener, StreamingSyncKeepalive, StreamingSyncLine, StreamingSyncLineOrCrudUploadComplete, StreamingSyncRequest, StreamingSyncRequestParameterType, SyncDataBucketJSON, SyncDataFlowStatus, SyncLocalDatabaseResult, SyncNewCheckpointRequest, SyncPriorityStatus, SyncRequest, SyncResponse, SyncStatusOptions, SyncStreamOptions, TableOptions, TableUpdateOperation, TableV2Options, TrackDiffOptions, TrackPreviousOptions, Transaction, TriggerCreationHooks, TriggerDiffDeleteRecord, TriggerDiffHandlerContext, TriggerDiffInsertRecord, TriggerDiffRecord, TriggerDiffUpdateRecord, TriggerManager, TriggerRemoveCallback, UpdateNotification, WatchCompatibleQuery, WatchExecuteOptions, WatchHandler, WatchOnChangeEvent, WatchOnChangeHandler, WatchedQuery, WatchedQueryComparator, WatchedQueryDifferential, WatchedQueryListener, WatchedQueryOptions, WatchedQueryRowDifferential, WatchedQuerySettings, WatchedQueryState };
+export type { AbstractQueryProcessorOptions, AbstractRemoteOptions, AbstractStreamingSyncImplementationOptions, AdditionalConnectionOptions, ArrayComparatorOptions, ArrayQueryDefinition, BSONImplementation, BaseColumnType, BaseConnectionOptions, BaseListener, BaseObserverInterface, BasePowerSyncDatabaseOptions, BaseTriggerDiffRecord, BatchedUpdateNotification, BucketChecksum, BucketDescription, BucketOperationProgress, BucketRequest, BucketState, BucketStorageAdapter, BucketStorageListener, Checkpoint, ChecksumCache, ColumnOptions, ColumnsType, CompilableQuery, CompilableQueryWatchHandler, CompiledQuery, ConnectionManagerListener, ConnectionManagerOptions, ConnectionManagerSyncImplementationResult, ContinueCheckpointRequest, ControlledExecutorOptions, CreateDiffTriggerOptions, CreateLoggerOptions, CreateSyncImplementationOptions, CrudRequest, CrudResponse, CrudUploadNotification, DBAdapter, DBAdapterListener, DBGetUtils, DBLockOptions, DataStreamCallback, DataStreamListener, DataStreamOptions, DifferentialQueryProcessorOptions, DifferentialWatchedQuery, DifferentialWatchedQueryComparator, DifferentialWatchedQueryListener, DifferentialWatchedQueryOptions, DifferentialWatchedQuerySettings, DisconnectAndClearOptions, Disposable, ExtractColumnValueType, ExtractedTriggerDiffRecord, FetchImplementation, GetAllQueryOptions, IndexColumnOptions, IndexOptions, IndexShorthand, InternalConnectionOptions, InternalSubscriptionAdapter, LinkQueryOptions, LockContext, LockOptions, MutableWatchedQueryState, OnChangeQueryProcessorOptions, OpId, OpTypeJSON, OplogEntryJSON, ParsedQuery, PowerSyncBackendConnector, PowerSyncCloseOptions, PowerSyncConnectionOptions, PowerSyncCredentials, PowerSyncDBListener, PowerSyncDatabaseOptions, PowerSyncDatabaseOptionsWithDBAdapter, PowerSyncDatabaseOptionsWithOpenFactory, PowerSyncDatabaseOptionsWithSettings, PowerSyncOpenFactoryOptions, ProgressWithOperations, Query, QueryParam, QueryResult, RemoteConnector, RequiredAdditionalConnectionOptions, RequiredPowerSyncConnectionOptions, RowType, SQLOnChangeOptions, SQLOpenFactory, SQLOpenOptions, SQLWatchOptions, SavedProgress, SchemaTableType, SocketSyncStreamOptions, StandardWatchedQuery, StandardWatchedQueryOptions, StreamingSyncCheckpoint, StreamingSyncCheckpointComplete, StreamingSyncCheckpointDiff, StreamingSyncCheckpointPartiallyComplete, StreamingSyncDataJSON, StreamingSyncImplementation, StreamingSyncImplementationListener, StreamingSyncKeepalive, StreamingSyncLine, StreamingSyncLineOrCrudUploadComplete, StreamingSyncRequest, StreamingSyncRequestParameterType, SubscribedStream, SyncDataBucketJSON, SyncDataFlowStatus, SyncLocalDatabaseResult, SyncNewCheckpointRequest, SyncPriorityStatus, SyncRequest, SyncResponse, SyncStatusOptions, SyncStream, SyncStreamDescription, SyncStreamOptions, SyncStreamStatus, SyncStreamSubscribeOptions, SyncStreamSubscription, SyncSubscriptionDescription, TableOptions, TableUpdateOperation, TableV2Options, TrackDiffOptions, TrackPreviousOptions, Transaction, TriggerCreationHooks, TriggerDiffDeleteRecord, TriggerDiffHandlerContext, TriggerDiffInsertRecord, TriggerDiffRecord, TriggerDiffUpdateRecord, TriggerManager, TriggerRemoveCallback, UpdateNotification, WatchCompatibleQuery, WatchExecuteOptions, WatchHandler, WatchOnChangeEvent, WatchOnChangeHandler, WatchedQuery, WatchedQueryComparator, WatchedQueryDifferential, WatchedQueryListener, WatchedQueryOptions, WatchedQueryRowDifferential, WatchedQuerySettings, WatchedQueryState };

package/lib/client/AbstractPowerSyncDatabase.d.ts

@@ -5,7 +5,7 @@ import { SyncStatus } from '../db/crud/SyncStatus.js';
 import { UploadQueueStats } from '../db/crud/UploadQueueStatus.js';
 import { Schema } from '../db/schema/Schema.js';
 import { BaseObserver } from '../utils/BaseObserver.js';
-import { ConnectionManager } from './ConnectionManager.js';
+import { ConnectionManager, CreateSyncImplementationOptions } from './ConnectionManager.js';
 import { ArrayQueryDefinition, Query } from './Query.js';
 import { SQLOpenFactory, SQLOpenOptions } from './SQLOpenFactory.js';
 import { PowerSyncBackendConnector } from './connection/PowerSyncBackendConnector.js';
@@ -16,6 +16,7 @@ import { StreamingSyncImplementation, StreamingSyncImplementationListener, type
 import { TriggerManager } from './triggers/TriggerManager.js';
 import { WatchCompatibleQuery } from './watched/WatchedQuery.js';
 import { WatchedQueryComparator } from './watched/processors/comparators.js';
+import { SyncStream } from './sync/sync-streams.js';
 export interface DisconnectAndClearOptions {
     /** When set to false, data in local-only tables is preserved. */
     clearLocal?: boolean;
@@ -129,6 +130,7 @@ export declare abstract class AbstractPowerSyncDatabase extends BaseObserver<Pow
     protected bucketStorageAdapter: BucketStorageAdapter;
     protected _isReadyPromise: Promise<void>;
     protected connectionManager: ConnectionManager;
+    private subscriptions;
     get syncStreamImplementation(): StreamingSyncImplementation | null;
     protected _schema: Schema;
     private _database;
@@ -164,7 +166,7 @@ export declare abstract class AbstractPowerSyncDatabase extends BaseObserver<Pow
      * Opens the DBAdapter given open options using a default open factory
      */
     protected abstract openDBAdapter(options: PowerSyncDatabaseOptionsWithSettings): DBAdapter;
-    protected abstract generateSyncStreamImplementation(connector: PowerSyncBackendConnector, options: RequiredAdditionalConnectionOptions): StreamingSyncImplementation;
+    protected abstract generateSyncStreamImplementation(connector: PowerSyncBackendConnector, options: CreateSyncImplementationOptions & RequiredAdditionalConnectionOptions): StreamingSyncImplementation;
     protected abstract generateBucketStorageAdapter(): BucketStorageAdapter;
     /**
      * @returns A promise which will resolve once initialization is completed.
@@ -183,6 +185,7 @@ export declare abstract class AbstractPowerSyncDatabase extends BaseObserver<Pow
         signal?: AbortSignal;
         priority?: number;
     }): Promise<void>;
+    private waitForStatus;
     /**
      * Allows for extended implementations to execute custom initialization
      * logic as part of the total init process
@@ -194,7 +197,7 @@ export declare abstract class AbstractPowerSyncDatabase extends BaseObserver<Pow
      */
     protected initialize(): Promise<void>;
     private _loadVersion;
-    protected updateHasSynced(): Promise<void>;
+    protected resolveOfflineSyncStatus(): Promise<void>;
     /**
      * Replace the schema with a new version. This is for advanced use cases - typically the schema should just be specified once in the constructor.
      *
@@ -206,7 +209,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;
+    protected resolvedConnectionOptions(options: CreateSyncImplementationOptions): CreateSyncImplementationOptions & RequiredAdditionalConnectionOptions;
     /**
      * @deprecated Use {@link AbstractPowerSyncDatabase#close} instead.
      * Clears all listeners registered by {@link AbstractPowerSyncDatabase#registerListener}.
@@ -236,6 +239,15 @@ export declare abstract class AbstractPowerSyncDatabase extends BaseObserver<Pow
      * To preserve data in local-only tables, set clearLocal to false.
      */
     disconnectAndClear(options?: DisconnectAndClearOptions): Promise<void>;
+    /**
+     * Create a sync stream to query its status or to subscribe to it.
+     *
+     * @param name The name of the stream to subscribe to.
+     * @param params Optional parameters for the stream subscription.
+     * @returns A {@link SyncStream} instance that can be subscribed to.
+     * @experimental Sync streams are currently in alpha.
+     */
+    syncStream(name: string, params?: Record<string, any>): SyncStream;
     /**
      * Close the database, releasing resources.
      *