@powersync/common 0.0.0-dev-20250711131120 → 0.0.0-dev-20250714151300

package/lib/client/AbstractPowerSyncDatabase.d.ts

@@ -1,17 +1,20 @@
 import { Mutex } from 'async-mutex';
-import { ILogger } from 'js-logger';
+import Logger, { ILogger } from 'js-logger';
 import { DBAdapter, QueryResult, Transaction } from '../db/DBAdapter.js';
 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 { ArrayQueryDefinition, Query } from './Query.js';
 import { SQLOpenFactory, SQLOpenOptions } from './SQLOpenFactory.js';
 import { PowerSyncBackendConnector } from './connection/PowerSyncBackendConnector.js';
 import { BucketStorageAdapter } from './sync/bucket/BucketStorageAdapter.js';
 import { CrudBatch } from './sync/bucket/CrudBatch.js';
 import { CrudTransaction } from './sync/bucket/CrudTransaction.js';
 import { StreamingSyncImplementation, StreamingSyncImplementationListener, type AdditionalConnectionOptions, type PowerSyncConnectionOptions, type RequiredAdditionalConnectionOptions } from './sync/stream/AbstractStreamingSyncImplementation.js';
+import { WatchCompatibleQuery } from './watched/WatchedQuery.js';
+import { WatchedQueryComparator } from './watched/processors/comparators.js';
 export interface DisconnectAndClearOptions {
     /** When set to false, data in local-only tables is preserved. */
     clearLocal?: boolean;
@@ -44,7 +47,7 @@ export interface PowerSyncDatabaseOptionsWithOpenFactory extends BasePowerSyncDa
 export interface PowerSyncDatabaseOptionsWithSettings extends BasePowerSyncDatabaseOptions {
     database: SQLOpenOptions;
 }
-export interface SQLWatchOptions {
+export interface SQLOnChangeOptions {
     signal?: AbortSignal;
     tables?: string[];
     /** The minimum interval between queries. */
@@ -56,6 +59,17 @@ export interface SQLWatchOptions {
      * by not removing PowerSync table name prefixes
      */
     rawTableNames?: boolean;
+    /**
+     * Emits an empty result set immediately
+     */
+    triggerImmediate?: boolean;
+}
+export interface SQLWatchOptions extends SQLOnChangeOptions {
+    /**
+     * Optional comparator which will be used to compare the results of the query.
+     * The watched query will only yield results if the comparator returns false.
+     */
+    comparator?: WatchedQueryComparator<QueryResult>;
 }
 export interface WatchOnChangeEvent {
     changedTables: string[];
@@ -71,6 +85,8 @@ export interface WatchOnChangeHandler {
 export interface PowerSyncDBListener extends StreamingSyncImplementationListener {
     initialized: () => void;
     schemaChanged: (schema: Schema) => void;
+    closing: () => Promise<void> | void;
+    closed: () => Promise<void> | void;
 }
 export interface PowerSyncCloseOptions {
     /**
@@ -81,9 +97,9 @@ export interface PowerSyncCloseOptions {
     disconnect?: boolean;
 }
 export declare const DEFAULT_POWERSYNC_CLOSE_OPTIONS: PowerSyncCloseOptions;
-export declare const DEFAULT_WATCH_THROTTLE_MS = 30;
 export declare const DEFAULT_POWERSYNC_DB_OPTIONS: {
     retryDelayMs: number;
+    logger: Logger.ILogger;
     crudUploadThrottleMs: number;
 };
 export declare const DEFAULT_CRUD_BATCH_LIMIT = 100;
@@ -100,11 +116,6 @@ export declare const DEFAULT_LOCK_TIMEOUT_MS = 120000;
 export declare const isPowerSyncDatabaseOptionsWithSettings: (test: any) => test is PowerSyncDatabaseOptionsWithSettings;
 export declare abstract class AbstractPowerSyncDatabase extends BaseObserver<PowerSyncDBListener> {
     protected options: PowerSyncDatabaseOptions;
-    /**
-     * Transactions should be queued in the DBAdapter, but we also want to prevent
-     * calls to `.execute` while an async transaction is running.
-     */
-    protected static transactionMutex: Mutex;
     /**
      * Returns true if the connection is closed.
      */
@@ -122,7 +133,6 @@ export declare abstract class AbstractPowerSyncDatabase extends BaseObserver<Pow
     protected _schema: Schema;
     private _database;
     protected runExclusiveMutex: Mutex;
-    logger: ILogger;
     constructor(options: PowerSyncDatabaseOptionsWithDBAdapter);
     constructor(options: PowerSyncDatabaseOptionsWithOpenFactory);
     constructor(options: PowerSyncDatabaseOptionsWithSettings);
@@ -185,6 +195,7 @@ export declare abstract class AbstractPowerSyncDatabase extends BaseObserver<Pow
      * Cannot be used while connected - this should only be called before {@link AbstractPowerSyncDatabase.connect}.
      */
     updateSchema(schema: Schema): Promise<void>;
+    get logger(): Logger.ILogger;
     /**
      * Wait for initialization to complete.
      * While initializing is automatic, this helps to catch and report initialization errors.
@@ -394,6 +405,42 @@ export declare abstract class AbstractPowerSyncDatabase extends BaseObserver<Pow
      * ```
      */
     watch(sql: string, parameters?: any[], handler?: WatchHandler, options?: SQLWatchOptions): void;
+    /**
+     * Allows defining a query which can be used to build a {@link WatchedQuery}.
+     * The defined query will be executed with {@link AbstractPowerSyncDatabase#getAll}.
+     * An optional mapper function can be provided to transform the results.
+     *
+     * @example
+     * ```javascript
+     * const watchedTodos = powersync.query({
+     *  sql: `SELECT photo_id as id FROM todos WHERE photo_id IS NOT NULL`,
+     *  parameters: [],
+     *  mapper: (row) => ({
+     *    ...row,
+     *    created_at: new Date(row.created_at as string)
+     *  })
+     * })
+     * .watch()
+     * // OR use .differentialWatch() for fine-grained watches.
+     * ```
+     */
+    query<RowType>(query: ArrayQueryDefinition<RowType>): Query<RowType>;
+    /**
+     * Allows building a {@link WatchedQuery} using an existing {@link WatchCompatibleQuery}.
+     * The watched query will use the provided {@link WatchCompatibleQuery.execute} method to query results.
+     *
+     * @example
+     * ```javascript
+     *
+     * // Potentially a query from an ORM like Drizzle
+     * const query = db.select().from(lists);
+     *
+     * const watchedTodos = powersync.customQuery(query)
+     * .watch()
+     * // OR use .differentialWatch() for fine-grained watches.
+     * ```
+     */
+    customQuery<RowType>(query: WatchCompatibleQuery<RowType[]>): Query<RowType>;
     /**
      * Execute a read query every time the source tables are modified.
      * Use {@link SQLWatchOptions.throttleMs} to specify the minimum interval between queries.
@@ -442,7 +489,7 @@ export declare abstract class AbstractPowerSyncDatabase extends BaseObserver<Pow
      * }
      * ```
      */
-    onChange(options?: SQLWatchOptions): AsyncIterable<WatchOnChangeEvent>;
+    onChange(options?: SQLOnChangeOptions): AsyncIterable<WatchOnChangeEvent>;
     /**
      * See {@link onChangeWithCallback}.
      *
@@ -457,7 +504,7 @@ export declare abstract class AbstractPowerSyncDatabase extends BaseObserver<Pow
      * }
      * ```
      */
-    onChange(handler?: WatchOnChangeHandler, options?: SQLWatchOptions): () => void;
+    onChange(handler?: WatchOnChangeHandler, options?: SQLOnChangeOptions): () => void;
     /**
      * Invoke the provided callback on any changes to any of the specified tables.
      *
@@ -470,7 +517,7 @@ export declare abstract class AbstractPowerSyncDatabase extends BaseObserver<Pow
      * @param options Options for configuring watch behavior
      * @returns A dispose function to stop watching for changes
      */
-    onChangeWithCallback(handler?: WatchOnChangeHandler, options?: SQLWatchOptions): () => void;
+    onChangeWithCallback(handler?: WatchOnChangeHandler, options?: SQLOnChangeOptions): () => void;
     /**
      * Create a Stream of changes to any of the specified tables.
      *

package/lib/client/AbstractPowerSyncDatabase.js

@@ -8,15 +8,16 @@ import { UploadQueueStats } from '../db/crud/UploadQueueStatus.js';
 import { BaseObserver } from '../utils/BaseObserver.js';
 import { ControlledExecutor } from '../utils/ControlledExecutor.js';
 import { throttleTrailing } from '../utils/async.js';
-import { mutexRunExclusive } from '../utils/mutex.js';
 import { ConnectionManager } from './ConnectionManager.js';
+import { CustomQuery } from './CustomQuery.js';
 import { isDBAdapter, isSQLOpenFactory, isSQLOpenOptions } from './SQLOpenFactory.js';
-import { runOnSchemaChange } from './runOnSchemaChange.js';
 import { PSInternalTable } from './sync/bucket/BucketStorageAdapter.js';
 import { CrudBatch } from './sync/bucket/CrudBatch.js';
 import { CrudEntry } from './sync/bucket/CrudEntry.js';
 import { CrudTransaction } from './sync/bucket/CrudTransaction.js';
 import { DEFAULT_CRUD_UPLOAD_THROTTLE_MS, DEFAULT_RETRY_DELAY_MS } from './sync/stream/AbstractStreamingSyncImplementation.js';
+import { DEFAULT_WATCH_THROTTLE_MS } from './watched/WatchedQuery.js';
+import { OnChangeQueryProcessor } from './watched/processors/OnChangeQueryProcessor.js';
 const POWERSYNC_TABLE_MATCH = /(^ps_data__|^ps_data_local__)/;
 const DEFAULT_DISCONNECT_CLEAR_OPTIONS = {
     clearLocal: true
@@ -24,9 +25,9 @@ const DEFAULT_DISCONNECT_CLEAR_OPTIONS = {
 export const DEFAULT_POWERSYNC_CLOSE_OPTIONS = {
     disconnect: true
 };
-export const DEFAULT_WATCH_THROTTLE_MS = 30;
 export const DEFAULT_POWERSYNC_DB_OPTIONS = {
     retryDelayMs: 5000,
+    logger: Logger.get('PowerSyncDatabase'),
     crudUploadThrottleMs: DEFAULT_CRUD_UPLOAD_THROTTLE_MS
 };
 export const DEFAULT_CRUD_BATCH_LIMIT = 100;
@@ -45,11 +46,6 @@ export const isPowerSyncDatabaseOptionsWithSettings = (test) => {
 };
 export class AbstractPowerSyncDatabase extends BaseObserver {
     options;
-    /**
-     * Transactions should be queued in the DBAdapter, but we also want to prevent
-     * calls to `.execute` while an async transaction is running.
-     */
-    static transactionMutex = new Mutex();
     /**
      * Returns true if the connection is closed.
      */
@@ -69,7 +65,6 @@ export class AbstractPowerSyncDatabase extends BaseObserver {
     _schema;
     _database;
     runExclusiveMutex;
-    logger;
     constructor(options) {
         super();
         this.options = options;
@@ -89,7 +84,6 @@ export class AbstractPowerSyncDatabase extends BaseObserver {
         else {
             throw new Error('The provided `database` option is invalid.');
         }
-        this.logger = options.logger ?? Logger.get(`PowerSyncDatabase[${this._database.name}]`);
         this.bucketStorageAdapter = this.generateBucketStorageAdapter();
         this.closed = false;
         this.currentStatus = new SyncStatus({});
@@ -269,13 +263,16 @@ export class AbstractPowerSyncDatabase extends BaseObserver {
             schema.validate();
         }
         catch (ex) {
-            this.logger.warn('Schema validation failed. Unexpected behaviour could occur', ex);
+            this.options.logger?.warn('Schema validation failed. Unexpected behaviour could occur', ex);
         }
         this._schema = schema;
         await this.database.execute('SELECT powersync_replace_schema(?)', [JSON.stringify(this.schema.toJSON())]);
         await this.database.refreshSchema();
         this.iterateListeners(async (cb) => cb.schemaChanged?.(schema));
     }
+    get logger() {
+        return this.options.logger;
+    }
     /**
      * Wait for initialization to complete.
      * While initializing is automatic, this helps to catch and report initialization errors.
@@ -345,6 +342,7 @@ export class AbstractPowerSyncDatabase extends BaseObserver {
         if (this.closed) {
             return;
         }
+        await this.iterateAsyncListeners(async (cb) => cb.closing?.());
         const { disconnect } = options;
         if (disconnect) {
             await this.disconnect();
@@ -352,6 +350,7 @@ export class AbstractPowerSyncDatabase extends BaseObserver {
         await this.connectionManager.close();
         await this.database.close();
         this.closed = true;
+        await this.iterateAsyncListeners(async (cb) => cb.closed?.());
     }
     /**
      * Get upload queue size estimate and count.
@@ -475,8 +474,7 @@ export class AbstractPowerSyncDatabase extends BaseObserver {
      * @returns The query result as an object with structured key-value pairs
      */
     async execute(sql, parameters) {
-        await this.waitForReady();
-        return this.database.execute(sql, parameters);
+        return this.writeLock((tx) => tx.execute(sql, parameters));
     }
     /**
      * Execute a SQL write (INSERT/UPDATE/DELETE) query directly on the database without any PowerSync processing.
@@ -544,7 +542,7 @@ export class AbstractPowerSyncDatabase extends BaseObserver {
      */
     async readLock(callback) {
         await this.waitForReady();
-        return mutexRunExclusive(AbstractPowerSyncDatabase.transactionMutex, () => callback(this.database));
+        return this.database.readLock(callback);
     }
     /**
      * Takes a global lock, without starting a transaction.
@@ -552,10 +550,7 @@ export class AbstractPowerSyncDatabase extends BaseObserver {
      */
     async writeLock(callback) {
         await this.waitForReady();
-        return mutexRunExclusive(AbstractPowerSyncDatabase.transactionMutex, async () => {
-            const res = await callback(this.database);
-            return res;
-        });
+        return this.database.writeLock(callback);
     }
     /**
      * Open a read-only transaction.
@@ -602,6 +597,60 @@ export class AbstractPowerSyncDatabase extends BaseObserver {
         const options = handlerOrOptions;
         return this.watchWithAsyncGenerator(sql, parameters, options);
     }
+    /**
+     * Allows defining a query which can be used to build a {@link WatchedQuery}.
+     * The defined query will be executed with {@link AbstractPowerSyncDatabase#getAll}.
+     * An optional mapper function can be provided to transform the results.
+     *
+     * @example
+     * ```javascript
+     * const watchedTodos = powersync.query({
+     *  sql: `SELECT photo_id as id FROM todos WHERE photo_id IS NOT NULL`,
+     *  parameters: [],
+     *  mapper: (row) => ({
+     *    ...row,
+     *    created_at: new Date(row.created_at as string)
+     *  })
+     * })
+     * .watch()
+     * // OR use .differentialWatch() for fine-grained watches.
+     * ```
+     */
+    query(query) {
+        const { sql, parameters = [], mapper } = query;
+        const compatibleQuery = {
+            compile: () => ({
+                sql,
+                parameters
+            }),
+            execute: async ({ sql, parameters }) => {
+                const result = await this.getAll(sql, parameters);
+                return mapper ? result.map(mapper) : result;
+            }
+        };
+        return this.customQuery(compatibleQuery);
+    }
+    /**
+     * Allows building a {@link WatchedQuery} using an existing {@link WatchCompatibleQuery}.
+     * The watched query will use the provided {@link WatchCompatibleQuery.execute} method to query results.
+     *
+     * @example
+     * ```javascript
+     *
+     * // Potentially a query from an ORM like Drizzle
+     * const query = db.select().from(lists);
+     *
+     * const watchedTodos = powersync.customQuery(query)
+     * .watch()
+     * // OR use .differentialWatch() for fine-grained watches.
+     * ```
+     */
+    customQuery(query) {
+        return new CustomQuery({
+            db: this,
+            query
+        });
+    }
     /**
      * Execute a read query every time the source tables are modified.
      * Use {@link SQLWatchOptions.throttleMs} to specify the minimum interval between queries.
@@ -615,39 +664,45 @@ export class AbstractPowerSyncDatabase extends BaseObserver {
      * @param options Options for configuring watch behavior
      */
     watchWithCallback(sql, parameters, handler, options) {
-        const { onResult, onError = (e) => this.logger.error(e) } = handler ?? {};
+        const { onResult, onError = (e) => this.options.logger?.error(e) } = handler ?? {};
         if (!onResult) {
             throw new Error('onResult is required');
         }
-        const watchQuery = async (abortSignal) => {
-            try {
-                const resolvedTables = await this.resolveTables(sql, parameters, options);
-                // Fetch initial data
-                const result = await this.executeReadOnly(sql, parameters);
-                onResult(result);
-                this.onChangeWithCallback({
-                    onChange: async () => {
-                        try {
-                            const result = await this.executeReadOnly(sql, parameters);
-                            onResult(result);
-                        }
-                        catch (error) {
-                            onError?.(error);
-                        }
-                    },
-                    onError
-                }, {
-                    ...(options ?? {}),
-                    tables: resolvedTables,
-                    // Override the abort signal since we intercept it
-                    signal: abortSignal
-                });
+        const { comparator } = options ?? {};
+        // This API yields a QueryResult type.
+        // This is not a standard Array result, which makes it incompatible with the .query API.
+        const watchedQuery = new OnChangeQueryProcessor({
+            db: this,
+            comparator,
+            placeholderData: null,
+            watchOptions: {
+                query: {
+                    compile: () => ({
+                        sql: sql,
+                        parameters: parameters ?? []
+                    }),
+                    execute: () => this.executeReadOnly(sql, parameters)
+                },
+                reportFetching: false,
+                throttleMs: options?.throttleMs ?? DEFAULT_WATCH_THROTTLE_MS
             }
-            catch (error) {
-                onError?.(error);
+        });
+        const dispose = watchedQuery.registerListener({
+            onData: (data) => {
+                if (!data) {
+                    // This should not happen. We only use null for the initial data.
+                    return;
+                }
+                onResult(data);
+            },
+            onError: (error) => {
+                onError(error);
             }
-        };
-        runOnSchemaChange(watchQuery, this, options);
+        });
+        options?.signal?.addEventListener('abort', () => {
+            dispose();
+            watchedQuery.close();
+        });
     }
     /**
      * Execute a read query every time the source tables are modified.
@@ -721,7 +776,7 @@ export class AbstractPowerSyncDatabase extends BaseObserver {
      * @returns A dispose function to stop watching for changes
      */
     onChangeWithCallback(handler, options) {
-        const { onChange, onError = (e) => this.logger.error(e) } = handler ?? {};
+        const { onChange, onError = (e) => this.options.logger?.error(e) } = handler ?? {};
         if (!onChange) {
             throw new Error('onChange is required');
         }
@@ -737,6 +792,9 @@ export class AbstractPowerSyncDatabase extends BaseObserver {
                 return;
             executor.schedule({ changedTables: intersection });
         }), throttleMs);
+        if (options?.triggerImmediate) {
+            executor.schedule({ changedTables: [] });
+        }
         const dispose = this.database.registerListener({
             tablesUpdated: async (update) => {
                 try {

package/lib/client/CustomQuery.d.ts

@@ -0,0 +1,25 @@
+import { AbstractPowerSyncDatabase } from './AbstractPowerSyncDatabase.js';
+import { Query, StandardWatchedQueryOptions } from './Query.js';
+import { DifferentialQueryProcessor, DifferentialWatchedQueryOptions } from './watched/processors/DifferentialQueryProcessor.js';
+import { OnChangeQueryProcessor } from './watched/processors/OnChangeQueryProcessor.js';
+import { WatchCompatibleQuery, WatchedQueryOptions } from './watched/WatchedQuery.js';
+/**
+ * @internal
+ */
+export interface CustomQueryOptions<RowType> {
+    db: AbstractPowerSyncDatabase;
+    query: WatchCompatibleQuery<RowType[]>;
+}
+/**
+ * @internal
+ */
+export declare class CustomQuery<RowType> implements Query<RowType> {
+    protected options: CustomQueryOptions<RowType>;
+    constructor(options: CustomQueryOptions<RowType>);
+    protected resolveOptions(options: WatchedQueryOptions): {
+        reportFetching: boolean | undefined;
+        throttleMs: number | undefined;
+    };
+    watch(watchOptions: StandardWatchedQueryOptions<RowType>): OnChangeQueryProcessor<RowType[]>;
+    differentialWatch(differentialWatchOptions: DifferentialWatchedQueryOptions<RowType>): DifferentialQueryProcessor<RowType>;
+}

package/lib/client/CustomQuery.js

@@ -0,0 +1,41 @@
+import { FalsyComparator } from './watched/processors/comparators.js';
+import { DifferentialQueryProcessor } from './watched/processors/DifferentialQueryProcessor.js';
+import { OnChangeQueryProcessor } from './watched/processors/OnChangeQueryProcessor.js';
+import { DEFAULT_WATCH_QUERY_OPTIONS } from './watched/WatchedQuery.js';
+/**
+ * @internal
+ */
+export class CustomQuery {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    resolveOptions(options) {
+        return {
+            reportFetching: options?.reportFetching ?? DEFAULT_WATCH_QUERY_OPTIONS.reportFetching,
+            throttleMs: options?.throttleMs ?? DEFAULT_WATCH_QUERY_OPTIONS.throttleMs
+        };
+    }
+    watch(watchOptions) {
+        return new OnChangeQueryProcessor({
+            db: this.options.db,
+            comparator: watchOptions?.comparator ?? FalsyComparator,
+            placeholderData: watchOptions?.placeholderData ?? [],
+            watchOptions: {
+                ...this.resolveOptions(watchOptions),
+                query: this.options.query
+            }
+        });
+    }
+    differentialWatch(differentialWatchOptions) {
+        return new DifferentialQueryProcessor({
+            db: this.options.db,
+            differentiator: differentialWatchOptions?.differentiator,
+            placeholderData: differentialWatchOptions?.placeholderData ?? [],
+            watchOptions: {
+                ...this.resolveOptions(differentialWatchOptions),
+                query: this.options.query
+            }
+        });
+    }
+}

package/lib/client/Query.d.ts

@@ -0,0 +1,79 @@
+import { ArrayComparator } from './watched/processors/comparators.js';
+import { DifferentialWatchedQuery, DifferentialWatchedQueryOptions } from './watched/processors/DifferentialQueryProcessor.js';
+import { ComparisonWatchedQuery } from './watched/processors/OnChangeQueryProcessor.js';
+import { WatchedQueryOptions } from './watched/WatchedQuery.js';
+/**
+ * Query parameters for {@link ArrayQueryDefinition#parameters}
+ */
+export type QueryParam = string | number | boolean | null | undefined | bigint | Uint8Array;
+/**
+ * Options for building a query with {@link AbstractPowerSyncDatabase#query}.
+ * This query will be executed with {@link AbstractPowerSyncDatabase#getAll}.
+ */
+export interface ArrayQueryDefinition<RowType = unknown> {
+    sql: string;
+    parameters?: ReadonlyArray<Readonly<QueryParam>>;
+    /**
+     * Maps the raw SQLite row to a custom typed object.
+     * @example
+     * ```javascript
+     * mapper: (row) => ({
+     *  ...row,
+     *  created_at: new Date(row.created_at as string),
+     * })
+     * ```
+     */
+    mapper?: (row: Record<string, unknown>) => RowType;
+}
+/**
+ * Options for {@link Query.watch}.
+ */
+export interface StandardWatchedQueryOptions<RowType> extends WatchedQueryOptions {
+    /**
+     * Optional comparator which processes the items of an array of rows.
+     * The comparator compares the result set rows by index using the {@link ArrayComparatorOptions#compareBy} function.
+     * The comparator reports a changed result set as soon as a row does not match the previous result set.
+     *
+     * @example
+     * ```javascript
+     * comparator: new ArrayComparator({
+     *     compareBy: (item) => JSON.stringify(item)
+     * })
+     * ```
+     */
+    comparator?: ArrayComparator<RowType>;
+    /**
+     * The initial data state reported while the query is loading for the first time.
+     * @default []
+     */
+    placeholderData?: RowType[];
+}
+export interface Query<RowType> {
+    /**
+     * Creates a {@link WatchedQuery} which watches and emits results of the linked query.
+     *
+     * By default the returned watched query will emit changes whenever a change to the underlying SQLite tables is made.
+     * These changes might not be relevant to the query, but the query will emit a new result set.
+     *
+     * A {@link StandardWatchedQueryOptions#comparator} can be provided to limit the data emissions. The watched query will still
+     * query the underlying DB on underlying table changes, but the result will only be emitted if the comparator detects a change in the results.
+     *
+     * The comparator in this method is optimized and returns early as soon as it detects a change. Each data emission will correlate to a change in the result set,
+     * but note that the result set will not maintain internal object references to the previous result set. If internal object references are needed,
+     * consider using {@link Query#differentialWatch} instead.
+     */
+    watch(options?: StandardWatchedQueryOptions<RowType>): ComparisonWatchedQuery<ReadonlyArray<Readonly<RowType>>>;
+    /**
+     * Creates a {@link WatchedQuery} which watches and emits results of the linked query.
+     *
+     * This query method watches for changes in the underlying SQLite tables and runs the query on each table change.
+     * The difference between the current and previous result set is computed.
+     * The watched query will not emit changes if the result set is identical to the previous result set.
+     * If the result set is different, the watched query will emit the new result set and provide a detailed diff of the changes.
+     *
+     * The deep differentiation allows maintaining result set object references between result emissions.
+     * The {@link DifferentialWatchedQuery#state} `data` array will contain the previous row references for unchanged rows.
+     * A detailed diff of the changes can be accessed via {@link DifferentialWatchedQuery#state} `diff`.
+     */
+    differentialWatch(options?: DifferentialWatchedQueryOptions<RowType>): DifferentialWatchedQuery<RowType>;
+}

package/lib/client/Query.js

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

package/lib/client/sync/bucket/BucketStorageAdapter.d.ts

@@ -1,4 +1,4 @@
-import { BaseListener, BaseObserver, Disposable } from '../../../utils/BaseObserver.js';
+import { BaseListener, BaseObserverInterface, Disposable } from '../../../utils/BaseObserver.js';
 import { CrudBatch } from './CrudBatch.js';
 import { CrudEntry, OpId } from './CrudEntry.js';
 import { SyncDataBatch } from './SyncDataBatch.js';
@@ -62,7 +62,7 @@ export declare enum PowerSyncControlCommand {
 export interface BucketStorageListener extends BaseListener {
     crudUpdate: () => void;
 }
-export interface BucketStorageAdapter extends BaseObserver<BucketStorageListener>, Disposable {
+export interface BucketStorageAdapter extends BaseObserverInterface<BucketStorageListener>, Disposable {
     init(): Promise<void>;
     saveSyncData(batch: SyncDataBatch, fixedKeyFormat?: boolean): Promise<void>;
     removeBuckets(buckets: string[]): Promise<void>;

package/lib/client/sync/bucket/SqliteBucketStorage.d.ts

@@ -1,4 +1,3 @@
-import { Mutex } from 'async-mutex';
 import { ILogger } from 'js-logger';
 import { DBAdapter, Transaction } from '../../../db/DBAdapter.js';
 import { BaseObserver } from '../../../utils/BaseObserver.js';
@@ -8,13 +7,12 @@ import { CrudEntry } from './CrudEntry.js';
 import { SyncDataBatch } from './SyncDataBatch.js';
 export declare class SqliteBucketStorage extends BaseObserver<BucketStorageListener> implements BucketStorageAdapter {
     private db;
-    private mutex;
     private logger;
     tableNames: Set<string>;
     private _hasCompletedSync;
     private updateListener;
     private _clientId?;
-    constructor(db: DBAdapter, mutex: Mutex, logger?: ILogger);
+    constructor(db: DBAdapter, logger?: ILogger);
     init(): Promise<void>;
     dispose(): Promise<void>;
     _getClientId(): Promise<string>;

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

@@ -6,16 +6,14 @@ import { PSInternalTable } from './BucketStorageAdapter.js';
 import { CrudEntry } from './CrudEntry.js';
 export class SqliteBucketStorage extends BaseObserver {
     db;
-    mutex;
     logger;
     tableNames;
     _hasCompletedSync;
     updateListener;
     _clientId;
-    constructor(db, mutex, logger = Logger.get('SqliteBucketStorage')) {
+    constructor(db, logger = Logger.get('SqliteBucketStorage')) {
         super();
         this.db = db;
-        this.mutex = mutex;
         this.logger = logger;
         this._hasCompletedSync = false;
         this.tableNames = new Set();

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';
@@ -131,7 +131,7 @@ 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
      */
@@ -164,6 +164,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;