feat: add new function type to notifyOnChangeProps (#5734)

Co-authored-by: Dominik Dorfmeister <[email protected]>

Author: paulobmarcos

docs/react/react-native.md

@@ -76,3 +76,64 @@ export function useRefreshOnFocus<T>(refetch: () => Promise<T>) {
 ```
 
 In the above code, `refetch` is skipped the first time because `useFocusEffect` calls our callback on mount in addition to screen focus.
+
+## Disable re-renders on out of focus Screens
+
+In some situations, including performance concerns, you may want to stop re-renders when a React Native screen gets out of focus. To achieve this we can use `useFocusEffect` from `@react-navigation/native` together with the `notifyOnChangeProps` query option.
+
+This custom hook provides a `notifyOnChangeProps` option that will return an empty array whenever a screen goes out of focus - effectively stopping any re-renders on that scenario. Whenever the screens gets in focus again, the behavior goes back to normal.
+
+```tsx
+import React from 'react'
+import { NotifyOnChangeProps } from '@tanstack/query-core'
+import { useFocusEffect } from '@react-navigation/native'
+
+export function useFocusNotifyOnChangeProps(notifyOnChangeProps?: NotifyOnChangeProps) {
+  const focusedRef = React.useRef(true)
+
+  useFocusEffect(
+    React.useCallback(() => {
+      focusedRef.current = true
+
+      return () => {
+        focusedRef.current = false
+      }
+    }, [])
+  )
+
+  return () => {
+    if (!focusedRef.current) {
+      return []
+    }
+
+    if (typeof notifyOnChangeProps === 'function') {
+      return notifyOnChangeProps()
+    }
+
+    return notifyOnChangeProps.current
+  }
+}
+```
+
+In the above code, `useFocusEffect` is used to change the value of a reference that the callback will use as a condition.
+
+The argument is wrapped in a reference to also guarantee that the returned callback always keeps the same reference.
+
+Example usage:
+
+```tsx
+function MyComponent() {
+  const notifyOnChangeProps = useFocusNotifyOnChangeProps();
+
+  const { dataUpdatedAt } = useQuery({
+    queryKey: ['myKey'],
+    queryFn: async () => {
+      const response = await fetch('https://api.github.com/repos/tannerlinsley/react-query');
+      return response.json();
+    },
+    notifyOnChangeProps,
+  });
+
+  return <div>DataUpdatedAt: {dataUpdatedAt}</div>;
+};
+```

docs/react/reference/useQuery.md

@@ -131,11 +131,12 @@ const {
   - If set to `false`, the query will not refetch on reconnect.
   - If set to `"always"`, the query will always refetch on reconnect.
   - If set to a function, the function will be executed with the query to compute the value
-- `notifyOnChangeProps: string[] | "all"`
+- `notifyOnChangeProps: string[] | "all" | (() => string[] | "all")`
   - Optional
   - 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.
   - If set to `"all"`, the component will opt-out of smart tracking and re-render whenever a query is updated.
+  - If set to a function, the function will be executed to compute the list of properties.
   - By default, access to properties will be tracked, and the component will only re-render when one of the tracked properties change.
 - `onSuccess: (data: TData) => void`
   - **Deprecated** - this callback will be removed in the next major version

packages/query-core/src/queryObserver.ts

@@ -637,15 +637,21 @@ export class QueryObserver<
       }
 
       const { notifyOnChangeProps } = this.options
+      const notifyOnChangePropsValue =
+        typeof notifyOnChangeProps === 'function'
+          ? notifyOnChangeProps()
+          : notifyOnChangeProps
 
       if (
-        notifyOnChangeProps === 'all' ||
-        (!notifyOnChangeProps && !this.trackedProps.size)
+        notifyOnChangePropsValue === 'all' ||
+        (!notifyOnChangePropsValue && !this.trackedProps.size)
       ) {
         return true
       }
 
-      const includedProps = new Set(notifyOnChangeProps ?? this.trackedProps)
+      const includedProps = new Set(
+        notifyOnChangePropsValue ?? this.trackedProps,
+      )
 
       if (this.options.useErrorBoundary) {
         includedProps.add('error')

packages/query-core/src/types.ts

@@ -55,6 +55,11 @@ export interface QueryMeta {
 
 export type NetworkMode = 'online' | 'always' | 'offlineFirst'
 
+export type NotifyOnChangeProps =
+  | Array<keyof InfiniteQueryObserverResult>
+  | 'all'
+  | (() => Array<keyof InfiniteQueryObserverResult> | 'all')
+
 export interface QueryOptions<
   TQueryFnData = unknown,
   TError = unknown,
@@ -200,9 +205,10 @@ export interface QueryObserverOptions<
    * 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.
    * When set to `'all'`, the component will re-render whenever a query is updated.
+   * When set to a function, the function will be executed to compute the list of properties.
    * By default, access to properties will be tracked, and the component will only re-render when one of the tracked properties change.
    */
-  notifyOnChangeProps?: Array<keyof InfiniteQueryObserverResult> | 'all'
+  notifyOnChangeProps?: NotifyOnChangeProps
   /**
    * This callback will fire any time the query successfully fetches new data.
    *