Revert breaking changes for react package.

Author: stevensJourney

.changeset/nine-pens-ring.md

@@ -2,13 +2,16 @@
 '@powersync/vue': 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.
+[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.
 
 ```javascript
- useQuery('SELECT * FROM lists WHERE name = ?', ['todo'], {
-    // This will be used to compare result sets between internal queries
-    comparator: new ArrayComparator({
-        compareBy: (item) => JSON.stringify(item)
-    })
-}),
+// 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,
+    compareBy: (item) => JSON.stringify(item)
+  }
+});
 ```

.changeset/swift-guests-explain.md

@@ -2,13 +2,14 @@
 '@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 `differentiator` for query results. The `useQuery` hook will only emit `data` changes when the data has changed.
 
 ```javascript
- useQuery('SELECT * FROM lists WHERE name = ?', ['todo'], {
-    // This will be used to compare result sets between internal queries
-    comparator: new ArrayComparator({
-        compareBy: (item) => JSON.stringify(item)
-    })
-}),
+// 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,
+    compareBy: (item) => JSON.stringify(item)
+  }
+});
 ```

.changeset/tricky-bottles-greet.md

@@ -4,12 +4,12 @@ import {
   WatchedQuery,
   WatchedQueryListenerEvent
 } from '@powersync/common';
-import { AdditionalOptions } from './hooks/watched/watch-types';
+import { DifferentialHookOptions } from './hooks/watched/watch-types';
 
 export function generateQueryKey(
   sqlStatement: string,
   parameters: ReadonlyArray<unknown>,
-  options: AdditionalOptions
+  options: DifferentialHookOptions<unknown>
 ): string {
   return `${sqlStatement} -- ${JSON.stringify(parameters)} -- ${JSON.stringify(options)}`;
 }
@@ -19,7 +19,7 @@ export class QueryStore {
 
   constructor(private db: AbstractPowerSyncDatabase) {}
 
-  getQuery<RowType>(key: string, query: WatchCompatibleQuery<RowType[]>, options: AdditionalOptions) {
+  getQuery<RowType>(key: string, query: WatchCompatibleQuery<RowType[]>, options: DifferentialHookOptions<RowType>) {
     if (this.cache.has(key)) {
       return this.cache.get(key) as WatchedQuery<RowType[]>;
     }

packages/react/src/QueryStore.ts

@@ -1,3 +1,4 @@
-import { QueryResult } from '../watched/watch-types';
+import { QueryResult, ReadonlyQueryResult } from '../watched/watch-types';
 
 export type SuspenseQueryResult<T> = Pick<QueryResult<T>, 'data' | 'refresh'>;
+export type ReadonlySuspenseQueryResult<T> = Pick<ReadonlyQueryResult<T>, 'data' | 'refresh'>;

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

@@ -1,13 +1,15 @@
 import { CompilableQuery } from '@powersync/common';
-import { AdditionalOptions } from '../watched/watch-types';
-import { SuspenseQueryResult } from './SuspenseQueryResult';
+import { AdditionalOptions, DifferentialHookOptions } from '../watched/watch-types';
+import { ReadonlySuspenseQueryResult, SuspenseQueryResult } from './SuspenseQueryResult';
 import { useSingleSuspenseQuery } from './useSingleSuspenseQuery';
 import { useWatchedSuspenseQuery } from './useWatchedSuspenseQuery';
 
 /**
  * A hook to access the results of a watched query that suspends until the initial result has loaded.
  * @example
  * export const ContentComponent = () => {
+ * // The lists array here will be a new Array reference whenever a change to the
+ * // lists table is made.
  * const { data: lists }  = useSuspenseQuery('SELECT * from lists');
  *
  * return <View>
@@ -24,16 +26,51 @@ import { useWatchedSuspenseQuery } from './useWatchedSuspenseQuery';
  *    </Suspense>
  * );
  * }
+ *
+ * export const DiffContentComponent = () => {
+ * // A differential query will emit results when a change to the result set occurs.
+ * // The internal array object references are maintained for unchanged rows.
+ * // The returned lists array is read only when a `differentiator` is provided.
+ * const { data: lists }  = useSuspenseQuery('SELECT * from lists', [], {
+ *  differentiator: {
+ *     identify: (item) => item.id,
+ *     compareBy: (item) => JSON.stringify(item)
+ *   }
+ * });
+ * return <View>
+ *   {lists.map((l) => (
+ *     <Text key={l.id}>{JSON.stringify(l)}</Text>
+ *   ))}
+ * </View>;
+ * }
+ *
+ * export const DisplayComponent = () => {
+ * return (
+ *    <Suspense fallback={<div>Loading content...</div>}>
+ *       <ContentComponent />
+ *    </Suspense>
+ * );
+ * }
  */
-export const useSuspenseQuery = <T = any>(
-  query: string | CompilableQuery<T>,
+export function useSuspenseQuery<RowType = any>(
+  query: string | CompilableQuery<RowType>,
+  parameters?: any[],
+  options?: AdditionalOptions
+): SuspenseQueryResult<RowType>;
+export function useSuspenseQuery<RowType = any>(
+  query: string | CompilableQuery<RowType>,
+  paramerers?: any[],
+  options?: DifferentialHookOptions<RowType>
+): ReadonlySuspenseQueryResult<RowType>;
+export function useSuspenseQuery<RowType = any>(
+  query: string | CompilableQuery<RowType>,
   parameters: any[] = [],
-  options: AdditionalOptions<T> = {}
-): SuspenseQueryResult<T> => {
-  switch (options.runQueryOnce) {
+  options: AdditionalOptions & DifferentialHookOptions<RowType> = {}
+) {
+  switch (options?.runQueryOnce) {
     case true:
-      return useSingleSuspenseQuery<T>(query, parameters, options);
+      return useSingleSuspenseQuery<RowType>(query, parameters, options);
     default:
-      return useWatchedSuspenseQuery<T>(query, parameters, options);
+      return useWatchedSuspenseQuery<RowType>(query, parameters, options);
   }
-};
+}

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

@@ -3,14 +3,16 @@ import { generateQueryKey, getQueryStore } from '../../QueryStore';
 import { usePowerSync } from '../PowerSyncContext';
 import { AdditionalOptions } from '../watched/watch-types';
 import { constructCompatibleQuery } from '../watched/watch-utils';
-import { SuspenseQueryResult } from './SuspenseQueryResult';
 import { useWatchedQuerySuspenseSubscription } from './useWatchedQuerySuspenseSubscription';
 
+/**
+ * @internal This is not exported in the index.ts
+ */
 export const useWatchedSuspenseQuery = <T = any>(
   query: string | CompilableQuery<T>,
   parameters: any[] = [],
   options: AdditionalOptions = {}
-): SuspenseQueryResult<T> => {
+) => {
   const powerSync = usePowerSync();
   if (!powerSync) {
     throw new Error('PowerSync not configured.');

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

@@ -2,13 +2,16 @@ import { type CompilableQuery } from '@powersync/common';
 import { usePowerSync } from '../PowerSyncContext';
 import { useSingleQuery } from './useSingleQuery';
 import { useWatchedQuery } from './useWatchedQuery';
-import { AdditionalOptions, QueryResult } from './watch-types';
+import { AdditionalOptions, DifferentialHookOptions, QueryResult, ReadonlyQueryResult } from './watch-types';
 import { constructCompatibleQuery } from './watch-utils';
 
 /**
  * A hook to access the results of a watched query.
  * @example
+ *
  * export const Component = () => {
+ * // The lists array here will be a new Array reference whenever a change to the
+ * // lists table is made.
  * const { data: lists }  = useQuery('SELECT * from lists');
  *
  * return <View>
@@ -17,20 +20,48 @@ import { constructCompatibleQuery } from './watch-utils';
  *   ))}
  * </View>
  * }
+ *
+ * export const DiffComponent = () => {
+ * // A differential query will emit results when a change to the result set occurs.
+ * // The internal array object references are maintained for unchanged rows.
+ * // The returned lists array is read only when a `differentiator` is provided.
+ * const { data: lists }  = useQuery('SELECT * from lists', [], {
+ *  differentiator: {
+ *     identify: (item) => item.id,
+ *     compareBy: (item) => JSON.stringify(item)
+ *   }
+ * });
+ *
+ * return <View>
+ *   {lists.map((l) => (
+ *     <Text key={l.id}>{JSON.stringify(l)}</Text>
+ *   ))}
+ * </View>
+ * }
  */
-export const useQuery = <RowType = any>(
+
+export function useQuery<RowType = any>(
+  query: string | CompilableQuery<RowType>,
+  parameters?: any[],
+  options?: AdditionalOptions
+): QueryResult<RowType>;
+export function useQuery<RowType = any>(
+  query: string | CompilableQuery<RowType>,
+  paramerers?: any[],
+  options?: DifferentialHookOptions<RowType>
+): ReadonlyQueryResult<RowType>;
+export function useQuery<RowType = any>(
   query: string | CompilableQuery<RowType>,
   parameters: any[] = [],
-  options: AdditionalOptions<RowType> = { runQueryOnce: false }
-): QueryResult<RowType> => {
+  options: AdditionalOptions & DifferentialHookOptions<RowType> = {}
+) {
   const powerSync = usePowerSync();
   if (!powerSync) {
     return { isLoading: false, isFetching: false, data: [], error: new Error('PowerSync not configured.') };
   }
-
   const { parsedQuery, queryChanged } = constructCompatibleQuery(query, parameters, options);
 
-  switch (options.runQueryOnce) {
+  switch (options?.runQueryOnce) {
     case true:
       return useSingleQuery<RowType>({
         query: parsedQuery,
@@ -51,4 +82,4 @@ export const useQuery = <RowType = any>(
         }
       });
   }
-};
+}

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

@@ -1,11 +1,19 @@
 import React from 'react';
 import { useWatchedQuerySubscription } from './useWatchedQuerySubscription';
-import { HookWatchOptions, QueryResult } from './watch-types';
+import { DifferentialHookOptions, QueryResult, ReadonlyQueryResult } from './watch-types';
 import { InternalHookOptions } from './watch-utils';
 
+/**
+ * @internal This is not exported from the index.ts
+ *
+ * When a differential query is used the return type is readonly. This is required
+ * since the implementation requires a stable ref.
+ * For legacy compatibility we allow mutating when a standard query is used. Mutations should
+ * not affect the internal implementation in this case.
+ */
 export const useWatchedQuery = <RowType = unknown>(
-  options: InternalHookOptions<RowType[]> & { options: HookWatchOptions }
-): QueryResult<RowType> => {
+  options: InternalHookOptions<RowType[]> & { options: DifferentialHookOptions<RowType> }
+): QueryResult<RowType> | ReadonlyQueryResult<RowType> => {
   const { query, powerSync, queryChanged, options: hookOptions } = options;
 
   const createWatchedQuery = React.useCallback(() => {

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

@@ -1,15 +1,18 @@
 import { SQLOnChangeOptions, WatchedQueryDifferentiator } from '@powersync/common';
 
-export interface HookWatchOptions<RowType = unknown> extends Omit<SQLOnChangeOptions, 'signal'> {
+export interface HookWatchOptions extends Omit<SQLOnChangeOptions, 'signal'> {
   reportFetching?: boolean;
-  differentiator?: WatchedQueryDifferentiator<RowType>;
 }
 
-export interface AdditionalOptions<RowType = unknown> extends HookWatchOptions<RowType> {
+export interface AdditionalOptions extends HookWatchOptions {
   runQueryOnce?: boolean;
 }
 
-export type QueryResult<RowType> = {
+export interface DifferentialHookOptions<RowType> extends HookWatchOptions {
+  differentiator?: WatchedQueryDifferentiator<RowType>;
+}
+
+export type ReadonlyQueryResult<RowType> = {
   readonly data: ReadonlyArray<Readonly<RowType>>;
   /**
    * Indicates the initial loading state (hard loading). Loading becomes false once the first set of results from the watched query is available or an error occurs.
@@ -25,3 +28,20 @@ export type QueryResult<RowType> = {
    */
   refresh?: (signal?: AbortSignal) => Promise<void>;
 };
+
+export type QueryResult<RowType> = {
+  data: RowType[];
+  /**
+   * Indicates the initial loading state (hard loading). Loading becomes false once the first set of results from the watched query is available or an error occurs.
+   */
+  isLoading: boolean;
+  /**
+   * Indicates whether the query is currently fetching data, is true during the initial load and any time when the query is re-evaluating (useful for large queries).
+   */
+  isFetching: boolean;
+  error: Error | undefined;
+  /**
+   * Function used to run the query again.
+   */
+  refresh?: (signal?: AbortSignal) => Promise<void>;
+};