@powersync/common 0.0.0-dev-20250714144421 → 0.0.0-dev-20250715080712

package/lib/client/sync/bucket/SqliteBucketStorage.js

@@ -64,11 +64,11 @@ export class SqliteBucketStorage extends BaseObserver {
     async saveSyncData(batch, fixedKeyFormat = false) {
         await this.writeTransaction(async (tx) => {
             for (const b of batch.buckets) {
-                await tx.execute('INSERT INTO powersync_operations(op, data) VALUES(?, ?)', [
+                const result = await tx.execute('INSERT INTO powersync_operations(op, data) VALUES(?, ?)', [
                     'save',
                     JSON.stringify({ buckets: [b.toJSON(fixedKeyFormat)] })
                 ]);
-                this.logger.debug(`Saved batch of data for  bucket: ${b.bucket}, operations: ${b.data.length}`);
+                this.logger.debug('saveSyncData', JSON.stringify(result));
             }
         });
     }
@@ -84,7 +84,7 @@ export class SqliteBucketStorage extends BaseObserver {
         await this.writeTransaction(async (tx) => {
             await tx.execute('INSERT INTO powersync_operations(op, data) VALUES(?, ?)', ['delete_bucket', bucket]);
         });
-        this.logger.debug(`Done deleting bucket ${bucket}`);
+        this.logger.debug('done deleting bucket');
     }
     async hasCompletedSync() {
         if (this._hasCompletedSync) {
@@ -106,12 +106,6 @@ export class SqliteBucketStorage extends BaseObserver {
             }
             return { ready: false, checkpointValid: false, checkpointFailures: r.checkpointFailures };
         }
-        if (priority == null) {
-            this.logger.debug(`Validated checksums checkpoint ${checkpoint.last_op_id}`);
-        }
-        else {
-            this.logger.debug(`Validated checksums for partial checkpoint ${checkpoint.last_op_id}, priority ${priority}`);
-        }
         let buckets = checkpoint.buckets;
         if (priority !== undefined) {
             buckets = buckets.filter((b) => hasMatchingPriority(priority, b));
@@ -128,6 +122,7 @@ export class SqliteBucketStorage extends BaseObserver {
         });
         const valid = await this.updateObjectsFromBuckets(checkpoint, priority);
         if (!valid) {
+            this.logger.debug('Not at a consistent checkpoint - cannot update local db');
             return { ready: false, checkpointValid: true };
         }
         return {
@@ -180,6 +175,7 @@ export class SqliteBucketStorage extends BaseObserver {
             JSON.stringify({ ...checkpoint })
         ]);
         const resultItem = rs.rows?.item(0);
+        this.logger.debug('validateChecksums priority, checkpoint, result item', priority, checkpoint, resultItem);
         if (!resultItem) {
             return {
                 checkpointValid: false,
@@ -212,26 +208,30 @@ export class SqliteBucketStorage extends BaseObserver {
         }
         const seqBefore = rs[0]['seq'];
         const opId = await cb();
+        this.logger.debug(`[updateLocalTarget] Updating target to checkpoint ${opId}`);
         return this.writeTransaction(async (tx) => {
             const anyData = await tx.execute('SELECT 1 FROM ps_crud LIMIT 1');
             if (anyData.rows?.length) {
                 // if isNotEmpty
-                this.logger.debug(`New data uploaded since write checkpoint ${opId} - need new write checkpoint`);
+                this.logger.debug('updateLocalTarget', 'ps crud is not empty');
                 return false;
             }
             const rs = await tx.execute("SELECT seq FROM sqlite_sequence WHERE name = 'ps_crud'");
             if (!rs.rows?.length) {
                 // assert isNotEmpty
-                throw new Error('SQLite Sequence should not be empty');
+                throw new Error('SQlite Sequence should not be empty');
             }
             const seqAfter = rs.rows?.item(0)['seq'];
+            this.logger.debug('seqAfter', JSON.stringify(rs.rows?.item(0)));
             if (seqAfter != seqBefore) {
-                this.logger.debug(`New data uploaded since write checpoint ${opId} - need new write checkpoint (sequence updated)`);
+                this.logger.debug('seqAfter != seqBefore', seqAfter, seqBefore);
                 // New crud data may have been uploaded since we got the checkpoint. Abort.
                 return false;
             }
-            this.logger.debug(`Updating target write checkpoint to ${opId}`);
-            await tx.execute("UPDATE ps_buckets SET target_op = CAST(? as INTEGER) WHERE name='$local'", [opId]);
+            const response = await tx.execute("UPDATE ps_buckets SET target_op = CAST(? as INTEGER) WHERE name='$local'", [
+                opId
+            ]);
+            this.logger.debug(['[updateLocalTarget] Response from updating target_op ', JSON.stringify(response)]);
             return true;
         });
     }

package/lib/client/sync/stream/AbstractStreamingSyncImplementation.d.ts

@@ -1,6 +1,6 @@
 import Logger, { ILogger } from 'js-logger';
 import { SyncStatus, SyncStatusOptions } from '../../../db/crud/SyncStatus.js';
-import { BaseListener, BaseObserver, Disposable } from '../../../utils/BaseObserver.js';
+import { BaseListener, BaseObserver, BaseObserverInterface, Disposable } from '../../../utils/BaseObserver.js';
 import { BucketStorageAdapter } from '../bucket/BucketStorageAdapter.js';
 import { AbstractRemote, FetchStrategy } from './AbstractRemote.js';
 import { StreamingSyncRequestParameterType } from './streaming-sync-types.js';
@@ -88,7 +88,8 @@ export interface StreamingSyncImplementationListener extends BaseListener {
  * Configurable options to be used when connecting to the PowerSync
  * backend instance.
  */
-export interface PowerSyncConnectionOptions extends BaseConnectionOptions, AdditionalConnectionOptions {
+export type PowerSyncConnectionOptions = Omit<InternalConnectionOptions, 'serializedSchema'>;
+export interface InternalConnectionOptions extends BaseConnectionOptions, AdditionalConnectionOptions {
 }
 /** @internal */
 export interface BaseConnectionOptions {
@@ -114,6 +115,10 @@ export interface BaseConnectionOptions {
      * These parameters are passed to the sync rules, and will be available under the`user_parameters` object.
      */
     params?: Record<string, StreamingSyncRequestParameterType>;
+    /**
+     * The serialized schema - mainly used to forward information about raw tables to the sync client.
+     */
+    serializedSchema?: any;
 }
 /** @internal */
 export interface AdditionalConnectionOptions {
@@ -131,11 +136,11 @@ export interface AdditionalConnectionOptions {
 }
 /** @internal */
 export type RequiredAdditionalConnectionOptions = Required<AdditionalConnectionOptions>;
-export interface StreamingSyncImplementation extends BaseObserver<StreamingSyncImplementationListener>, Disposable {
+export interface StreamingSyncImplementation extends BaseObserverInterface<StreamingSyncImplementationListener>, Disposable {
     /**
      * Connects to the sync service
      */
-    connect(options?: PowerSyncConnectionOptions): Promise<void>;
+    connect(options?: InternalConnectionOptions): Promise<void>;
     /**
      * Disconnects from the sync services.
      * @throws if not connected or if abort is not controlled internally
@@ -164,6 +169,7 @@ export declare abstract class AbstractStreamingSyncImplementation extends BaseOb
     protected _lastSyncedAt: Date | null;
     protected options: AbstractStreamingSyncImplementationOptions;
     protected abortController: AbortController | null;
+    protected uploadAbortController: AbortController | null;
     protected crudUpdateListener?: () => void;
     protected streamingSyncPromise?: Promise<void>;
     private isUploadingCrud;

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

@@ -1,6 +1,6 @@
 import Logger from 'js-logger';
-import { SyncStatus } from '../../../db/crud/SyncStatus.js';
 import { FULL_SYNC_PRIORITY } from '../../../db/crud/SyncProgress.js';
+import { SyncStatus } from '../../../db/crud/SyncStatus.js';
 import { AbortOperation } from '../../../utils/AbortOperation.js';
 import { BaseObserver } from '../../../utils/BaseObserver.js';
 import { throttleLeadingTrailing } from '../../../utils/async.js';
@@ -72,7 +72,8 @@ export const DEFAULT_STREAM_CONNECTION_OPTIONS = {
     connectionMethod: SyncStreamConnectionMethod.WEB_SOCKET,
     clientImplementation: DEFAULT_SYNC_CLIENT_IMPLEMENTATION,
     fetchStrategy: FetchStrategy.Buffered,
-    params: {}
+    params: {},
+    serializedSchema: undefined
 };
 // The priority we assume when we receive checkpoint lines where no priority is set.
 // This is the default priority used by the sync service, but can be set to an arbitrary
@@ -83,6 +84,9 @@ export class AbstractStreamingSyncImplementation extends BaseObserver {
     _lastSyncedAt;
     options;
     abortController;
+    // In rare cases, mostly for tests, uploads can be triggered without being properly connected.
+    // This allows ensuring that all upload processes can be aborted.
+    uploadAbortController;
     crudUpdateListener;
     streamingSyncPromise;
     isUploadingCrud = false;
@@ -159,8 +163,10 @@ export class AbstractStreamingSyncImplementation extends BaseObserver {
         return this.options.logger;
     }
     async dispose() {
+        super.dispose();
         this.crudUpdateListener?.();
         this.crudUpdateListener = undefined;
+        this.uploadAbortController?.abort();
     }
     async hasCompletedSync() {
         return this.options.adapter.hasCompletedSync();
@@ -169,9 +175,7 @@ export class AbstractStreamingSyncImplementation extends BaseObserver {
         const clientId = await this.options.adapter.getClientId();
         let path = `/write-checkpoint2.json?client_id=${clientId}`;
         const response = await this.options.remote.get(path);
-        const checkpoint = response['data']['write_checkpoint'];
-        this.logger.debug(`Created write checkpoint: ${checkpoint}`);
-        return checkpoint;
+        return response['data']['write_checkpoint'];
     }
     async _uploadAllCrud() {
         return this.obtainLock({
@@ -181,7 +185,12 @@ export class AbstractStreamingSyncImplementation extends BaseObserver {
                  * Keep track of the first item in the CRUD queue for the last `uploadCrud` iteration.
                  */
                 let checkedCrudItem;
-                while (true) {
+                const controller = new AbortController();
+                this.uploadAbortController = controller;
+                this.abortController?.signal.addEventListener('abort', () => {
+                    controller.abort();
+                }, { once: true });
+                while (!controller.signal.aborted) {
                     try {
                         /**
                          * This is the first item in the FIFO CRUD queue.
@@ -210,11 +219,7 @@ The next upload iteration will be delayed.`);
                         }
                         else {
                             // Uploading is completed
-                            const neededUpdate = await this.options.adapter.updateLocalTarget(() => this.getWriteCheckpoint());
-                            if (neededUpdate == false && checkedCrudItem != null) {
-                                // Only log this if there was something to upload
-                                this.logger.debug('Upload complete, no write checkpoint needed.');
-                            }
+                            await this.options.adapter.updateLocalTarget(() => this.getWriteCheckpoint());
                             break;
                         }
                     }
@@ -226,7 +231,7 @@ The next upload iteration will be delayed.`);
                                 uploadError: ex
                             }
                         });
-                        await this.delayRetry();
+                        await this.delayRetry(controller.signal);
                         if (!this.isConnected) {
                             // Exit the upload loop if the sync stream is no longer connected
                             break;
@@ -241,6 +246,7 @@ The next upload iteration will be delayed.`);
                         });
                     }
                 }
+                this.uploadAbortController = null;
             }
         });
     }
@@ -832,9 +838,11 @@ The next upload iteration will be delayed.`);
             }
         }
         try {
-            await control(PowerSyncControlCommand.START, JSON.stringify({
-                parameters: resolvedOptions.params
-            }));
+            const options = { parameters: resolvedOptions.params };
+            if (resolvedOptions.serializedSchema) {
+                options.schema = resolvedOptions.serializedSchema;
+            }
+            await control(PowerSyncControlCommand.START, JSON.stringify(options));
             this.notifyCompletedUploads = () => {
                 controlInvocations?.enqueueData({ command: PowerSyncControlCommand.NOTIFY_CRUD_UPLOAD_COMPLETED });
             };
@@ -885,17 +893,17 @@ The next upload iteration will be delayed.`);
     async applyCheckpoint(checkpoint) {
         let result = await this.options.adapter.syncLocalDatabase(checkpoint);
         if (!result.checkpointValid) {
-            this.logger.debug(`Checksum mismatch in checkpoint ${checkpoint.last_op_id}, will reconnect`);
+            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) {
-            this.logger.debug(`Could not apply checkpoint ${checkpoint.last_op_id} due to local data. We will retry applying the checkpoint after that upload is completed.`);
+            this.logger.debug('Could not apply checkpoint due to local data. We will retry applying the checkpoint after that upload is completed.');
             return { applied: false, endIteration: false };
         }
-        this.logger.debug(`Applied checkpoint ${checkpoint.last_op_id}`, checkpoint);
+        this.logger.debug('validated checkpoint', checkpoint);
         this.updateSyncStatus({
             connected: true,
             lastSyncedAt: new Date(),

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

@@ -0,0 +1,32 @@
+import { CompiledQuery } from '../../types/types.js';
+import { AbstractPowerSyncDatabase } from '../AbstractPowerSyncDatabase.js';
+import { WatchCompatibleQuery } from './WatchedQuery.js';
+/**
+ * Options for {@link GetAllQuery}.
+ */
+export type GetAllQueryOptions<RowType = unknown> = {
+    sql: string;
+    parameters?: ReadonlyArray<unknown>;
+    /**
+     * Optional mapper function to convert raw rows into the desired RowType.
+     * @example
+     * ```javascript
+     * (rawRow) => ({
+     *   id: rawRow.id,
+     *   created_at: new Date(rawRow.created_at),
+     * })
+     * ```
+     */
+    mapper?: (rawRow: Record<string, unknown>) => RowType;
+};
+/**
+ * Performs a {@link AbstractPowerSyncDatabase.getAll} operation for a watched query.
+ */
+export declare class GetAllQuery<RowType = unknown> implements WatchCompatibleQuery<RowType[]> {
+    protected options: GetAllQueryOptions<RowType>;
+    constructor(options: GetAllQueryOptions<RowType>);
+    compile(): CompiledQuery;
+    execute(options: {
+        db: AbstractPowerSyncDatabase;
+    }): Promise<RowType[]>;
+}

package/lib/client/watched/GetAllQuery.js

@@ -0,0 +1,24 @@
+/**
+ * Performs a {@link AbstractPowerSyncDatabase.getAll} operation for a watched query.
+ */
+export class GetAllQuery {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    compile() {
+        return {
+            sql: this.options.sql,
+            parameters: this.options.parameters ?? []
+        };
+    }
+    async execute(options) {
+        const { db } = options;
+        const { sql, parameters = [] } = this.compile();
+        const rawResult = await db.getAll(sql, [...parameters]);
+        if (this.options.mapper) {
+            return rawResult.map(this.options.mapper);
+        }
+        return rawResult;
+    }
+}

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

@@ -0,0 +1,93 @@
+import { CompiledQuery } from '../../types/types.js';
+import { BaseListener } from '../../utils/BaseObserver.js';
+import { MetaBaseObserverInterface } from '../../utils/MetaBaseObserver.js';
+import { AbstractPowerSyncDatabase } from '../AbstractPowerSyncDatabase.js';
+/**
+ * State for {@link WatchedQuery} instances.
+ */
+export interface WatchedQueryState<Data> {
+    /**
+     * Indicates the initial loading state (hard loading).
+     * Loading becomes false once the first set of results from the watched query is available or an error occurs.
+     */
+    readonly isLoading: boolean;
+    /**
+     * Indicates whether the query is currently fetching data, is true during the initial load
+     * and any time when the query is re-evaluating (useful for large queries).
+     */
+    readonly isFetching: boolean;
+    /**
+     * The last error that occurred while executing the query.
+     */
+    readonly error: Error | null;
+    /**
+     * The last time the query was updated.
+     */
+    readonly lastUpdated: Date | null;
+    /**
+     * The last data returned by the query.
+     */
+    readonly data: Data;
+}
+/**
+ * Options provided to the `execute` method of a {@link WatchCompatibleQuery}.
+ */
+export interface WatchExecuteOptions {
+    sql: string;
+    parameters: any[];
+    db: AbstractPowerSyncDatabase;
+}
+/**
+ * Similar to {@link CompatibleQuery}, except the `execute` method
+ * does not enforce an Array result type.
+ */
+export interface WatchCompatibleQuery<ResultType> {
+    execute(options: WatchExecuteOptions): Promise<ResultType>;
+    compile(): CompiledQuery;
+}
+export interface WatchedQueryOptions {
+    /** The minimum interval between queries. */
+    throttleMs?: number;
+    /**
+     * If true (default) the watched query will update its state to report
+     * on the fetching state of the query.
+     * Setting to false reduces the number of state changes if the fetch status
+     * is not relevant to the consumer.
+     */
+    reportFetching?: boolean;
+}
+export declare enum WatchedQueryListenerEvent {
+    ON_DATA = "onData",
+    ON_ERROR = "onError",
+    ON_STATE_CHANGE = "onStateChange",
+    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.CLOSED]?: () => void | Promise<void>;
+}
+export declare const DEFAULT_WATCH_THROTTLE_MS = 30;
+export declare const DEFAULT_WATCH_QUERY_OPTIONS: WatchedQueryOptions;
+export interface WatchedQuery<Data = unknown, Settings extends WatchedQueryOptions = WatchedQueryOptions, Listener extends WatchedQueryListener<Data> = WatchedQueryListener<Data>> extends MetaBaseObserverInterface<Listener> {
+    /**
+     * Current state of the watched query.
+     */
+    readonly state: WatchedQueryState<Data>;
+    readonly closed: boolean;
+    /**
+     * Subscribe to watched query events.
+     * @returns A function to unsubscribe from the events.
+     */
+    registerListener(listener: Listener): () => void;
+    /**
+     * Updates the underlying query options.
+     * This will trigger a re-evaluation of the query and update the state.
+     */
+    updateSettings(options: Settings): Promise<void>;
+    /**
+     * Close the watched query and end all subscriptions.
+     */
+    close(): Promise<void>;
+}

package/lib/client/watched/WatchedQuery.js

@@ -0,0 +1,12 @@
+export var WatchedQueryListenerEvent;
+(function (WatchedQueryListenerEvent) {
+    WatchedQueryListenerEvent["ON_DATA"] = "onData";
+    WatchedQueryListenerEvent["ON_ERROR"] = "onError";
+    WatchedQueryListenerEvent["ON_STATE_CHANGE"] = "onStateChange";
+    WatchedQueryListenerEvent["CLOSED"] = "closed";
+})(WatchedQueryListenerEvent || (WatchedQueryListenerEvent = {}));
+export const DEFAULT_WATCH_THROTTLE_MS = 30;
+export const DEFAULT_WATCH_QUERY_OPTIONS = {
+    throttleMs: DEFAULT_WATCH_THROTTLE_MS,
+    reportFetching: true
+};

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

@@ -0,0 +1,67 @@
+import { AbstractPowerSyncDatabase } from '../../../client/AbstractPowerSyncDatabase.js';
+import { MetaBaseObserver } from '../../../utils/MetaBaseObserver.js';
+import { WatchedQuery, WatchedQueryListener, WatchedQueryOptions, WatchedQueryState } from '../WatchedQuery.js';
+/**
+ * @internal
+ */
+export interface AbstractQueryProcessorOptions<Data, Settings extends WatchedQueryOptions = WatchedQueryOptions> {
+    db: AbstractPowerSyncDatabase;
+    watchOptions: Settings;
+    placeholderData: Data;
+}
+/**
+ * @internal
+ */
+export interface LinkQueryOptions<Data, Settings extends WatchedQueryOptions = WatchedQueryOptions> {
+    abortSignal: AbortSignal;
+    settings: Settings;
+}
+type MutableDeep<T> = T extends ReadonlyArray<infer U> ? U[] : T;
+/**
+ * @internal Mutable version of {@link WatchedQueryState}.
+ * This is used internally to allow updates to the state.
+ */
+export type MutableWatchedQueryState<Data> = {
+    -readonly [P in keyof WatchedQueryState<Data>]: MutableDeep<WatchedQueryState<Data>[P]>;
+};
+type WatchedQueryProcessorListener<Data> = WatchedQueryListener<Data>;
+/**
+ * Performs underlying watching and yields a stream of results.
+ * @internal
+ */
+export declare abstract class AbstractQueryProcessor<Data = unknown[], Settings extends WatchedQueryOptions = WatchedQueryOptions> extends MetaBaseObserver<WatchedQueryProcessorListener<Data>> implements WatchedQuery<Data, Settings> {
+    protected options: AbstractQueryProcessorOptions<Data, Settings>;
+    readonly state: WatchedQueryState<Data>;
+    protected abortController: AbortController;
+    protected initialized: Promise<void>;
+    protected _closed: boolean;
+    protected disposeListeners: (() => void) | null;
+    get closed(): boolean;
+    constructor(options: AbstractQueryProcessorOptions<Data, Settings>);
+    protected constructInitialState(): WatchedQueryState<Data>;
+    protected get reportFetching(): boolean;
+    /**
+     * Updates the underlying query.
+     */
+    updateSettings(settings: Settings): Promise<void>;
+    /**
+     * This method is used to link a query to the subscribers of this listener class.
+     * This method should perform actual query watching and report results via {@link updateState} method.
+     */
+    protected abstract linkQuery(options: LinkQueryOptions<Data>): Promise<void>;
+    protected updateState(update: Partial<MutableWatchedQueryState<Data>>): Promise<void>;
+    /**
+     * Configures base DB listeners and links the query to listeners.
+     */
+    protected init(): Promise<void>;
+    close(): Promise<void>;
+    /**
+     * Runs a callback and reports errors to the error listeners.
+     */
+    protected runWithReporting<T>(callback: () => Promise<T>): Promise<void>;
+    /**
+     * Iterate listeners and reports errors to onError handlers.
+     */
+    protected iterateAsyncListenersWithError(callback: (listener: Partial<WatchedQueryProcessorListener<Data>>) => Promise<void> | void): Promise<void>;
+}
+export {};

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

@@ -0,0 +1,136 @@
+import { MetaBaseObserver } from '../../../utils/MetaBaseObserver.js';
+/**
+ * Performs underlying watching and yields a stream of results.
+ * @internal
+ */
+export class AbstractQueryProcessor extends MetaBaseObserver {
+    options;
+    state;
+    abortController;
+    initialized;
+    _closed;
+    disposeListeners;
+    get closed() {
+        return this._closed;
+    }
+    constructor(options) {
+        super();
+        this.options = options;
+        this.abortController = new AbortController();
+        this._closed = false;
+        this.state = this.constructInitialState();
+        this.disposeListeners = null;
+        this.initialized = this.init();
+    }
+    constructInitialState() {
+        return {
+            isLoading: true,
+            isFetching: this.reportFetching, // Only set to true if we will report updates in future
+            error: null,
+            lastUpdated: null,
+            data: this.options.placeholderData
+        };
+    }
+    get reportFetching() {
+        return this.options.watchOptions.reportFetching ?? true;
+    }
+    /**
+     * Updates the underlying query.
+     */
+    async updateSettings(settings) {
+        await this.initialized;
+        if (!this.state.isLoading) {
+            await this.updateState({
+                isLoading: true,
+                isFetching: this.reportFetching ? true : false
+            });
+        }
+        this.options.watchOptions = settings;
+        this.abortController.abort();
+        this.abortController = new AbortController();
+        await this.runWithReporting(() => this.linkQuery({
+            abortSignal: this.abortController.signal,
+            settings
+        }));
+    }
+    async updateState(update) {
+        if (typeof update.error !== 'undefined') {
+            await this.iterateAsyncListenersWithError(async (l) => l.onError?.(update.error));
+            // An error always stops for the current fetching state
+            update.isFetching = false;
+            update.isLoading = false;
+        }
+        Object.assign(this.state, { lastUpdated: new Date() }, update);
+        if (typeof update.data !== 'undefined') {
+            await this.iterateAsyncListenersWithError(async (l) => l.onData?.(this.state.data));
+        }
+        await this.iterateAsyncListenersWithError(async (l) => l.onStateChange?.(this.state));
+    }
+    /**
+     * Configures base DB listeners and links the query to listeners.
+     */
+    async init() {
+        const { db } = this.options;
+        const disposeCloseListener = db.registerListener({
+            closing: async () => {
+                await this.close();
+            }
+        });
+        // Wait for the schema to be set before listening to changes
+        await db.waitForReady();
+        const disposeSchemaListener = db.registerListener({
+            schemaChanged: async () => {
+                await this.runWithReporting(async () => {
+                    await this.updateSettings(this.options.watchOptions);
+                });
+            }
+        });
+        this.disposeListeners = () => {
+            disposeCloseListener();
+            disposeSchemaListener();
+        };
+        // Initial setup
+        this.runWithReporting(async () => {
+            await this.updateSettings(this.options.watchOptions);
+        });
+    }
+    async close() {
+        await this.initialized;
+        this.abortController.abort();
+        this.disposeListeners?.();
+        this.disposeListeners = null;
+        this._closed = true;
+        this.iterateListeners((l) => l.closed?.());
+        this.listeners.clear();
+    }
+    /**
+     * Runs a callback and reports errors to the error listeners.
+     */
+    async runWithReporting(callback) {
+        try {
+            await callback();
+        }
+        catch (error) {
+            // This will update the error on the state and iterate error listeners
+            await this.updateState({ error });
+        }
+    }
+    /**
+     * Iterate listeners and reports errors to onError handlers.
+     */
+    async iterateAsyncListenersWithError(callback) {
+        try {
+            await this.iterateAsyncListeners(async (l) => callback(l));
+        }
+        catch (error) {
+            try {
+                await this.iterateAsyncListeners(async (l) => l.onError?.(error));
+            }
+            catch (error) {
+                // Errors here are ignored
+                // since we are already in an error state
+                this.options.db.logger.error('Watched query error handler threw an Error', error);
+            }
+        }
+    }
+}