@tanstack/react-query 5.0.0-beta.2 → 5.0.0-beta.23

package/src/__tests__/useQuery.types.test.tsx

@@ -1,6 +1,7 @@
 import { useQuery } from '../useQuery'
 import { queryOptions } from '../queryOptions'
 import { doNotExecute } from './utils'
+import type { UseQueryOptions } from '../types'
 import type { Equal, Expect } from './utils'
 
 describe('initialData', () => {
@@ -44,6 +45,19 @@ describe('initialData', () => {
       })
     })
 
+    it('it should be possible to define a different TData than TQueryFnData using select with queryOptions spread into useQuery', () => {
+      doNotExecute(() => {
+        const options = queryOptions({
+          queryKey: ['key'],
+          queryFn: () => Promise.resolve(1),
+        })
+        useQuery({
+          ...options,
+          select: (data) => data > 1,
+        })
+      })
+    })
+
     it('TData should always be defined when initialData is provided as a function which ALWAYS returns the data', () => {
       doNotExecute(() => {
         const { data } = useQuery({
@@ -97,79 +111,46 @@ describe('initialData', () => {
         return result
       })
     })
-  })
-
-  describe('Query key overload', () => {
-    it('TData should always be defined when initialData is provided', () => {
-      doNotExecute(() => {
-        const { data } = useQuery({
-          queryKey: ['key'],
-          queryFn: () => {
-            return {
-              wow: true,
-            }
-          },
-          initialData: {
-            wow: true,
-          },
-        })
-
-        const result: Expect<Equal<{ wow: boolean }, typeof data>> = true
-        return result
-      })
-    })
 
-    it('TData should have undefined in the union when initialData is NOT provided', () => {
+    it('TData should be narrowed after an isSuccess check when initialData is provided as a function which can return undefined', () => {
       doNotExecute(() => {
-        const { data } = useQuery({
+        const { data, isSuccess } = useQuery({
           queryKey: ['key'],
           queryFn: () => {
             return {
               wow: true,
             }
           },
+          initialData: () => undefined as { wow: boolean } | undefined,
         })
 
-        const result: Expect<Equal<{ wow: boolean } | undefined, typeof data>> =
-          true
-        return result
+        if (isSuccess) {
+          const result: Expect<Equal<{ wow: boolean }, typeof data>> = true
+          return result
+        }
+        return false
       })
     })
   })
 
-  describe('Query key and func', () => {
-    it('TData should always be defined when initialData is provided', () => {
+  describe('custom hook', () => {
+    it('should allow custom hooks using UseQueryOptions', () => {
       doNotExecute(() => {
-        const { data } = useQuery({
-          queryKey: ['key'],
-          queryFn: () => {
-            return {
-              wow: true,
-            }
-          },
-          initialData: {
-            wow: true,
-          },
-        })
+        type Data = string
 
-        const result: Expect<Equal<{ wow: boolean }, typeof data>> = true
-        return result
-      })
-    })
+        const useCustomQuery = (
+          options?: Omit<UseQueryOptions<Data>, 'queryKey' | 'queryFn'>,
+        ) => {
+          return useQuery({
+            ...options,
+            queryKey: ['todos-key'],
+            queryFn: () => Promise.resolve('data'),
+          })
+        }
 
-    it('TData should have undefined in the union when initialData is NOT provided', () => {
-      doNotExecute(() => {
-        const { data } = useQuery({
-          queryKey: ['key'],
-          queryFn: () => {
-            return {
-              wow: true,
-            }
-          },
-        })
+        const { data } = useCustomQuery()
 
-        const result: Expect<Equal<{ wow: boolean } | undefined, typeof data>> =
-          true
+        const result: Expect<Equal<Data | undefined, typeof data>> = true
         return result
       })
     })

package/src/index.ts

@@ -10,8 +10,21 @@ export type { QueriesResults, QueriesOptions } from './useQueries'
 export { useQuery } from './useQuery'
 export { useSuspenseQuery } from './useSuspenseQuery'
 export { useSuspenseInfiniteQuery } from './useSuspenseInfiniteQuery'
+export { useSuspenseQueries } from './useSuspenseQueries'
+export type {
+  SuspenseQueriesResults,
+  SuspenseQueriesOptions,
+} from './useSuspenseQueries'
 export { queryOptions } from './queryOptions'
+export type {
+  DefinedInitialDataOptions,
+  UndefinedInitialDataOptions,
+} from './queryOptions'
 export { infiniteQueryOptions } from './infiniteQueryOptions'
+export type {
+  DefinedInitialDataInfiniteOptions,
+  UndefinedInitialDataInfiniteOptions,
+} from './infiniteQueryOptions'
 export {
   QueryClientContext,
   QueryClientProvider,

package/src/infiniteQueryOptions.ts

@@ -35,7 +35,9 @@ export type DefinedInitialDataInfiniteOptions<
   TQueryKey,
   TPageParam
 > & {
-  initialData: InfiniteData<TQueryData> | (() => InfiniteData<TQueryData>)
+  initialData:
+    | InfiniteData<TQueryData, TPageParam>
+    | (() => InfiniteData<TQueryData, TPageParam>)
 }
 
 export function infiniteQueryOptions<

package/src/queryOptions.ts

@@ -10,13 +10,17 @@ export type UndefinedInitialDataOptions<
   initialData?: undefined
 }
 
+type NonUndefinedGuard<T> = T extends undefined ? never : T
+
 export type DefinedInitialDataOptions<
   TQueryFnData = unknown,
   TError = DefaultError,
   TData = TQueryFnData,
   TQueryKey extends QueryKey = QueryKey,
 > = UseQueryOptions<TQueryFnData, TError, TData, TQueryKey> & {
-  initialData: TQueryFnData | (() => TQueryFnData)
+  initialData:
+    | NonUndefinedGuard<TQueryFnData>
+    | (() => NonUndefinedGuard<TQueryFnData>)
 }
 
 export function queryOptions<
@@ -24,18 +28,26 @@ export function queryOptions<
   TError = DefaultError,
   TData = TQueryFnData,
   TQueryKey extends QueryKey = QueryKey,
->(
-  options: UndefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey>,
-): UndefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey>
+  TOptions extends UndefinedInitialDataOptions<
+    TQueryFnData,
+    TError,
+    TData,
+    TQueryKey
+  > = UndefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey>,
+>(options: TOptions): TOptions
 
 export function queryOptions<
   TQueryFnData = unknown,
   TError = DefaultError,
   TData = TQueryFnData,
   TQueryKey extends QueryKey = QueryKey,
->(
-  options: DefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey>,
-): DefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey>
+  TOptions extends DefinedInitialDataOptions<
+    TQueryFnData,
+    TError,
+    TData,
+    TQueryKey
+  > = DefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey>,
+>(options: TOptions): TOptions
 
 export function queryOptions(options: unknown) {
   return options

package/src/suspense.ts

@@ -1,11 +1,23 @@
+import type { DefaultError } from '@tanstack/query-core/src'
 import type {
   DefaultedQueryObserverOptions,
+  Query,
   QueryKey,
   QueryObserver,
   QueryObserverResult,
 } from '@tanstack/query-core'
 import type { QueryErrorResetBoundaryValue } from './QueryErrorResetBoundary'
 
+export const defaultThrowOnError = <
+  TQueryFnData = unknown,
+  TError = DefaultError,
+  TData = TQueryFnData,
+  TQueryKey extends QueryKey = QueryKey,
+>(
+  _error: TError,
+  query: Query<TQueryFnData, TError, TData, TQueryKey>,
+) => typeof query.state.data === 'undefined'
+
 export const ensureStaleTime = (
   defaultedOptions: DefaultedQueryObserverOptions<any, any, any, any, any>,
 ) => {

package/src/types.ts

@@ -33,9 +33,12 @@ export interface UseQueryOptions<
   TError = DefaultError,
   TData = TQueryFnData,
   TQueryKey extends QueryKey = QueryKey,
-> extends WithRequired<
-    UseBaseQueryOptions<TQueryFnData, TError, TData, TQueryFnData, TQueryKey>,
-    'queryKey'
+> extends Omit<
+    WithRequired<
+      UseBaseQueryOptions<TQueryFnData, TError, TData, TQueryFnData, TQueryKey>,
+      'queryKey'
+    >,
+    'suspense'
   > {}
 
 export interface UseSuspenseQueryOptions<
@@ -45,7 +48,7 @@ export interface UseSuspenseQueryOptions<
   TQueryKey extends QueryKey = QueryKey,
 > extends Omit<
     UseQueryOptions<TQueryFnData, TError, TData, TQueryKey>,
-    'enabled' | 'suspense' | 'throwOnError' | 'placeholderData'
+    'enabled' | 'throwOnError' | 'placeholderData'
   > {}
 
 export interface UseInfiniteQueryOptions<
@@ -56,13 +59,16 @@ export interface UseInfiniteQueryOptions<
   TQueryKey extends QueryKey = QueryKey,
   TPageParam = unknown,
 > extends WithRequired<
-    InfiniteQueryObserverOptions<
-      TQueryFnData,
-      TError,
-      TData,
-      TQueryData,
-      TQueryKey,
-      TPageParam
+    Omit<
+      InfiniteQueryObserverOptions<
+        TQueryFnData,
+        TError,
+        TData,
+        TQueryData,
+        TQueryKey,
+        TPageParam
+      >,
+      'suspense'
     >,
     'queryKey'
   > {}
@@ -83,7 +89,7 @@ export interface UseSuspenseInfiniteQueryOptions<
       TQueryKey,
       TPageParam
     >,
-    'enabled' | 'suspense' | 'throwOnError' | 'placeholderData'
+    'enabled' | 'throwOnError' | 'placeholderData'
   > {}
 
 export type UseBaseQueryResult<

package/src/useInfiniteQuery.ts

@@ -70,11 +70,16 @@ export function useInfiniteQuery<
     TPageParam
   >,
   queryClient?: QueryClient,
-): UseInfiniteQueryResult<TData, TError> {
+): UseInfiniteQueryResult<TData, TError>
+
+export function useInfiniteQuery(
+  options: UseInfiniteQueryOptions,
+  queryClient?: QueryClient,
+) {
   return useBaseQuery(
     options,
     // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-assertion
     InfiniteQueryObserver as typeof QueryObserver,
     queryClient,
-  ) as UseInfiniteQueryResult<TData, TError>
+  )
 }

package/src/useQueries.ts

@@ -35,7 +35,7 @@ type UseQueryOptionsForUseQueries<
   TQueryKey extends QueryKey = QueryKey,
 > = Omit<
   UseQueryOptions<TQueryFnData, TError, TData, TQueryKey>,
-  'placeholderData'
+  'placeholderData' | 'suspense'
 > & {
   placeholderData?: TQueryFnData | QueriesPlaceholderDataFunction<TQueryFnData>
 }
@@ -103,62 +103,68 @@ type GetResults<T> =
  * QueriesOptions reducer recursively unwraps function arguments to infer/enforce type param
  */
 export type QueriesOptions<
-  T extends any[],
-  Result extends any[] = [],
+  T extends Array<any>,
+  Result extends Array<any> = [],
   Depth extends ReadonlyArray<number> = [],
 > = Depth['length'] extends MAXIMUM_DEPTH
-  ? UseQueryOptionsForUseQueries[]
+  ? Array<UseQueryOptionsForUseQueries>
   : T extends []
   ? []
   : T extends [infer Head]
   ? [...Result, GetOptions<Head>]
   : T extends [infer Head, ...infer Tail]
   ? QueriesOptions<[...Tail], [...Result, GetOptions<Head>], [...Depth, 1]>
-  : unknown[] extends T
+  : Array<unknown> extends T
   ? T
   : // If T is *some* array but we couldn't assign unknown[] to it, then it must hold some known/homogenous type!
   // use this to infer the param types in the case of Array.map() argument
-  T extends UseQueryOptionsForUseQueries<
-      infer TQueryFnData,
-      infer TError,
-      infer TData,
-      infer TQueryKey
-    >[]
-  ? UseQueryOptionsForUseQueries<TQueryFnData, TError, TData, TQueryKey>[]
+  T extends Array<
+      UseQueryOptionsForUseQueries<
+        infer TQueryFnData,
+        infer TError,
+        infer TData,
+        infer TQueryKey
+      >
+    >
+  ? Array<UseQueryOptionsForUseQueries<TQueryFnData, TError, TData, TQueryKey>>
   : // Fallback
-    UseQueryOptionsForUseQueries[]
+    Array<UseQueryOptionsForUseQueries>
 
 /**
  * QueriesResults reducer recursively maps type param to results
  */
 export type QueriesResults<
-  T extends any[],
-  Result extends any[] = [],
+  T extends Array<any>,
+  Result extends Array<any> = [],
   Depth extends ReadonlyArray<number> = [],
 > = Depth['length'] extends MAXIMUM_DEPTH
-  ? UseQueryResult[]
+  ? Array<UseQueryResult>
   : T extends []
   ? []
   : T extends [infer Head]
   ? [...Result, GetResults<Head>]
   : T extends [infer Head, ...infer Tail]
   ? QueriesResults<[...Tail], [...Result, GetResults<Head>], [...Depth, 1]>
-  : T extends UseQueryOptionsForUseQueries<
-      infer TQueryFnData,
-      infer TError,
-      infer TData,
-      any
-    >[]
+  : T extends Array<
+      UseQueryOptionsForUseQueries<
+        infer TQueryFnData,
+        infer TError,
+        infer TData,
+        any
+      >
+    >
   ? // Dynamic-size (homogenous) UseQueryOptions array: map directly to array of results
-    UseQueryResult<
-      unknown extends TData ? TQueryFnData : TData,
-      unknown extends TError ? DefaultError : TError
-    >[]
+    Array<
+      UseQueryResult<
+        unknown extends TData ? TQueryFnData : TData,
+        unknown extends TError ? DefaultError : TError
+      >
+    >
   : // Fallback
-    UseQueryResult[]
+    Array<UseQueryResult>
 
 export function useQueries<
-  T extends any[],
+  T extends Array<any>,
   TCombinedResult = QueriesResults<T>,
 >(
   {

package/src/useQuery.ts

@@ -40,6 +40,8 @@ export function useQuery<
 >(
   options: UseQueryOptions<TQueryFnData, TError, TData, TQueryKey>,
   queryClient?: QueryClient,
-) {
+): UseQueryResult<TData, TError>
+
+export function useQuery(options: UseQueryOptions, queryClient?: QueryClient) {
   return useBaseQuery(options, QueryObserver, queryClient)
 }

package/src/useSuspenseQueries.ts

@@ -0,0 +1,164 @@
+'use client'
+import { useQueries } from './useQueries'
+import { defaultThrowOnError } from './suspense'
+import type { UseSuspenseQueryOptions, UseSuspenseQueryResult } from './types'
+import type {
+  DefaultError,
+  QueryClient,
+  QueryFunction,
+} from '@tanstack/query-core'
+
+// Avoid TS depth-limit error in case of large array literal
+type MAXIMUM_DEPTH = 20
+
+type GetSuspenseOptions<T> =
+  // Part 1: responsible for applying explicit type parameter to function arguments, if object { queryFnData: TQueryFnData, error: TError, data: TData }
+  T extends {
+    queryFnData: infer TQueryFnData
+    error?: infer TError
+    data: infer TData
+  }
+    ? UseSuspenseQueryOptions<TQueryFnData, TError, TData>
+    : T extends { queryFnData: infer TQueryFnData; error?: infer TError }
+    ? UseSuspenseQueryOptions<TQueryFnData, TError>
+    : T extends { data: infer TData; error?: infer TError }
+    ? UseSuspenseQueryOptions<unknown, TError, TData>
+    : // Part 2: responsible for applying explicit type parameter to function arguments, if tuple [TQueryFnData, TError, TData]
+    T extends [infer TQueryFnData, infer TError, infer TData]
+    ? UseSuspenseQueryOptions<TQueryFnData, TError, TData>
+    : T extends [infer TQueryFnData, infer TError]
+    ? UseSuspenseQueryOptions<TQueryFnData, TError>
+    : T extends [infer TQueryFnData]
+    ? UseSuspenseQueryOptions<TQueryFnData>
+    : // Part 3: responsible for inferring and enforcing type if no explicit parameter was provided
+    T extends {
+        queryFn?: QueryFunction<infer TQueryFnData, infer TQueryKey>
+        select: (data: any) => infer TData
+      }
+    ? UseSuspenseQueryOptions<TQueryFnData, Error, TData, TQueryKey>
+    : T extends { queryFn?: QueryFunction<infer TQueryFnData, infer TQueryKey> }
+    ? UseSuspenseQueryOptions<TQueryFnData, Error, TQueryFnData, TQueryKey>
+    : // Fallback
+      UseSuspenseQueryOptions
+
+type GetSuspenseResults<T> =
+  // Part 1: responsible for mapping explicit type parameter to function result, if object
+  T extends { queryFnData: any; error?: infer TError; data: infer TData }
+    ? UseSuspenseQueryResult<TData, TError>
+    : T extends { queryFnData: infer TQueryFnData; error?: infer TError }
+    ? UseSuspenseQueryResult<TQueryFnData, TError>
+    : T extends { data: infer TData; error?: infer TError }
+    ? UseSuspenseQueryResult<TData, TError>
+    : // Part 2: responsible for mapping explicit type parameter to function result, if tuple
+    T extends [any, infer TError, infer TData]
+    ? UseSuspenseQueryResult<TData, TError>
+    : T extends [infer TQueryFnData, infer TError]
+    ? UseSuspenseQueryResult<TQueryFnData, TError>
+    : T extends [infer TQueryFnData]
+    ? UseSuspenseQueryResult<TQueryFnData>
+    : // Part 3: responsible for mapping inferred type to results, if no explicit parameter was provided
+    T extends {
+        queryFn?: QueryFunction<unknown, any>
+        select: (data: any) => infer TData
+      }
+    ? UseSuspenseQueryResult<TData>
+    : T extends { queryFn?: QueryFunction<infer TQueryFnData, any> }
+    ? UseSuspenseQueryResult<TQueryFnData>
+    : // Fallback
+      UseSuspenseQueryResult
+
+/**
+ * SuspenseQueriesOptions reducer recursively unwraps function arguments to infer/enforce type param
+ */
+export type SuspenseQueriesOptions<
+  T extends Array<any>,
+  Result extends Array<any> = [],
+  Depth extends ReadonlyArray<number> = [],
+> = Depth['length'] extends MAXIMUM_DEPTH
+  ? Array<UseSuspenseQueryOptions>
+  : T extends []
+  ? []
+  : T extends [infer Head]
+  ? [...Result, GetSuspenseOptions<Head>]
+  : T extends [infer Head, ...infer Tail]
+  ? SuspenseQueriesOptions<
+      [...Tail],
+      [...Result, GetSuspenseOptions<Head>],
+      [...Depth, 1]
+    >
+  : Array<unknown> extends T
+  ? T
+  : // If T is *some* array but we couldn't assign unknown[] to it, then it must hold some known/homogenous type!
+  // use this to infer the param types in the case of Array.map() argument
+  T extends Array<
+      UseSuspenseQueryOptions<
+        infer TQueryFnData,
+        infer TError,
+        infer TData,
+        infer TQueryKey
+      >
+    >
+  ? Array<UseSuspenseQueryOptions<TQueryFnData, TError, TData, TQueryKey>>
+  : // Fallback
+    Array<UseSuspenseQueryOptions>
+
+/**
+ * SuspenseQueriesResults reducer recursively maps type param to results
+ */
+export type SuspenseQueriesResults<
+  T extends Array<any>,
+  Result extends Array<any> = [],
+  Depth extends ReadonlyArray<number> = [],
+> = Depth['length'] extends MAXIMUM_DEPTH
+  ? Array<UseSuspenseQueryResult>
+  : T extends []
+  ? []
+  : T extends [infer Head]
+  ? [...Result, GetSuspenseResults<Head>]
+  : T extends [infer Head, ...infer Tail]
+  ? SuspenseQueriesResults<
+      [...Tail],
+      [...Result, GetSuspenseResults<Head>],
+      [...Depth, 1]
+    >
+  : T extends Array<
+      UseSuspenseQueryOptions<
+        infer TQueryFnData,
+        infer TError,
+        infer TData,
+        any
+      >
+    >
+  ? // Dynamic-size (homogenous) UseQueryOptions array: map directly to array of results
+    Array<
+      UseSuspenseQueryResult<
+        unknown extends TData ? TQueryFnData : TData,
+        unknown extends TError ? DefaultError : TError
+      >
+    >
+  : // Fallback
+    Array<UseSuspenseQueryResult>
+
+export function useSuspenseQueries<
+  T extends Array<any>,
+  TCombinedResult = SuspenseQueriesResults<T>,
+>(
+  options: {
+    queries: readonly [...SuspenseQueriesOptions<T>]
+    combine?: (result: SuspenseQueriesResults<T>) => TCombinedResult
+  },
+  queryClient?: QueryClient,
+): TCombinedResult {
+  return useQueries(
+    {
+      ...options,
+      queries: options.queries.map((query) => ({
+        ...query,
+        suspense: true,
+        throwOnError: defaultThrowOnError,
+        enabled: true,
+      })),
+    } as any,
+    queryClient,
+  )
+}

package/src/useSuspenseQuery.ts

@@ -1,6 +1,7 @@
 'use client'
 import { QueryObserver } from '@tanstack/query-core'
 import { useBaseQuery } from './useBaseQuery'
+import { defaultThrowOnError } from './suspense'
 import type { UseSuspenseQueryOptions, UseSuspenseQueryResult } from './types'
 import type { DefaultError, QueryClient, QueryKey } from '@tanstack/query-core'
 
@@ -18,7 +19,7 @@ export function useSuspenseQuery<
       ...options,
       enabled: true,
       suspense: true,
-      throwOnError: true,
+      throwOnError: defaultThrowOnError,
     },
     QueryObserver,
     queryClient,

package/src/utils.ts

@@ -1,4 +1,4 @@
-export function shouldThrowError<T extends (...args: any[]) => boolean>(
+export function shouldThrowError<T extends (...args: Array<any>) => boolean>(
   throwError: boolean | T | undefined,
   params: Parameters<T>,
 ): boolean {