@powersync/common 1.33.2 → 1.35.0

package/lib/client/AbstractPowerSyncDatabase.d.ts

@@ -1,17 +1,20 @@
 import { Mutex } from 'async-mutex';
-import Logger, { ILogger } from 'js-logger';
+import { 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,10 +97,8 @@ 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;
@@ -101,11 +115,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.
      */
@@ -123,6 +132,7 @@ 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,7 +195,6 @@ 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.
@@ -395,6 +404,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.
@@ -443,7 +488,7 @@ export declare abstract class AbstractPowerSyncDatabase extends BaseObserver<Pow
      * }
      * ```
      */
-    onChange(options?: SQLWatchOptions): AsyncIterable<WatchOnChangeEvent>;
+    onChange(options?: SQLOnChangeOptions): AsyncIterable<WatchOnChangeEvent>;
     /**
      * See {@link onChangeWithCallback}.
      *
@@ -458,7 +503,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.
      *
@@ -471,7 +516,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,10 +25,8 @@ 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;
@@ -46,11 +45,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.
      */
@@ -70,6 +64,7 @@ export class AbstractPowerSyncDatabase extends BaseObserver {
     _schema;
     _database;
     runExclusiveMutex;
+    logger;
     constructor(options) {
         super();
         this.options = options;
@@ -89,6 +84,7 @@ 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({});
@@ -268,16 +264,13 @@ export class AbstractPowerSyncDatabase extends BaseObserver {
             schema.validate();
         }
         catch (ex) {
-            this.options.logger?.warn('Schema validation failed. Unexpected behaviour could occur', ex);
+            this.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.
@@ -304,7 +297,9 @@ export class AbstractPowerSyncDatabase extends BaseObserver {
      * Connects to stream of events from the PowerSync instance.
      */
     async connect(connector, options) {
-        return this.connectionManager.connect(connector, options);
+        const resolvedOptions = options ?? {};
+        resolvedOptions.serializedSchema = this.schema.toJSON();
+        return this.connectionManager.connect(connector, resolvedOptions);
     }
     /**
      * Close the sync connection.
@@ -347,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();
@@ -354,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.
@@ -477,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.
@@ -546,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.
@@ -554,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.
@@ -604,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.
@@ -617,39 +664,46 @@ export class AbstractPowerSyncDatabase extends BaseObserver {
      * @param options Options for configuring watch behavior
      */
     watchWithCallback(sql, parameters, handler, options) {
-        const { onResult, onError = (e) => this.options.logger?.error(e) } = handler ?? {};
+        const { onResult, onError = (e) => this.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,
+                triggerOnTables: options?.tables
             }
-            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.
@@ -723,7 +777,7 @@ export class AbstractPowerSyncDatabase extends BaseObserver {
      * @returns A dispose function to stop watching for changes
      */
     onChangeWithCallback(handler, options) {
-        const { onChange, onError = (e) => this.options.logger?.error(e) } = handler ?? {};
+        const { onChange, onError = (e) => this.logger.error(e) } = handler ?? {};
         if (!onChange) {
             throw new Error('onChange is required');
         }
@@ -739,6 +793,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/ConnectionManager.d.ts

@@ -1,7 +1,7 @@
 import { ILogger } from 'js-logger';
 import { BaseListener, BaseObserver } from '../utils/BaseObserver.js';
 import { PowerSyncBackendConnector } from './connection/PowerSyncBackendConnector.js';
-import { PowerSyncConnectionOptions, StreamingSyncImplementation } from './sync/stream/AbstractStreamingSyncImplementation.js';
+import { InternalConnectionOptions, StreamingSyncImplementation } from './sync/stream/AbstractStreamingSyncImplementation.js';
 /**
  * @internal
  */
@@ -17,12 +17,12 @@ export interface ConnectionManagerSyncImplementationResult {
  * @internal
  */
 export interface ConnectionManagerOptions {
-    createSyncImplementation(connector: PowerSyncBackendConnector, options: PowerSyncConnectionOptions): Promise<ConnectionManagerSyncImplementationResult>;
+    createSyncImplementation(connector: PowerSyncBackendConnector, options: InternalConnectionOptions): Promise<ConnectionManagerSyncImplementationResult>;
     logger: ILogger;
 }
 type StoredConnectionOptions = {
     connector: PowerSyncBackendConnector;
-    options: PowerSyncConnectionOptions;
+    options: InternalConnectionOptions;
 };
 /**
  * @internal
@@ -66,7 +66,7 @@ export declare class ConnectionManager extends BaseObserver<ConnectionManagerLis
     constructor(options: ConnectionManagerOptions);
     get logger(): ILogger;
     close(): Promise<void>;
-    connect(connector: PowerSyncBackendConnector, options?: PowerSyncConnectionOptions): Promise<void>;
+    connect(connector: PowerSyncBackendConnector, options: InternalConnectionOptions): Promise<void>;
     protected connectInternal(): Promise<void>;
     /**
      * Close the sync connection.

package/lib/client/CustomQuery.d.ts

@@ -0,0 +1,22 @@
+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): WatchedQueryOptions;
+    watch(watchOptions: StandardWatchedQueryOptions<RowType>): OnChangeQueryProcessor<RowType[]>;
+    differentialWatch(differentialWatchOptions: DifferentialWatchedQueryOptions<RowType>): DifferentialQueryProcessor<RowType>;
+}

package/lib/client/CustomQuery.js

@@ -0,0 +1,42 @@
+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,
+            triggerOnTables: options?.triggerOnTables
+        };
+    }
+    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,
+            rowComparator: differentialWatchOptions?.rowComparator,
+            placeholderData: differentialWatchOptions?.placeholderData ?? [],
+            watchOptions: {
+                ...this.resolveOptions(differentialWatchOptions),
+                query: this.options.query
+            }
+        });
+    }
+}

package/lib/client/Query.d.ts

@@ -0,0 +1,97 @@
+import { WatchedQueryComparator } from './watched/processors/comparators.js';
+import { DifferentialWatchedQuery, DifferentialWatchedQueryOptions } from './watched/processors/DifferentialQueryProcessor.js';
+import { StandardWatchedQuery } 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 {
+    /**
+     * The underlying watched query implementation (re)evaluates the query on any SQLite table change.
+     *
+     * Providing this optional comparator can be used to filter duplicate result set emissions when the result set is unchanged.
+     * The comparator compares the previous and current result set.
+     *
+     * For an efficient comparator see {@link ArrayComparator}.
+     *
+     * @example
+     * ```javascript
+     * comparator: new ArrayComparator({
+     *     compareBy: (item) => JSON.stringify(item)
+     * })
+     * ```
+     */
+    comparator?: WatchedQueryComparator<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>): StandardWatchedQuery<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 emit a detailed diff of the changes via the `onData` and `onDiff` listeners.
+     *
+     * 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.
+     *
+     * @example
+     * ```javascript
+     * const watchedLists = powerSync.query({sql: 'SELECT * FROM lists'})
+     *  .differentialWatch();
+     *
+     * const disposeListener = watchedLists.registerListener({
+     *  onData: (lists) => {
+     *    console.log('The latest result set for the query is', lists);
+     *  },
+     *  onDiff: (diff) => {
+     *    console.log('The lists result set has changed since the last emission', diff.added, diff.removed, diff.updated, diff.all)
+     *  }
+     * })
+     * ```
+     */
+    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>;