feat(infiniteQuery): add possibility to decide which pages should be refetched

documentation for refetchPage

Author: TkDodo

docs/src/pages/guides/infinite-queries.md

@@ -95,6 +95,27 @@ function Projects() {
 
 When an infinite query becomes `stale` and needs to be refetched, each group is fetched `sequentially`, starting from the first one. This ensures that even if the underlying data is mutated, we're not using stale cursors and potentially getting duplicates or skipping records. If an infinite query's results are ever removed from the queryCache, the pagination restarts at the initial state with only the initial group being requested.
 
+### refetchPage
+
+If you only want to actively refetch a subset of all pages, you can pass the `refetchPage` function to `refetch` returned from `useInfiniteQuery`.
+
+```js
+const { refetch } = useInfiniteQuery('projects', fetchProjects, {
+  getNextPageParam: (lastPage, pages) => lastPage.nextCursor,
+})
+
+// only refetch the first page
+refetch({ refetchPage: (page, index) => index === 0 })
+```
+
+You can also pass this function as part of the 3rd argument (`options`) to [queryClient.refetchQueries](/reference/QueryClient#queryclientrefetchqueries), [queryClient.invalidateQueries](/reference/QueryClient#queryclientinvalidatequeries) or [queryClient.resetQueries](/reference/QueryClient#queryclientresetqueries).
+
+**Signature**
+
+- `refetchPage: (page: TData, index: number, allPages: TData[]) => boolean`
+
+The function is executed for each page, and only pages where this function returns `true` will be refetched.
+
 ## What if I need to pass custom information to my query function?
 
 By default, the variable returned from `getNextPageParam` will be supplied to the query function, but in some cases, you may want to override this. You can pass custom variables to the `fetchNextPage` function which will override the default variable like so:

docs/src/pages/reference/QueryClient.md

@@ -194,7 +194,7 @@ const data = queryClient.getQueriesData(queryKey | filters)
 
 - `[queryKey:QueryKey, data:TData | unknown][]`
   - An array of tuples for the matched query keys, or `[]` if there are no matches. The tuples are the query key and its associated data.
-  
+
 **Caveats**
 
 Because the returned data in each tuple can be of varying structures (i.e. using a filter to return "active" queries can return different data types), the `TData` generic defaults to `unknown`. If you provide a more specific type to `TData` it is assumed that you are certain each tuple's data entry is all the same type.
@@ -290,6 +290,9 @@ await queryClient.invalidateQueries('posts', {
 - `refetchOptions?: RefetchOptions`:
   - `throwOnError?: boolean`
     - When set to `true`, this method will throw if any of the query refetch tasks fail.
+  - `refetchPage: (page: TData, index: number, allPages: TData[]) => boolean`
+    - Only for [Infinite Queries](../guides/infinite-queries#refetchpage)
+    - Use this function to specify which pages should be refetched
 
 ## `queryClient.refetchQueries`
 
@@ -318,6 +321,9 @@ await queryClient.refetchQueries(['posts', 1], { active: true, exact: true })
 - `refetchOptions?: RefetchOptions`:
   - `throwOnError?: boolean`
     - When set to `true`, this method will throw if any of the query refetch tasks fail.
+  - `refetchPage: (page: TData, index: number, allPages: TData[]) => boolean`
+    - Only for [Infinite Queries](../guides/infinite-queries#refetchpage)
+    - Use this function to specify which pages should be refetched
 
 **Returns**
 
@@ -381,6 +387,9 @@ queryClient.resetQueries(queryKey, { exact: true })
 - `resetOptions?: ResetOptions`:
   - `throwOnError?: boolean`
     - When set to `true`, this method will throw if any of the query refetch tasks fail.
+  - `refetchPage: (page: TData, index: number, allPages: TData[]) => boolean`
+    - Only for [Infinite Queries](../guides/infinite-queries#refetchpage)
+    - Use this function to specify which pages should be refetched
 
 **Returns**