rename comparator to rowComparator for useQuery and query.differentialWatch methods.

Author: stevensJourney

.changeset/nine-pens-ring.md

@@ -4,12 +4,12 @@
 
 [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 `comparator` 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 `rowComparator` 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'], {
-  comparator: {
+  rowComparator: {
     keyBy: (item) => item.id,
     compareBy: (item) => JSON.stringify(item)
   }

.changeset/swift-guests-explain.md

@@ -2,12 +2,12 @@
 '@powersync/react': minor
 ---
 
-- 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.
+- Added the ability to limit re-renders by specifying a `rowComparator` 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'], {
-  comparator: {
+  rowComparator: {
     keyBy: (item) => item.id,
     compareBy: (item) => JSON.stringify(item)
   }

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

@@ -63,7 +63,7 @@ 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.
      */
-    comparator: {
+    rowComparator: {
       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,
-      comparator: differentialWatchOptions?.comparator,
+      rowComparator: differentialWatchOptions?.rowComparator,
       placeholderData: differentialWatchOptions?.placeholderData ?? [],
       watchOptions: {
         ...this.resolveOptions(differentialWatchOptions),

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

@@ -65,12 +65,12 @@ export interface DifferentialWatchedQueryOptions<RowType> extends WatchedQueryOp
   placeholderData?: RowType[];
 
   /**
-   * Comparator used to identify and compare items in the result set.
+   * 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_COMPARATOR}
    */
-  comparator?: DifferentialWatchedQueryComparator<RowType>;
+  rowComparator?: DifferentialWatchedQueryComparator<RowType>;
 }
 
 /**
@@ -99,7 +99,7 @@ export type DifferentialWatchedQuery<RowType> = WatchedQuery<
  */
 export interface DifferentialQueryProcessorOptions<RowType>
   extends AbstractQueryProcessorOptions<RowType[], DifferentialWatchedQuerySettings<RowType>> {
-  comparator?: DifferentialWatchedQueryComparator<RowType>;
+  rowComparator?: DifferentialWatchedQueryComparator<RowType>;
 }
 
 type DataHashMap<RowType> = Map<string, { hash: string; item: RowType }>;
@@ -144,7 +144,7 @@ export class DifferentialQueryProcessor<RowType>
 
   constructor(protected options: DifferentialQueryProcessorOptions<RowType>) {
     super(options);
-    this.comparator = options.comparator ?? DEFAULT_COMPARATOR;
+    this.comparator = options.rowComparator ?? DEFAULT_COMPARATOR;
   }
 
   /*

packages/react/README.md

@@ -346,7 +346,7 @@ 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'`, [], {
-      comparator: {
+      rowComparator: {
             keyBy: (item) => item.id,
             compareBy: (item) => JSON.stringify(item)
       }
@@ -374,7 +374,7 @@ 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'`, [], {
-    comparator: {
+    rowComparator: {
       keyBy: (item) => item.id,
       compareBy: (item) => JSON.stringify(item)
       }

packages/react/src/QueryStore.ts

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

packages/react/src/hooks/suspense/useSuspenseQuery.ts

@@ -32,7 +32,7 @@ import { useWatchedSuspenseQuery } from './useWatchedSuspenseQuery';
  * // The internal array object references are maintained for unchanged rows.
  * // The returned lists array is read only when a `comparator` is provided.
  * const { data: lists }  = useSuspenseQuery('SELECT * from lists', [], {
- *  comparator: {
+ *  rowComparator: {
  *     keyBy: (item) => item.id,
  *     compareBy: (item) => JSON.stringify(item)
  *   }

packages/react/src/hooks/watched/useQuery.ts

@@ -26,7 +26,7 @@ import { constructCompatibleQuery } from './watch-utils';
  * // The internal array object references are maintained for unchanged rows.
  * // The returned lists array is read only when a `comparator` is provided.
  * const { data: lists }  = useQuery('SELECT * from lists', [], {
- *  comparator: {
+ *  rowComparator: {
  *     keyBy: (item) => item.id,
  *     compareBy: (item) => JSON.stringify(item)
  *   }
@@ -78,7 +78,7 @@ export function useQuery<RowType = any>(
           // Maintains backwards compatibility with previous versions
           // Differentiation is opt-in by default
           // We emit new data for each table change by default.
-          comparator: options.comparator
+          rowComparator: options.rowComparator
         }
       });
   }

packages/react/src/hooks/watched/useWatchedQuery.ts

@@ -17,9 +17,9 @@ export const useWatchedQuery = <RowType = unknown>(
   const { query, powerSync, queryChanged, options: hookOptions } = options;
 
   const createWatchedQuery = React.useCallback(() => {
-    const watch = hookOptions.comparator
+    const watch = hookOptions.rowComparator
       ? powerSync.customQuery(query).differentialWatch({
-          comparator: hookOptions.comparator,
+          rowComparator: hookOptions.rowComparator,
           reportFetching: hookOptions.reportFetching,
           throttleMs: hookOptions.throttleMs
         })