feat: imperative infinite queries

let's bring back imperative infinite queries, but only allow them in an all-or-nothing mode, dependent on if `getNextPageParam` has been passed

Author: TkDodo

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

@@ -201,6 +201,110 @@ describe('InfiniteQueryBehavior', () => {
     unsubscribe()
   })
 
+  test('InfiniteQueryBehavior should apply pageParam', async () => {
+    const key = queryKey()
+
+    const queryFn = vi.fn().mockImplementation(({ pageParam }) => {
+      return pageParam
+    })
+
+    const observer = new InfiniteQueryObserver<number>(queryClient, {
+      queryKey: key,
+      queryFn,
+      initialPageParam: 0,
+    })
+
+    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: [0], pageParams: [0] },
+      }),
+    )
+
+    queryFn.mockClear()
+
+    // Fetch the next page using pageParam
+    await observer.fetchNextPage({ pageParam: 1 })
+
+    expect(queryFn).toHaveBeenNthCalledWith(1, {
+      queryKey: key,
+      pageParam: 1,
+      meta: undefined,
+      client: queryClient,
+      direction: 'forward',
+      signal: expect.anything(),
+    })
+
+    expect(observerResult).toMatchObject({
+      isFetching: false,
+      data: { pages: [0, 1], pageParams: [0, 1] },
+    })
+
+    queryFn.mockClear()
+
+    // Fetch the previous page using pageParam
+    await observer.fetchPreviousPage({ pageParam: -1 })
+
+    expect(queryFn).toHaveBeenNthCalledWith(1, {
+      queryKey: key,
+      pageParam: -1,
+      meta: undefined,
+      client: queryClient,
+      direction: 'backward',
+      signal: expect.anything(),
+    })
+
+    expect(observerResult).toMatchObject({
+      isFetching: false,
+      data: { pages: [-1, 0, 1], pageParams: [-1, 0, 1] },
+    })
+
+    queryFn.mockClear()
+
+    // Refetch pages: old manual page params should be used
+    await observer.refetch()
+
+    expect(queryFn).toHaveBeenCalledTimes(3)
+
+    expect(queryFn).toHaveBeenNthCalledWith(1, {
+      queryKey: key,
+      pageParam: -1,
+      meta: undefined,
+      client: queryClient,
+      direction: 'forward',
+      signal: expect.anything(),
+    })
+
+    expect(queryFn).toHaveBeenNthCalledWith(2, {
+      queryKey: key,
+      pageParam: 0,
+      meta: undefined,
+      client: queryClient,
+      direction: 'forward',
+      signal: expect.anything(),
+    })
+
+    expect(queryFn).toHaveBeenNthCalledWith(3, {
+      queryKey: key,
+      pageParam: 1,
+      meta: undefined,
+      client: queryClient,
+      direction: 'forward',
+      signal: expect.anything(),
+    })
+
+    unsubscribe()
+  })
+
   test('InfiniteQueryBehavior should support query cancellation', async () => {
     const key = queryKey()
     let abortSignal: AbortSignal | null = null

packages/query-core/src/infiniteQueryBehavior.ts

@@ -14,7 +14,7 @@ export function infiniteQueryBehavior<TQueryFnData, TError, TData, TPageParam>(
   return {
     onFetch: (context, query) => {
       const options = context.options as InfiniteQueryPageParamsOptions<TData>
-      const direction = context.fetchOptions?.meta?.fetchMore?.direction
+      const fetchMore = context.fetchOptions?.meta?.fetchMore
       const oldPages = context.state.data?.pages || []
       const oldPageParams = context.state.data?.pageParams || []
       let result: InfiniteData<unknown> = { pages: [], pageParams: [] }
@@ -81,14 +81,17 @@ export function infiniteQueryBehavior<TQueryFnData, TError, TData, TPageParam>(
         }
 
         // fetch next / previous page?
-        if (direction && oldPages.length) {
-          const previous = direction === 'backward'
+        if (fetchMore && oldPages.length) {
+          const previous = fetchMore.direction === 'backward'
           const pageParamFn = previous ? getPreviousPageParam : getNextPageParam
           const oldData = {
             pages: oldPages,
             pageParams: oldPageParams,
           }
-          const param = pageParamFn(options, oldData)
+          const param =
+            fetchMore.pageParam === undefined
+              ? pageParamFn(options, oldData)
+              : fetchMore.pageParam
 
           result = await fetchPage(oldData, param, previous)
         } else {
@@ -97,8 +100,8 @@ export function infiniteQueryBehavior<TQueryFnData, TError, TData, TPageParam>(
           // Fetch all pages
           do {
             const param =
-              currentPage === 0
-                ? (oldPageParams[0] ?? options.initialPageParam)
+              currentPage === 0 || !options.getNextPageParam
+                ? (oldPageParams[currentPage] ?? options.initialPageParam)
                 : getNextPageParam(options, result)
             if (currentPage > 0 && param == null) {
               break
@@ -136,7 +139,7 @@ function getNextPageParam(
 ): unknown | undefined {
   const lastIndex = pages.length - 1
   return pages.length > 0
-    ? options.getNextPageParam(
+    ? options.getNextPageParam?.(
         pages[lastIndex],
         pages,
         pageParams[lastIndex],

packages/query-core/src/infiniteQueryObserver.ts

@@ -124,24 +124,27 @@ export class InfiniteQueryObserver<
     >
   }
 
-  fetchNextPage(
-    options?: FetchNextPageOptions,
-  ): Promise<InfiniteQueryObserverResult<TData, TError>> {
+  fetchNextPage({ pageParam, ...options }: FetchNextPageOptions = {}): Promise<
+    InfiniteQueryObserverResult<TData, TError>
+  > {
     return this.fetch({
       ...options,
       meta: {
-        fetchMore: { direction: 'forward' },
+        fetchMore: { direction: 'forward', pageParam },
       },
     })
   }
 
-  fetchPreviousPage(
-    options?: FetchPreviousPageOptions,
-  ): Promise<InfiniteQueryObserverResult<TData, TError>> {
+  fetchPreviousPage({
+    pageParam,
+    ...options
+  }: FetchPreviousPageOptions = {}): Promise<
+    InfiniteQueryObserverResult<TData, TError>
+  > {
     return this.fetch({
       ...options,
       meta: {
-        fetchMore: { direction: 'backward' },
+        fetchMore: { direction: 'backward', pageParam },
       },
     })
   }

packages/query-core/src/query.ts

@@ -89,7 +89,7 @@ export interface QueryBehavior<
 export type FetchDirection = 'forward' | 'backward'
 
 export interface FetchMeta {
-  fetchMore?: { direction: FetchDirection }
+  fetchMore?: { direction: FetchDirection; pageParam?: unknown }
 }
 
 export interface FetchOptions<TData = unknown> {

packages/query-core/src/types.ts

@@ -271,7 +271,7 @@ export interface InfiniteQueryPageParamsOptions<
    * This function can be set to automatically get the next cursor for infinite queries.
    * The result will also be used to determine the value of `hasNextPage`.
    */
-  getNextPageParam: GetNextPageParamFunction<TPageParam, TQueryFnData>
+  getNextPageParam?: GetNextPageParamFunction<TPageParam, TQueryFnData>
 }
 
 export type ThrowOnError<