feat(infiniteQuery): type pageParams and allow null cursors (#5811)

* type pageParams and allow null cursors

* doc

* use TPageParam in some places [WIP]

* dont pluralize

* docs: document return value in api-reference

* docs: migration guide

* refactor: use != null to check for null and undefined

* fix: we also need to widen the check in `fetchPage`

* test: check for null returned from getNextPageParam

* more

* fix react type test

* dont need that i guess

* prettier

* migration guide

* revert generic order

* format

* fix test

---------

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

Author: juliusmarminge

docs/react/guides/infinite-queries.md

@@ -13,8 +13,8 @@ When using `useInfiniteQuery`, you'll notice a few things are different:
 - The `fetchNextPage` and `fetchPreviousPage` functions are now available (`fetchNextPage` is required)
 - The `defaultPageParam` option is now available (and required) to specify the initial page param
 - The `getNextPageParam` and `getPreviousPageParam` options are available for both determining if there is more data to load and the information to fetch it. This information is supplied as an additional parameter in the query function
-- A `hasNextPage` boolean is now available and is `true` if `getNextPageParam` returns a value other than `undefined`
-- A `hasPreviousPage` boolean is now available and is `true` if `getPreviousPageParam` returns a value other than `undefined`
+- A `hasNextPage` boolean is now available and is `true` if `getNextPageParam` returns a value other than `null` or `undefined`
+- A `hasPreviousPage` boolean is now available and is `true` if `getPreviousPageParam` returns a value other than `null` or `undefined`
 - The `isFetchingNextPage` and `isFetchingPreviousPage` booleans are now available to distinguish between a background refresh state and a loading more state
 
 > Note: Options `initialData` or `placeholderData` need to conform to the same structure of an object with `data.pages` and `data.pageParams` properties.

docs/react/guides/migrating-to-v5.md

@@ -341,6 +341,10 @@ useInfiniteQuery({
 
 Previously, we've allowed to overwrite the `pageParams` that would be returned from `getNextPageParam` or `getPreviousPageParam` by passing a `pageParam` value directly to `fetchNextPage` or `fetchPreviousPage`. This feature didn't work at all with refetches and wasn't widely known or used. This also means that `getNextPageParam` is now required for infinite queries.
 
+### Returning `null` from `getNextPageParam` or `getPreviousPageParam` now indicates that there is no further page available
+
+In v4, you needed to explicitly return `undefined` to indicate that there is no further page available. We've widened this check to include `null`.
+
 ### No retries on the server
 
 On the server, `retry` now defaults to `0` instead of `3`. For prefetching, we have always defaulted to `0` retries, but since queries that have `suspense` enabled can now execute directly on the server as well (since React18), we have to make sure that we don't retry on the server at all.
@@ -401,8 +405,6 @@ 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 🚀
@@ -414,29 +416,26 @@ v5 also comes with new features:
 We have a new, simplified way to perform optimistic updates by leveraging the returned `variables` from `useMutation`:
 
 ```tsx
-  const queryInfo = useTodos()
-  const addTodoMutation = useMutation({
-    mutationFn: (newTodo: string) => axios.post('/api/data', { text: newTodo }),
-    onSettled: () => queryClient.invalidateQueries({ queryKey: ['todos'] }),
-  })
+const queryInfo = useTodos()
+const addTodoMutation = useMutation({
+  mutationFn: (newTodo: string) => axios.post('/api/data', { text: newTodo }),
+  onSettled: () => queryClient.invalidateQueries({ queryKey: ['todos'] }),
+})
 
-  if (queryInfo.data) {
-    return (
-      <ul>
-        {queryInfo.data.items.map((todo) => (
-          <li key={todo.id}>{todo.text}</li>
-        ))}
-        {addTodoMutation.isPending && (
-          <li
-            key={String(addTodoMutation.submittedAt)}
-            style={{opacity: 0.5}}
-          >
-            {addTodoMutation.variables}
-          </li>
-        )}
-      </ul>
-    )
-  }
+if (queryInfo.data) {
+  return (
+    <ul>
+      {queryInfo.data.items.map((todo) => (
+        <li key={todo.id}>{todo.text}</li>
+      ))}
+      {addTodoMutation.isPending && (
+        <li key={String(addTodoMutation.submittedAt)} style={{ opacity: 0.5 }}>
+          {addTodoMutation.variables}
+        </li>
+      )}
+    </ul>
+  )
+}
 ```
 
 Here, we are only changing how the UI looks when the mutation is running instead of writing data directly to the cache. This works best if we only have one place where we need to show the optimistic update. For more details, have a look at the [optimistic updates documentation](../guides/optimistic-updates).

docs/react/reference/QueryClient.md

@@ -116,7 +116,7 @@ The options for `fetchInfiniteQuery` are exactly the same as those of [`fetchQue
 
 **Returns**
 
-- `Promise<InfiniteData<TData>>`
+- `Promise<InfiniteData<TData, TPageParam>>`
 
 ## `queryClient.prefetchQuery`
 

docs/react/reference/useInfiniteQuery.md

@@ -36,15 +36,15 @@ The options for `useInfiniteQuery` are identical to the [`useQuery` hook](../ref
 - `defaultPageParam: TPageParam`
   - **Required**
   - The default page param to use when fetching the first page.
-- `getNextPageParam: (lastPage, allPages, lastPageParam, allPageParams) => TPageParam | undefined`
+- `getNextPageParam: (lastPage, allPages, lastPageParam, allPageParams) => TPageParam | undefined | null`
   - **Required**
   - When new data is received for this query, this function receives both the last page of the infinite list of data and the full array of all pages, as well as pageParam information.
   - It should return a **single variable** that will be passed as the last optional parameter to your query function.
-  - Return `undefined` to indicate there is no next page available.
-- `getPreviousPageParam: (firstPage, allPages, firstPageParam, allPageParams) => TPageParam | undefined`
+  - Return `undefined` or `null` to indicate there is no next page available.
+- `getPreviousPageParam: (firstPage, allPages, firstPageParam, allPageParams) => TPageParam | undefined | null`
   - When new data is received for this query, this function receives both the first page of the infinite list of data and the full array of all pages, as well as pageParam information.
   - It should return a **single variable** that will be passed as the last optional parameter to your query function.
-  - Return `undefined` to indicate there is no previous page available.
+  - Return `undefined` or `null`to indicate there is no previous page available.
 - `maxPages: number | undefined`
   - The maximum number of pages to store in the infinite query data.
   - When the maximum number of pages is reached, fetching a new page will result in the removal of either the first or last page from the pages array, depending on the specified direction.

packages/query-core/src/infiniteQueryBehavior.ts

@@ -7,9 +7,9 @@ import type {
   QueryKey,
 } from './types'
 
-export function infiniteQueryBehavior<TQueryFnData, TError, TData>(
+export function infiniteQueryBehavior<TQueryFnData, TError, TData, TPageParam>(
   pages?: number,
-): QueryBehavior<TQueryFnData, TError, InfiniteData<TData>> {
+): QueryBehavior<TQueryFnData, TError, InfiniteData<TData, TPageParam>> {
   return {
     onFetch: (context) => {
       context.fetchFn = async () => {
@@ -54,7 +54,7 @@ export function infiniteQueryBehavior<TQueryFnData, TError, TData>(
             return Promise.reject()
           }
 
-          if (typeof param === 'undefined' && data.pages.length) {
+          if (param == null && data.pages.length) {
             return Promise.resolve(data)
           }
 
@@ -151,7 +151,7 @@ export function hasNextPage(
   data?: InfiniteData<unknown>,
 ): boolean {
   if (!data) return false
-  return typeof getNextPageParam(options, data) !== 'undefined'
+  return getNextPageParam(options, data) != null
 }
 
 /**
@@ -162,5 +162,5 @@ export function hasPreviousPage(
   data?: InfiniteData<unknown>,
 ): boolean {
   if (!data || !options.getPreviousPageParam) return false
-  return typeof getPreviousPageParam(options, data) !== 'undefined'
+  return getPreviousPageParam(options, data) != null
 }

packages/query-core/src/infiniteQueryObserver.ts

@@ -33,7 +33,7 @@ export class InfiniteQueryObserver<
   TQueryFnData,
   TError,
   TData,
-  InfiniteData<TQueryData>,
+  InfiniteData<TQueryData, TPageParam>,
   TQueryKey
 > {
   // Type override
@@ -130,7 +130,12 @@ export class InfiniteQueryObserver<
   }
 
   protected createResult(
-    query: Query<TQueryFnData, TError, InfiniteData<TQueryData>, TQueryKey>,
+    query: Query<
+      TQueryFnData,
+      TError,
+      InfiniteData<TQueryData, TPageParam>,
+      TQueryKey
+    >,
     options: InfiniteQueryObserverOptions<
       TQueryFnData,
       TError,

packages/query-core/src/queryClient.ts

@@ -324,10 +324,13 @@ export class QueryClient {
       TQueryKey,
       TPageParam
     >,
-  ): Promise<InfiniteData<TData>> {
-    options.behavior = infiniteQueryBehavior<TQueryFnData, TError, TData>(
-      options.pages,
-    )
+  ): Promise<InfiniteData<TData, TPageParam>> {
+    options.behavior = infiniteQueryBehavior<
+      TQueryFnData,
+      TError,
+      TData,
+      TPageParam
+    >(options.pages)
     return this.fetchQuery(options)
   }
 

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

@@ -1,4 +1,4 @@
-import { vi } from 'vitest'
+import { expect, vi } from 'vitest'
 import { InfiniteQueryObserver } from '..'
 import { createQueryClient, queryKey, sleep } from './utils'
 import type { QueryClient } from '..'
@@ -119,12 +119,41 @@ describe('InfiniteQueryObserver', () => {
 
     expect(observer.getCurrentResult().data?.pages).toEqual(['1', '2'])
     expect(queryFn).toBeCalledTimes(2)
+    expect(observer.getCurrentResult().hasNextPage).toBe(true)
 
     next = undefined
 
     await observer.refetch()
 
     expect(observer.getCurrentResult().data?.pages).toEqual(['1'])
     expect(queryFn).toBeCalledTimes(3)
+    expect(observer.getCurrentResult().hasNextPage).toBe(false)
+  })
+
+  test('should stop refetching if null is returned from getNextPageParam', async () => {
+    const key = queryKey()
+    let next: number | null = 2
+    const queryFn = vi.fn<any, any>(({ pageParam }) => String(pageParam))
+    const observer = new InfiniteQueryObserver(queryClient, {
+      queryKey: key,
+      queryFn,
+      defaultPageParam: 1,
+      getNextPageParam: () => next,
+    })
+
+    await observer.fetchNextPage()
+    await observer.fetchNextPage()
+
+    expect(observer.getCurrentResult().data?.pages).toEqual(['1', '2'])
+    expect(queryFn).toBeCalledTimes(2)
+    expect(observer.getCurrentResult().hasNextPage).toBe(true)
+
+    next = null
+
+    await observer.refetch()
+
+    expect(observer.getCurrentResult().data?.pages).toEqual(['1'])
+    expect(queryFn).toBeCalledTimes(3)
+    expect(observer.getCurrentResult().hasNextPage).toBe(false)
   })
 })

packages/query-core/src/types.ts

@@ -71,18 +71,18 @@ export type GetPreviousPageParamFunction<TPageParam, TQueryFnData = unknown> = (
   allPages: TQueryFnData[],
   firstPageParam: TPageParam,
   allPageParams: TPageParam[],
-) => TPageParam | undefined
+) => TPageParam | undefined | null
 
 export type GetNextPageParamFunction<TPageParam, TQueryFnData = unknown> = (
   lastPage: TQueryFnData,
   allPages: TQueryFnData[],
   lastPageParam: TPageParam,
   allPageParams: TPageParam[],
-) => TPageParam | undefined
+) => TPageParam | undefined | null
 
-export interface InfiniteData<TData> {
+export interface InfiniteData<TData, TPageParam = unknown> {
   pages: TData[]
-  pageParams: unknown[]
+  pageParams: TPageParam[]
 }
 
 export type QueryMeta = Register extends {
@@ -322,7 +322,7 @@ export interface InfiniteQueryObserverOptions<
       TQueryFnData,
       TError,
       TData,
-      InfiniteData<TQueryData>,
+      InfiniteData<TQueryData, TPageParam>,
       TQueryKey,
       TPageParam
     >,
@@ -380,7 +380,7 @@ export type FetchInfiniteQueryOptions<
 > = FetchQueryOptions<
   TQueryFnData,
   TError,
-  InfiniteData<TData>,
+  InfiniteData<TData, TPageParam>,
   TQueryKey,
   TPageParam
 > &

packages/react-query/src/__tests__/useInfiniteQuery.type.test.tsx

@@ -100,9 +100,14 @@ describe('select', () => {
         getNextPageParam: () => undefined,
       })
 
+      // TODO: Order of generics prevents pageParams to be typed correctly. Using `unknown` for now
       const result: Expect<
-        Equal<InfiniteData<number> | undefined, (typeof infiniteQuery)['data']>
+        Equal<
+          InfiniteData<number, unknown> | undefined,
+          (typeof infiniteQuery)['data']
+        >
       > = true
+
       return result
     })
   })
@@ -117,7 +122,9 @@ describe('select', () => {
         defaultPageParam: 1,
         getNextPageParam: () => undefined,
         select: (data) => {
-          const result: Expect<Equal<InfiniteData<number>, typeof data>> = true
+          const result: Expect<
+            Equal<InfiniteData<number, number>, typeof data>
+          > = true
           return result
         },
       })
@@ -203,8 +210,12 @@ describe('getNextPageParam / getPreviousPageParam', () => {
         },
       })
 
+      // TODO: Order of generics prevents pageParams to be typed correctly. Using `unknown` for now
       const result: Expect<
-        Equal<InfiniteData<string> | undefined, (typeof infiniteQuery)['data']>
+        Equal<
+          InfiniteData<string, unknown> | undefined,
+          (typeof infiniteQuery)['data']
+        >
       > = true
       return result
     })