Merge commit '118801df342881021c2bb6c8add5bb11b6dd944a' into alpha

# Conflicts:
#	packages/query-async-storage-persister/package.json
#	packages/query-broadcast-client-experimental/package.json
#	packages/query-core/package.json
#	packages/query-core/src/queryObserver.ts
#	packages/query-persist-client-core/package.json
#	packages/query-sync-storage-persister/package.json
#	packages/react-query-devtools/package.json
#	packages/react-query-persist-client/package.json
#	packages/react-query/package.json
#	packages/react-query/src/__tests__/useQuery.test.tsx
#	packages/solid-query/package.json
#	packages/svelte-query/package.json
#	packages/vue-query/package.json

Author: TkDodo

README.md

@@ -43,7 +43,7 @@ Still on **React Query v3**? No problem! Check out the v3 docs here: https://tan
 - Paginated + Cursor-based Queries
 - Load-More + Infinite Scroll Queries w/ Scroll Recovery
 - Request Cancellation
-- [React Suspense](https://reactjs.org/docs/concurrent-mode-suspense.html) + Fetch-As-You-Render Query Prefetching
+- [React Suspense](https://react.dev/reference/react/Suspense) + Fetch-As-You-Render Query Prefetching
 - Dedicated Devtools
 - <a href="https://bundlephobia.com/package/@tanstack/react-query@latest" target="\_parent">
   <img alt="" src="https://badgen.net/bundlephobia/minzip/@tanstack/react-query" />

docs/react/guides/query-keys.md

@@ -91,7 +91,8 @@ function Todos({ todoId }) {
 
 [//]: # 'Example5'
 
-Note that query keys act as dependencies for your query functions. Adding dependent variables to your query key will ensure that queries are cached independently, and that any time a variable changes, *queries will be refetched automatically (depending on your `staleTime` settings).* (See the [exhaustive-deps](../eslint/exhaustive-deps) section for more information and examples.)
+Note that query keys act as dependencies for your query functions. Adding dependent variables to your query key will ensure that queries are cached independently, and that any time a variable changes, *queries will be refetched automatically* (depending on your `staleTime` settings). See the [exhaustive-deps](../eslint/exhaustive-deps) section for more information and examples.
+
 [//]: # 'Materials'
 
 ## Further reading

docs/react/overview.md

@@ -69,7 +69,7 @@ function Example() {
   const { isPending, error, data } = useQuery({
     queryKey: ['repoData'],
     queryFn: () =>
-      fetch('https://api.github.com/repos/tannerlinsley/react-query').then(
+      fetch('https://api.github.com/repos/TanStack/query').then(
         (res) => res.json(),
       ),
   })

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

@@ -125,11 +125,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.
 - `select: (data: TData) => unknown`
   - Optional

packages/query-core/src/queryObserver.ts

@@ -612,15 +612,19 @@ 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.throwOnError) {
         includedProps.add('error')

packages/query-core/src/types.ts

@@ -95,6 +95,11 @@ export type QueryMeta = Register extends {
 
 export type NetworkMode = 'online' | 'always' | 'offlineFirst'
 
+export type NotifyOnChangeProps =
+  | Array<keyof InfiniteQueryObserverResult>
+  | 'all'
+  | (() => Array<keyof InfiniteQueryObserverResult> | 'all')
+
 export interface QueryOptions<
   TQueryFnData = unknown,
   TError = DefaultError,
@@ -261,9 +266,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
   /**
    * Whether errors should be thrown instead of setting the `error` property.
    * If set to `true` or `suspense` is `true`, all errors will be thrown to the error boundary.
@@ -292,8 +298,8 @@ export interface QueryObserverOptions<
   _optimisticResults?: 'optimistic' | 'isRestoring'
 }
 
-export type WithRequired<T, K extends keyof T> = Omit<T, K> &
-  Required<Pick<T, K>>
+export type WithRequired<T, K extends keyof T> = T & { [_ in K]: {} }
+
 export type DefaultedQueryObserverOptions<
   TQueryFnData = unknown,
   TError = DefaultError,