feat: add granular component re-render control

Author: boschni

docs/src/pages/reference/useQuery.md

@@ -26,9 +26,8 @@ const {
   initialData,
   isDataEqual,
   keepPreviousData,
-  notifyOnFetchChange,
-  notifyOnStaleChange,
-  notifyOnStatusChange,
+  notifyOnChangeProps,
+  notifyOnChangePropsExclusions,
   onError,
   onSettled,
   onSuccess,
@@ -109,14 +108,14 @@ const result = useQuery({
   - If set to `true`, the query will refetch on reconnect if the data is stale.
   - If set to `false`, the query will not refetch on reconnect.
   - If set to `"always"`, the query will always refetch on reconnect.
-- `notifyOnStaleChange: boolean`
+- `notifyOnChangeProps: string[]`
   - Optional
-  - Set this to `true` to re-render when the `isStale` property changes.
-  - Defaults to `false`.
-- `notifyOnStatusChange: boolean`
+  - If set, the component will only re-render if any of the listed properties change.
+  - If set to `['data', 'error']` for example, the component will only re-render when the `data` or `error` properties change.
+- `notifyOnChangePropsExclusions: string[]`
   - Optional
-  - Set this to `false` to only re-render when there are changes to `data` or `error`.
-  - Defaults to `true`.
+  - If set, the component will not re-render if any of the listed properties change.
+  - If set to `['isStale']` for example, the component will not re-render when the `isStale` property changes.
 - `onSuccess: (data: TData) => void`
   - Optional
   - This function will fire any time the query successfully fetches new data.

src/core/queryObserver.ts

@@ -288,9 +288,10 @@ export class QueryObserver<
 
     this.staleTimeoutId = setTimeout(() => {
       if (!this.currentResult.isStale) {
+        const prevResult = this.currentResult
         this.updateResult()
         this.notify({
-          listeners: this.options.notifyOnStaleChange === true,
+          listeners: this.shouldNotifyListeners(prevResult, this.currentResult),
           cache: true,
         })
       }
@@ -423,6 +424,42 @@ export class QueryObserver<
     return result as QueryObserverResult<TData, TError>
   }
 
+  private shouldNotifyListeners(
+    prevResult: QueryObserverResult,
+    result: QueryObserverResult
+  ): boolean {
+    const { notifyOnChangeProps, notifyOnChangePropsExclusions } = this.options
+
+    if (prevResult === result) {
+      return false
+    }
+
+    if (!notifyOnChangeProps && !notifyOnChangePropsExclusions) {
+      return true
+    }
+
+    const keys = Object.keys(result)
+
+    for (let i = 0; i < keys.length; i++) {
+      const key = keys[i] as keyof QueryObserverResult
+      const changed = prevResult[key] !== result[key]
+      const isIncluded = notifyOnChangeProps?.some(x => x === key)
+      const isExcluded = notifyOnChangePropsExclusions?.some(x => x === key)
+
+      if (changed) {
+        if (notifyOnChangePropsExclusions && isExcluded) {
+          break
+        }
+
+        if (!notifyOnChangeProps || isIncluded) {
+          return true
+        }
+      }
+    }
+
+    return false
+  }
+
   private updateResult(willFetch?: boolean): void {
     const result = this.getNewResult(willFetch)
 
@@ -466,7 +503,9 @@ export class QueryObserver<
     prevQuery?.removeObserver(this)
     this.currentQuery.addObserver(this)
 
-    if (this.options.notifyOnStatusChange !== false) {
+    if (
+      this.shouldNotifyListeners(this.previousQueryResult, this.currentResult)
+    ) {
       this.notify({ listeners: true })
     }
   }
@@ -494,13 +533,7 @@ export class QueryObserver<
       notifyOptions.onError = true
     }
 
-    if (
-      // Always notify if notifyOnStatusChange is set
-      this.options.notifyOnStatusChange !== false ||
-      // Otherwise only notify on data or error change
-      currentResult.data !== prevResult.data ||
-      currentResult.error !== prevResult.error
-    ) {
+    if (this.shouldNotifyListeners(prevResult, currentResult)) {
       notifyOptions.listeners = true
     }
 

src/core/tests/queryCache.test.tsx

@@ -614,7 +614,7 @@ describe('queryCache', () => {
     const testCache = new QueryCache()
     const testClient = new QueryClient({
       queryCache: testCache,
-      defaultOptions: { queries: { notifyOnStaleChange: true } },
+      defaultOptions: { queries: { notifyOnChangePropsExclusions: [] } },
     })
     const observer = new QueryObserver(testClient, {
       queryKey: key,

src/core/types.ts

@@ -128,16 +128,14 @@ export interface QueryObserverOptions<
    */
   refetchOnMount?: boolean | 'always'
   /**
-   * Whether a component should re-render when the `isStale` property changes.
-   * Defaults to `false`.
+   * If set, the component will only re-render if any of the listed properties change.
+   * When set to `['data', 'error']`, the component will only re-render when the `data` or `error` properties change.
    */
-  notifyOnStaleChange?: boolean
+  notifyOnChangeProps?: Array<keyof InfiniteQueryObserverResult>
   /**
-   * Whether a change to the query status should re-render a component.
-   * If set to `false`, the component will only re-render when the actual `data` or `error` changes.
-   * Defaults to `true`.
+   * If set, the component will not re-render if any of the listed properties change.
    */
-  notifyOnStatusChange?: boolean
+  notifyOnChangePropsExclusions?: Array<keyof InfiniteQueryObserverResult>
   /**
    * This callback will fire any time the query successfully fetches new data.
    */

src/react/tests/useInfiniteQuery.test.tsx

@@ -45,7 +45,7 @@ describe('useInfiniteQuery', () => {
     queryCache,
     defaultOptions: {
       queries: {
-        notifyOnStaleChange: true,
+        notifyOnChangePropsExclusions: [],
       },
     },
   })

src/react/tests/useQuery.test.tsx

@@ -20,14 +20,7 @@ import {
 
 describe('useQuery', () => {
   const queryCache = new QueryCache()
-  const queryClient = new QueryClient({
-    queryCache,
-    defaultOptions: {
-      queries: {
-        notifyOnStaleChange: true,
-      },
-    },
-  })
+  const queryClient = new QueryClient({ queryCache })
 
   it('should return the correct types', () => {
     const key = queryKey()
@@ -665,8 +658,7 @@ describe('useQuery', () => {
     function Page() {
       const state = useQuery(key, () => ({ name: 'test' }), {
         select: data => data.name,
-        notifyOnStaleChange: false,
-        notifyOnStatusChange: false,
+        notifyOnChangeProps: ['data'],
       })
 
       states.push(state)
@@ -1266,7 +1258,9 @@ describe('useQuery', () => {
 
     renderWithClient(queryClient, <Page />)
 
-    await waitFor(() => expect(states.length).toBe(7))
+    await sleep(100)
+
+    expect(states.length).toBe(6)
 
     // Disabled query
     expect(states[0]).toMatchObject({
@@ -1298,20 +1292,13 @@ describe('useQuery', () => {
     })
     // Switched query key
     expect(states[4]).toMatchObject({
-      data: 10,
-      isFetching: false,
-      isSuccess: true,
-      isPreviousData: true,
-    })
-    // Refetch
-    expect(states[5]).toMatchObject({
       data: 10,
       isFetching: true,
       isSuccess: true,
       isPreviousData: true,
     })
     // Refetch done
-    expect(states[6]).toMatchObject({
+    expect(states[5]).toMatchObject({
       data: 12,
       isFetching: false,
       isSuccess: true,
@@ -1516,8 +1503,7 @@ describe('useQuery', () => {
           return 'test'
         },
         {
-          notifyOnStatusChange: false,
-          notifyOnStaleChange: false,
+          notifyOnChangeProps: ['data'],
         }
       )