use comparator as the option name for hooks. Update identify to keyBy for differential watches.

Author: stevensJourney

.changeset/nine-pens-ring.md

@@ -4,13 +4,13 @@
 
 [Potentially breaking change] The `useQuery` hook results are now explicitly defined as readonly. These values should not be mutated.
 
-- Added the ability to limit re-renders by specifying a `differentiator` for query results. The `useQuery` hook will only emit `data` changes when the data has changed.
+- Added the ability to limit re-renders by specifying a `comparator` for query results. The `useQuery` hook will only emit `data` changes when the data has changed.
 
 ```javascript
 // The data here will maintain previous object references for unchanged items.
 const { data } = useQuery('SELECT * FROM lists WHERE name = ?', ['aname'], {
-  differentiator: {
-    identify: (item) => item.id,
+  comparator: {
+    keyBy: (item) => item.id,
     compareBy: (item) => JSON.stringify(item)
   }
 });

.changeset/swift-guests-explain.md

@@ -2,13 +2,13 @@
 '@powersync/react': minor
 ---
 
-- Added the ability to limit re-renders by specifying a `differentiator` for query results. The `useQuery` hook will only emit `data` changes when the data has changed.
+- Added the ability to limit re-renders by specifying a `comparator` for query results. The `useQuery` hook will only emit `data` changes when the data has changed.
 
 ```javascript
 // The data here will maintain previous object references for unchanged items.
 const { data } = useQuery('SELECT * FROM lists WHERE name = ?', ['aname'], {
-  differentiator: {
-    identify: (item) => item.id,
+  comparator: {
+    keyBy: (item) => item.id,
     compareBy: (item) => JSON.stringify(item)
   }
 });

demos/react-supabase-todolist/src/app/views/sql-console/page.tsx

@@ -63,8 +63,8 @@ export default function SQLConsolePage() {
      * The query here will only emit results when the query data set changes.
      * Result sets are compared by serializing each item to JSON and comparing the strings.
      */
-    differentiator: {
-      identify: (item: any) => JSON.stringify(item),
+    comparator: {
+      keyBy: (item: any) => JSON.stringify(item),
       compareBy: (item: any) => JSON.stringify(item)
     }
   });

packages/common/src/client/CustomQuery.ts

@@ -44,7 +44,7 @@ export class CustomQuery<RowType> implements Query<RowType> {
   differentialWatch(differentialWatchOptions: DifferentialWatchedQueryOptions<RowType>) {
     return new DifferentialQueryProcessor<RowType>({
       db: this.options.db,
-      differentiator: differentialWatchOptions?.differentiator,
+      comparator: differentialWatchOptions?.comparator,
       placeholderData: differentialWatchOptions?.placeholderData ?? [],
       watchOptions: {
         ...this.resolveOptions(differentialWatchOptions),

packages/common/src/client/Query.ts

@@ -3,7 +3,7 @@ import {
   DifferentialWatchedQuery,
   DifferentialWatchedQueryOptions
 } from './watched/processors/DifferentialQueryProcessor.js';
-import { ComparisonWatchedQuery } from './watched/processors/OnChangeQueryProcessor.js';
+import { StandardWatchedQuery } from './watched/processors/OnChangeQueryProcessor.js';
 import { WatchedQueryOptions } from './watched/WatchedQuery.js';
 
 /**
@@ -73,7 +73,7 @@ export interface Query<RowType> {
    * 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>>>;
+  watch(options?: StandardWatchedQueryOptions<RowType>): StandardWatchedQuery<ReadonlyArray<Readonly<RowType>>>;
 
   /**
    * Creates a {@link WatchedQuery} which watches and emits results of the linked query.

packages/common/src/client/watched/processors/DifferentialQueryProcessor.ts

@@ -42,13 +42,13 @@ export interface WatchedQueryDifferential<RowType> {
 }
 
 /**
- * Differentiator for incremental watched queries which allows to identify and compare items in the result set.
+ * Comparator for differentially watched queries which keys and compares items in the result set.
  */
-export interface WatchedQueryDifferentiator<RowType> {
+export interface DifferentialWatchedQueryComparator<RowType> {
   /**
    * Unique identifier for the item.
    */
-  identify: (item: RowType) => string;
+  keyBy: (item: RowType) => string;
   /**
    * Generates a key for comparing items with matching identifiers.
    */
@@ -65,12 +65,12 @@ export interface DifferentialWatchedQueryOptions<RowType> extends WatchedQueryOp
   placeholderData?: RowType[];
 
   /**
-   * Differentiator used to identify and compare items in the result set.
-   * If not provided, the default differentiator will be used which identifies items by their `id` property if available,
-   * otherwise it uses JSON stringification of the entire item for identification and comparison.
-   * @defaultValue {@link DEFAULT_WATCHED_QUERY_DIFFERENTIATOR}
+   * Comparator used to identify and compare items 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_DIFFERENTIAL_WATCHED_QUERY_COMPARATOR}
    */
-  differentiator?: WatchedQueryDifferentiator<RowType>;
+  comparator?: DifferentialWatchedQueryComparator<RowType>;
 }
 
 /**
@@ -99,7 +99,7 @@ export type DifferentialWatchedQuery<RowType> = WatchedQuery<
  */
 export interface DifferentialQueryProcessorOptions<RowType>
   extends AbstractQueryProcessorOptions<RowType[], DifferentialWatchedQuerySettings<RowType>> {
-  differentiator?: WatchedQueryDifferentiator<RowType>;
+  comparator?: DifferentialWatchedQueryComparator<RowType>;
 }
 
 type DataHashMap<RowType> = Map<string, { hash: string; item: RowType }>;
@@ -117,12 +117,12 @@ export const EMPTY_DIFFERENTIAL = {
 };
 
 /**
- * Default implementation of the {@link Differentiator} for watched queries.
- * It identifies items by their `id` property if available, otherwise it uses JSON stringification
- * of the entire item for identification and comparison.
+ * 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_WATCHED_QUERY_DIFFERENTIATOR: WatchedQueryDifferentiator<any> = {
-  identify: (item) => {
+export const DEFAULT_DIFFERENTIAL_WATCHED_QUERY_COMPARATOR: DifferentialWatchedQueryComparator<any> = {
+  keyBy: (item) => {
     if (item && typeof item == 'object' && typeof item['id'] == 'string') {
       return item['id'];
     }
@@ -140,11 +140,11 @@ export class DifferentialQueryProcessor<RowType>
   extends AbstractQueryProcessor<ReadonlyArray<Readonly<RowType>>, DifferentialWatchedQuerySettings<RowType>>
   implements DifferentialWatchedQuery<RowType>
 {
-  protected differentiator: WatchedQueryDifferentiator<RowType>;
+  protected comparator: DifferentialWatchedQueryComparator<RowType>;
 
   constructor(protected options: DifferentialQueryProcessorOptions<RowType>) {
     super(options);
-    this.differentiator = options.differentiator ?? DEFAULT_WATCHED_QUERY_DIFFERENTIATOR;
+    this.comparator = options.comparator ?? DEFAULT_DIFFERENTIAL_WATCHED_QUERY_COMPARATOR;
   }
 
   /*
@@ -154,7 +154,7 @@ export class DifferentialQueryProcessor<RowType>
     current: RowType[],
     previousMap: DataHashMap<RowType>
   ): { diff: WatchedQueryDifferential<RowType>; map: DataHashMap<RowType>; hasChanged: boolean } {
-    const { identify, compareBy } = this.differentiator;
+    const { keyBy, compareBy } = this.comparator;
 
     let hasChanged = false;
     const currentMap = new Map<string, { hash: string; item: RowType }>();
@@ -175,7 +175,7 @@ export class DifferentialQueryProcessor<RowType>
      * We can replace items in the current array with previous object references if they are equal.
      */
     for (const item of current) {
-      const key = identify(item);
+      const key = keyBy(item);
       const hash = compareBy(item);
       currentMap.set(key, { hash, item });
 
@@ -225,8 +225,8 @@ export class DifferentialQueryProcessor<RowType>
 
     // populate the currentMap from the placeholder data
     this.state.data.forEach((item) => {
-      currentMap.set(this.differentiator.identify(item), {
-        hash: this.differentiator.compareBy(item),
+      currentMap.set(this.comparator.keyBy(item), {
+        hash: this.comparator.compareBy(item),
         item
       });
     });

packages/common/src/client/watched/processors/OnChangeQueryProcessor.ts

@@ -7,17 +7,23 @@ import {
 } from './AbstractQueryProcessor.js';
 import { WatchedQueryComparator } from './comparators.js';
 
-export interface ComparisonWatchedQuerySettings<DataType> extends WatchedQueryOptions {
+/**
+ * Settings for {@link WatchedQuery} instances created via {@link Query#watch}.
+ */
+export interface WatchedQuerySettings<DataType> extends WatchedQueryOptions {
   query: WatchCompatibleQuery<DataType>;
 }
 
-export type ComparisonWatchedQuery<DataType> = WatchedQuery<DataType, ComparisonWatchedQuerySettings<DataType>>;
+/**
+ * {@link WatchedQuery} returned from {@link Query#watch}.
+ */
+export type StandardWatchedQuery<DataType> = WatchedQuery<DataType, WatchedQuerySettings<DataType>>;
 
 /**
  * @internal
  */
 export interface OnChangeQueryProcessorOptions<Data>
-  extends AbstractQueryProcessorOptions<Data, ComparisonWatchedQuerySettings<Data>> {
+  extends AbstractQueryProcessorOptions<Data, WatchedQuerySettings<Data>> {
   comparator?: WatchedQueryComparator<Data>;
 }
 
@@ -26,7 +32,7 @@ export interface OnChangeQueryProcessorOptions<Data>
  * Results are emitted on every change of the relevant tables.
  * @internal
  */
-export class OnChangeQueryProcessor<Data> extends AbstractQueryProcessor<Data, ComparisonWatchedQuerySettings<Data>> {
+export class OnChangeQueryProcessor<Data> extends AbstractQueryProcessor<Data, WatchedQuerySettings<Data>> {
   constructor(protected options: OnChangeQueryProcessorOptions<Data>) {
     super(options);
   }

packages/common/src/client/watched/processors/comparators.ts

@@ -1,3 +1,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.
+ */
 export interface WatchedQueryComparator<Data> {
   checkEquality: (current: Data, previous: Data) => boolean;
 }
@@ -13,7 +18,8 @@ export type ArrayComparatorOptions<ItemType> = {
 };
 
 /**
- * Compares array results of watched queries for incrementally watched queries created in the standard mode.
+ * 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.
  */
 export class ArrayComparator<ItemType> implements WatchedQueryComparator<ItemType[]> {
   constructor(protected options: ArrayComparatorOptions<ItemType>) {}

packages/react/README.md

@@ -346,8 +346,8 @@ function MyWidget() {
   // Note that isFetching is set (by default) whenever the query is being fetched/checked.
   // This will result in `MyWidget` re-rendering for any change to the `cats` table.
   const { data, isLoading, isFetching } = useQuery(`SELECT * FROM cats WHERE breed = 'tabby'`, [], {
-      differentiator: {
-            identify: (item) => item.id,
+      comparator: {
+            keyBy: (item) => item.id,
             compareBy: (item) => JSON.stringify(item)
       }
   })
@@ -374,8 +374,8 @@ function MyWidget() {
   // When reportFetching == false the object returned from useQuery will only be changed when the data, isLoading or error state changes.
   // This method performs a comparison in memory in order to determine changes.
   const { data, isLoading } = useQuery(`SELECT * FROM cats WHERE breed = 'tabby'`, [], {
-    differentiator: {
-      identify: (item) => item.id,
+    comparator: {
+      keyBy: (item) => item.id,
       compareBy: (item) => JSON.stringify(item)
       }
     reportFetching: false

packages/react/src/QueryStore.ts

@@ -24,9 +24,9 @@ export class QueryStore {
       return this.cache.get(key) as WatchedQuery<RowType[]>;
     }
 
-    const watch = options.differentiator
+    const watch = options.comparator
       ? this.db.customQuery(query).differentialWatch({
-          differentiator: options.differentiator,
+          comparator: options.comparator,
           reportFetching: options.reportFetching,
           throttleMs: options.throttleMs
         })