From 12652684b8ce416606713cd65bc9b781844ddb00 Mon Sep 17 00:00:00 2001 From: Wonsuk Choi Date: Tue, 22 Sep 2026 14:52:52 +0900 Subject: [PATCH 1/4] docs(react-query): correct inaccurate JSDoc statements --- .../react/reference/functions/queryOptions.md | 9 +++++---- .../framework/react/reference/functions/useQueries.md | 2 +- docs/framework/react/reference/functions/useQuery.md | 9 +++++---- .../react/reference/functions/useSuspenseQueries.md | 4 ++-- .../react/reference/interfaces/UseMutationOptions.md | 2 +- .../reference/type-aliases/AnyUseMutationOptions.md | 2 +- .../type-aliases/DefinedInitialDataInfiniteOptions.md | 2 +- .../type-aliases/DefinedUseInfiniteQueryResult.md | 7 ++++--- .../reference/type-aliases/DefinedUseQueryResult.md | 4 ++-- .../react/reference/type-aliases/QueriesOptions.md | 10 ++++++---- .../react/reference/type-aliases/QueriesResults.md | 2 +- .../reference/type-aliases/SuspenseQueriesOptions.md | 11 +++++++---- .../reference/type-aliases/SuspenseQueriesResults.md | 2 +- .../reference/type-aliases/UseBaseMutationResult.md | 2 +- .../reference/type-aliases/UseMutateAsyncFunction.md | 2 +- .../react/reference/type-aliases/UseMutateFunction.md | 2 +- .../react/reference/type-aliases/UseMutationResult.md | 2 +- .../type-aliases/UseSuspenseInfiniteQueryResult.md | 2 +- packages/react-query/src/infiniteQueryOptions.ts | 2 +- packages/react-query/src/queryOptions.ts | 3 ++- packages/react-query/src/types.ts | 9 +++++---- packages/react-query/src/useQueries.ts | 8 +++++--- packages/react-query/src/useQuery.ts | 3 ++- packages/react-query/src/useSuspenseQueries.ts | 9 ++++++--- 24 files changed, 63 insertions(+), 47 deletions(-) diff --git a/docs/framework/react/reference/functions/queryOptions.md b/docs/framework/react/reference/functions/queryOptions.md index 7885b4ac370..73d87d1f384 100644 --- a/docs/framework/react/reference/functions/queryOptions.md +++ b/docs/framework/react/reference/functions/queryOptions.md @@ -11,13 +11,14 @@ redirect_from: function queryOptions(options: DefinedInitialDataOptions): Omit, "queryFn"> & object & QueryKeyWithDataTag; ``` -Defined in: [packages/react-query/src/queryOptions.ts:142](https://github.com/TanStack/query/blob/main/packages/react-query/src/queryOptions.ts#L142) +Defined in: [packages/react-query/src/queryOptions.ts:143](https://github.com/TanStack/query/blob/main/packages/react-query/src/queryOptions.ts#L143) You can generally pass everything to `queryOptions` that you can also pass to `useQuery`. These options can be shared across hooks and imperative APIs such as `queryClient.query`. `options.queryKey` is required and is the query key to generate options for. -This overload is selected when `initialData` is set, so the resulting `data` is never `undefined`. +This overload is selected when `initialData` is set, so the resulting `data` is never `undefined` (unless +a `select` changes `TData` to include `undefined`). ### Type Parameters @@ -87,7 +88,7 @@ function Posts() { function queryOptions(options: UnusedSkipTokenOptions): OmitKeyof, "queryFn"> & object & QueryKeyWithDataTag; ``` -Defined in: [packages/react-query/src/queryOptions.ts:183](https://github.com/TanStack/query/blob/main/packages/react-query/src/queryOptions.ts#L183) +Defined in: [packages/react-query/src/queryOptions.ts:184](https://github.com/TanStack/query/blob/main/packages/react-query/src/queryOptions.ts#L184) You can generally pass everything to `queryOptions` that you can also pass to `useQuery`. These options can be shared across hooks and imperative APIs such as `queryClient.query`. `options.queryKey` is required and @@ -156,7 +157,7 @@ function Post({ id }: { id: string }) { function queryOptions(options: UndefinedInitialDataOptions): UseQueryOptions & object & QueryKeyWithDataTag; ``` -Defined in: [packages/react-query/src/queryOptions.ts:247](https://github.com/TanStack/query/blob/main/packages/react-query/src/queryOptions.ts#L247) +Defined in: [packages/react-query/src/queryOptions.ts:248](https://github.com/TanStack/query/blob/main/packages/react-query/src/queryOptions.ts#L248) You can generally pass everything to `queryOptions` that you can also pass to `useQuery`. These options can be shared across hooks and imperative APIs such as `queryClient.query`. `options.queryKey` is required and diff --git a/docs/framework/react/reference/functions/useQueries.md b/docs/framework/react/reference/functions/useQueries.md index 3bb87417446..b2aabae4532 100644 --- a/docs/framework/react/reference/functions/useQueries.md +++ b/docs/framework/react/reference/functions/useQueries.md @@ -9,7 +9,7 @@ redirect_from: function useQueries(__namedParameters: object, queryClient?: QueryClient): TCombinedResult; ``` -Defined in: [packages/react-query/src/useQueries.ts:355](https://github.com/TanStack/query/blob/main/packages/react-query/src/useQueries.ts#L355) +Defined in: [packages/react-query/src/useQueries.ts:357](https://github.com/TanStack/query/blob/main/packages/react-query/src/useQueries.ts#L357) The `useQueries` hook can be used to fetch a variable number of queries. diff --git a/docs/framework/react/reference/functions/useQuery.md b/docs/framework/react/reference/functions/useQuery.md index 5badc176158..c8fe48a009c 100644 --- a/docs/framework/react/reference/functions/useQuery.md +++ b/docs/framework/react/reference/functions/useQuery.md @@ -11,9 +11,10 @@ redirect_from: function useQuery(options: DefinedInitialDataOptions, queryClient?: QueryClient): DefinedUseQueryResult; ``` -Defined in: [packages/react-query/src/useQuery.ts:50](https://github.com/TanStack/query/blob/main/packages/react-query/src/useQuery.ts#L50) +Defined in: [packages/react-query/src/useQuery.ts:51](https://github.com/TanStack/query/blob/main/packages/react-query/src/useQuery.ts#L51) -This overload is selected when `initialData` is set, so the resulting `data` is never `undefined`. +This overload is selected when `initialData` is set, so the resulting `data` is never `undefined` (unless +a `select` changes `TData` to include `undefined`). ### Type Parameters @@ -91,7 +92,7 @@ function Posts() { function useQuery(options: UndefinedInitialDataOptions, queryClient?: QueryClient): UseQueryResult; ``` -Defined in: [packages/react-query/src/useQuery.ts:117](https://github.com/TanStack/query/blob/main/packages/react-query/src/useQuery.ts#L117) +Defined in: [packages/react-query/src/useQuery.ts:118](https://github.com/TanStack/query/blob/main/packages/react-query/src/useQuery.ts#L118) ### Type Parameters @@ -192,7 +193,7 @@ function Posts() { function useQuery(options: UseQueryOptions, queryClient?: QueryClient): UseQueryResult; ``` -Defined in: [packages/react-query/src/useQuery.ts:281](https://github.com/TanStack/query/blob/main/packages/react-query/src/useQuery.ts#L281) +Defined in: [packages/react-query/src/useQuery.ts:282](https://github.com/TanStack/query/blob/main/packages/react-query/src/useQuery.ts#L282) ### Type Parameters diff --git a/docs/framework/react/reference/functions/useSuspenseQueries.md b/docs/framework/react/reference/functions/useSuspenseQueries.md index 7ea5e75a48b..56e970c381a 100644 --- a/docs/framework/react/reference/functions/useSuspenseQueries.md +++ b/docs/framework/react/reference/functions/useSuspenseQueries.md @@ -11,7 +11,7 @@ redirect_from: function useSuspenseQueries(options: object, queryClient?: QueryClient): TCombinedResult; ``` -Defined in: [packages/react-query/src/useSuspenseQueries.ts:349](https://github.com/TanStack/query/blob/main/packages/react-query/src/useSuspenseQueries.ts#L349) +Defined in: [packages/react-query/src/useSuspenseQueries.ts:352](https://github.com/TanStack/query/blob/main/packages/react-query/src/useSuspenseQueries.ts#L352) The options for `useSuspenseQueries` are the same as for `useQueries`, except that the top-level `subscribed` option isn't supported, and each `query` can't have `throwOnError`, `enabled`, or `placeholderData`. @@ -221,7 +221,7 @@ function App() { function useSuspenseQueries(options: object, queryClient?: QueryClient): TCombinedResult; ``` -Defined in: [packages/react-query/src/useSuspenseQueries.ts:489](https://github.com/TanStack/query/blob/main/packages/react-query/src/useSuspenseQueries.ts#L489) +Defined in: [packages/react-query/src/useSuspenseQueries.ts:492](https://github.com/TanStack/query/blob/main/packages/react-query/src/useSuspenseQueries.ts#L492) The options for `useSuspenseQueries` are the same as for `useQueries`, except that the top-level `subscribed` option isn't supported, and each `query` can't have `throwOnError`, `enabled`, or `placeholderData`. diff --git a/docs/framework/react/reference/interfaces/UseMutationOptions.md b/docs/framework/react/reference/interfaces/UseMutationOptions.md index ab56dbfeb7c..e0728cb188a 100644 --- a/docs/framework/react/reference/interfaces/UseMutationOptions.md +++ b/docs/framework/react/reference/interfaces/UseMutationOptions.md @@ -3,7 +3,7 @@ id: UseMutationOptions title: UseMutationOptions --- -Defined in: [packages/react-query/src/types.ts:412](https://github.com/TanStack/query/blob/main/packages/react-query/src/types.ts#L412) +Defined in: [packages/react-query/src/types.ts:413](https://github.com/TanStack/query/blob/main/packages/react-query/src/types.ts#L413) The options accepted by `useMutation`. Same as [MutationObserverOptions](MutationObserverOptions.md) from `@tanstack/query-core`, minus the internal `_defaulted` flag. diff --git a/docs/framework/react/reference/type-aliases/AnyUseMutationOptions.md b/docs/framework/react/reference/type-aliases/AnyUseMutationOptions.md index 77e6c303e94..6c81f821e61 100644 --- a/docs/framework/react/reference/type-aliases/AnyUseMutationOptions.md +++ b/docs/framework/react/reference/type-aliases/AnyUseMutationOptions.md @@ -7,7 +7,7 @@ title: AnyUseMutationOptions type AnyUseMutationOptions = UseMutationOptions; ``` -Defined in: [packages/react-query/src/types.ts:401](https://github.com/TanStack/query/blob/main/packages/react-query/src/types.ts#L401) +Defined in: [packages/react-query/src/types.ts:402](https://github.com/TanStack/query/blob/main/packages/react-query/src/types.ts#L402) [UseMutationOptions](../interfaces/UseMutationOptions.md) with all type parameters set to `any`, useful when the specific types aren't relevant, e.g. when accepting options for any mutation in a helper function. diff --git a/docs/framework/react/reference/type-aliases/DefinedInitialDataInfiniteOptions.md b/docs/framework/react/reference/type-aliases/DefinedInitialDataInfiniteOptions.md index 9a70bff735c..4e7b21eb1fb 100644 --- a/docs/framework/react/reference/type-aliases/DefinedInitialDataInfiniteOptions.md +++ b/docs/framework/react/reference/type-aliases/DefinedInitialDataInfiniteOptions.md @@ -10,7 +10,7 @@ type DefinedInitialDataInfiniteOptions = DefinedInfiniteQueryObserverResult; ``` -Defined in: [packages/react-query/src/types.ts:377](https://github.com/TanStack/query/blob/main/packages/react-query/src/types.ts#L377) +Defined in: [packages/react-query/src/types.ts:378](https://github.com/TanStack/query/blob/main/packages/react-query/src/types.ts#L378) -The result of `useInfiniteQuery` when `initialData` is set — `data` is never `undefined`. Re-exports -[DefinedInfiniteQueryObserverResult](DefinedInfiniteQueryObserverResult.md) from `@tanstack/query-core`. +The result of `useInfiniteQuery` when `initialData` is set — `data` is never `undefined` (unless a +`select` changes `TData` to include `undefined`). Re-exports [DefinedInfiniteQueryObserverResult](DefinedInfiniteQueryObserverResult.md) +from `@tanstack/query-core`. ## Type Parameters diff --git a/docs/framework/react/reference/type-aliases/DefinedUseQueryResult.md b/docs/framework/react/reference/type-aliases/DefinedUseQueryResult.md index 5340c35d628..6533a575119 100644 --- a/docs/framework/react/reference/type-aliases/DefinedUseQueryResult.md +++ b/docs/framework/react/reference/type-aliases/DefinedUseQueryResult.md @@ -10,8 +10,8 @@ type DefinedUseQueryResult = DefinedQueryObserverResult = TDepth["length"] extends MAXIMUM_DEPTH ? UseQueryOptionsForUseQueries[] : T extends [] ? [] : T extends [infer Head] ? [...TResults, GetUseQueryOptionsForUseQueries] : T extends [infer Head, ...(infer Tails)] ? QueriesOptions<[...Tails], [...TResults, GetUseQueryOptionsForUseQueries], [...TDepth, 1]> : ReadonlyArray extends T ? T : T extends UseQueryOptionsForUseQueries[] ? UseQueryOptionsForUseQueries[] : UseQueryOptionsForUseQueries[]; ``` -Defined in: [packages/react-query/src/useQueries.ts:156](https://github.com/TanStack/query/blob/main/packages/react-query/src/useQueries.ts#L156) +Defined in: [packages/react-query/src/useQueries.ts:158](https://github.com/TanStack/query/blob/main/packages/react-query/src/useQueries.ts#L158) The `queries` array accepted by `useQueries`. Recursively unwraps each tuple element so every entry's -`queryFn`/`select`/`throwOnError` are inferred individually, up to 20 elements. An opaque array (e.g. -`unknown[]`) is returned as-is; a non-tuple array of a known element type, or a tuple past 20 elements, falls -back to a single homogeneous options type. +`queryFn`/`select`/`throwOnError` are inferred individually, up to 20 elements — past that, a tuple falls +back to a single homogeneous options type. An opaque array (e.g. `unknown[]`) is returned as-is; a +non-tuple array whose element type structurally matches a query options object is mapped per-element +instead, still inferring each entry individually; any other non-tuple array — one whose element type +doesn't match the expected options shape — falls back to that same homogeneous options type too. ## Type Parameters diff --git a/docs/framework/react/reference/type-aliases/QueriesResults.md b/docs/framework/react/reference/type-aliases/QueriesResults.md index 4742d4045bc..57f19a66627 100644 --- a/docs/framework/react/reference/type-aliases/QueriesResults.md +++ b/docs/framework/react/reference/type-aliases/QueriesResults.md @@ -7,7 +7,7 @@ title: QueriesResults type QueriesResults = TDepth["length"] extends MAXIMUM_DEPTH ? UseQueryResult[] : T extends [] ? [] : T extends [infer Head] ? [...TResults, GetUseQueryResult] : T extends [infer Head, ...(infer Tails)] ? QueriesResults<[...Tails], [...TResults, GetUseQueryResult], [...TDepth, 1]> : { [K in keyof T]: GetUseQueryResult }; ``` -Defined in: [packages/react-query/src/useQueries.ts:207](https://github.com/TanStack/query/blob/main/packages/react-query/src/useQueries.ts#L207) +Defined in: [packages/react-query/src/useQueries.ts:209](https://github.com/TanStack/query/blob/main/packages/react-query/src/useQueries.ts#L209) The result type returned by `useQueries`, when no `combine` is provided. Mirrors [QueriesOptions](QueriesOptions.md): each tuple element's result type is inferred individually, up to 20 elements. A non-tuple array is mapped diff --git a/docs/framework/react/reference/type-aliases/SuspenseQueriesOptions.md b/docs/framework/react/reference/type-aliases/SuspenseQueriesOptions.md index e63aa2563b8..1459b69e1bf 100644 --- a/docs/framework/react/reference/type-aliases/SuspenseQueriesOptions.md +++ b/docs/framework/react/reference/type-aliases/SuspenseQueriesOptions.md @@ -7,12 +7,15 @@ title: SuspenseQueriesOptions type SuspenseQueriesOptions = TDepth["length"] extends MAXIMUM_DEPTH ? UseSuspenseQueryOptions[] : T extends [] ? [] : T extends [infer Head] ? [...TResults, GetUseSuspenseQueryOptions] : T extends [infer Head, ...(infer Tails)] ? SuspenseQueriesOptions<[...Tails], [...TResults, GetUseSuspenseQueryOptions], [...TDepth, 1]> : unknown[] extends T ? T : T extends UseSuspenseQueryOptions[] ? UseSuspenseQueryOptions[] : UseSuspenseQueryOptions[]; ``` -Defined in: [packages/react-query/src/useSuspenseQueries.ts:119](https://github.com/TanStack/query/blob/main/packages/react-query/src/useSuspenseQueries.ts#L119) +Defined in: [packages/react-query/src/useSuspenseQueries.ts:122](https://github.com/TanStack/query/blob/main/packages/react-query/src/useSuspenseQueries.ts#L122) The `queries` array accepted by `useSuspenseQueries`. Recursively unwraps each tuple element so every -entry's `queryFn`/`select` are inferred individually, up to 20 elements. An opaque array (e.g. `unknown[]`) -is returned as-is; a non-tuple array of a known element type, or a tuple past 20 elements, falls back to a -single homogeneous [UseSuspenseQueryOptions](../interfaces/UseSuspenseQueryOptions.md) type. +entry's `queryFn`/`select` are inferred individually, up to 20 elements — past that, a tuple falls back to +a single homogeneous [UseSuspenseQueryOptions](../interfaces/UseSuspenseQueryOptions.md) type. An opaque array (e.g. `unknown[]`) is returned +as-is; a non-tuple array whose element type structurally matches a query options object is mapped +per-element instead, still inferring each entry individually; any other non-tuple array — one whose +element type doesn't match the expected options shape — falls back to that same homogeneous options type +too. ## Type Parameters diff --git a/docs/framework/react/reference/type-aliases/SuspenseQueriesResults.md b/docs/framework/react/reference/type-aliases/SuspenseQueriesResults.md index f1c2d32eca0..f8132fcefaf 100644 --- a/docs/framework/react/reference/type-aliases/SuspenseQueriesResults.md +++ b/docs/framework/react/reference/type-aliases/SuspenseQueriesResults.md @@ -7,7 +7,7 @@ title: SuspenseQueriesResults type SuspenseQueriesResults = TDepth["length"] extends MAXIMUM_DEPTH ? UseSuspenseQueryResult[] : T extends [] ? [] : T extends [infer Head] ? [...TResults, GetUseSuspenseQueryResult] : T extends [infer Head, ...(infer Tails)] ? SuspenseQueriesResults<[...Tails], [...TResults, GetUseSuspenseQueryResult], [...TDepth, 1]> : { [K in keyof T]: GetUseSuspenseQueryResult }; ``` -Defined in: [packages/react-query/src/useSuspenseQueries.ts:165](https://github.com/TanStack/query/blob/main/packages/react-query/src/useSuspenseQueries.ts#L165) +Defined in: [packages/react-query/src/useSuspenseQueries.ts:168](https://github.com/TanStack/query/blob/main/packages/react-query/src/useSuspenseQueries.ts#L168) The result type returned by `useSuspenseQueries`, when no `combine` is provided. Mirrors [SuspenseQueriesOptions](SuspenseQueriesOptions.md): each tuple element's result type is inferred individually, up to 20 elements. diff --git a/docs/framework/react/reference/type-aliases/UseBaseMutationResult.md b/docs/framework/react/reference/type-aliases/UseBaseMutationResult.md index 86d821ea070..e0f10c5100a 100644 --- a/docs/framework/react/reference/type-aliases/UseBaseMutationResult.md +++ b/docs/framework/react/reference/type-aliases/UseBaseMutationResult.md @@ -9,7 +9,7 @@ type UseBaseMutationResult = Overrid }> & object; ``` -Defined in: [packages/react-query/src/types.ts:471](https://github.com/TanStack/query/blob/main/packages/react-query/src/types.ts#L471) +Defined in: [packages/react-query/src/types.ts:472](https://github.com/TanStack/query/blob/main/packages/react-query/src/types.ts#L472) The result of `useMutation`. Same as [MutationObserverResult](MutationObserverResult.md) from `@tanstack/query-core`, with `mutate` narrowed to the fire-and-forget [UseMutateFunction](UseMutateFunction.md) signature, plus the added `mutateAsync`. diff --git a/docs/framework/react/reference/type-aliases/UseMutateAsyncFunction.md b/docs/framework/react/reference/type-aliases/UseMutateAsyncFunction.md index 3cedcd5ea1f..938e1abec45 100644 --- a/docs/framework/react/reference/type-aliases/UseMutateAsyncFunction.md +++ b/docs/framework/react/reference/type-aliases/UseMutateAsyncFunction.md @@ -7,7 +7,7 @@ title: UseMutateAsyncFunction type UseMutateAsyncFunction = MutateFunction; ``` -Defined in: [packages/react-query/src/types.ts:454](https://github.com/TanStack/query/blob/main/packages/react-query/src/types.ts#L454) +Defined in: [packages/react-query/src/types.ts:455](https://github.com/TanStack/query/blob/main/packages/react-query/src/types.ts#L455) The type of `mutateAsync`, as returned by `useMutation`. Similar to [UseMutateFunction](UseMutateFunction.md), but returns a promise which can be awaited. diff --git a/docs/framework/react/reference/type-aliases/UseMutateFunction.md b/docs/framework/react/reference/type-aliases/UseMutateFunction.md index b095bf61e32..77c533b612e 100644 --- a/docs/framework/react/reference/type-aliases/UseMutateFunction.md +++ b/docs/framework/react/reference/type-aliases/UseMutateFunction.md @@ -7,7 +7,7 @@ title: UseMutateFunction type UseMutateFunction = (...args: Parameters>) => void; ``` -Defined in: [packages/react-query/src/types.ts:433](https://github.com/TanStack/query/blob/main/packages/react-query/src/types.ts#L433) +Defined in: [packages/react-query/src/types.ts:434](https://github.com/TanStack/query/blob/main/packages/react-query/src/types.ts#L434) The type of `mutate`, as returned by `useMutation`. Forwards the variables (and an optional per-call `onSuccess`/`onError`/`onSettled`) to the underlying `mutate` call. Fire-and-forget — errors are surfaced diff --git a/docs/framework/react/reference/type-aliases/UseMutationResult.md b/docs/framework/react/reference/type-aliases/UseMutationResult.md index 5eed68d0161..f40e5086592 100644 --- a/docs/framework/react/reference/type-aliases/UseMutationResult.md +++ b/docs/framework/react/reference/type-aliases/UseMutationResult.md @@ -7,7 +7,7 @@ title: UseMutationResult type UseMutationResult = UseBaseMutationResult; ``` -Defined in: [packages/react-query/src/types.ts:500](https://github.com/TanStack/query/blob/main/packages/react-query/src/types.ts#L500) +Defined in: [packages/react-query/src/types.ts:501](https://github.com/TanStack/query/blob/main/packages/react-query/src/types.ts#L501) The result of `useMutation`. Same as [UseBaseMutationResult](UseBaseMutationResult.md). diff --git a/docs/framework/react/reference/type-aliases/UseSuspenseInfiniteQueryResult.md b/docs/framework/react/reference/type-aliases/UseSuspenseInfiniteQueryResult.md index eda0d8b290e..fe3dab7a752 100644 --- a/docs/framework/react/reference/type-aliases/UseSuspenseInfiniteQueryResult.md +++ b/docs/framework/react/reference/type-aliases/UseSuspenseInfiniteQueryResult.md @@ -7,7 +7,7 @@ title: UseSuspenseInfiniteQueryResult type UseSuspenseInfiniteQueryResult = OmitKeyof, "isPlaceholderData">; ``` -Defined in: [packages/react-query/src/types.ts:389](https://github.com/TanStack/query/blob/main/packages/react-query/src/types.ts#L389) +Defined in: [packages/react-query/src/types.ts:390](https://github.com/TanStack/query/blob/main/packages/react-query/src/types.ts#L390) The result of `useSuspenseInfiniteQuery`. Same as [DefinedUseInfiniteQueryResult](DefinedUseInfiniteQueryResult.md), minus `isPlaceholderData` — Suspense hooks never render placeholder data. diff --git a/packages/react-query/src/infiniteQueryOptions.ts b/packages/react-query/src/infiniteQueryOptions.ts index 10898979d7b..27eb8d7945f 100644 --- a/packages/react-query/src/infiniteQueryOptions.ts +++ b/packages/react-query/src/infiniteQueryOptions.ts @@ -91,7 +91,7 @@ export type UnusedSkipTokenInfiniteOptions< /** * The options accepted by the `infiniteQueryOptions` overload selected when `initialData` is set — `data` is - * never `undefined`. + * never `undefined` (unless a `select` changes `TData` to include `undefined`). * * @template TQueryFnData - The type of a single page, as your `queryFn` resolves it. * @template TError - The type of errors your `queryFn` may throw. diff --git a/packages/react-query/src/queryOptions.ts b/packages/react-query/src/queryOptions.ts index aa824b7389b..ffed03fe461 100644 --- a/packages/react-query/src/queryOptions.ts +++ b/packages/react-query/src/queryOptions.ts @@ -106,7 +106,8 @@ export type DefinedInitialDataOptions< * be shared across hooks and imperative APIs such as `queryClient.query`. `options.queryKey` is required and * is the query key to generate options for. * - * This overload is selected when `initialData` is set, so the resulting `data` is never `undefined`. + * This overload is selected when `initialData` is set, so the resulting `data` is never `undefined` (unless + * a `select` changes `TData` to include `undefined`). * * @see {@link useQuery} to run a query with these options. * @see [The Query Options API](https://tkdodo.eu/blog/the-query-options-api) for more on this pattern. diff --git a/packages/react-query/src/types.ts b/packages/react-query/src/types.ts index 15eb826709e..4e5ff6bac6b 100644 --- a/packages/react-query/src/types.ts +++ b/packages/react-query/src/types.ts @@ -344,8 +344,8 @@ export type UseSuspenseQueryResult< /** * The result of `useQuery` when `initialData` is set, or of `useSuspenseQuery` before the `isPlaceholderData` - * omission — `data` is never `undefined`. Re-exports {@link DefinedQueryObserverResult} from - * `@tanstack/query-core`. + * omission — `data` is never `undefined` (unless a `select` changes `TData` to include `undefined`). + * Re-exports {@link DefinedQueryObserverResult} from `@tanstack/query-core`. * * @template TData - The type `data` ends up as after `select` runs. * @template TError - The type of errors your `queryFn` may throw. @@ -368,8 +368,9 @@ export type UseInfiniteQueryResult< > = InfiniteQueryObserverResult /** - * The result of `useInfiniteQuery` when `initialData` is set — `data` is never `undefined`. Re-exports - * {@link DefinedInfiniteQueryObserverResult} from `@tanstack/query-core`. + * The result of `useInfiniteQuery` when `initialData` is set — `data` is never `undefined` (unless a + * `select` changes `TData` to include `undefined`). Re-exports {@link DefinedInfiniteQueryObserverResult} + * from `@tanstack/query-core`. * * @template TData - The type `data` ends up as after `select` runs. * @template TError - The type of errors your `queryFn` may throw. diff --git a/packages/react-query/src/useQueries.ts b/packages/react-query/src/useQueries.ts index e77ca05ed4b..6c320296fb6 100644 --- a/packages/react-query/src/useQueries.ts +++ b/packages/react-query/src/useQueries.ts @@ -143,9 +143,11 @@ type GetUseQueryResult = /** * The `queries` array accepted by `useQueries`. Recursively unwraps each tuple element so every entry's - * `queryFn`/`select`/`throwOnError` are inferred individually, up to 20 elements. An opaque array (e.g. - * `unknown[]`) is returned as-is; a non-tuple array of a known element type, or a tuple past 20 elements, falls - * back to a single homogeneous options type. + * `queryFn`/`select`/`throwOnError` are inferred individually, up to 20 elements — past that, a tuple falls + * back to a single homogeneous options type. An opaque array (e.g. `unknown[]`) is returned as-is; a + * non-tuple array whose element type structurally matches a query options object is mapped per-element + * instead, still inferring each entry individually; any other non-tuple array — one whose element type + * doesn't match the expected options shape — falls back to that same homogeneous options type too. * * @template T - The type of the `queries` array as written at the call site. * @template TResults - The internal accumulator that this type builds during recursion. It is not meant diff --git a/packages/react-query/src/useQuery.ts b/packages/react-query/src/useQuery.ts index b67acc8604b..d14c6497bbf 100644 --- a/packages/react-query/src/useQuery.ts +++ b/packages/react-query/src/useQuery.ts @@ -13,7 +13,8 @@ import type { } from './queryOptions' /** - * This overload is selected when `initialData` is set, so the resulting `data` is never `undefined`. + * This overload is selected when `initialData` is set, so the resulting `data` is never `undefined` (unless + * a `select` changes `TData` to include `undefined`). * * @see {@link queryOptions} to share these options between `useQuery` and imperative APIs like `queryClient.query`. * @param options - The {@link DefinedInitialDataOptions} to use — everything you can pass to `useQuery`, with `initialData` set. diff --git a/packages/react-query/src/useSuspenseQueries.ts b/packages/react-query/src/useSuspenseQueries.ts index b13daaf02b3..e871f75f407 100644 --- a/packages/react-query/src/useSuspenseQueries.ts +++ b/packages/react-query/src/useSuspenseQueries.ts @@ -106,9 +106,12 @@ type GetUseSuspenseQueryResult = /** * The `queries` array accepted by `useSuspenseQueries`. Recursively unwraps each tuple element so every - * entry's `queryFn`/`select` are inferred individually, up to 20 elements. An opaque array (e.g. `unknown[]`) - * is returned as-is; a non-tuple array of a known element type, or a tuple past 20 elements, falls back to a - * single homogeneous {@link UseSuspenseQueryOptions} type. + * entry's `queryFn`/`select` are inferred individually, up to 20 elements — past that, a tuple falls back to + * a single homogeneous {@link UseSuspenseQueryOptions} type. An opaque array (e.g. `unknown[]`) is returned + * as-is; a non-tuple array whose element type structurally matches a query options object is mapped + * per-element instead, still inferring each entry individually; any other non-tuple array — one whose + * element type doesn't match the expected options shape — falls back to that same homogeneous options type + * too. * * @template T - The type of the `queries` array as written at the call site. * @template TResults - The internal accumulator that this type builds during recursion. It is not meant From 7cfc7243eb00537ac9b0c875c6cd2d1266447f04 Mon Sep 17 00:00:00 2001 From: Wonsuk Choi Date: Tue, 22 Sep 2026 14:54:51 +0900 Subject: [PATCH 2/4] docs(react-query): split QueriesOptions/SuspenseQueriesOptions JSDoc into paragraphs --- .../react/reference/functions/useQueries.md | 2 +- .../react/reference/functions/useSuspenseQueries.md | 4 ++-- .../react/reference/type-aliases/QueriesOptions.md | 12 +++++++----- .../react/reference/type-aliases/QueriesResults.md | 2 +- .../type-aliases/SuspenseQueriesOptions.md | 13 +++++++------ .../type-aliases/SuspenseQueriesResults.md | 2 +- packages/react-query/src/useQueries.ts | 10 ++++++---- packages/react-query/src/useSuspenseQueries.ts | 11 ++++++----- 8 files changed, 31 insertions(+), 25 deletions(-) diff --git a/docs/framework/react/reference/functions/useQueries.md b/docs/framework/react/reference/functions/useQueries.md index b2aabae4532..61db7461507 100644 --- a/docs/framework/react/reference/functions/useQueries.md +++ b/docs/framework/react/reference/functions/useQueries.md @@ -9,7 +9,7 @@ redirect_from: function useQueries(__namedParameters: object, queryClient?: QueryClient): TCombinedResult; ``` -Defined in: [packages/react-query/src/useQueries.ts:357](https://github.com/TanStack/query/blob/main/packages/react-query/src/useQueries.ts#L357) +Defined in: [packages/react-query/src/useQueries.ts:359](https://github.com/TanStack/query/blob/main/packages/react-query/src/useQueries.ts#L359) The `useQueries` hook can be used to fetch a variable number of queries. diff --git a/docs/framework/react/reference/functions/useSuspenseQueries.md b/docs/framework/react/reference/functions/useSuspenseQueries.md index 56e970c381a..ceee7bdf046 100644 --- a/docs/framework/react/reference/functions/useSuspenseQueries.md +++ b/docs/framework/react/reference/functions/useSuspenseQueries.md @@ -11,7 +11,7 @@ redirect_from: function useSuspenseQueries(options: object, queryClient?: QueryClient): TCombinedResult; ``` -Defined in: [packages/react-query/src/useSuspenseQueries.ts:352](https://github.com/TanStack/query/blob/main/packages/react-query/src/useSuspenseQueries.ts#L352) +Defined in: [packages/react-query/src/useSuspenseQueries.ts:353](https://github.com/TanStack/query/blob/main/packages/react-query/src/useSuspenseQueries.ts#L353) The options for `useSuspenseQueries` are the same as for `useQueries`, except that the top-level `subscribed` option isn't supported, and each `query` can't have `throwOnError`, `enabled`, or `placeholderData`. @@ -221,7 +221,7 @@ function App() { function useSuspenseQueries(options: object, queryClient?: QueryClient): TCombinedResult; ``` -Defined in: [packages/react-query/src/useSuspenseQueries.ts:492](https://github.com/TanStack/query/blob/main/packages/react-query/src/useSuspenseQueries.ts#L492) +Defined in: [packages/react-query/src/useSuspenseQueries.ts:493](https://github.com/TanStack/query/blob/main/packages/react-query/src/useSuspenseQueries.ts#L493) The options for `useSuspenseQueries` are the same as for `useQueries`, except that the top-level `subscribed` option isn't supported, and each `query` can't have `throwOnError`, `enabled`, or `placeholderData`. diff --git a/docs/framework/react/reference/type-aliases/QueriesOptions.md b/docs/framework/react/reference/type-aliases/QueriesOptions.md index 49296eec078..0db84a3ec0b 100644 --- a/docs/framework/react/reference/type-aliases/QueriesOptions.md +++ b/docs/framework/react/reference/type-aliases/QueriesOptions.md @@ -7,14 +7,16 @@ title: QueriesOptions type QueriesOptions = TDepth["length"] extends MAXIMUM_DEPTH ? UseQueryOptionsForUseQueries[] : T extends [] ? [] : T extends [infer Head] ? [...TResults, GetUseQueryOptionsForUseQueries] : T extends [infer Head, ...(infer Tails)] ? QueriesOptions<[...Tails], [...TResults, GetUseQueryOptionsForUseQueries], [...TDepth, 1]> : ReadonlyArray extends T ? T : T extends UseQueryOptionsForUseQueries[] ? UseQueryOptionsForUseQueries[] : UseQueryOptionsForUseQueries[]; ``` -Defined in: [packages/react-query/src/useQueries.ts:158](https://github.com/TanStack/query/blob/main/packages/react-query/src/useQueries.ts#L158) +Defined in: [packages/react-query/src/useQueries.ts:160](https://github.com/TanStack/query/blob/main/packages/react-query/src/useQueries.ts#L160) The `queries` array accepted by `useQueries`. Recursively unwraps each tuple element so every entry's `queryFn`/`select`/`throwOnError` are inferred individually, up to 20 elements — past that, a tuple falls -back to a single homogeneous options type. An opaque array (e.g. `unknown[]`) is returned as-is; a -non-tuple array whose element type structurally matches a query options object is mapped per-element -instead, still inferring each entry individually; any other non-tuple array — one whose element type -doesn't match the expected options shape — falls back to that same homogeneous options type too. +back to a single homogeneous options type. + +An opaque array (e.g. `unknown[]`) is returned as-is; a non-tuple array whose element type structurally +matches a query options object is mapped per-element instead, still inferring each entry individually; any +other non-tuple array — one whose element type doesn't match the expected options shape — falls back to +that same homogeneous options type too. ## Type Parameters diff --git a/docs/framework/react/reference/type-aliases/QueriesResults.md b/docs/framework/react/reference/type-aliases/QueriesResults.md index 57f19a66627..44410d3533b 100644 --- a/docs/framework/react/reference/type-aliases/QueriesResults.md +++ b/docs/framework/react/reference/type-aliases/QueriesResults.md @@ -7,7 +7,7 @@ title: QueriesResults type QueriesResults = TDepth["length"] extends MAXIMUM_DEPTH ? UseQueryResult[] : T extends [] ? [] : T extends [infer Head] ? [...TResults, GetUseQueryResult] : T extends [infer Head, ...(infer Tails)] ? QueriesResults<[...Tails], [...TResults, GetUseQueryResult], [...TDepth, 1]> : { [K in keyof T]: GetUseQueryResult }; ``` -Defined in: [packages/react-query/src/useQueries.ts:209](https://github.com/TanStack/query/blob/main/packages/react-query/src/useQueries.ts#L209) +Defined in: [packages/react-query/src/useQueries.ts:211](https://github.com/TanStack/query/blob/main/packages/react-query/src/useQueries.ts#L211) The result type returned by `useQueries`, when no `combine` is provided. Mirrors [QueriesOptions](QueriesOptions.md): each tuple element's result type is inferred individually, up to 20 elements. A non-tuple array is mapped diff --git a/docs/framework/react/reference/type-aliases/SuspenseQueriesOptions.md b/docs/framework/react/reference/type-aliases/SuspenseQueriesOptions.md index 1459b69e1bf..3953b3df4a2 100644 --- a/docs/framework/react/reference/type-aliases/SuspenseQueriesOptions.md +++ b/docs/framework/react/reference/type-aliases/SuspenseQueriesOptions.md @@ -7,15 +7,16 @@ title: SuspenseQueriesOptions type SuspenseQueriesOptions = TDepth["length"] extends MAXIMUM_DEPTH ? UseSuspenseQueryOptions[] : T extends [] ? [] : T extends [infer Head] ? [...TResults, GetUseSuspenseQueryOptions] : T extends [infer Head, ...(infer Tails)] ? SuspenseQueriesOptions<[...Tails], [...TResults, GetUseSuspenseQueryOptions], [...TDepth, 1]> : unknown[] extends T ? T : T extends UseSuspenseQueryOptions[] ? UseSuspenseQueryOptions[] : UseSuspenseQueryOptions[]; ``` -Defined in: [packages/react-query/src/useSuspenseQueries.ts:122](https://github.com/TanStack/query/blob/main/packages/react-query/src/useSuspenseQueries.ts#L122) +Defined in: [packages/react-query/src/useSuspenseQueries.ts:123](https://github.com/TanStack/query/blob/main/packages/react-query/src/useSuspenseQueries.ts#L123) The `queries` array accepted by `useSuspenseQueries`. Recursively unwraps each tuple element so every entry's `queryFn`/`select` are inferred individually, up to 20 elements — past that, a tuple falls back to -a single homogeneous [UseSuspenseQueryOptions](../interfaces/UseSuspenseQueryOptions.md) type. An opaque array (e.g. `unknown[]`) is returned -as-is; a non-tuple array whose element type structurally matches a query options object is mapped -per-element instead, still inferring each entry individually; any other non-tuple array — one whose -element type doesn't match the expected options shape — falls back to that same homogeneous options type -too. +a single homogeneous [UseSuspenseQueryOptions](../interfaces/UseSuspenseQueryOptions.md) type. + +An opaque array (e.g. `unknown[]`) is returned as-is; a non-tuple array whose element type structurally +matches a query options object is mapped per-element instead, still inferring each entry individually; any +other non-tuple array — one whose element type doesn't match the expected options shape — falls back to +that same homogeneous options type too. ## Type Parameters diff --git a/docs/framework/react/reference/type-aliases/SuspenseQueriesResults.md b/docs/framework/react/reference/type-aliases/SuspenseQueriesResults.md index f8132fcefaf..6025e7913ba 100644 --- a/docs/framework/react/reference/type-aliases/SuspenseQueriesResults.md +++ b/docs/framework/react/reference/type-aliases/SuspenseQueriesResults.md @@ -7,7 +7,7 @@ title: SuspenseQueriesResults type SuspenseQueriesResults = TDepth["length"] extends MAXIMUM_DEPTH ? UseSuspenseQueryResult[] : T extends [] ? [] : T extends [infer Head] ? [...TResults, GetUseSuspenseQueryResult] : T extends [infer Head, ...(infer Tails)] ? SuspenseQueriesResults<[...Tails], [...TResults, GetUseSuspenseQueryResult], [...TDepth, 1]> : { [K in keyof T]: GetUseSuspenseQueryResult }; ``` -Defined in: [packages/react-query/src/useSuspenseQueries.ts:168](https://github.com/TanStack/query/blob/main/packages/react-query/src/useSuspenseQueries.ts#L168) +Defined in: [packages/react-query/src/useSuspenseQueries.ts:169](https://github.com/TanStack/query/blob/main/packages/react-query/src/useSuspenseQueries.ts#L169) The result type returned by `useSuspenseQueries`, when no `combine` is provided. Mirrors [SuspenseQueriesOptions](SuspenseQueriesOptions.md): each tuple element's result type is inferred individually, up to 20 elements. diff --git a/packages/react-query/src/useQueries.ts b/packages/react-query/src/useQueries.ts index 6c320296fb6..0c7b9d8d8ba 100644 --- a/packages/react-query/src/useQueries.ts +++ b/packages/react-query/src/useQueries.ts @@ -144,10 +144,12 @@ type GetUseQueryResult = /** * The `queries` array accepted by `useQueries`. Recursively unwraps each tuple element so every entry's * `queryFn`/`select`/`throwOnError` are inferred individually, up to 20 elements — past that, a tuple falls - * back to a single homogeneous options type. An opaque array (e.g. `unknown[]`) is returned as-is; a - * non-tuple array whose element type structurally matches a query options object is mapped per-element - * instead, still inferring each entry individually; any other non-tuple array — one whose element type - * doesn't match the expected options shape — falls back to that same homogeneous options type too. + * back to a single homogeneous options type. + * + * An opaque array (e.g. `unknown[]`) is returned as-is; a non-tuple array whose element type structurally + * matches a query options object is mapped per-element instead, still inferring each entry individually; any + * other non-tuple array — one whose element type doesn't match the expected options shape — falls back to + * that same homogeneous options type too. * * @template T - The type of the `queries` array as written at the call site. * @template TResults - The internal accumulator that this type builds during recursion. It is not meant diff --git a/packages/react-query/src/useSuspenseQueries.ts b/packages/react-query/src/useSuspenseQueries.ts index e871f75f407..cc6564f0cda 100644 --- a/packages/react-query/src/useSuspenseQueries.ts +++ b/packages/react-query/src/useSuspenseQueries.ts @@ -107,11 +107,12 @@ type GetUseSuspenseQueryResult = /** * The `queries` array accepted by `useSuspenseQueries`. Recursively unwraps each tuple element so every * entry's `queryFn`/`select` are inferred individually, up to 20 elements — past that, a tuple falls back to - * a single homogeneous {@link UseSuspenseQueryOptions} type. An opaque array (e.g. `unknown[]`) is returned - * as-is; a non-tuple array whose element type structurally matches a query options object is mapped - * per-element instead, still inferring each entry individually; any other non-tuple array — one whose - * element type doesn't match the expected options shape — falls back to that same homogeneous options type - * too. + * a single homogeneous {@link UseSuspenseQueryOptions} type. + * + * An opaque array (e.g. `unknown[]`) is returned as-is; a non-tuple array whose element type structurally + * matches a query options object is mapped per-element instead, still inferring each entry individually; any + * other non-tuple array — one whose element type doesn't match the expected options shape — falls back to + * that same homogeneous options type too. * * @template T - The type of the `queries` array as written at the call site. * @template TResults - The internal accumulator that this type builds during recursion. It is not meant From d5a764d1af42b4231f7acf6e81c3772195426fdc Mon Sep 17 00:00:00 2001 From: Wonsuk Choi Date: Tue, 22 Sep 2026 14:58:58 +0900 Subject: [PATCH 3/4] docs(preact-query): correct 'initialData'/'select' and 'QueriesOptions' fallback JSDoc inaccuracies --- .../preact/reference/functions/queryOptions.md | 9 +++++---- .../preact/reference/functions/useQueries.md | 2 +- .../framework/preact/reference/functions/useQuery.md | 9 +++++---- .../preact/reference/functions/useSuspenseQueries.md | 4 ++-- .../reference/interfaces/UseMutationOptions.md | 2 +- .../reference/type-aliases/AnyUseMutationOptions.md | 2 +- .../DefinedInitialDataInfiniteOptions.md | 2 +- .../type-aliases/DefinedUseInfiniteQueryResult.md | 7 ++++--- .../reference/type-aliases/DefinedUseQueryResult.md | 4 ++-- .../preact/reference/type-aliases/QueriesOptions.md | 10 +++++++--- .../preact/reference/type-aliases/QueriesResults.md | 2 +- .../reference/type-aliases/SuspenseQueriesOptions.md | 12 ++++++++---- .../reference/type-aliases/SuspenseQueriesResults.md | 2 +- .../reference/type-aliases/UseBaseMutationResult.md | 2 +- .../reference/type-aliases/UseMutateAsyncFunction.md | 2 +- .../reference/type-aliases/UseMutateFunction.md | 2 +- .../reference/type-aliases/UseMutationResult.md | 2 +- .../type-aliases/UseSuspenseInfiniteQueryResult.md | 2 +- packages/preact-query/src/infiniteQueryOptions.ts | 2 +- packages/preact-query/src/queryOptions.ts | 3 ++- packages/preact-query/src/types.ts | 9 +++++---- packages/preact-query/src/useQueries.ts | 8 ++++++-- packages/preact-query/src/useQuery.ts | 3 ++- packages/preact-query/src/useSuspenseQueries.ts | 10 +++++++--- 24 files changed, 67 insertions(+), 45 deletions(-) diff --git a/docs/framework/preact/reference/functions/queryOptions.md b/docs/framework/preact/reference/functions/queryOptions.md index 12f96be5aac..d999476811f 100644 --- a/docs/framework/preact/reference/functions/queryOptions.md +++ b/docs/framework/preact/reference/functions/queryOptions.md @@ -9,13 +9,14 @@ title: queryOptions function queryOptions(options: DefinedInitialDataOptions): Omit, "queryFn"> & object & QueryKeyWithDataTag; ``` -Defined in: [packages/preact-query/src/queryOptions.ts:143](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L143) +Defined in: [packages/preact-query/src/queryOptions.ts:144](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L144) You can generally pass everything to `queryOptions` that you can also pass to `useQuery`. These options can be shared across hooks and imperative APIs such as `queryClient.query`. `options.queryKey` is required and is the query key to generate options for. -This overload is selected when `initialData` is set, so the resulting `data` is never `undefined`. +This overload is selected when `initialData` is set, so the resulting `data` is never `undefined` (unless +a `select` changes `TData` to include `undefined`). ### Type Parameters @@ -85,7 +86,7 @@ function Posts() { function queryOptions(options: UnusedSkipTokenOptions): OmitKeyof, "queryFn"> & object & QueryKeyWithDataTag; ``` -Defined in: [packages/preact-query/src/queryOptions.ts:184](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L184) +Defined in: [packages/preact-query/src/queryOptions.ts:185](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L185) You can generally pass everything to `queryOptions` that you can also pass to `useQuery`. These options can be shared across hooks and imperative APIs such as `queryClient.query`. `options.queryKey` is required and @@ -154,7 +155,7 @@ function Post({ id }: { id: string }) { function queryOptions(options: UndefinedInitialDataOptions): UseQueryOptions & object & QueryKeyWithDataTag; ``` -Defined in: [packages/preact-query/src/queryOptions.ts:248](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L248) +Defined in: [packages/preact-query/src/queryOptions.ts:249](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L249) You can generally pass everything to `queryOptions` that you can also pass to `useQuery`. These options can be shared across hooks and imperative APIs such as `queryClient.query`. `options.queryKey` is required and diff --git a/docs/framework/preact/reference/functions/useQueries.md b/docs/framework/preact/reference/functions/useQueries.md index d9d4a955c6e..f74199b4aaf 100644 --- a/docs/framework/preact/reference/functions/useQueries.md +++ b/docs/framework/preact/reference/functions/useQueries.md @@ -7,7 +7,7 @@ title: useQueries function useQueries(__namedParameters: object, queryClient?: QueryClient): TCombinedResult; ``` -Defined in: [packages/preact-query/src/useQueries.ts:302](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useQueries.ts#L302) +Defined in: [packages/preact-query/src/useQueries.ts:306](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useQueries.ts#L306) The `useQueries` hook can be used to fetch a variable number of queries. diff --git a/docs/framework/preact/reference/functions/useQuery.md b/docs/framework/preact/reference/functions/useQuery.md index a0b65cad2fe..a73f2b19147 100644 --- a/docs/framework/preact/reference/functions/useQuery.md +++ b/docs/framework/preact/reference/functions/useQuery.md @@ -9,9 +9,10 @@ title: useQuery function useQuery(options: DefinedInitialDataOptions, queryClient?: QueryClient): DefinedUseQueryResult; ``` -Defined in: [packages/preact-query/src/useQuery.ts:50](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useQuery.ts#L50) +Defined in: [packages/preact-query/src/useQuery.ts:51](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useQuery.ts#L51) -This overload is selected when `initialData` is set, so the resulting `data` is never `undefined`. +This overload is selected when `initialData` is set, so the resulting `data` is never `undefined` (unless +a `select` changes `TData` to include `undefined`). ### Type Parameters @@ -89,7 +90,7 @@ function Posts() { function useQuery(options: UndefinedInitialDataOptions, queryClient?: QueryClient): UseQueryResult; ``` -Defined in: [packages/preact-query/src/useQuery.ts:117](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useQuery.ts#L117) +Defined in: [packages/preact-query/src/useQuery.ts:118](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useQuery.ts#L118) ### Type Parameters @@ -190,7 +191,7 @@ function Posts() { function useQuery(options: UseQueryOptions, queryClient?: QueryClient): UseQueryResult; ``` -Defined in: [packages/preact-query/src/useQuery.ts:281](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useQuery.ts#L281) +Defined in: [packages/preact-query/src/useQuery.ts:282](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useQuery.ts#L282) ### Type Parameters diff --git a/docs/framework/preact/reference/functions/useSuspenseQueries.md b/docs/framework/preact/reference/functions/useSuspenseQueries.md index b4feba0e096..c19d6bf748c 100644 --- a/docs/framework/preact/reference/functions/useSuspenseQueries.md +++ b/docs/framework/preact/reference/functions/useSuspenseQueries.md @@ -9,7 +9,7 @@ title: useSuspenseQueries function useSuspenseQueries(options: object, queryClient?: QueryClient): TCombinedResult; ``` -Defined in: [packages/preact-query/src/useSuspenseQueries.ts:409](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useSuspenseQueries.ts#L409) +Defined in: [packages/preact-query/src/useSuspenseQueries.ts:413](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useSuspenseQueries.ts#L413) The options for `useSuspenseQueries` are the same as for `useQueries`, except that the top-level `subscribed` option isn't supported, and each `query` can't have `throwOnError`, `enabled`, or `placeholderData`. @@ -279,7 +279,7 @@ function ErrorBoundary({ function useSuspenseQueries(options: object, queryClient?: QueryClient): TCombinedResult; ``` -Defined in: [packages/preact-query/src/useSuspenseQueries.ts:589](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useSuspenseQueries.ts#L589) +Defined in: [packages/preact-query/src/useSuspenseQueries.ts:593](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useSuspenseQueries.ts#L593) The options for `useSuspenseQueries` are the same as for `useQueries`, except that the top-level `subscribed` option isn't supported, and each `query` can't have `throwOnError`, `enabled`, or `placeholderData`. diff --git a/docs/framework/preact/reference/interfaces/UseMutationOptions.md b/docs/framework/preact/reference/interfaces/UseMutationOptions.md index 73e5d054a9e..3704bf427d0 100644 --- a/docs/framework/preact/reference/interfaces/UseMutationOptions.md +++ b/docs/framework/preact/reference/interfaces/UseMutationOptions.md @@ -3,7 +3,7 @@ id: UseMutationOptions title: UseMutationOptions --- -Defined in: [packages/preact-query/src/types.ts:411](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L411) +Defined in: [packages/preact-query/src/types.ts:412](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L412) The options accepted by `useMutation`. Same as [MutationObserverOptions](MutationObserverOptions.md) from `@tanstack/query-core`, minus the internal `_defaulted` flag. diff --git a/docs/framework/preact/reference/type-aliases/AnyUseMutationOptions.md b/docs/framework/preact/reference/type-aliases/AnyUseMutationOptions.md index 7afacd10bc7..47c459e5983 100644 --- a/docs/framework/preact/reference/type-aliases/AnyUseMutationOptions.md +++ b/docs/framework/preact/reference/type-aliases/AnyUseMutationOptions.md @@ -7,7 +7,7 @@ title: AnyUseMutationOptions type AnyUseMutationOptions = UseMutationOptions; ``` -Defined in: [packages/preact-query/src/types.ts:400](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L400) +Defined in: [packages/preact-query/src/types.ts:401](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L401) [UseMutationOptions](../interfaces/UseMutationOptions.md) with all type parameters set to `any`, useful when the specific types aren't relevant, e.g. when accepting options for any mutation in a helper function. diff --git a/docs/framework/preact/reference/type-aliases/DefinedInitialDataInfiniteOptions.md b/docs/framework/preact/reference/type-aliases/DefinedInitialDataInfiniteOptions.md index 51b78d85c96..a14a716df4b 100644 --- a/docs/framework/preact/reference/type-aliases/DefinedInitialDataInfiniteOptions.md +++ b/docs/framework/preact/reference/type-aliases/DefinedInitialDataInfiniteOptions.md @@ -10,7 +10,7 @@ type DefinedInitialDataInfiniteOptions = DefinedInfiniteQueryObserverResult; ``` -Defined in: [packages/preact-query/src/types.ts:376](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L376) +Defined in: [packages/preact-query/src/types.ts:377](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L377) -The result of `useInfiniteQuery` when `initialData` is set — `data` is never `undefined`. Re-exports -[DefinedInfiniteQueryObserverResult](DefinedInfiniteQueryObserverResult.md) from `@tanstack/query-core`. +The result of `useInfiniteQuery` when `initialData` is set — `data` is never `undefined` (unless a +`select` changes `TData` to include `undefined`). Re-exports [DefinedInfiniteQueryObserverResult](DefinedInfiniteQueryObserverResult.md) +from `@tanstack/query-core`. ## Type Parameters diff --git a/docs/framework/preact/reference/type-aliases/DefinedUseQueryResult.md b/docs/framework/preact/reference/type-aliases/DefinedUseQueryResult.md index 4f9f9fdfb25..bcefc019152 100644 --- a/docs/framework/preact/reference/type-aliases/DefinedUseQueryResult.md +++ b/docs/framework/preact/reference/type-aliases/DefinedUseQueryResult.md @@ -10,8 +10,8 @@ type DefinedUseQueryResult = DefinedQueryObserverResult = TDepth["length"] extends MAXIMUM_DEPTH ? UseQueryOptionsForUseQueries[] : T extends [] ? [] : T extends [infer Head] ? [...TResults, GetUseQueryOptionsForUseQueries] : T extends [infer Head, ...(infer Tails)] ? QueriesOptions<[...Tails], [...TResults, GetUseQueryOptionsForUseQueries], [...TDepth, 1]> : ReadonlyArray extends T ? T : T extends UseQueryOptionsForUseQueries[] ? UseQueryOptionsForUseQueries[] : UseQueryOptionsForUseQueries[]; ``` -Defined in: [packages/preact-query/src/useQueries.ts:156](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useQueries.ts#L156) +Defined in: [packages/preact-query/src/useQueries.ts:160](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useQueries.ts#L160) The `queries` array accepted by `useQueries`. Recursively unwraps each tuple element so every entry's -`queryFn`/`select`/`throwOnError` are inferred individually, up to 20 elements. An opaque array (e.g. -`unknown[]`) is returned as-is; a non-tuple array of a known element type, or a tuple past 20 elements, falls +`queryFn`/`select`/`throwOnError` are inferred individually, up to 20 elements — past that, a tuple falls back to a single homogeneous options type. +An opaque array (e.g. `unknown[]`) is returned as-is; a non-tuple array whose element type structurally +matches a query options object is mapped per-element instead, still inferring each entry individually; any +other non-tuple array — one whose element type doesn't match the expected options shape — falls back to +that same homogeneous options type too. + ## Type Parameters ### T diff --git a/docs/framework/preact/reference/type-aliases/QueriesResults.md b/docs/framework/preact/reference/type-aliases/QueriesResults.md index ab0ce69b005..97c69acdae8 100644 --- a/docs/framework/preact/reference/type-aliases/QueriesResults.md +++ b/docs/framework/preact/reference/type-aliases/QueriesResults.md @@ -7,7 +7,7 @@ title: QueriesResults type QueriesResults = TDepth["length"] extends MAXIMUM_DEPTH ? UseQueryResult[] : T extends [] ? [] : T extends [infer Head] ? [...TResults, GetUseQueryResult] : T extends [infer Head, ...(infer Tails)] ? QueriesResults<[...Tails], [...TResults, GetUseQueryResult], [...TDepth, 1]> : { [K in keyof T]: GetUseQueryResult }; ``` -Defined in: [packages/preact-query/src/useQueries.ts:207](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useQueries.ts#L207) +Defined in: [packages/preact-query/src/useQueries.ts:211](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useQueries.ts#L211) The result type returned by `useQueries`, when no `combine` is provided. Mirrors [QueriesOptions](QueriesOptions.md): each tuple element's result type is inferred individually, up to 20 elements. A non-tuple array is mapped diff --git a/docs/framework/preact/reference/type-aliases/SuspenseQueriesOptions.md b/docs/framework/preact/reference/type-aliases/SuspenseQueriesOptions.md index a61ae66de38..b6a9ee2b618 100644 --- a/docs/framework/preact/reference/type-aliases/SuspenseQueriesOptions.md +++ b/docs/framework/preact/reference/type-aliases/SuspenseQueriesOptions.md @@ -7,12 +7,16 @@ title: SuspenseQueriesOptions type SuspenseQueriesOptions = TDepth["length"] extends MAXIMUM_DEPTH ? UseSuspenseQueryOptions[] : T extends [] ? [] : T extends [infer Head] ? [...TResults, GetUseSuspenseQueryOptions] : T extends [infer Head, ...(infer Tails)] ? SuspenseQueriesOptions<[...Tails], [...TResults, GetUseSuspenseQueryOptions], [...TDepth, 1]> : unknown[] extends T ? T : T extends UseSuspenseQueryOptions[] ? UseSuspenseQueryOptions[] : UseSuspenseQueryOptions[]; ``` -Defined in: [packages/preact-query/src/useSuspenseQueries.ts:119](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useSuspenseQueries.ts#L119) +Defined in: [packages/preact-query/src/useSuspenseQueries.ts:123](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useSuspenseQueries.ts#L123) The `queries` array accepted by `useSuspenseQueries`. Recursively unwraps each tuple element so every -entry's `queryFn`/`select` are inferred individually, up to 20 elements. An opaque array (e.g. `unknown[]`) -is returned as-is; a non-tuple array of a known element type, or a tuple past 20 elements, falls back to a -single homogeneous [UseSuspenseQueryOptions](../interfaces/UseSuspenseQueryOptions.md) type. +entry's `queryFn`/`select` are inferred individually, up to 20 elements — past that, a tuple falls back to +a single homogeneous [UseSuspenseQueryOptions](../interfaces/UseSuspenseQueryOptions.md) type. + +An opaque array (e.g. `unknown[]`) is returned as-is; a non-tuple array whose element type structurally +matches a query options object is mapped per-element instead, still inferring each entry individually; any +other non-tuple array — one whose element type doesn't match the expected options shape — falls back to +that same homogeneous options type too. ## Type Parameters diff --git a/docs/framework/preact/reference/type-aliases/SuspenseQueriesResults.md b/docs/framework/preact/reference/type-aliases/SuspenseQueriesResults.md index 747e090ef9e..beefd0790b2 100644 --- a/docs/framework/preact/reference/type-aliases/SuspenseQueriesResults.md +++ b/docs/framework/preact/reference/type-aliases/SuspenseQueriesResults.md @@ -7,7 +7,7 @@ title: SuspenseQueriesResults type SuspenseQueriesResults = TDepth["length"] extends MAXIMUM_DEPTH ? UseSuspenseQueryResult[] : T extends [] ? [] : T extends [infer Head] ? [...TResults, GetUseSuspenseQueryResult] : T extends [infer Head, ...(infer Tails)] ? SuspenseQueriesResults<[...Tails], [...TResults, GetUseSuspenseQueryResult], [...TDepth, 1]> : { [K in keyof T]: GetUseSuspenseQueryResult }; ``` -Defined in: [packages/preact-query/src/useSuspenseQueries.ts:165](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useSuspenseQueries.ts#L165) +Defined in: [packages/preact-query/src/useSuspenseQueries.ts:169](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useSuspenseQueries.ts#L169) The result type returned by `useSuspenseQueries`, when no `combine` is provided. Mirrors [SuspenseQueriesOptions](SuspenseQueriesOptions.md): each tuple element's result type is inferred individually, up to 20 elements. diff --git a/docs/framework/preact/reference/type-aliases/UseBaseMutationResult.md b/docs/framework/preact/reference/type-aliases/UseBaseMutationResult.md index 5a473c0895c..7f625d89f37 100644 --- a/docs/framework/preact/reference/type-aliases/UseBaseMutationResult.md +++ b/docs/framework/preact/reference/type-aliases/UseBaseMutationResult.md @@ -9,7 +9,7 @@ type UseBaseMutationResult = Overrid }> & object; ``` -Defined in: [packages/preact-query/src/types.ts:470](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L470) +Defined in: [packages/preact-query/src/types.ts:471](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L471) The result of `useMutation`. Same as [MutationObserverResult](MutationObserverResult.md) from `@tanstack/query-core`, with `mutate` narrowed to the fire-and-forget [UseMutateFunction](UseMutateFunction.md) signature, plus the added `mutateAsync`. diff --git a/docs/framework/preact/reference/type-aliases/UseMutateAsyncFunction.md b/docs/framework/preact/reference/type-aliases/UseMutateAsyncFunction.md index edcdd01ae2e..d1a7002c275 100644 --- a/docs/framework/preact/reference/type-aliases/UseMutateAsyncFunction.md +++ b/docs/framework/preact/reference/type-aliases/UseMutateAsyncFunction.md @@ -7,7 +7,7 @@ title: UseMutateAsyncFunction type UseMutateAsyncFunction = MutateFunction; ``` -Defined in: [packages/preact-query/src/types.ts:453](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L453) +Defined in: [packages/preact-query/src/types.ts:454](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L454) The type of `mutateAsync`, as returned by `useMutation`. Similar to [UseMutateFunction](UseMutateFunction.md), but returns a promise which can be awaited. diff --git a/docs/framework/preact/reference/type-aliases/UseMutateFunction.md b/docs/framework/preact/reference/type-aliases/UseMutateFunction.md index 3ed6c2510cd..4e08f22706f 100644 --- a/docs/framework/preact/reference/type-aliases/UseMutateFunction.md +++ b/docs/framework/preact/reference/type-aliases/UseMutateFunction.md @@ -7,7 +7,7 @@ title: UseMutateFunction type UseMutateFunction = (...args: Parameters>) => void; ``` -Defined in: [packages/preact-query/src/types.ts:432](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L432) +Defined in: [packages/preact-query/src/types.ts:433](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L433) The type of `mutate`, as returned by `useMutation`. Forwards the variables (and an optional per-call `onSuccess`/`onError`/`onSettled`) to the underlying `mutate` call. Fire-and-forget — errors are surfaced diff --git a/docs/framework/preact/reference/type-aliases/UseMutationResult.md b/docs/framework/preact/reference/type-aliases/UseMutationResult.md index 1e0a4631542..df13e625c69 100644 --- a/docs/framework/preact/reference/type-aliases/UseMutationResult.md +++ b/docs/framework/preact/reference/type-aliases/UseMutationResult.md @@ -7,7 +7,7 @@ title: UseMutationResult type UseMutationResult = UseBaseMutationResult; ``` -Defined in: [packages/preact-query/src/types.ts:499](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L499) +Defined in: [packages/preact-query/src/types.ts:500](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L500) The result of `useMutation`. Same as [UseBaseMutationResult](UseBaseMutationResult.md). diff --git a/docs/framework/preact/reference/type-aliases/UseSuspenseInfiniteQueryResult.md b/docs/framework/preact/reference/type-aliases/UseSuspenseInfiniteQueryResult.md index 038e3614cc9..d6b77cf26c2 100644 --- a/docs/framework/preact/reference/type-aliases/UseSuspenseInfiniteQueryResult.md +++ b/docs/framework/preact/reference/type-aliases/UseSuspenseInfiniteQueryResult.md @@ -7,7 +7,7 @@ title: UseSuspenseInfiniteQueryResult type UseSuspenseInfiniteQueryResult = OmitKeyof, "isPlaceholderData">; ``` -Defined in: [packages/preact-query/src/types.ts:388](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L388) +Defined in: [packages/preact-query/src/types.ts:389](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L389) The result of `useSuspenseInfiniteQuery`. Same as [DefinedUseInfiniteQueryResult](DefinedUseInfiniteQueryResult.md), minus `isPlaceholderData` — Suspense hooks never render placeholder data. diff --git a/packages/preact-query/src/infiniteQueryOptions.ts b/packages/preact-query/src/infiniteQueryOptions.ts index 7e419b6d5e1..5cfe0dac7c3 100644 --- a/packages/preact-query/src/infiniteQueryOptions.ts +++ b/packages/preact-query/src/infiniteQueryOptions.ts @@ -92,7 +92,7 @@ export type UnusedSkipTokenInfiniteOptions< /** * The options accepted by the `infiniteQueryOptions` overload selected when `initialData` is set — `data` is - * never `undefined`. + * never `undefined` (unless a `select` changes `TData` to include `undefined`). * * @template TQueryFnData - The type of a single page, as your `queryFn` resolves it. * @template TError - The type of errors your `queryFn` may throw. diff --git a/packages/preact-query/src/queryOptions.ts b/packages/preact-query/src/queryOptions.ts index 30084a77928..0d683c9fcc1 100644 --- a/packages/preact-query/src/queryOptions.ts +++ b/packages/preact-query/src/queryOptions.ts @@ -107,7 +107,8 @@ export type DefinedInitialDataOptions< * be shared across hooks and imperative APIs such as `queryClient.query`. `options.queryKey` is required and * is the query key to generate options for. * - * This overload is selected when `initialData` is set, so the resulting `data` is never `undefined`. + * This overload is selected when `initialData` is set, so the resulting `data` is never `undefined` (unless + * a `select` changes `TData` to include `undefined`). * * @see {@link useQuery} to run a query with these options. * @see [The Query Options API](https://tkdodo.eu/blog/the-query-options-api) for more on this pattern. diff --git a/packages/preact-query/src/types.ts b/packages/preact-query/src/types.ts index a4155b5b2ad..a108a78f008 100644 --- a/packages/preact-query/src/types.ts +++ b/packages/preact-query/src/types.ts @@ -343,8 +343,8 @@ export type UseSuspenseQueryResult< /** * The result of `useQuery` when `initialData` is set, or of `useSuspenseQuery` before the `isPlaceholderData` - * omission — `data` is never `undefined`. Re-exports {@link DefinedQueryObserverResult} from - * `@tanstack/query-core`. + * omission — `data` is never `undefined` (unless a `select` changes `TData` to include `undefined`). + * Re-exports {@link DefinedQueryObserverResult} from `@tanstack/query-core`. * * @template TData - The type `data` ends up as after `select` runs. * @template TError - The type of errors your `queryFn` may throw. @@ -367,8 +367,9 @@ export type UseInfiniteQueryResult< > = InfiniteQueryObserverResult /** - * The result of `useInfiniteQuery` when `initialData` is set — `data` is never `undefined`. Re-exports - * {@link DefinedInfiniteQueryObserverResult} from `@tanstack/query-core`. + * The result of `useInfiniteQuery` when `initialData` is set — `data` is never `undefined` (unless a + * `select` changes `TData` to include `undefined`). Re-exports {@link DefinedInfiniteQueryObserverResult} + * from `@tanstack/query-core`. * * @template TData - The type `data` ends up as after `select` runs. * @template TError - The type of errors your `queryFn` may throw. diff --git a/packages/preact-query/src/useQueries.ts b/packages/preact-query/src/useQueries.ts index 1e608bb835a..86b55926c76 100644 --- a/packages/preact-query/src/useQueries.ts +++ b/packages/preact-query/src/useQueries.ts @@ -143,10 +143,14 @@ type GetUseQueryResult = /** * The `queries` array accepted by `useQueries`. Recursively unwraps each tuple element so every entry's - * `queryFn`/`select`/`throwOnError` are inferred individually, up to 20 elements. An opaque array (e.g. - * `unknown[]`) is returned as-is; a non-tuple array of a known element type, or a tuple past 20 elements, falls + * `queryFn`/`select`/`throwOnError` are inferred individually, up to 20 elements — past that, a tuple falls * back to a single homogeneous options type. * + * An opaque array (e.g. `unknown[]`) is returned as-is; a non-tuple array whose element type structurally + * matches a query options object is mapped per-element instead, still inferring each entry individually; any + * other non-tuple array — one whose element type doesn't match the expected options shape — falls back to + * that same homogeneous options type too. + * * @template T - The type of the `queries` array as written at the call site. * @template TResults - The internal accumulator that this type builds during recursion. It is not meant * to be set explicitly. diff --git a/packages/preact-query/src/useQuery.ts b/packages/preact-query/src/useQuery.ts index b579f13c5e5..bfbadf2221f 100644 --- a/packages/preact-query/src/useQuery.ts +++ b/packages/preact-query/src/useQuery.ts @@ -13,7 +13,8 @@ import type { import { useBaseQuery } from './useBaseQuery' /** - * This overload is selected when `initialData` is set, so the resulting `data` is never `undefined`. + * This overload is selected when `initialData` is set, so the resulting `data` is never `undefined` (unless + * a `select` changes `TData` to include `undefined`). * * @see {@link queryOptions} to share these options between `useQuery` and imperative APIs like `queryClient.query`. * @param options - The {@link DefinedInitialDataOptions} to use — everything you can pass to `useQuery`, with `initialData` set. diff --git a/packages/preact-query/src/useSuspenseQueries.ts b/packages/preact-query/src/useSuspenseQueries.ts index 78f2173e946..ffdfbf42e7f 100644 --- a/packages/preact-query/src/useSuspenseQueries.ts +++ b/packages/preact-query/src/useSuspenseQueries.ts @@ -106,9 +106,13 @@ type GetUseSuspenseQueryResult = /** * The `queries` array accepted by `useSuspenseQueries`. Recursively unwraps each tuple element so every - * entry's `queryFn`/`select` are inferred individually, up to 20 elements. An opaque array (e.g. `unknown[]`) - * is returned as-is; a non-tuple array of a known element type, or a tuple past 20 elements, falls back to a - * single homogeneous {@link UseSuspenseQueryOptions} type. + * entry's `queryFn`/`select` are inferred individually, up to 20 elements — past that, a tuple falls back to + * a single homogeneous {@link UseSuspenseQueryOptions} type. + * + * An opaque array (e.g. `unknown[]`) is returned as-is; a non-tuple array whose element type structurally + * matches a query options object is mapped per-element instead, still inferring each entry individually; any + * other non-tuple array — one whose element type doesn't match the expected options shape — falls back to + * that same homogeneous options type too. * * @template T - The type of the `queries` array as written at the call site. * @template TResults - The internal accumulator that this type builds during recursion. It is not meant From e84f699edacf01a4eb2d864b99a10c710fce989c Mon Sep 17 00:00:00 2001 From: Wonsuk Choi Date: Tue, 22 Sep 2026 15:32:28 +0900 Subject: [PATCH 4/4] docs({react,preact}-query): fix missed 'select' qualifier on 'DefinedInitialDataOptions' JSDoc --- .../preact/reference/type-aliases/DefinedInitialDataOptions.md | 2 +- .../react/reference/type-aliases/DefinedInitialDataOptions.md | 2 +- packages/preact-query/src/queryOptions.ts | 2 +- packages/react-query/src/queryOptions.ts | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/framework/preact/reference/type-aliases/DefinedInitialDataOptions.md b/docs/framework/preact/reference/type-aliases/DefinedInitialDataOptions.md index 5187c08ab47..fd052751044 100644 --- a/docs/framework/preact/reference/type-aliases/DefinedInitialDataOptions.md +++ b/docs/framework/preact/reference/type-aliases/DefinedInitialDataOptions.md @@ -10,7 +10,7 @@ type DefinedInitialDataOptions = Omit = Omit