feat: remove refetchPage (#4990)

* feat: remove refetchPage

* fix: unused type

* fix: types generics

* refactor: remove ResetQueryFilters type

* docs: migration guide: new feature

* docs: migration guide wording

* docs: new features typo

Author: arnaudbzn

docs/react/guides/infinite-queries.md

@@ -103,33 +103,6 @@ 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`.
-
-[//]: # 'Example2'
-
-```tsx
-const { refetch } = useInfiniteQuery({
-  queryKey: ['projects'],
-  queryFn: fetchProjects,
-  getNextPageParam: (lastPage, pages) => lastPage.nextCursor,
-})
-
-// only refetch the first page
-refetch({ refetchPage: (page, index) => index === 0 })
-```
-
-[//]: # 'Example2'
-
-You can also pass this function as part of the 2nd argument (`queryFilters`) 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/react/guides/migrating-to-v5.md

@@ -257,6 +257,14 @@ const { data } = useQuery(
 )
 ```
 
+### Removed `refetchPage` in favor of `maxPages`
+
+In v4, we introduced the possibility to define the pages to refetch for infinite queries with the `refetchPage` function.
+
+However, refetching all pages might lead to UI inconsistencies. Also, this option is available on e.g. `queryClient.refetchQueries`, but it only does something for infinite queries, not "normal" queries.
+
+The v5 includes a new `maxPages` option for infinite queries to limit the number of pages to store in the query data and to refetch. This new feature handles the use cases initially identified for the `refetchPage` page feature without the related issues.
+
 [//]: # 'FrameworkBreakingChanges'
 
 ## React Query Breaking Changes
@@ -309,3 +317,20 @@ Lastly the a new derived `isLoading` flag has been added to the queries that is
 To understand the reasoning behing this change checkout the [v5 roadmap discussion](https://github.com/TanStack/query/discussions/4252).
 
 [//]: # 'FrameworkBreakingChanges'
+
+
+[//]: # 'NewFeatures'
+
+## New Features 🚀
+
+### Eterneral list: scalable infinite query with new maxPages option
+
+Infinite queries are great when infinite scroll or pagination are needed.
+However, the more pages you fetch, the more memory you consume, and this also slows down the query refetching process as all the pages are sequentially refetched.
+
+Version 5 has a new `maxPages` option for infinite queries, which allows developers to limit the number of pages that are stored in the query data and subsequently refetched.
+You can adjust the `maxPages` value according to the UX and refetching performance you want to deliver.
+
+Note that the infinite list must be bi-directional, which requires both `getNextPageParam` and `getPreviousPageParam` to be defined.
+
+[//]: # 'NewFeatures'

docs/react/reference/QueryClient.md

@@ -307,9 +307,6 @@ await queryClient.invalidateQueries({
     - When set to `inactive`, only queries that match the refetch predicate and are NOT actively being rendered via `useQuery` and friends will be refetched in the background.
     - When set to `all`, all queries that match the refetch predicate will be refetched in the background.
     - When set to `none`, no queries will be refetched, and those that match the refetch predicate will be marked as invalid only.
-  - `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
 - `options?: InvalidateOptions`:
   - `throwOnError?: boolean`
     - When set to `true`, this method will throw if any of the query refetch tasks fail.
@@ -341,9 +338,6 @@ await queryClient.refetchQueries({ queryKey: ['posts', 1], type: 'active', exact
 **Options**
 
 - `filters?: QueryFilters`: [Query Filters](../guides/filters#query-filters)
-  - `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
 - `options?: RefetchOptions`:
   - `throwOnError?: boolean`
     - When set to `true`, this method will throw if any of the query refetch tasks fail.
@@ -408,9 +402,6 @@ queryClient.resetQueries({ queryKey, exact: true })
 **Options**
 
 - `filters?: QueryFilters`: [Query Filters](../guides/filters#query-filters)
-  - `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
 - `options?: ResetOptions`:
   - `throwOnError?: boolean`
     - When set to `true`, this method will throw if any of the query refetch tasks fail.

packages/query-core/src/infiniteQueryBehavior.ts

@@ -1,11 +1,6 @@
 import type { QueryBehavior } from './query'
 import { addToEnd, addToStart } from './utils'
-import type {
-  InfiniteData,
-  QueryFunctionContext,
-  QueryOptions,
-  RefetchQueryFilters,
-} from './types'
+import type { InfiniteData, QueryFunctionContext, QueryOptions } from './types'
 
 export function infiniteQueryBehavior<
   TQueryFnData,
@@ -15,8 +10,6 @@ export function infiniteQueryBehavior<
   return {
     onFetch: (context) => {
       context.fetchFn = () => {
-        const refetchPage: RefetchQueryFilters['refetchPage'] | undefined =
-          context.fetchOptions?.meta?.refetchPage
         const fetchMore = context.fetchOptions?.meta?.fetchMore
         const pageParam = fetchMore?.pageParam
         const isFetchingNextPage = fetchMore?.direction === 'forward'
@@ -127,33 +120,16 @@ export function infiniteQueryBehavior<
 
           const manual = typeof context.options.getNextPageParam === 'undefined'
 
-          const shouldFetchFirstPage =
-            refetchPage && oldPages[0]
-              ? refetchPage(oldPages[0], 0, oldPages)
-              : true
-
           // Fetch first page
-          promise = shouldFetchFirstPage
-            ? fetchPage([], manual, oldPageParams[0])
-            : Promise.resolve(buildNewPages([], oldPageParams[0], oldPages[0]))
+          promise = fetchPage([], manual, oldPageParams[0])
 
           // Fetch remaining pages
           for (let i = 1; i < oldPages.length; i++) {
             promise = promise.then((pages) => {
-              const shouldFetchNextPage =
-                refetchPage && oldPages[i]
-                  ? refetchPage(oldPages[i], i, oldPages)
-                  : true
-
-              if (shouldFetchNextPage) {
-                const param = manual
-                  ? oldPageParams[i]
-                  : getNextPageParam(context.options, pages)
-                return fetchPage(pages, manual, param)
-              }
-              return Promise.resolve(
-                buildNewPages(pages, oldPageParams[i], oldPages[i]),
-              )
+              const param = manual
+                ? oldPageParams[i]
+                : getNextPageParam(context.options, pages)
+              return fetchPage(pages, manual, param)
             })
           }
         }

packages/query-core/src/queryClient.ts

@@ -23,7 +23,6 @@ import type {
   RefetchOptions,
   RefetchQueryFilters,
   ResetOptions,
-  ResetQueryFilters,
   SetDataOptions,
   RegisteredError,
 } from './types'
@@ -193,13 +192,10 @@ export class QueryClient {
     })
   }
 
-  resetQueries<TPageData = unknown>(
-    filters?: ResetQueryFilters<TPageData>,
-    options?: ResetOptions,
-  ): Promise<void> {
+  resetQueries(filters?: QueryFilters, options?: ResetOptions): Promise<void> {
     const queryCache = this.#queryCache
 
-    const refetchFilters: RefetchQueryFilters<TPageData> = {
+    const refetchFilters: RefetchQueryFilters = {
       type: 'active',
       ...filters,
     }
@@ -229,8 +225,8 @@ export class QueryClient {
     return Promise.all(promises).then(noop).catch(noop)
   }
 
-  invalidateQueries<TPageData = unknown>(
-    filters: InvalidateQueryFilters<TPageData> = {},
+  invalidateQueries(
+    filters: InvalidateQueryFilters = {},
     options: InvalidateOptions = {},
   ): Promise<void> {
     return notifyManager.batch(() => {
@@ -241,16 +237,16 @@ export class QueryClient {
       if (filters.refetchType === 'none') {
         return Promise.resolve()
       }
-      const refetchFilters: RefetchQueryFilters<TPageData> = {
+      const refetchFilters: RefetchQueryFilters = {
         ...filters,
         type: filters.refetchType ?? filters.type ?? 'active',
       }
       return this.refetchQueries(refetchFilters, options)
     })
   }
 
-  refetchQueries<TPageData = unknown>(
-    filters: RefetchQueryFilters<TPageData> = {},
+  refetchQueries(
+    filters: RefetchQueryFilters = {},
     options?: RefetchOptions,
   ): Promise<void> {
     const promises = notifyManager.batch(() =>
@@ -261,7 +257,6 @@ export class QueryClient {
           query.fetch(undefined, {
             ...options,
             cancelRefetch: options?.cancelRefetch ?? true,
-            meta: { refetchPage: filters.refetchPage },
           }),
         ),
     )

packages/query-core/src/queryObserver.ts

@@ -1,8 +1,4 @@
-import type {
-  DefaultedQueryObserverOptions,
-  RefetchPageFilters,
-  RegisteredError,
-} from './types'
+import type { DefaultedQueryObserverOptions, RegisteredError } from './types'
 import {
   isServer,
   isValidTimeout,
@@ -260,15 +256,11 @@ export class QueryObserver<
     return this.#currentQuery
   }
 
-  refetch<TPageData>({
-    refetchPage,
-    ...options
-  }: RefetchOptions & RefetchPageFilters<TPageData> = {}): Promise<
+  refetch({ ...options }: RefetchOptions = {}): Promise<
     QueryObserverResult<TData, TError>
   > {
     return this.fetch({
       ...options,
-      meta: { refetchPage },
     })
   }
 

packages/query-core/src/tests/infiniteQueryBehavior.test.tsx

@@ -44,84 +44,6 @@ describe('InfiniteQueryBehavior', () => {
     unsubscribe()
   })
 
-  test('InfiniteQueryBehavior should not refetch the first page if another page refetched', async () => {
-    const key = queryKey()
-    let abortSignal: AbortSignal | null = null
-
-    const queryFnSpy = jest
-      .fn()
-      .mockImplementation(({ pageParam = 1, signal }) => {
-        abortSignal = signal
-        return pageParam
-      })
-
-    const observer = new InfiniteQueryObserver<number>(queryClient, {
-      queryKey: key,
-      queryFn: queryFnSpy,
-      getNextPageParam: (lastPage) => lastPage + 1,
-    })
-
-    let observerResult:
-      | InfiniteQueryObserverResult<unknown, unknown>
-      | undefined
-
-    const unsubscribe = observer.subscribe((result) => {
-      observerResult = result
-    })
-
-    // Wait for the first page to be fetched
-    await waitFor(() =>
-      expect(observerResult).toMatchObject({
-        isFetching: false,
-        data: { pages: [1] },
-      }),
-    )
-
-    expect(queryFnSpy).toHaveBeenNthCalledWith(1, {
-      queryKey: key,
-      pageParam: undefined,
-      meta: undefined,
-      signal: abortSignal,
-    })
-
-    queryFnSpy.mockClear()
-
-    // Fetch the second page
-    await observer.fetchNextPage()
-
-    expect(queryFnSpy).toHaveBeenNthCalledWith(1, {
-      queryKey: key,
-      pageParam: 2,
-      meta: undefined,
-      signal: abortSignal,
-    })
-
-    expect(observerResult).toMatchObject({
-      isFetching: false,
-      data: { pages: [1, 2] },
-    })
-
-    queryFnSpy.mockClear()
-
-    // Refetch the second page
-    await queryClient.refetchQueries({
-      refetchPage: (_page, index) => index === 1,
-    })
-
-    expect(queryFnSpy).toHaveBeenNthCalledWith(1, {
-      queryKey: key,
-      pageParam: 2,
-      meta: undefined,
-      signal: abortSignal,
-    })
-
-    expect(observerResult).toMatchObject({
-      data: { pages: [1, 2] },
-    })
-
-    unsubscribe()
-  })
-
   test('InfiniteQueryBehavior should apply the maxPages option to limit the number of pages', async () => {
     const key = queryKey()
     let abortSignal: AbortSignal | null = null