feat: add PageParam typing (#5005)

* feat: add PageParam typing

* feat(infinite-query): more typing

* feat(infinite-query): make pageParam never by defaukt

* feat(infinite-query):  PageParam type unknown for infinite queries

* fix(infinite-query): fix tests

* feat(infinite-query): add previous end next return TPageParam type

Author: ecyrbe

packages/query-core/src/infiniteQueryBehavior.ts

@@ -4,6 +4,7 @@ import type {
   InfiniteData,
   InfiniteQueryOptions,
   QueryFunctionContext,
+  QueryKey,
 } from './types'
 
 export function infiniteQueryBehavior<
@@ -74,15 +75,20 @@ export function infiniteQueryBehavior<
             return Promise.resolve(pages)
           }
 
-          const queryFnContext: Omit<QueryFunctionContext, 'signal'> = {
+          const queryFnContext: Omit<
+            QueryFunctionContext<QueryKey, unknown>,
+            'signal'
+          > = {
             queryKey: context.queryKey,
             pageParam: param,
             meta: context.options.meta,
           }
 
           addSignalProperty(queryFnContext)
 
-          const queryFnResult = queryFn(queryFnContext as QueryFunctionContext)
+          const queryFnResult = queryFn(
+            queryFnContext as QueryFunctionContext<QueryKey, unknown>,
+          )
 
           const promise = Promise.resolve(queryFnResult).then((page) =>
             buildNewPages(pages, param, page, previous),

packages/query-core/src/query.ts

@@ -362,7 +362,6 @@ export class Query<
     // Create query function context
     const queryFnContext: Omit<QueryFunctionContext<TQueryKey>, 'signal'> = {
       queryKey: this.queryKey,
-      pageParam: undefined,
       meta: this.meta,
     }
 

packages/query-core/src/queryClient.ts

@@ -275,8 +275,15 @@ export class QueryClient {
     TError = RegisteredError,
     TData = TQueryFnData,
     TQueryKey extends QueryKey = QueryKey,
+    TPageParam = never,
   >(
-    options: FetchQueryOptions<TQueryFnData, TError, TData, TQueryKey>,
+    options: FetchQueryOptions<
+      TQueryFnData,
+      TError,
+      TData,
+      TQueryKey,
+      TPageParam
+    >,
   ): Promise<TData> {
     const defaultedOptions = this.defaultQueryOptions(options)
 
@@ -308,8 +315,15 @@ export class QueryClient {
     TError = RegisteredError,
     TData = TQueryFnData,
     TQueryKey extends QueryKey = QueryKey,
+    TPageParam = unknown,
   >(
-    options: FetchInfiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey>,
+    options: FetchInfiniteQueryOptions<
+      TQueryFnData,
+      TError,
+      TData,
+      TQueryKey,
+      TPageParam
+    >,
   ): Promise<InfiniteData<TData>> {
     options.behavior = infiniteQueryBehavior<TQueryFnData, TError, TData>()
     return this.fetchQuery(options)
@@ -320,8 +334,15 @@ export class QueryClient {
     TError = RegisteredError,
     TData = TQueryFnData,
     TQueryKey extends QueryKey = QueryKey,
+    TPageParam = unknown,
   >(
-    options: FetchInfiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey>,
+    options: FetchInfiniteQueryOptions<
+      TQueryFnData,
+      TError,
+      TData,
+      TQueryKey,
+      TPageParam
+    >,
   ): Promise<void> {
     return this.fetchInfiniteQuery(options).then(noop).catch(noop)
   }
@@ -405,9 +426,17 @@ export class QueryClient {
     TData = TQueryFnData,
     TQueryData = TQueryFnData,
     TQueryKey extends QueryKey = QueryKey,
+    TPageParam = never,
   >(
     options?:
-      | QueryObserverOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey>
+      | QueryObserverOptions<
+          TQueryFnData,
+          TError,
+          TData,
+          TQueryData,
+          TQueryKey,
+          TPageParam
+        >
       | DefaultedQueryObserverOptions<
           TQueryFnData,
           TError,

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

@@ -200,6 +200,7 @@ describe('query', () => {
     expect(queryFn).toHaveBeenCalledTimes(1)
     const args = queryFn.mock.calls[0]![0]
     expect(args).toBeDefined()
+    // @ts-expect-error page param should be undefined
     expect(args.pageParam).toBeUndefined()
     expect(args.queryKey).toEqual(key)
     expect(args.signal).toBeInstanceOf(AbortSignal)

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

@@ -565,15 +565,16 @@ describe('queryClient', () => {
         pageParams: [0],
       } as const
 
-      const fetchFn: QueryFunction<StrictData, StrictQueryKey> = () =>
+      const fetchFn: QueryFunction<StrictData, StrictQueryKey, number> = () =>
         Promise.resolve(data.pages[0])
 
       await expect(
         queryClient.fetchInfiniteQuery<
           StrictData,
           any,
           StrictData,
-          StrictQueryKey
+          StrictQueryKey,
+          number
         >({ queryKey: key, queryFn: fetchFn, defaultPageParam: 0 }),
       ).resolves.toEqual(data)
     })
@@ -603,14 +604,15 @@ describe('queryClient', () => {
       type StrictQueryKey = ['strict', ...ReturnType<typeof queryKey>]
       const key: StrictQueryKey = ['strict', ...queryKey()]
 
-      const fetchFn: QueryFunction<StrictData, StrictQueryKey> = () =>
+      const fetchFn: QueryFunction<StrictData, StrictQueryKey, number> = () =>
         Promise.resolve('data')
 
       await queryClient.prefetchInfiniteQuery<
         StrictData,
         any,
         StrictData,
-        StrictQueryKey
+        StrictQueryKey,
+        number
       >({ queryKey: key, queryFn: fetchFn, defaultPageParam: 0 })
 
       const result = queryClient.getQueryData(key)

packages/query-core/src/types.ts

@@ -22,17 +22,24 @@ export type QueryKey = readonly unknown[]
 export type QueryFunction<
   T = unknown,
   TQueryKey extends QueryKey = QueryKey,
-> = (context: QueryFunctionContext<TQueryKey>) => T | Promise<T>
+  TPageParam = never,
+> = (context: QueryFunctionContext<TQueryKey, TPageParam>) => T | Promise<T>
 
-export interface QueryFunctionContext<
+export type QueryFunctionContext<
   TQueryKey extends QueryKey = QueryKey,
-  TPageParam = any,
-> {
-  queryKey: TQueryKey
-  signal: AbortSignal
-  pageParam?: TPageParam
-  meta: QueryMeta | undefined
-}
+  TPageParam = never,
+> = [TPageParam] extends [never]
+  ? {
+      queryKey: TQueryKey
+      signal: AbortSignal
+      meta: QueryMeta | undefined
+    }
+  : {
+      queryKey: TQueryKey
+      signal: AbortSignal
+      pageParam: TPageParam
+      meta: QueryMeta | undefined
+    }
 
 export type InitialDataFunction<T> = () => T | undefined
 
@@ -50,15 +57,15 @@ export type QueryKeyHashFunction<TQueryKey extends QueryKey> = (
   queryKey: TQueryKey,
 ) => string
 
-export type GetPreviousPageParamFunction<TQueryFnData = unknown> = (
+export type GetPreviousPageParamFunction<TPageParam, TQueryFnData = unknown> = (
   firstPage: TQueryFnData,
   allPages: TQueryFnData[],
-) => unknown
+) => TPageParam | undefined
 
-export type GetNextPageParamFunction<TQueryFnData = unknown> = (
+export type GetNextPageParamFunction<TPageParam, TQueryFnData = unknown> = (
   lastPage: TQueryFnData,
   allPages: TQueryFnData[],
-) => unknown
+) => TPageParam | undefined
 
 export interface InfiniteData<TData> {
   pages: TData[]
@@ -76,6 +83,7 @@ export interface QueryOptions<
   TError = RegisteredError,
   TData = TQueryFnData,
   TQueryKey extends QueryKey = QueryKey,
+  TPageParam = never,
 > {
   /**
    * If `false`, failed queries will not retry by default.
@@ -87,7 +95,7 @@ export interface QueryOptions<
   retryDelay?: RetryDelayValue<TError>
   networkMode?: NetworkMode
   gcTime?: number
-  queryFn?: QueryFunction<TQueryFnData, TQueryKey>
+  queryFn?: QueryFunction<TQueryFnData, TQueryKey, TPageParam>
   queryHash?: string
   queryKey?: TQueryKey
   queryKeyHashFn?: QueryKeyHashFunction<TQueryKey>
@@ -114,22 +122,24 @@ export interface QueryOptions<
   maxPages?: number
 }
 
-export interface DefaultPageParam {
-  defaultPageParam: unknown
+export interface DefaultPageParam<TPageParam = unknown> {
+  defaultPageParam: TPageParam
 }
 
-export interface InfiniteQueryOptions<TQueryFnData = unknown>
-  extends DefaultPageParam {
+export interface InfiniteQueryOptions<
+  TQueryFnData = unknown,
+  TPageParam = unknown,
+> extends DefaultPageParam<TPageParam> {
   /**
    * This function can be set to automatically get the previous cursor for infinite queries.
    * The result will also be used to determine the value of `hasPreviousPage`.
    */
-  getPreviousPageParam?: GetPreviousPageParamFunction<TQueryFnData>
+  getPreviousPageParam?: GetPreviousPageParamFunction<TPageParam, TQueryFnData>
   /**
    * 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<TQueryFnData>
+  getNextPageParam: GetNextPageParamFunction<TPageParam, TQueryFnData>
 }
 
 export type ThrowErrors<
@@ -150,7 +160,14 @@ export interface QueryObserverOptions<
   TData = TQueryFnData,
   TQueryData = TQueryFnData,
   TQueryKey extends QueryKey = QueryKey,
-> extends QueryOptions<TQueryFnData, TError, TQueryData, TQueryKey> {
+  TPageParam = never,
+> extends QueryOptions<
+    TQueryFnData,
+    TError,
+    TQueryData,
+    TQueryKey,
+    TPageParam
+  > {
   /**
    * Set this to `false` to disable automatic refetching when the query mounts or changes query keys.
    * To refetch the query, use the `refetch` method returned from the `useQuery` instance.
@@ -289,14 +306,16 @@ export interface InfiniteQueryObserverOptions<
   TData = TQueryFnData,
   TQueryData = TQueryFnData,
   TQueryKey extends QueryKey = QueryKey,
+  TPageParam = unknown,
 > extends QueryObserverOptions<
       TQueryFnData,
       TError,
       InfiniteData<TData>,
       InfiniteData<TQueryData>,
-      TQueryKey
+      TQueryKey,
+      TPageParam
     >,
-    InfiniteQueryOptions<TQueryFnData> {}
+    InfiniteQueryOptions<TQueryFnData, TPageParam> {}
 
 export type DefaultedInfiniteQueryObserverOptions<
   TQueryFnData = unknown,
@@ -320,8 +339,9 @@ export interface FetchQueryOptions<
   TError = RegisteredError,
   TData = TQueryFnData,
   TQueryKey extends QueryKey = QueryKey,
+  TPageParam = never,
 > extends WithRequired<
-    QueryOptions<TQueryFnData, TError, TData, TQueryKey>,
+    QueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>,
     'queryKey'
   > {
   /**
@@ -336,13 +356,15 @@ export interface FetchInfiniteQueryOptions<
   TError = RegisteredError,
   TData = TQueryFnData,
   TQueryKey extends QueryKey = QueryKey,
+  TPageParam = unknown,
 > extends FetchQueryOptions<
       TQueryFnData,
       TError,
       InfiniteData<TData>,
-      TQueryKey
+      TQueryKey,
+      TPageParam
     >,
-    DefaultPageParam {}
+    DefaultPageParam<TPageParam> {}
 
 export interface ResultOptions {
   throwOnError?: boolean

packages/react-query/src/types.ts

@@ -41,13 +41,15 @@ export interface UseInfiniteQueryOptions<
   TData = TQueryFnData,
   TQueryData = TQueryFnData,
   TQueryKey extends QueryKey = QueryKey,
+  TPageParam = unknown,
 > extends WithRequired<
     InfiniteQueryObserverOptions<
       TQueryFnData,
       TError,
       TData,
       TQueryData,
-      TQueryKey
+      TQueryKey,
+      TPageParam
     >,
     'queryKey'
   > {}

packages/react-query/src/useInfiniteQuery.ts

@@ -14,13 +14,15 @@ export function useInfiniteQuery<
   TError = RegisteredError,
   TData = TQueryFnData,
   TQueryKey extends QueryKey = QueryKey,
+  TPageParam = unknown,
 >(
   options: UseInfiniteQueryOptions<
     TQueryFnData,
     TError,
     TData,
     TQueryFnData,
-    TQueryKey
+    TQueryKey,
+    TPageParam
   >,
   queryClient?: QueryClient,
 ): UseInfiniteQueryResult<TData, TError> {