@tanstack/react-query 4.35.7 → 4.39.0

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

@@ -0,0 +1,102 @@
+import { expectTypeOf } from 'expect-type'
+import { queryOptions } from '..'
+import { useSuspenseQueries } from '..'
+import { doNotExecute } from './utils'
+import type { UseSuspenseQueryResult } from '../useSuspenseQuery'
+
+export const queryKey = ['key'] as const
+const sleep = (ms: number) =>
+  new Promise<undefined>((resolve) => setTimeout(() => resolve(undefined), ms))
+export const queryFn = () => sleep(10).then(() => ({ text: 'response' }))
+export const select = (data: Awaited<ReturnType<typeof queryFn>>) => data.text
+
+describe('useSuspenseQueries', () => {
+  it('type check', () => {
+    doNotExecute(() => {
+      useSuspenseQueries({
+        queries: [
+          {
+            queryKey: [...queryKey, 1] as const,
+            queryFn,
+            // @ts-expect-error no suspense
+            suspense: false,
+          },
+        ] as const,
+      })
+      useSuspenseQueries({
+        queries: [
+          {
+            queryKey: [...queryKey, 2] as const,
+            queryFn,
+            select,
+            // @ts-expect-error no suspense
+            suspense: true,
+          },
+        ] as const,
+      })
+      useSuspenseQueries({
+        queries: [
+          {
+            queryKey: [...queryKey, 3] as const,
+            queryFn,
+            // @ts-expect-error no enabled
+            enabled: true,
+          },
+        ] as const,
+      })
+      useSuspenseQueries({
+        queries: [
+          {
+            queryKey: [...queryKey, 4] as const,
+            queryFn,
+            // @ts-expect-error no enabled
+            enabled: true,
+            select,
+          },
+        ] as const,
+      })
+      useSuspenseQueries({
+        queries: [
+          {
+            queryKey: [...queryKey, 4] as const,
+            queryFn,
+            // @ts-expect-error no networkMode
+            networkMode: 'always',
+            select,
+          },
+        ] as const,
+      })
+      useSuspenseQueries({
+        queries: [
+          queryOptions({
+            queryKey: [...queryKey, 4] as const,
+            queryFn: () => Promise.resolve({ field: 'success' }),
+            select: (data) => data.field,
+          }),
+        ] as const,
+      })
+      // @ts-expect-error if no items
+      useSuspenseQueries({})
+      // @ts-expect-error if no items
+      useSuspenseQueries()
+
+      const [query1, query2, query3] = useSuspenseQueries({
+        queries: [
+          { queryKey: [...queryKey, 5] as const, queryFn },
+          { queryKey: [...queryKey, 6] as const, queryFn, select },
+          queryOptions({
+            queryKey: [...queryKey, 4] as const,
+            queryFn: () => Promise.resolve({ field: 'success' }),
+            select: (data) => data.field,
+          }),
+        ] as const,
+      })
+
+      expectTypeOf(query1).toEqualTypeOf<
+        UseSuspenseQueryResult<{ text: string }>
+      >()
+      expectTypeOf(query2).toEqualTypeOf<UseSuspenseQueryResult<string>>()
+      expectTypeOf(query3).toEqualTypeOf<UseSuspenseQueryResult<string>>()
+    })
+  })
+})

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

@@ -0,0 +1,81 @@
+import { expectTypeOf } from 'expect-type'
+import {
+  type UseSuspenseQueryResult,
+  useSuspenseQuery,
+} from '../useSuspenseQuery'
+import { queryOptions } from '..'
+import { doNotExecute } from './utils'
+
+const queryKey = ['key'] as const
+const sleep = (ms: number) =>
+  new Promise<undefined>((resolve) => setTimeout(() => resolve(undefined), ms))
+const queryFn = () => sleep(10).then(() => ({ text: 'response' }))
+
+describe('useSuspenseQuery', () => {
+  it('type check', () => {
+    doNotExecute(() => {
+      //@ts-expect-error no arg
+      useSuspenseQuery()
+      useSuspenseQuery({
+        queryKey,
+        queryFn,
+        //@ts-expect-error no suspense
+        suspense: boolean,
+      })
+      useSuspenseQuery({
+        queryKey,
+        queryFn,
+        //@ts-expect-error no useErrorBoundary
+        useErrorBoundary: boolean,
+      })
+      useSuspenseQuery({
+        queryKey,
+        queryFn,
+        //@ts-expect-error no enabled
+        enabled: boolean,
+      })
+      useSuspenseQuery({
+        queryKey,
+        queryFn,
+        //@ts-expect-error no placeholderData
+        placeholderData: 'placeholder',
+      })
+      // eslint-disable-next-line @typescript-eslint/no-unused-expressions
+      useSuspenseQuery({
+        queryKey,
+        queryFn,
+        //@ts-expect-error no isPlaceholderData
+      }).isPlaceholderData
+      useSuspenseQuery({
+        queryKey,
+        queryFn,
+        //@ts-expect-error no networkMode
+        networkMode: 'always',
+      })
+
+      expectTypeOf(useSuspenseQuery({ queryKey, queryFn })).toEqualTypeOf<
+        UseSuspenseQueryResult<{ text: string }>
+      >()
+      expectTypeOf(
+        useSuspenseQuery({
+          queryKey,
+          queryFn,
+          select: (data) => data.text,
+        }),
+      ).toEqualTypeOf<UseSuspenseQueryResult<string>>()
+      const options = queryOptions({
+        queryKey,
+        queryFn,
+      })
+      expectTypeOf(useSuspenseQuery(options)).toEqualTypeOf<
+        UseSuspenseQueryResult<{ text: string }>
+      >()
+      expectTypeOf(
+        useSuspenseQuery({
+          ...options,
+          select: (data) => data.text,
+        }),
+      ).toEqualTypeOf<UseSuspenseQueryResult<string>>()
+    })
+  })
+})

package/src/__tests__/utils.tsx

@@ -4,6 +4,8 @@ import * as utils from '@tanstack/query-core'
 import { QueryClient, QueryClientProvider } from '..'
 import type { ContextOptions, MutationOptions, QueryClientConfig } from '..'
 
+export const doNotExecute = (_func: () => void) => true
+
 export function renderWithClient(
   client: QueryClient,
   ui: React.ReactElement,

package/src/index.ts

@@ -11,6 +11,8 @@ export * from './types'
 export { useQueries } from './useQueries'
 export type { QueriesResults, QueriesOptions } from './useQueries'
 export { useQuery } from './useQuery'
+export { useSuspenseQuery } from './useSuspenseQuery'
+export { useSuspenseQueries } from './useSuspenseQueries'
 export {
   defaultContext,
   QueryClientProvider,
@@ -29,3 +31,4 @@ export { useIsMutating } from './useIsMutating'
 export { useMutation } from './useMutation'
 export { useInfiniteQuery } from './useInfiniteQuery'
 export { useIsRestoring, IsRestoringProvider } from './isRestoring'
+export { queryOptions } from './queryOptions'

package/src/queryOptions.ts

@@ -0,0 +1,86 @@
+import type {
+  InitialDataFunction,
+  NonUndefinedGuard,
+  OmitKeyof,
+  QueryKey,
+  WithRequired,
+} from '@tanstack/query-core'
+import type { UseQueryOptions } from './types'
+
+type UseQueryOptionsOmitted<
+  TQueryFnData = unknown,
+  TError = unknown,
+  TData = TQueryFnData,
+  TQueryKey extends QueryKey = QueryKey,
+> = OmitKeyof<
+  UseQueryOptions<TQueryFnData, TError, TData, TQueryKey>,
+  'onSuccess' | 'onError' | 'onSettled' | 'refetchInterval'
+>
+
+type ProhibitedQueryOptionsKeyInV5 = keyof Pick<
+  UseQueryOptionsOmitted,
+  'useErrorBoundary' | 'suspense' | 'getNextPageParam' | 'getPreviousPageParam'
+>
+
+export type UndefinedInitialDataOptions<
+  TQueryFnData = unknown,
+  TError = unknown,
+  TData = TQueryFnData,
+  TQueryKey extends QueryKey = QueryKey,
+> = UseQueryOptionsOmitted<TQueryFnData, TError, TData, TQueryKey> & {
+  initialData?:
+    | undefined
+    | InitialDataFunction<NonUndefinedGuard<TQueryFnData>>
+    | NonUndefinedGuard<TQueryFnData>
+}
+
+export type DefinedInitialDataOptions<
+  TQueryFnData = unknown,
+  TError = unknown,
+  TData = TQueryFnData,
+  TQueryKey extends QueryKey = QueryKey,
+> = UseQueryOptionsOmitted<TQueryFnData, TError, TData, TQueryKey> & {
+  initialData:
+    | NonUndefinedGuard<TQueryFnData>
+    | (() => NonUndefinedGuard<TQueryFnData>)
+}
+
+export function queryOptions<
+  TQueryFnData = unknown,
+  TError = unknown,
+  TData = TQueryFnData,
+  TQueryKey extends QueryKey = QueryKey,
+>(
+  options: WithRequired<
+    OmitKeyof<
+      DefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey>,
+      ProhibitedQueryOptionsKeyInV5
+    >,
+    'queryKey'
+  >,
+): WithRequired<
+  DefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey>,
+  'queryKey'
+>
+
+export function queryOptions<
+  TQueryFnData = unknown,
+  TError = unknown,
+  TData = TQueryFnData,
+  TQueryKey extends QueryKey = QueryKey,
+>(
+  options: WithRequired<
+    OmitKeyof<
+      UndefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey>,
+      ProhibitedQueryOptionsKeyInV5
+    >,
+    'queryKey'
+  >,
+): WithRequired<
+  UndefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey>,
+  'queryKey'
+>
+
+export function queryOptions(options: unknown) {
+  return options
+}

package/src/useQueries.ts

@@ -17,8 +17,12 @@ import {
   shouldSuspend,
   willFetch,
 } from './suspense'
-import type { QueryFunction, QueryKey } from '@tanstack/query-core'
-import type { UseQueryOptions, UseQueryResult } from './types'
+import type { OmitKeyof, QueryFunction, QueryKey } from '@tanstack/query-core'
+import type {
+  DefinedUseQueryResult,
+  UseQueryOptions,
+  UseQueryResult,
+} from './types'
 
 // This defines the `UseQueryOptions` that are accepted in `QueriesOptions` & `GetOptions`.
 // - `context` is omitted as it is passed as a root-level option to `useQueries` instead.
@@ -27,7 +31,10 @@ type UseQueryOptionsForUseQueries<
   TError = unknown,
   TData = TQueryFnData,
   TQueryKey extends QueryKey = QueryKey,
-> = Omit<UseQueryOptions<TQueryFnData, TError, TData, TQueryKey>, 'context'>
+> = OmitKeyof<
+  UseQueryOptions<TQueryFnData, TError, TData, TQueryKey>,
+  'context'
+>
 
 // Avoid TS depth-limit error in case of large array literal
 type MAXIMUM_DEPTH = 20
@@ -67,29 +74,46 @@ type GetOptions<T> =
     : // Fallback
       UseQueryOptionsForUseQueries
 
-type GetResults<T> =
+// A defined initialData setting should return a DefinedUseQueryResult rather than UseQueryResult
+type GetDefinedOrUndefinedQueryResult<T, TData, TError = unknown> = T extends {
+  initialData?: infer TInitialData
+}
+  ? unknown extends TInitialData
+    ? UseQueryResult<TData, TError>
+    : TInitialData extends TData
+    ? DefinedUseQueryResult<TData, TError>
+    : TInitialData extends () => infer TInitialDataResult
+    ? unknown extends TInitialDataResult
+      ? UseQueryResult<TData, TError>
+      : TInitialDataResult extends TData
+      ? DefinedUseQueryResult<TData, TError>
+      : UseQueryResult<TData, TError>
+    : UseQueryResult<TData, TError>
+  : UseQueryResult<TData, TError>
+
+type GetUseQueryResult<T> =
   // Part 1: responsible for mapping explicit type parameter to function result, if object
   T extends { queryFnData: any; error?: infer TError; data: infer TData }
-    ? UseQueryResult<TData, TError>
+    ? GetDefinedOrUndefinedQueryResult<T, TData, TError>
     : T extends { queryFnData: infer TQueryFnData; error?: infer TError }
-    ? UseQueryResult<TQueryFnData, TError>
+    ? GetDefinedOrUndefinedQueryResult<T, TQueryFnData, TError>
     : T extends { data: infer TData; error?: infer TError }
-    ? UseQueryResult<TData, TError>
+    ? GetDefinedOrUndefinedQueryResult<T, TData, TError>
     : // Part 2: responsible for mapping explicit type parameter to function result, if tuple
     T extends [any, infer TError, infer TData]
-    ? UseQueryResult<TData, TError>
+    ? GetDefinedOrUndefinedQueryResult<T, TData, TError>
     : T extends [infer TQueryFnData, infer TError]
-    ? UseQueryResult<TQueryFnData, TError>
+    ? GetDefinedOrUndefinedQueryResult<T, TQueryFnData, TError>
     : T extends [infer TQueryFnData]
-    ? UseQueryResult<TQueryFnData>
+    ? GetDefinedOrUndefinedQueryResult<T, 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
       }
-    ? UseQueryResult<TData>
+    ? GetDefinedOrUndefinedQueryResult<T, TData>
     : T extends { queryFn?: QueryFunction<infer TQueryFnData, any> }
-    ? UseQueryResult<TQueryFnData>
+    ? GetDefinedOrUndefinedQueryResult<T, TQueryFnData>
     : // Fallback
       UseQueryResult
 
@@ -98,16 +122,16 @@ type GetResults<T> =
  */
 export type QueriesOptions<
   T extends any[],
-  Result extends any[] = [],
-  Depth extends ReadonlyArray<number> = [],
-> = Depth['length'] extends MAXIMUM_DEPTH
+  TResult extends any[] = [],
+  TDepth extends ReadonlyArray<number> = [],
+> = TDepth['length'] extends MAXIMUM_DEPTH
   ? UseQueryOptionsForUseQueries[]
   : T extends []
   ? []
   : T extends [infer Head]
-  ? [...Result, GetOptions<Head>]
+  ? [...TResult, GetOptions<Head>]
   : T extends [infer Head, ...infer Tail]
-  ? QueriesOptions<[...Tail], [...Result, GetOptions<Head>], [...Depth, 1]>
+  ? QueriesOptions<[...Tail], [...TResult, GetOptions<Head>], [...TDepth, 1]>
   : 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!
@@ -127,16 +151,20 @@ export type QueriesOptions<
  */
 export type QueriesResults<
   T extends any[],
-  Result extends any[] = [],
-  Depth extends ReadonlyArray<number> = [],
-> = Depth['length'] extends MAXIMUM_DEPTH
+  TResults extends any[] = [],
+  TDepth extends ReadonlyArray<number> = [],
+> = TDepth['length'] extends MAXIMUM_DEPTH
   ? UseQueryResult[]
   : T extends []
   ? []
   : T extends [infer Head]
-  ? [...Result, GetResults<Head>]
+  ? [...TResults, GetUseQueryResult<Head>]
   : T extends [infer Head, ...infer Tail]
-  ? QueriesResults<[...Tail], [...Result, GetResults<Head>], [...Depth, 1]>
+  ? QueriesResults<
+      [...Tail],
+      [...TResults, GetUseQueryResult<Head>],
+      [...TDepth, 1]
+    >
   : T extends UseQueryOptionsForUseQueries<
       infer TQueryFnData,
       infer TError,

package/src/useQuery.ts

@@ -1,7 +1,17 @@
 'use client'
 import { QueryObserver, parseQueryArgs } from '@tanstack/query-core'
 import { useBaseQuery } from './useBaseQuery'
-import type { QueryFunction, QueryKey } from '@tanstack/query-core'
+import type {
+  DefinedInitialDataOptions,
+  UndefinedInitialDataOptions,
+} from './queryOptions'
+import type {
+  InitialDataFunction,
+  NonUndefinedGuard,
+  OmitKeyof,
+  QueryFunction,
+  QueryKey,
+} from '@tanstack/query-core'
 import type {
   DefinedUseQueryResult,
   UseQueryOptions,
@@ -9,31 +19,53 @@ import type {
 } from './types'
 
 // HOOK
-
 export function useQuery<
   TQueryFnData = unknown,
   TError = unknown,
   TData = TQueryFnData,
   TQueryKey extends QueryKey = QueryKey,
 >(
-  options: Omit<
+  options: DefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey>,
+): DefinedUseQueryResult<TData, TError>
+export function useQuery<
+  TQueryFnData = unknown,
+  TError = unknown,
+  TData = TQueryFnData,
+  TQueryKey extends QueryKey = QueryKey,
+>(
+  options: OmitKeyof<
     UseQueryOptions<TQueryFnData, TError, TData, TQueryKey>,
     'initialData'
-  > & { initialData?: () => undefined },
+  > & {
+    initialData:
+      | NonUndefinedGuard<TQueryFnData>
+      | (() => NonUndefinedGuard<TQueryFnData>)
+  },
+): DefinedUseQueryResult<TData, TError>
+export function useQuery<
+  TQueryFnData = unknown,
+  TError = unknown,
+  TData = TQueryFnData,
+  TQueryKey extends QueryKey = QueryKey,
+>(
+  options: UndefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey>,
 ): UseQueryResult<TData, TError>
-
 export function useQuery<
   TQueryFnData = unknown,
   TError = unknown,
   TData = TQueryFnData,
   TQueryKey extends QueryKey = QueryKey,
 >(
-  options: Omit<
+  options: OmitKeyof<
     UseQueryOptions<TQueryFnData, TError, TData, TQueryKey>,
     'initialData'
-  > & { initialData: TQueryFnData | (() => TQueryFnData) },
-): DefinedUseQueryResult<TData, TError>
-
+  > & {
+    initialData?:
+      | undefined
+      | InitialDataFunction<NonUndefinedGuard<TQueryFnData>>
+      | NonUndefinedGuard<TQueryFnData>
+  },
+): UseQueryResult<TData, TError>
 export function useQuery<
   TQueryFnData = unknown,
   TError = unknown,
@@ -43,6 +75,7 @@ export function useQuery<
   options: UseQueryOptions<TQueryFnData, TError, TData, TQueryKey>,
 ): UseQueryResult<TData, TError>
 
+/** @deprecated */
 export function useQuery<
   TQueryFnData = unknown,
   TError = unknown,
@@ -50,12 +83,12 @@ export function useQuery<
   TQueryKey extends QueryKey = QueryKey,
 >(
   queryKey: TQueryKey,
-  options?: Omit<
+  options?: OmitKeyof<
     UseQueryOptions<TQueryFnData, TError, TData, TQueryKey>,
     'queryKey' | 'initialData'
-  > & { initialData?: () => undefined },
+  >,
 ): UseQueryResult<TData, TError>
-
+/** @deprecated */
 export function useQuery<
   TQueryFnData = unknown,
   TError = unknown,
@@ -63,12 +96,12 @@ export function useQuery<
   TQueryKey extends QueryKey = QueryKey,
 >(
   queryKey: TQueryKey,
-  options?: Omit<
+  options?: OmitKeyof<
     UseQueryOptions<TQueryFnData, TError, TData, TQueryKey>,
     'queryKey' | 'initialData'
   > & { initialData: TQueryFnData | (() => TQueryFnData) },
 ): DefinedUseQueryResult<TData, TError>
-
+/** @deprecated */
 export function useQuery<
   TQueryFnData = unknown,
   TError = unknown,
@@ -76,12 +109,12 @@ export function useQuery<
   TQueryKey extends QueryKey = QueryKey,
 >(
   queryKey: TQueryKey,
-  options?: Omit<
+  options?: OmitKeyof<
     UseQueryOptions<TQueryFnData, TError, TData, TQueryKey>,
     'queryKey'
   >,
 ): UseQueryResult<TData, TError>
-
+/** @deprecated */
 export function useQuery<
   TQueryFnData = unknown,
   TError = unknown,
@@ -90,12 +123,12 @@ export function useQuery<
 >(
   queryKey: TQueryKey,
   queryFn: QueryFunction<TQueryFnData, TQueryKey>,
-  options?: Omit<
+  options?: OmitKeyof<
     UseQueryOptions<TQueryFnData, TError, TData, TQueryKey>,
     'queryKey' | 'queryFn' | 'initialData'
   > & { initialData?: () => undefined },
 ): UseQueryResult<TData, TError>
-
+/** @deprecated */
 export function useQuery<
   TQueryFnData = unknown,
   TError = unknown,
@@ -104,12 +137,12 @@ export function useQuery<
 >(
   queryKey: TQueryKey,
   queryFn: QueryFunction<TQueryFnData, TQueryKey>,
-  options?: Omit<
+  options?: OmitKeyof<
     UseQueryOptions<TQueryFnData, TError, TData, TQueryKey>,
     'queryKey' | 'queryFn' | 'initialData'
   > & { initialData: TQueryFnData | (() => TQueryFnData) },
 ): DefinedUseQueryResult<TData, TError>
-
+/** @deprecated */
 export function useQuery<
   TQueryFnData = unknown,
   TError = unknown,
@@ -118,12 +151,12 @@ export function useQuery<
 >(
   queryKey: TQueryKey,
   queryFn: QueryFunction<TQueryFnData, TQueryKey>,
-  options?: Omit<
+  options?: OmitKeyof<
     UseQueryOptions<TQueryFnData, TError, TData, TQueryKey>,
     'queryKey' | 'queryFn'
   >,
 ): UseQueryResult<TData, TError>
-
+/** @deprecated */
 export function useQuery<
   TQueryFnData,
   TError,