@powersync/common 0.0.0-dev-20260504100448 → 0.0.0-dev-20260630144038

package/src/client/watched/GetAllQuery.ts

@@ -1,9 +1,11 @@
 import { CompiledQuery } from '../../types/types.js';
-import { AbstractPowerSyncDatabase } from '../AbstractPowerSyncDatabase.js';
+import { CommonPowerSyncDatabase } from '../CommonPowerSyncDatabase.js';
 import { WatchCompatibleQuery } from './WatchedQuery.js';
 
 /**
  * Options for {@link GetAllQuery}.
+ *
+ * @public
  */
 export type GetAllQueryOptions<RowType = unknown> = {
   sql: string;
@@ -22,7 +24,9 @@ export type GetAllQueryOptions<RowType = unknown> = {
 };
 
 /**
- * Performs a {@link AbstractPowerSyncDatabase.getAll} operation for a watched query.
+ * Performs a {@link DBGetUtils.getAll} operation for a watched query.
+ *
+ * @public
  */
 export class GetAllQuery<RowType = unknown> implements WatchCompatibleQuery<RowType[]> {
   constructor(protected options: GetAllQueryOptions<RowType>) {}
@@ -34,10 +38,10 @@ export class GetAllQuery<RowType = unknown> implements WatchCompatibleQuery<RowT
     };
   }
 
-  async execute(options: { db: AbstractPowerSyncDatabase }): Promise<RowType[]> {
+  async execute(options: { db: CommonPowerSyncDatabase }): Promise<RowType[]> {
     const { db } = options;
     const { sql, parameters = [] } = this.compile();
-    const rawResult = await db.getAll<unknown>(sql, [...parameters]);
+    const rawResult = await db.getAll<Record<string, unknown>>(sql, [...parameters]);
     if (this.options.mapper) {
       return rawResult.map(this.options.mapper);
     }

package/src/client/watched/WatchedQuery.ts

@@ -1,10 +1,12 @@
 import { CompiledQuery } from '../../types/types.js';
 import { BaseListener } from '../../utils/BaseObserver.js';
 import { MetaBaseObserverInterface } from '../../utils/MetaBaseObserver.js';
-import { AbstractPowerSyncDatabase } from '../AbstractPowerSyncDatabase.js';
+import { CommonPowerSyncDatabase } from '../CommonPowerSyncDatabase.js';
 
 /**
  * State for {@link WatchedQuery} instances.
+ *
+ * @public
  */
 export interface WatchedQueryState<Data> {
   /**
@@ -33,22 +35,27 @@ export interface WatchedQueryState<Data> {
 
 /**
  * Options provided to the `execute` method of a {@link WatchCompatibleQuery}.
+ *
+ * @public
  */
 export interface WatchExecuteOptions {
   sql: string;
   parameters: any[];
-  db: AbstractPowerSyncDatabase;
+  db: CommonPowerSyncDatabase;
 }
 
 /**
- * Similar to {@link CompatibleQuery}, except the `execute` method
- * does not enforce an Array result type.
+ *
+ * @public
  */
 export interface WatchCompatibleQuery<ResultType> {
   execute(options: WatchExecuteOptions): Promise<ResultType>;
   compile(): CompiledQuery;
 }
 
+/**
+ * @public
+ */
 export interface WatchedQueryOptions {
   /** The minimum interval between queries. */
   throttleMs?: number;
@@ -67,6 +74,9 @@ export interface WatchedQueryOptions {
   triggerOnTables?: string[];
 }
 
+/**
+ * @public
+ */
 export enum WatchedQueryListenerEvent {
   ON_DATA = 'onData',
   ON_ERROR = 'onError',
@@ -75,6 +85,9 @@ export enum WatchedQueryListenerEvent {
   CLOSED = 'closed'
 }
 
+/**
+ * @public
+ */
 export interface WatchedQueryListener<Data> extends BaseListener {
   [WatchedQueryListenerEvent.ON_DATA]?: (data: Data) => void | Promise<void>;
   [WatchedQueryListenerEvent.ON_ERROR]?: (error: Error) => void | Promise<void>;
@@ -83,13 +96,9 @@ export interface WatchedQueryListener<Data> extends BaseListener {
   [WatchedQueryListenerEvent.CLOSED]?: () => void | Promise<void>;
 }
 
-export const DEFAULT_WATCH_THROTTLE_MS = 30;
-
-export const DEFAULT_WATCH_QUERY_OPTIONS: WatchedQueryOptions = {
-  throttleMs: DEFAULT_WATCH_THROTTLE_MS,
-  reportFetching: true
-};
-
+/**
+ * @public
+ */
 export interface WatchedQuery<
   Data = unknown,
   Settings extends WatchedQueryOptions = WatchedQueryOptions,

package/src/client/watched/processors/DifferentialQueryProcessor.ts

@@ -1,14 +1,10 @@
 import { WatchCompatibleQuery, WatchedQuery, WatchedQueryListener, WatchedQueryOptions } from '../WatchedQuery.js';
-import {
-  AbstractQueryProcessor,
-  AbstractQueryProcessorOptions,
-  LinkQueryOptions,
-  MutableWatchedQueryState
-} from './AbstractQueryProcessor.js';
 
 /**
  * Represents an updated row in a differential watched query.
  * It contains both the current and previous state of the row.
+ *
+ * @public
  */
 export interface WatchedQueryRowDifferential<RowType> {
   readonly current: RowType;
@@ -18,6 +14,8 @@ export interface WatchedQueryRowDifferential<RowType> {
 /**
  * Represents the result of a watched query that has been diffed.
  * {@link DifferentialWatchedQueryState#diff} is of the {@link WatchedQueryDifferential} form.
+ *
+ * @public
  */
 export interface WatchedQueryDifferential<RowType> {
   readonly added: ReadonlyArray<Readonly<RowType>>;
@@ -43,6 +41,8 @@ export interface WatchedQueryDifferential<RowType> {
 
 /**
  * Row comparator for differentially watched queries which keys and compares items in the result set.
+ *
+ * @public
  */
 export interface DifferentialWatchedQueryComparator<RowType> {
   /**
@@ -57,6 +57,8 @@ export interface DifferentialWatchedQueryComparator<RowType> {
 
 /**
  * Options for building a differential watched query with the {@link Query} builder.
+ *
+ * @public
  */
 export interface DifferentialWatchedQueryOptions<RowType> extends WatchedQueryOptions {
   /**
@@ -68,13 +70,14 @@ export interface DifferentialWatchedQueryOptions<RowType> extends WatchedQueryOp
    * Row comparator used to identify and compare rows in the result set.
    * If not provided, the default comparator will be used which keys items by their `id` property if available,
    * otherwise it uses JSON stringification of the entire item for keying and comparison.
-   * @defaultValue {@link DEFAULT_ROW_COMPARATOR}
    */
   rowComparator?: DifferentialWatchedQueryComparator<RowType>;
 }
 
 /**
  * Settings for differential incremental watched queries using.
+ *
+ * @public
  */
 export interface DifferentialWatchedQuerySettings<RowType> extends DifferentialWatchedQueryOptions<RowType> {
   /**
@@ -83,223 +86,20 @@ export interface DifferentialWatchedQuerySettings<RowType> extends DifferentialW
   query: WatchCompatibleQuery<RowType[]>;
 }
 
-export interface DifferentialWatchedQueryListener<RowType>
-  extends WatchedQueryListener<ReadonlyArray<Readonly<RowType>>> {
+/**
+ * @public
+ */
+export interface DifferentialWatchedQueryListener<RowType> extends WatchedQueryListener<
+  ReadonlyArray<Readonly<RowType>>
+> {
   onDiff?: (diff: WatchedQueryDifferential<RowType>) => void | Promise<void>;
 }
 
+/**
+ * @public
+ */
 export type DifferentialWatchedQuery<RowType> = WatchedQuery<
   ReadonlyArray<Readonly<RowType>>,
   DifferentialWatchedQuerySettings<RowType>,
   DifferentialWatchedQueryListener<RowType>
 >;
-
-/**
- * @internal
- */
-export interface DifferentialQueryProcessorOptions<RowType>
-  extends AbstractQueryProcessorOptions<RowType[], DifferentialWatchedQuerySettings<RowType>> {
-  rowComparator?: DifferentialWatchedQueryComparator<RowType>;
-}
-
-type DataHashMap<RowType> = Map<string, { hash: string; item: RowType }>;
-
-/**
- * An empty differential result set.
- * This is used as the initial state for differential incrementally watched queries.
- */
-export const EMPTY_DIFFERENTIAL = {
-  added: [],
-  all: [],
-  removed: [],
-  updated: [],
-  unchanged: []
-};
-
-/**
- * Default implementation of the {@link DifferentialWatchedQueryComparator} for watched queries.
- * It keys items by their `id` property if available, alternatively it uses JSON stringification
- * of the entire item for the key and comparison.
- */
-export const DEFAULT_ROW_COMPARATOR: DifferentialWatchedQueryComparator<any> = {
-  keyBy: (item) => {
-    if (item && typeof item == 'object' && typeof item['id'] == 'string') {
-      return item['id'];
-    }
-    return JSON.stringify(item);
-  },
-  compareBy: (item) => JSON.stringify(item)
-};
-
-/**
- * Uses the PowerSync onChange event to trigger watched queries.
- * Results are emitted on every change of the relevant tables.
- * @internal
- */
-export class DifferentialQueryProcessor<RowType>
-  extends AbstractQueryProcessor<ReadonlyArray<Readonly<RowType>>, DifferentialWatchedQuerySettings<RowType>>
-  implements DifferentialWatchedQuery<RowType>
-{
-  protected comparator: DifferentialWatchedQueryComparator<RowType>;
-
-  constructor(protected options: DifferentialQueryProcessorOptions<RowType>) {
-    super(options);
-    this.comparator = options.rowComparator ?? DEFAULT_ROW_COMPARATOR;
-  }
-
-  /*
-   * @returns If the sets are equal
-   */
-  protected differentiate(
-    current: RowType[],
-    previousMap: DataHashMap<RowType>
-  ): { diff: WatchedQueryDifferential<RowType>; map: DataHashMap<RowType>; hasChanged: boolean } {
-    const { keyBy, compareBy } = this.comparator;
-
-    let hasChanged = false;
-    const currentMap = new Map<string, { hash: string; item: RowType }>();
-    const removedTracker = new Set(previousMap.keys());
-
-    // Allow mutating to populate the data temporarily.
-    const diff = {
-      all: [] as RowType[],
-      added: [] as RowType[],
-      removed: [] as RowType[],
-      updated: [] as WatchedQueryRowDifferential<RowType>[],
-      unchanged: [] as RowType[]
-    };
-
-    /**
-     * Looping over the current result set array is important to preserve
-     * the ordering of the result set.
-     * We can replace items in the current array with previous object references if they are equal.
-     */
-    for (const item of current) {
-      const key = keyBy(item);
-      const hash = compareBy(item);
-      currentMap.set(key, { hash, item });
-
-      const previousItem = previousMap.get(key);
-      if (!previousItem) {
-        // New item
-        hasChanged = true;
-        diff.added.push(item);
-        diff.all.push(item);
-      } else {
-        // Existing item
-        if (hash == previousItem.hash) {
-          diff.unchanged.push(previousItem.item);
-          // Use the previous object reference
-          diff.all.push(previousItem.item);
-          // update the map to preserve the reference
-          currentMap.set(key, previousItem);
-        } else {
-          hasChanged = true;
-          diff.updated.push({ current: item, previous: previousItem.item });
-          // Use the new reference
-          diff.all.push(item);
-        }
-      }
-      // The item is present, we don't consider it removed
-      removedTracker.delete(key);
-    }
-
-    diff.removed = Array.from(removedTracker).map((key) => previousMap.get(key)!.item);
-    hasChanged = hasChanged || diff.removed.length > 0;
-
-    return {
-      diff,
-      hasChanged,
-      map: currentMap
-    };
-  }
-
-  protected async linkQuery(options: LinkQueryOptions<WatchedQueryDifferential<RowType>>): Promise<void> {
-    const { db, watchOptions } = this.options;
-    const { abortSignal } = options;
-
-    const compiledQuery = watchOptions.query.compile();
-    const tables = await db.resolveTables(compiledQuery.sql, compiledQuery.parameters as any[], {
-      tables: options.settings.triggerOnTables
-    });
-
-    let currentMap: DataHashMap<RowType> = new Map();
-
-    // populate the currentMap from the placeholder data
-    this.state.data.forEach((item) => {
-      currentMap.set(this.comparator.keyBy(item), {
-        hash: this.comparator.compareBy(item),
-        item
-      });
-    });
-
-    db.onChangeWithCallback(
-      {
-        onChange: async () => {
-          if (this.closed || abortSignal.aborted) {
-            return;
-          }
-          // This fires for each change of the relevant tables
-          try {
-            if (this.reportFetching && !this.state.isFetching) {
-              await this.updateState({ isFetching: true });
-            }
-
-            const partialStateUpdate: Partial<MutableWatchedQueryState<RowType[]>> = {};
-
-            // Always run the query if an underlying table has changed
-            const result = await watchOptions.query.execute({
-              sql: compiledQuery.sql,
-              // Allows casting from ReadOnlyArray[unknown] to Array<unknown>
-              // This allows simpler compatibility with PowerSync queries
-              parameters: [...compiledQuery.parameters],
-              db: this.options.db
-            });
-
-            if (abortSignal.aborted) {
-              return;
-            }
-
-            if (this.reportFetching) {
-              partialStateUpdate.isFetching = false;
-            }
-
-            if (this.state.isLoading) {
-              partialStateUpdate.isLoading = false;
-            }
-
-            const { diff, hasChanged, map } = this.differentiate(result, currentMap);
-            // Update for future comparisons
-            currentMap = map;
-
-            if (hasChanged) {
-              await this.iterateAsyncListenersWithError((l) => l.onDiff?.(diff));
-              Object.assign(partialStateUpdate, {
-                data: diff.all
-              });
-            }
-
-            if (this.state.error) {
-              partialStateUpdate.error = null;
-            }
-
-            if (Object.keys(partialStateUpdate).length > 0) {
-              await this.updateState(partialStateUpdate);
-            }
-          } catch (error) {
-            await this.updateState({ error });
-          }
-        },
-        onError: async (error) => {
-          await this.updateState({ error });
-        }
-      },
-      {
-        signal: abortSignal,
-        tables,
-        throttleMs: watchOptions.throttleMs,
-        triggerImmediate: true // used to emit the initial state
-      }
-    );
-  }
-}

package/src/client/watched/processors/OnChangeQueryProcessor.ts

@@ -1,14 +1,9 @@
 import { WatchCompatibleQuery, WatchedQuery, WatchedQueryOptions } from '../WatchedQuery.js';
-import {
-  AbstractQueryProcessor,
-  AbstractQueryProcessorOptions,
-  LinkQueryOptions,
-  MutableWatchedQueryState
-} from './AbstractQueryProcessor.js';
-import { WatchedQueryComparator } from './comparators.js';
 
 /**
  * Settings for {@link WatchedQuery} instances created via {@link Query#watch}.
+ *
+ * @public
  */
 export interface WatchedQuerySettings<DataType> extends WatchedQueryOptions {
   query: WatchCompatibleQuery<DataType>;
@@ -16,107 +11,7 @@ export interface WatchedQuerySettings<DataType> extends WatchedQueryOptions {
 
 /**
  * {@link WatchedQuery} returned from {@link Query#watch}.
+ *
+ * @public
  */
 export type StandardWatchedQuery<DataType> = WatchedQuery<DataType, WatchedQuerySettings<DataType>>;
-
-/**
- * @internal
- */
-export interface OnChangeQueryProcessorOptions<Data>
-  extends AbstractQueryProcessorOptions<Data, WatchedQuerySettings<Data>> {
-  comparator?: WatchedQueryComparator<Data>;
-}
-
-/**
- * Uses the PowerSync onChange event to trigger watched queries.
- * Results are emitted on every change of the relevant tables.
- * @internal
- */
-export class OnChangeQueryProcessor<Data> extends AbstractQueryProcessor<Data, WatchedQuerySettings<Data>> {
-  constructor(protected options: OnChangeQueryProcessorOptions<Data>) {
-    super(options);
-  }
-
-  /**
-   * @returns If the sets are equal
-   */
-  protected checkEquality(current: Data, previous: Data): boolean {
-    // Use the provided comparator if available. Assume values are unique if not available.
-    return this.options.comparator?.checkEquality?.(current, previous) ?? false;
-  }
-
-  protected async linkQuery(options: LinkQueryOptions<Data>): Promise<void> {
-    const { db, watchOptions } = this.options;
-    const { abortSignal } = options;
-
-    const compiledQuery = watchOptions.query.compile();
-    const tables = await db.resolveTables(compiledQuery.sql, compiledQuery.parameters as any[], {
-      tables: options.settings.triggerOnTables
-    });
-
-    db.onChangeWithCallback(
-      {
-        onChange: async () => {
-          if (this.closed || abortSignal.aborted) {
-            return;
-          }
-          // This fires for each change of the relevant tables
-          try {
-            if (this.reportFetching && !this.state.isFetching) {
-              await this.updateState({ isFetching: true });
-            }
-
-            const partialStateUpdate: Partial<MutableWatchedQueryState<Data>> & { data?: Data } = {};
-
-            // Always run the query if an underlying table has changed
-            const result = await watchOptions.query.execute({
-              sql: compiledQuery.sql,
-              // Allows casting from ReadOnlyArray[unknown] to Array<unknown>
-              // This allows simpler compatibility with PowerSync queries
-              parameters: [...compiledQuery.parameters],
-              db: this.options.db
-            });
-
-            if (abortSignal.aborted) {
-              return;
-            }
-
-            if (this.reportFetching) {
-              partialStateUpdate.isFetching = false;
-            }
-
-            if (this.state.isLoading) {
-              partialStateUpdate.isLoading = false;
-            }
-
-            // Check if the result has changed
-            if (!this.checkEquality(result, this.state.data)) {
-              Object.assign(partialStateUpdate, {
-                data: result
-              });
-            }
-
-            if (this.state.error) {
-              partialStateUpdate.error = null;
-            }
-
-            if (Object.keys(partialStateUpdate).length > 0) {
-              await this.updateState(partialStateUpdate);
-            }
-          } catch (error) {
-            await this.updateState({ error });
-          }
-        },
-        onError: async (error) => {
-          await this.updateState({ error });
-        }
-      },
-      {
-        signal: abortSignal,
-        tables,
-        throttleMs: watchOptions.throttleMs,
-        triggerImmediate: true // used to emit the initial state
-      }
-    );
-  }
-}

package/src/client/watched/processors/comparators.ts

@@ -2,6 +2,8 @@
  * A basic comparator for incrementally watched queries. This performs a single comparison which
  * determines if the result set has changed. The {@link WatchedQuery} will only emit the new result
  * if a change has been detected.
+ *
+ * @public
  */
 export interface WatchedQueryComparator<Data> {
   checkEquality: (current: Data, previous: Data) => boolean;
@@ -9,6 +11,8 @@ export interface WatchedQueryComparator<Data> {
 
 /**
  * Options for {@link ArrayComparator}
+ *
+ * @public
  */
 export type ArrayComparatorOptions<ItemType> = {
   /**
@@ -20,6 +24,8 @@ export type ArrayComparatorOptions<ItemType> = {
 /**
  * An efficient comparator for {@link WatchedQuery} created with {@link Query#watch}. This has the ability to determine if a query
  * result has changes without necessarily processing all items in the result.
+ *
+ * @public
  */
 export class ArrayComparator<ItemType> implements WatchedQueryComparator<ItemType[]> {
   constructor(protected options: ArrayComparatorOptions<ItemType>) {}
@@ -51,6 +57,8 @@ export class ArrayComparator<ItemType> implements WatchedQueryComparator<ItemTyp
 
 /**
  * Watched query comparator that always reports changed result sets.
+ *
+ * @public
  */
 export const FalsyComparator: WatchedQueryComparator<unknown> = {
   checkEquality: () => false // Default comparator that always returns false