fix: make sure component re-render when they should

Author: boschni

docs/src/pages/comparison.md

@@ -55,7 +55,7 @@ Feature/Capability Key:
 
 > **<sup>1</sup> Lagged Query Data** - React Query provides a way to continue to see an existing query's data while the next query loads (similar to the same UX that suspense will soon provide natively). This is extremely important when writing pagination UIs or infinite loading UIs where you do not want to show a hard loading state whenever a new query is requested. Other libraries do not have this capability and render a hard loading state for the new query (unless it has been prefetched), while the new query loads.
 
-> **<sup>2</sup> Render Optimization** - React Query has excellent rendering performance. It will only re-render your components when a query is updated. For example because it has new data, or to indicate it is fetching. React Query also batches updates together to make sure your application only re-renders once when multiple components are using the same query. If you are only interested in the `data` or `error` properties, you can reduce the number of renders even more by setting `notifyOnStatusChange` to `false`.
+> **<sup>2</sup> Render Optimization** - React Query has excellent rendering performance. It will only re-render your components when a query is updated. For example because it has new data, or to indicate it is fetching. React Query also batches updates together to make sure your application only re-renders once when multiple components are using the same query. If you are only interested in the `data` or `error` properties, you can reduce the number of renders even more by setting `notifyOnChangeProps` to `['data', 'error']`.
 
 > **<sup>3</sup> Partial query matching** - Because React Query uses deterministic query key serialization, this allows you to manipulate variable groups of queries without having to know each individual query-key that you want to match, eg. you can refetch every query that starts with `todos` in its key, regardless of variables, or you can target specific queries with (or without) variables or nested properties, and even use a filter function to only match queries that pass your specific conditions.
 

docs/src/pages/guides/migrating-to-react-query-3.md

@@ -320,6 +320,38 @@ The `queryFnParamsFilter` option has been removed because query functions now ge
 
 Parameters can still be filtered within the query function itself as the `QueryFunctionContext` also contains the query key.
 
+### QueryOptions.notifyOnStatusChange
+
+The `notifyOnStatusChange` option has been replaced by the `notifyOnChangeProps` and `notifyOnChangePropsExclusions` props.
+
+With these options it is possible to configure when a component should re-render on a granular level.
+
+Only re-render when the `data` or `error` properties change:
+
+```js
+import { useQuery } from 'react-query'
+
+function User() {
+  const { data } = useQuery('user', fetchUser, {
+    notifyOnChangeProps: ['data', 'error'],
+  })
+  return <div>Username: {data.username}</div>
+}
+```
+
+Prevent re-render when the `isStale` property changes:
+
+```js
+import { useQuery } from 'react-query'
+
+function User() {
+  const { data } = useQuery('user', fetchUser, {
+    notifyOnChangePropsExclusions: ['isStale'],
+  })
+  return <div>Username: {data.username}</div>
+}
+```
+
 ### QueryResult.clear()
 
 The `QueryResult.clear()` method has been renamed to `QueryResult.remove()`.
@@ -379,7 +411,7 @@ function User() {
 }
 ```
 
-Set the `notifyOnStatusChange` option to `false` to only re-render when the selected data changes.
+Set the `notifyOnChangeProps` option to `['data', 'error']` to only re-render when the selected data changes.
 
 #### useQueries()
 

src/core/queryObserver.ts

@@ -448,7 +448,7 @@ export class QueryObserver<
 
       if (changed) {
         if (notifyOnChangePropsExclusions && isExcluded) {
-          break
+          continue
         }
 
         if (!notifyOnChangeProps || isIncluded) {

src/core/tests/queryCache.test.tsx

@@ -612,10 +612,7 @@ describe('queryCache', () => {
     const key = queryKey()
     const queryFn = jest.fn()
     const testCache = new QueryCache()
-    const testClient = new QueryClient({
-      queryCache: testCache,
-      defaultOptions: { queries: { notifyOnChangePropsExclusions: [] } },
-    })
+    const testClient = new QueryClient({ queryCache: testCache })
     const observer = new QueryObserver(testClient, {
       queryKey: key,
       enabled: false,

src/react/tests/useInfiniteQuery.test.tsx

@@ -41,14 +41,7 @@ const fetchItems = async (
 
 describe('useInfiniteQuery', () => {
   const queryCache = new QueryCache()
-  const queryClient = new QueryClient({
-    queryCache,
-    defaultOptions: {
-      queries: {
-        notifyOnChangePropsExclusions: [],
-      },
-    },
-  })
+  const queryClient = new QueryClient({ queryCache })
 
   it('should return the correct states for a successful query', async () => {
     const key = queryKey()

src/react/tests/useQuery.test.tsx

@@ -651,7 +651,7 @@ describe('useQuery', () => {
     expect(states[1]).toMatchObject({ data: 'test' })
   })
 
-  it('should not re-render when notify flags are false and the selected data did not change', async () => {
+  it('should not re-render when it should only re-render only data change and the selected data did not change', async () => {
     const key = queryKey()
     const states: UseQueryResult<string>[] = []
 
@@ -683,6 +683,45 @@ describe('useQuery', () => {
     expect(states[1]).toMatchObject({ data: 'test' })
   })
 
+  it('should re-render when dataUpdatedAt changes but data remains the same', async () => {
+    const key = queryKey()
+    const states: UseQueryResult<string>[] = []
+
+    function Page() {
+      const state = useQuery(key, () => 'test', {
+        notifyOnChangePropsExclusions: [
+          'data',
+          'isFetching',
+          'isLoading',
+          'isSuccess',
+          'status',
+        ],
+      })
+
+      states.push(state)
+
+      const { refetch } = state
+
+      React.useEffect(() => {
+        setActTimeout(() => {
+          refetch()
+        }, 5)
+      }, [refetch])
+
+      return null
+    }
+
+    renderWithClient(queryClient, <Page />)
+
+    await sleep(10)
+
+    expect(states.length).toBe(3)
+    expect(states[0]).toMatchObject({ data: undefined, isFetching: true })
+    expect(states[1]).toMatchObject({ data: 'test', isFetching: false })
+    expect(states[2]).toMatchObject({ data: 'test', isFetching: false })
+    expect(states[1].dataUpdatedAt).not.toBe(states[2].dataUpdatedAt)
+  })
+
   it('should be able to remove a query', async () => {
     const key = queryKey()
     const states: UseQueryResult<number>[] = []
@@ -1491,7 +1530,7 @@ describe('useQuery', () => {
     expect(fn).toHaveBeenCalledTimes(5)
   })
 
-  it('should not re-render when a query status changes and notify flags are false', async () => {
+  it('should not re-render when it should only re-render on data changes and the data did not change', async () => {
     const key = queryKey()
     const states: UseQueryResult<string>[] = []