From 7ce9a959ffaf6d7d3b1dfab0c21072a3a9c3db63 Mon Sep 17 00:00:00 2001 From: Wonsuk Choi Date: Sat, 14 Nov 2026 21:04:44 +0900 Subject: [PATCH 1/2] docs({react,preact,vue,solid,svelte,angular}-query): describe when 'status' is 'error', 'success' or 'pending' in the 'useQuery' '@returns' --- .../reference/functions/injectQuery.md | 11 +++-- .../preact/reference/functions/useQuery.md | 34 ++++++++------ .../react/reference/functions/useQuery.md | 34 ++++++++------ .../solid/reference/functions/useQuery.md | 24 +++++----- .../solid/reference/variables/createQuery.md | 15 +++--- .../svelte/reference/functions/createQuery.md | 34 ++++++++------ .../vue/reference/functions/useQuery.md | 47 ++++++++++--------- .../src/inject-query.ts | 7 +-- packages/preact-query/src/useQuery.ts | 21 +++++---- packages/react-query/src/useQuery.ts | 21 +++++---- packages/solid-query/src/useQuery.ts | 15 +++--- packages/svelte-query/src/createQuery.ts | 21 +++++---- packages/vue-query/src/useQuery.ts | 32 +++++++------ 13 files changed, 174 insertions(+), 142 deletions(-) diff --git a/docs/framework/angular/reference/functions/injectQuery.md b/docs/framework/angular/reference/functions/injectQuery.md index e26af5742db..48e344b014c 100644 --- a/docs/framework/angular/reference/functions/injectQuery.md +++ b/docs/framework/angular/reference/functions/injectQuery.md @@ -116,7 +116,7 @@ export class Posts { function injectQuery(injectQueryFn: () => UndefinedInitialDataOptions, options?: InjectQueryOptions): CreateQueryResult; ``` -Defined in: [packages/angular-query-experimental/src/inject-query.ts:158](https://github.com/TanStack/query/blob/main/packages/angular-query-experimental/src/inject-query.ts#L158) +Defined in: [packages/angular-query-experimental/src/inject-query.ts:159](https://github.com/TanStack/query/blob/main/packages/angular-query-experimental/src/inject-query.ts#L159) Injects a query: a declarative dependency on an asynchronous source of data that is tied to a unique key. @@ -158,9 +158,10 @@ Additional configuration [`CreateQueryResult`](../type-aliases/CreateQueryResult.md)\<`TData`, `TError`\> -The query result. `status()` is `'pending'` if there is no cached data to display, `'error'` if -the last fetch attempt failed, or `'success'` if the query has data to display. `isPending`/`isSuccess`/ -`isError` are type-guard methods for convenience. +The query result. `status()` is `'error'` if the last fetch failed after its retries or +`select` threw, `'success'` if the query has data to display (including `placeholderData`), and +`'pending'` otherwise. A refetch that starts without data to display clears the error and sets +`status()` back to `'pending'`. `isPending`/`isSuccess`/`isError` are type-guard methods for convenience. ### See @@ -236,7 +237,7 @@ export class Posts { function injectQuery(injectQueryFn: () => CreateQueryOptions, options?: InjectQueryOptions): CreateQueryResult; ``` -Defined in: [packages/angular-query-experimental/src/inject-query.ts:184](https://github.com/TanStack/query/blob/main/packages/angular-query-experimental/src/inject-query.ts#L184) +Defined in: [packages/angular-query-experimental/src/inject-query.ts:185](https://github.com/TanStack/query/blob/main/packages/angular-query-experimental/src/inject-query.ts#L185) This overload accepts the general [CreateQueryOptions](../interfaces/CreateQueryOptions.md) shape rather than the `initialData`-aware overloads above, so whether `data` is defined can't be inferred from the call site — useful when wrapping diff --git a/docs/framework/preact/reference/functions/useQuery.md b/docs/framework/preact/reference/functions/useQuery.md index b4fd8d83a22..e512bed41ac 100644 --- a/docs/framework/preact/reference/functions/useQuery.md +++ b/docs/framework/preact/reference/functions/useQuery.md @@ -27,7 +27,7 @@ See also: [Parameters](#parameters-summary) · [Returns](#returns-summary) function useQuery(options: DefinedInitialDataOptions, queryClient?: QueryClient): DefinedUseQueryResult; ``` -Defined in: [packages/preact-query/src/useQuery.ts:49](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useQuery.ts#L49) +Defined in: [packages/preact-query/src/useQuery.ts:50](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useQuery.ts#L50) This overload is selected when `initialData` is known to be defined, so the resulting `data` is never `undefined` (unless a `select` changes `TData` to include `undefined`). @@ -69,9 +69,10 @@ be used. [`DefinedUseQueryResult`](../type-aliases/DefinedUseQueryResult.md)\<`TData`, `TError`\> -The current query result, typed so that `status` is `success` — or `error` if a fetch attempt -fails while keeping the existing data (`status` never resolves to `pending` in this overload's type, -since `initialData` guarantees data upfront). `isSuccess`/`isError` are derived booleans for convenience. +The current query result, typed so that `status` is `success` or `error` (`status` never +resolves to `pending` in this overload's type, since `initialData` guarantees data upfront). `status` is +`error` if the last fetch failed after its retries or `select` threw, and `success` otherwise. +`isSuccess`/`isError` are derived booleans for convenience. ### See @@ -110,7 +111,7 @@ function Posts() { function useQuery(options: UndefinedInitialDataOptions, queryClient?: QueryClient): UseQueryResult; ``` -Defined in: [packages/preact-query/src/useQuery.ts:116](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useQuery.ts#L116) +Defined in: [packages/preact-query/src/useQuery.ts:118](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useQuery.ts#L118) This overload is selected when `initialData` is omitted, may be `undefined`, or is a function that may return `undefined`, so the resulting `data` can be `undefined`. @@ -152,9 +153,10 @@ be used. [`UseQueryResult`](../type-aliases/UseQueryResult.md)\<`TData`, `TError`\> -The current query result. `status` is `pending` if there is no cached data to display, `error` if -the last fetch attempt failed, or `success` if the query has data to display. `isPending`/`isSuccess`/`isError` -are derived booleans for convenience. +The current query result. `status` is `error` if the last fetch failed after its retries or `select` +threw, `success` if the query has data to display (including `placeholderData`), and `pending` otherwise. A +refetch that starts without data to display clears the error and sets `status` back to `pending`. +`isPending`/`isSuccess`/`isError` are derived booleans for convenience. ### See @@ -216,7 +218,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:284](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useQuery.ts#L284) Fallback overload for options whose `initialData` presence isn't statically known — for example, an object typed as [UseQueryOptions](../interfaces/UseQueryOptions.md) rather than an object literal. Prefer one of the other overloads @@ -259,9 +261,10 @@ be used. [`UseQueryResult`](../type-aliases/UseQueryResult.md)\<`TData`, `TError`\> -The current query result. `status` is `pending` if there is no cached data to display, `error` if -the last fetch attempt failed, or `success` if the query has data to display. `isPending`/`isSuccess`/`isError` -are derived booleans for convenience. +The current query result. `status` is `error` if the last fetch failed after its retries or `select` +threw, `success` if the query has data to display (including `placeholderData`), and `pending` otherwise. A +refetch that starts without data to display clears the error and sets `status` back to `pending`. +`isPending`/`isSuccess`/`isError` are derived booleans for convenience. ### See @@ -469,9 +472,10 @@ be used. [`UseQueryResult`](../type-aliases/UseQueryResult.md)\<`TData`, `TError`\> -The current query result. `status` is `pending` if there is no cached data to display, `error` if -the last fetch attempt failed, or `success` if the query has data to display. `isPending`/`isSuccess`/`isError` -are derived booleans for convenience. +The current query result. `status` is `error` if the last fetch failed after its retries or `select` +threw, `success` if the query has data to display (including `placeholderData`), and `pending` otherwise. A +refetch that starts without data to display clears the error and sets `status` back to `pending`. +`isPending`/`isSuccess`/`isError` are derived booleans for convenience. diff --git a/docs/framework/react/reference/functions/useQuery.md b/docs/framework/react/reference/functions/useQuery.md index d9dac87d9f2..81b53e61667 100644 --- a/docs/framework/react/reference/functions/useQuery.md +++ b/docs/framework/react/reference/functions/useQuery.md @@ -29,7 +29,7 @@ See also: [Parameters](#parameters-summary) · [Returns](#returns-summary) function useQuery(options: DefinedInitialDataOptions, queryClient?: QueryClient): DefinedUseQueryResult; ``` -Defined in: [packages/react-query/src/useQuery.ts:49](https://github.com/TanStack/query/blob/main/packages/react-query/src/useQuery.ts#L49) +Defined in: [packages/react-query/src/useQuery.ts:50](https://github.com/TanStack/query/blob/main/packages/react-query/src/useQuery.ts#L50) This overload is selected when `initialData` is known to be defined, so the resulting `data` is never `undefined` (unless a `select` changes `TData` to include `undefined`). @@ -71,9 +71,10 @@ be used. [`DefinedUseQueryResult`](../type-aliases/DefinedUseQueryResult.md)\<`TData`, `TError`\> -The current query result, typed so that `status` is `success` — or `error` if a fetch attempt -fails while keeping the existing data (`status` never resolves to `pending` in this overload's type, -since `initialData` guarantees data upfront). `isSuccess`/`isError` are derived booleans for convenience. +The current query result, typed so that `status` is `success` or `error` (`status` never +resolves to `pending` in this overload's type, since `initialData` guarantees data upfront). `status` is +`error` if the last fetch failed after its retries or `select` threw, and `success` otherwise. +`isSuccess`/`isError` are derived booleans for convenience. ### See @@ -112,7 +113,7 @@ function Posts() { function useQuery(options: UndefinedInitialDataOptions, queryClient?: QueryClient): UseQueryResult; ``` -Defined in: [packages/react-query/src/useQuery.ts:116](https://github.com/TanStack/query/blob/main/packages/react-query/src/useQuery.ts#L116) +Defined in: [packages/react-query/src/useQuery.ts:118](https://github.com/TanStack/query/blob/main/packages/react-query/src/useQuery.ts#L118) This overload is selected when `initialData` is omitted, may be `undefined`, or is a function that may return `undefined`, so the resulting `data` can be `undefined`. @@ -154,9 +155,10 @@ be used. [`UseQueryResult`](../type-aliases/UseQueryResult.md)\<`TData`, `TError`\> -The current query result. `status` is `pending` if there is no cached data to display, `error` if -the last fetch attempt failed, or `success` if the query has data to display. `isPending`/`isSuccess`/`isError` -are derived booleans for convenience. +The current query result. `status` is `error` if the last fetch failed after its retries or `select` +threw, `success` if the query has data to display (including `placeholderData`), and `pending` otherwise. A +refetch that starts without data to display clears the error and sets `status` back to `pending`. +`isPending`/`isSuccess`/`isError` are derived booleans for convenience. ### See @@ -218,7 +220,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:284](https://github.com/TanStack/query/blob/main/packages/react-query/src/useQuery.ts#L284) Fallback overload for options whose `initialData` presence isn't statically known — for example, an object typed as [UseQueryOptions](../interfaces/UseQueryOptions.md) rather than an object literal. Prefer one of the other overloads @@ -261,9 +263,10 @@ be used. [`UseQueryResult`](../type-aliases/UseQueryResult.md)\<`TData`, `TError`\> -The current query result. `status` is `pending` if there is no cached data to display, `error` if -the last fetch attempt failed, or `success` if the query has data to display. `isPending`/`isSuccess`/`isError` -are derived booleans for convenience. +The current query result. `status` is `error` if the last fetch failed after its retries or `select` +threw, `success` if the query has data to display (including `placeholderData`), and `pending` otherwise. A +refetch that starts without data to display clears the error and sets `status` back to `pending`. +`isPending`/`isSuccess`/`isError` are derived booleans for convenience. ### See @@ -471,9 +474,10 @@ be used. [`UseQueryResult`](../type-aliases/UseQueryResult.md)\<`TData`, `TError`\> -The current query result. `status` is `pending` if there is no cached data to display, `error` if -the last fetch attempt failed, or `success` if the query has data to display. `isPending`/`isSuccess`/`isError` -are derived booleans for convenience. +The current query result. `status` is `error` if the last fetch failed after its retries or `select` +threw, `success` if the query has data to display (including `placeholderData`), and `pending` otherwise. A +refetch that starts without data to display clears the error and sets `status` back to `pending`. +`isPending`/`isSuccess`/`isError` are derived booleans for convenience. diff --git a/docs/framework/solid/reference/functions/useQuery.md b/docs/framework/solid/reference/functions/useQuery.md index 84b66cab679..5b09062ed76 100644 --- a/docs/framework/solid/reference/functions/useQuery.md +++ b/docs/framework/solid/reference/functions/useQuery.md @@ -73,10 +73,10 @@ will be used. [`DefinedUseQueryResult`](../type-aliases/DefinedUseQueryResult.md)\<`TData`, `TError`\> -The current query result, as a Solid store, typed so that `status` is `success` — or `error` if a -fetch attempt fails while keeping the existing data (`status` never resolves to `pending` in this overload's -type, since `initialData` guarantees data upfront). `isSuccess`/`isError` are derived booleans for -convenience. +The current query result, as a Solid store, typed so that `status` is `success` or `error` +(`status` never resolves to `pending` in this overload's type, since `initialData` guarantees data upfront). +`status` is `error` if the last fetch failed after its retries or `select` threw, and `success` otherwise. +`isSuccess`/`isError` are derived booleans for convenience. ### See @@ -116,7 +116,7 @@ function Posts() { function useQuery(options: UndefinedInitialDataOptions, queryClient?: () => QueryClient): UseQueryResult; ``` -Defined in: [packages/solid-query/src/useQuery.ts:228](https://github.com/TanStack/query/blob/main/packages/solid-query/src/useQuery.ts#L228) +Defined in: [packages/solid-query/src/useQuery.ts:229](https://github.com/TanStack/query/blob/main/packages/solid-query/src/useQuery.ts#L229) Subscribes to a query: a declarative dependency on an asynchronous source of data that is tied to a unique key. The query runs when the options call for it — `enabled: false` skips the initial fetch. @@ -159,9 +159,10 @@ will be used. [`UseQueryResult`](../type-aliases/UseQueryResult.md)\<`TData`, `TError`\> -The current query result, as a Solid store. `status` is `pending` if there is no cached data to -display, `error` if the last fetch attempt failed, or `success` if the query has data to display. -`isPending`/`isSuccess`/`isError` are derived booleans for convenience. +The current query result, as a Solid store. `status` is `error` if the last fetch failed after +its retries or `select` threw, `success` if the query has data to display (including `placeholderData`), +and `pending` otherwise. A refetch that starts without data to display clears the error and sets +`status` back to `pending`. `isPending`/`isSuccess`/`isError` are derived booleans for convenience. ### See @@ -348,9 +349,10 @@ will be used. [`UseQueryResult`](../type-aliases/UseQueryResult.md)\<`TData`, `TError`\> -The current query result, as a Solid store. `status` is `pending` if there is no cached data to -display, `error` if the last fetch attempt failed, or `success` if the query has data to display. -`isPending`/`isSuccess`/`isError` are derived booleans for convenience. +The current query result, as a Solid store. `status` is `error` if the last fetch failed after +its retries or `select` threw, `success` if the query has data to display (including `placeholderData`), +and `pending` otherwise. A refetch that starts without data to display clears the error and sets +`status` back to `pending`. `isPending`/`isSuccess`/`isError` are derived booleans for convenience. diff --git a/docs/framework/solid/reference/variables/createQuery.md b/docs/framework/solid/reference/variables/createQuery.md index 6c50cabff6c..94950c24cd8 100644 --- a/docs/framework/solid/reference/variables/createQuery.md +++ b/docs/framework/solid/reference/variables/createQuery.md @@ -64,10 +64,10 @@ will be used. [`DefinedUseQueryResult`](../type-aliases/DefinedUseQueryResult.md)\<`TData`, `TError`\> -The current query result, as a Solid store, typed so that `status` is `success` — or `error` if a -fetch attempt fails while keeping the existing data (`status` never resolves to `pending` in this overload's -type, since `initialData` guarantees data upfront). `isSuccess`/`isError` are derived booleans for -convenience. +The current query result, as a Solid store, typed so that `status` is `success` or `error` +(`status` never resolves to `pending` in this overload's type, since `initialData` guarantees data upfront). +`status` is `error` if the last fetch failed after its retries or `select` threw, and `success` otherwise. +`isSuccess`/`isError` are derived booleans for convenience. ### See @@ -146,9 +146,10 @@ will be used. [`UseQueryResult`](../type-aliases/UseQueryResult.md)\<`TData`, `TError`\> -The current query result, as a Solid store. `status` is `pending` if there is no cached data to -display, `error` if the last fetch attempt failed, or `success` if the query has data to display. -`isPending`/`isSuccess`/`isError` are derived booleans for convenience. +The current query result, as a Solid store. `status` is `error` if the last fetch failed after +its retries or `select` threw, `success` if the query has data to display (including `placeholderData`), +and `pending` otherwise. A refetch that starts without data to display clears the error and sets +`status` back to `pending`. `isPending`/`isSuccess`/`isError` are derived booleans for convenience. ### See diff --git a/docs/framework/svelte/reference/functions/createQuery.md b/docs/framework/svelte/reference/functions/createQuery.md index 8e9eaa8e931..85f8f3f949b 100644 --- a/docs/framework/svelte/reference/functions/createQuery.md +++ b/docs/framework/svelte/reference/functions/createQuery.md @@ -27,7 +27,7 @@ See also: [Parameters](#parameters-summary) · [Returns](#returns-summary) function createQuery(options: Accessor>, queryClient?: Accessor): DefinedCreateQueryResult; ``` -Defined in: [packages/svelte-query/src/createQuery.ts:53](https://github.com/TanStack/query/blob/main/packages/svelte-query/src/createQuery.ts#L53) +Defined in: [packages/svelte-query/src/createQuery.ts:54](https://github.com/TanStack/query/blob/main/packages/svelte-query/src/createQuery.ts#L54) Subscribes to a query: a declarative dependency on an asynchronous source of data that is tied to a unique key. The query runs when the options call for it — `enabled: false` skips the initial fetch. @@ -73,9 +73,10 @@ be used. [`DefinedCreateQueryResult`](../type-aliases/DefinedCreateQueryResult.md)\<`TData`, `TError`\> -The current query result, typed so that `status` is `success` — or `error` if a fetch attempt -fails while keeping the existing data (`status` never resolves to `pending` in this overload's type, -since `initialData` guarantees data upfront). `isSuccess`/`isError` are derived booleans for convenience. +The current query result, typed so that `status` is `success` or `error` (`status` never +resolves to `pending` in this overload's type, since `initialData` guarantees data upfront). `status` is +`error` if the last fetch failed after its retries or `select` threw, and `success` otherwise. +`isSuccess`/`isError` are derived booleans for convenience. ### See @@ -114,7 +115,7 @@ since `initialData` guarantees data upfront). `isSuccess`/`isError` are derived function createQuery(options: Accessor>, queryClient?: Accessor): CreateQueryResult; ``` -Defined in: [packages/svelte-query/src/createQuery.ts:124](https://github.com/TanStack/query/blob/main/packages/svelte-query/src/createQuery.ts#L124) +Defined in: [packages/svelte-query/src/createQuery.ts:126](https://github.com/TanStack/query/blob/main/packages/svelte-query/src/createQuery.ts#L126) Subscribes to a query: a declarative dependency on an asynchronous source of data that is tied to a unique key. The query runs when the options call for it — `enabled: false` skips the initial fetch. @@ -157,9 +158,10 @@ be used. [`CreateQueryResult`](../type-aliases/CreateQueryResult.md)\<`TData`, `TError`\> -The current query result. `status` is `pending` if there is no cached data to display, `error` if -the last fetch attempt failed, or `success` if the query has data to display. `isPending`/`isSuccess`/`isError` -are derived booleans for convenience. +The current query result. `status` is `error` if the last fetch failed after its retries or `select` +threw, `success` if the query has data to display (including `placeholderData`), and `pending` otherwise. A +refetch that starts without data to display clears the error and sets `status` back to `pending`. +`isPending`/`isSuccess`/`isError` are derived booleans for convenience. ### See @@ -222,7 +224,7 @@ The same query, checking `isPending`/`isError` instead of `status` — pick whic function createQuery(options: Accessor>, queryClient?: Accessor): CreateQueryResult; ``` -Defined in: [packages/svelte-query/src/createQuery.ts:249](https://github.com/TanStack/query/blob/main/packages/svelte-query/src/createQuery.ts#L249) +Defined in: [packages/svelte-query/src/createQuery.ts:252](https://github.com/TanStack/query/blob/main/packages/svelte-query/src/createQuery.ts#L252) Fallback overload for options whose `initialData` presence isn't statically known — for example, an object typed as [CreateQueryOptions](../type-aliases/CreateQueryOptions.md) rather than an object literal. Prefer one of the other @@ -266,9 +268,10 @@ be used. [`CreateQueryResult`](../type-aliases/CreateQueryResult.md)\<`TData`, `TError`\> -The current query result. `status` is `pending` if there is no cached data to display, `error` if -the last fetch attempt failed, or `success` if the query has data to display. `isPending`/`isSuccess`/`isError` -are derived booleans for convenience. +The current query result. `status` is `error` if the last fetch failed after its retries or `select` +threw, `success` if the query has data to display (including `placeholderData`), and `pending` otherwise. A +refetch that starts without data to display clears the error and sets `status` back to `pending`. +`isPending`/`isSuccess`/`isError` are derived booleans for convenience. ### See @@ -434,9 +437,10 @@ be used. [`CreateQueryResult`](../type-aliases/CreateQueryResult.md)\<`TData`, `TError`\> -The current query result. `status` is `pending` if there is no cached data to display, `error` if -the last fetch attempt failed, or `success` if the query has data to display. `isPending`/`isSuccess`/`isError` -are derived booleans for convenience. +The current query result. `status` is `error` if the last fetch failed after its retries or `select` +threw, `success` if the query has data to display (including `placeholderData`), and `pending` otherwise. A +refetch that starts without data to display clears the error and sets `status` back to `pending`. +`isPending`/`isSuccess`/`isError` are derived booleans for convenience. diff --git a/docs/framework/vue/reference/functions/useQuery.md b/docs/framework/vue/reference/functions/useQuery.md index 80fd95b7e53..2b55e34620e 100644 --- a/docs/framework/vue/reference/functions/useQuery.md +++ b/docs/framework/vue/reference/functions/useQuery.md @@ -78,11 +78,11 @@ will be used. [`UseQueryDefinedReturnType`](../type-aliases/UseQueryDefinedReturnType.md)\<`TData`, `TError`\> -The current query result, typed so that `status` is `success` — or `error` if a fetch attempt -fails while keeping the existing data (`status` never resolves to `pending` in this overload's type, -since `initialData` guarantees data upfront). `isSuccess`/`isError` are derived boolean `ref`s for -convenience. `state` is that result as one readonly reactive object — `state.data`, `state.isPending`, and -the rest are plain values. +The current query result, typed so that `status` is `success` or `error` (`status` never resolves +to `pending` in this overload's type, since `initialData` guarantees data upfront). `status` is `error` if +the last fetch failed after its retries or `select` threw, and `success` otherwise. `isSuccess`/`isError` +are derived boolean `ref`s for convenience. `state` is that result as one readonly reactive object — +`state.data`, `state.isPending`, and the rest are plain values. ### Example @@ -115,7 +115,7 @@ const { data, isError, error } = useQuery({ function useQuery(options: UndefinedInitialQueryOptions, queryClient?: QueryClient): UseQueryReturnType; ``` -Defined in: [packages/vue-query/src/useQuery.ts:239](https://github.com/TanStack/query/blob/main/packages/vue-query/src/useQuery.ts#L239) +Defined in: [packages/vue-query/src/useQuery.ts:240](https://github.com/TanStack/query/blob/main/packages/vue-query/src/useQuery.ts#L240) `enabled` accepts a `ref`, a plain boolean, or a zero-argument getter (`() => ...`): a `ref` or a getter is tracked, while a plain boolean isn't tracked on its own. query-core's `(query) => boolean` callback is @@ -160,11 +160,12 @@ will be used. [`UseQueryReturnType`](../type-aliases/UseQueryReturnType.md)\<`TData`, `TError`\> -The current query result. `status` is `pending` if there is no cached data to display, `error` if -the last fetch attempt failed, or `success` if the query has data to display. `isPending`/`isSuccess`/`isError` -are derived boolean `ref`s for convenience. `state` is that result as one readonly reactive object — -`state.data`, `state.isPending`, and the rest are plain values, and `state.status === 'success'` narrows -`state.data` to `TData`. +The current query result. `status` is `error` if the last fetch failed after its retries or `select` +threw, `success` if the query has data to display (including `placeholderData`), and `pending` otherwise. A +refetch that starts without data to display clears the error and sets `status` back to `pending`. +`isPending`/`isSuccess`/`isError` are derived boolean `ref`s for convenience. `state` is that result as one +readonly reactive object — `state.data`, `state.isPending`, and the rest are plain values, and +`state.status === 'success'` narrows `state.data` to `TData`. ### Examples @@ -313,7 +314,7 @@ const { state } = useQuery({ function useQuery(options: MaybeRefOrGetter>, queryClient?: QueryClient): UseQueryReturnType; ``` -Defined in: [packages/vue-query/src/useQuery.ts:317](https://github.com/TanStack/query/blob/main/packages/vue-query/src/useQuery.ts#L317) +Defined in: [packages/vue-query/src/useQuery.ts:319](https://github.com/TanStack/query/blob/main/packages/vue-query/src/useQuery.ts#L319) Fallback overload for options whose `initialData` presence isn't statically known — for example, a `ref`/reactive object built up conditionally, rather than a plain object literal. Prefer one of the other @@ -364,11 +365,12 @@ will be used. [`UseQueryReturnType`](../type-aliases/UseQueryReturnType.md)\<`TData`, `TError`\> -The current query result. `status` is `pending` if there is no cached data to display, `error` if -the last fetch attempt failed, or `success` if the query has data to display. `isPending`/`isSuccess`/`isError` -are derived boolean `ref`s for convenience. `state` is that result as one readonly reactive object — -`state.data`, `state.isPending`, and the rest are plain values, and `state.status === 'success'` narrows -`state.data` to `TData`. +The current query result. `status` is `error` if the last fetch failed after its retries or `select` +threw, `success` if the query has data to display (including `placeholderData`), and `pending` otherwise. A +refetch that starts without data to display clears the error and sets `status` back to `pending`. +`isPending`/`isSuccess`/`isError` are derived boolean `ref`s for convenience. `state` is that result as one +readonly reactive object — `state.data`, `state.isPending`, and the rest are plain values, and +`state.status === 'success'` narrows `state.data` to `TData`. ### Examples @@ -442,8 +444,9 @@ will be used. [`UseQueryReturnType`](../type-aliases/UseQueryReturnType.md)\<`TData`, `TError`\> -The current query result. `status` is `pending` if there is no cached data to display, `error` if -the last fetch attempt failed, or `success` if the query has data to display. `isPending`/`isSuccess`/`isError` -are derived boolean `ref`s for convenience. `state` is that result as one readonly reactive object — -`state.data`, `state.isPending`, and the rest are plain values, and `state.status === 'success'` narrows -`state.data` to `TData`. +The current query result. `status` is `error` if the last fetch failed after its retries or `select` +threw, `success` if the query has data to display (including `placeholderData`), and `pending` otherwise. A +refetch that starts without data to display clears the error and sets `status` back to `pending`. +`isPending`/`isSuccess`/`isError` are derived boolean `ref`s for convenience. `state` is that result as one +readonly reactive object — `state.data`, `state.isPending`, and the rest are plain values, and +`state.status === 'success'` narrows `state.data` to `TData`. diff --git a/packages/angular-query-experimental/src/inject-query.ts b/packages/angular-query-experimental/src/inject-query.ts index a2599a2fe87..0c10d99fde8 100644 --- a/packages/angular-query-experimental/src/inject-query.ts +++ b/packages/angular-query-experimental/src/inject-query.ts @@ -90,9 +90,10 @@ export function injectQuery< * you can pass to `injectQuery`. Similar to `computed` from Angular, this function runs in the reactive * context, so signals read inside it (in `queryKey`, `enabled`, etc.) drive the query. * @param options - Additional configuration - * @returns The query result. `status()` is `'pending'` if there is no cached data to display, `'error'` if - * the last fetch attempt failed, or `'success'` if the query has data to display. `isPending`/`isSuccess`/ - * `isError` are type-guard methods for convenience. + * @returns The query result. `status()` is `'error'` if the last fetch failed after its retries or + * `select` threw, `'success'` if the query has data to display (including `placeholderData`), and + * `'pending'` otherwise. A refetch that starts without data to display clears the error and sets + * `status()` back to `'pending'`. `isPending`/`isSuccess`/`isError` are type-guard methods for convenience. * @see https://tanstack.com/query/latest/docs/framework/angular/guides/queries * @see {@link queryOptions} to share these options between `injectQuery` and imperative APIs like * `queryClient.fetchQuery`. diff --git a/packages/preact-query/src/useQuery.ts b/packages/preact-query/src/useQuery.ts index 38a8e356f0b..0113d225414 100644 --- a/packages/preact-query/src/useQuery.ts +++ b/packages/preact-query/src/useQuery.ts @@ -18,9 +18,10 @@ import type { * @param options - The {@link DefinedInitialDataOptions} to use — everything you can pass to `useQuery`, with `initialData` known to be defined. * @param queryClient - Use this to use a custom `QueryClient`. Otherwise, the one from the nearest context will * be used. - * @returns The current query result, typed so that `status` is `success` — or `error` if a fetch attempt - * fails while keeping the existing data (`status` never resolves to `pending` in this overload's type, - * since `initialData` guarantees data upfront). `isSuccess`/`isError` are derived booleans for convenience. + * @returns The current query result, typed so that `status` is `success` or `error` (`status` never + * resolves to `pending` in this overload's type, since `initialData` guarantees data upfront). `status` is + * `error` if the last fetch failed after its retries or `select` threw, and `success` otherwise. + * `isSuccess`/`isError` are derived booleans for convenience. * @see {@link queryOptions} to share these options between `useQuery` and imperative APIs like `queryClient.query`. * @example * ```tsx @@ -62,9 +63,10 @@ export function useQuery< * @param options - The {@link UndefinedInitialDataOptions} to use — everything you can pass to `useQuery`. * @param queryClient - Use this to use a custom `QueryClient`. Otherwise, the one from the nearest context will * be used. - * @returns The current query result. `status` is `pending` if there is no cached data to display, `error` if - * the last fetch attempt failed, or `success` if the query has data to display. `isPending`/`isSuccess`/`isError` - * are derived booleans for convenience. + * @returns The current query result. `status` is `error` if the last fetch failed after its retries or `select` + * threw, `success` if the query has data to display (including `placeholderData`), and `pending` otherwise. A + * refetch that starts without data to display clears the error and sets `status` back to `pending`. + * `isPending`/`isSuccess`/`isError` are derived booleans for convenience. * @see {@link queryOptions} to share these options between `useQuery` and imperative APIs like `queryClient.query`. * @example * ```tsx @@ -130,9 +132,10 @@ export function useQuery< * @param options - The {@link UseQueryOptions} to use — everything you can pass to `useQuery`. * @param queryClient - Use this to use a custom `QueryClient`. Otherwise, the one from the nearest context will * be used. - * @returns The current query result. `status` is `pending` if there is no cached data to display, `error` if - * the last fetch attempt failed, or `success` if the query has data to display. `isPending`/`isSuccess`/`isError` - * are derived booleans for convenience. + * @returns The current query result. `status` is `error` if the last fetch failed after its retries or `select` + * threw, `success` if the query has data to display (including `placeholderData`), and `pending` otherwise. A + * refetch that starts without data to display clears the error and sets `status` back to `pending`. + * `isPending`/`isSuccess`/`isError` are derived booleans for convenience. * @see {@link queryOptions} to share these options between `useQuery` and imperative APIs like `queryClient.query`. * @example * ```tsx diff --git a/packages/react-query/src/useQuery.ts b/packages/react-query/src/useQuery.ts index dfd49331657..5952690f703 100644 --- a/packages/react-query/src/useQuery.ts +++ b/packages/react-query/src/useQuery.ts @@ -18,9 +18,10 @@ import type { * @param options - The {@link DefinedInitialDataOptions} to use — everything you can pass to `useQuery`, with `initialData` known to be defined. * @param queryClient - Use this to use a custom `QueryClient`. Otherwise, the one from the nearest context will * be used. - * @returns The current query result, typed so that `status` is `success` — or `error` if a fetch attempt - * fails while keeping the existing data (`status` never resolves to `pending` in this overload's type, - * since `initialData` guarantees data upfront). `isSuccess`/`isError` are derived booleans for convenience. + * @returns The current query result, typed so that `status` is `success` or `error` (`status` never + * resolves to `pending` in this overload's type, since `initialData` guarantees data upfront). `status` is + * `error` if the last fetch failed after its retries or `select` threw, and `success` otherwise. + * `isSuccess`/`isError` are derived booleans for convenience. * @see {@link queryOptions} to share these options between `useQuery` and imperative APIs like `queryClient.query`. * @example * ```tsx @@ -62,9 +63,10 @@ export function useQuery< * @param options - The {@link UndefinedInitialDataOptions} to use — everything you can pass to `useQuery`. * @param queryClient - Use this to use a custom `QueryClient`. Otherwise, the one from the nearest context will * be used. - * @returns The current query result. `status` is `pending` if there is no cached data to display, `error` if - * the last fetch attempt failed, or `success` if the query has data to display. `isPending`/`isSuccess`/`isError` - * are derived booleans for convenience. + * @returns The current query result. `status` is `error` if the last fetch failed after its retries or `select` + * threw, `success` if the query has data to display (including `placeholderData`), and `pending` otherwise. A + * refetch that starts without data to display clears the error and sets `status` back to `pending`. + * `isPending`/`isSuccess`/`isError` are derived booleans for convenience. * @see {@link queryOptions} to share these options between `useQuery` and imperative APIs like `queryClient.query`. * @example * ```tsx @@ -130,9 +132,10 @@ export function useQuery< * @param options - The {@link UseQueryOptions} to use — everything you can pass to `useQuery`. * @param queryClient - Use this to use a custom `QueryClient`. Otherwise, the one from the nearest context will * be used. - * @returns The current query result. `status` is `pending` if there is no cached data to display, `error` if - * the last fetch attempt failed, or `success` if the query has data to display. `isPending`/`isSuccess`/`isError` - * are derived booleans for convenience. + * @returns The current query result. `status` is `error` if the last fetch failed after its retries or `select` + * threw, `success` if the query has data to display (including `placeholderData`), and `pending` otherwise. A + * refetch that starts without data to display clears the error and sets `status` back to `pending`. + * `isPending`/`isSuccess`/`isError` are derived booleans for convenience. * @see {@link queryOptions} to share these options between `useQuery` and imperative APIs like `queryClient.query`. * @example * ```tsx diff --git a/packages/solid-query/src/useQuery.ts b/packages/solid-query/src/useQuery.ts index 8b9d3a53e67..57fe22e8bd3 100644 --- a/packages/solid-query/src/useQuery.ts +++ b/packages/solid-query/src/useQuery.ts @@ -24,10 +24,10 @@ import type { * pass to `useQuery`, with `initialData` known to be defined. * @param queryClient - An accessor for a custom `QueryClient`. Otherwise, the one from the nearest context * will be used. - * @returns The current query result, as a Solid store, typed so that `status` is `success` — or `error` if a - * fetch attempt fails while keeping the existing data (`status` never resolves to `pending` in this overload's - * type, since `initialData` guarantees data upfront). `isSuccess`/`isError` are derived booleans for - * convenience. + * @returns The current query result, as a Solid store, typed so that `status` is `success` or `error` + * (`status` never resolves to `pending` in this overload's type, since `initialData` guarantees data upfront). + * `status` is `error` if the last fetch failed after its retries or `select` threw, and `success` otherwise. + * `isSuccess`/`isError` are derived booleans for convenience. * @see {@link queryOptions} to share these options between `useQuery` and imperative APIs like `queryClient.query`. * @example * ```tsx @@ -71,9 +71,10 @@ export function useQuery< * pass to `useQuery`. * @param queryClient - An accessor for a custom `QueryClient`. Otherwise, the one from the nearest context * will be used. - * @returns The current query result, as a Solid store. `status` is `pending` if there is no cached data to - * display, `error` if the last fetch attempt failed, or `success` if the query has data to display. - * `isPending`/`isSuccess`/`isError` are derived booleans for convenience. + * @returns The current query result, as a Solid store. `status` is `error` if the last fetch failed after + * its retries or `select` threw, `success` if the query has data to display (including `placeholderData`), + * and `pending` otherwise. A refetch that starts without data to display clears the error and sets + * `status` back to `pending`. `isPending`/`isSuccess`/`isError` are derived booleans for convenience. * @see {@link queryOptions} to share these options between `useQuery` and imperative APIs like `queryClient.query`. * @example * ```tsx diff --git a/packages/svelte-query/src/createQuery.ts b/packages/svelte-query/src/createQuery.ts index 9c53b49cae6..16f1bdea3f6 100644 --- a/packages/svelte-query/src/createQuery.ts +++ b/packages/svelte-query/src/createQuery.ts @@ -22,9 +22,10 @@ import type { * with `initialData` known to be defined, wrapped in an {@link Accessor} so options can be reactive. * @param queryClient - Use this to use a custom `QueryClient`. Otherwise, the one from the nearest context will * be used. - * @returns The current query result, typed so that `status` is `success` — or `error` if a fetch attempt - * fails while keeping the existing data (`status` never resolves to `pending` in this overload's type, - * since `initialData` guarantees data upfront). `isSuccess`/`isError` are derived booleans for convenience. + * @returns The current query result, typed so that `status` is `success` or `error` (`status` never + * resolves to `pending` in this overload's type, since `initialData` guarantees data upfront). `status` is + * `error` if the last fetch failed after its retries or `select` threw, and `success` otherwise. + * `isSuccess`/`isError` are derived booleans for convenience. * @see {@link queryOptions} to share these options between `createQuery` and imperative APIs like `queryClient.query`. * @example * ```svelte @@ -69,9 +70,10 @@ export function createQuery< * wrapped in an {@link Accessor} so options can be reactive. * @param queryClient - Use this to use a custom `QueryClient`. Otherwise, the one from the nearest context will * be used. - * @returns The current query result. `status` is `pending` if there is no cached data to display, `error` if - * the last fetch attempt failed, or `success` if the query has data to display. `isPending`/`isSuccess`/`isError` - * are derived booleans for convenience. + * @returns The current query result. `status` is `error` if the last fetch failed after its retries or `select` + * threw, `success` if the query has data to display (including `placeholderData`), and `pending` otherwise. A + * refetch that starts without data to display clears the error and sets `status` back to `pending`. + * `isPending`/`isSuccess`/`isError` are derived booleans for convenience. * @see {@link queryOptions} to share these options between `createQuery` and imperative APIs like `queryClient.query`. * @example * ```svelte @@ -141,9 +143,10 @@ export function createQuery< * in an {@link Accessor} so options can be reactive. * @param queryClient - Use this to use a custom `QueryClient`. Otherwise, the one from the nearest context will * be used. - * @returns The current query result. `status` is `pending` if there is no cached data to display, `error` if - * the last fetch attempt failed, or `success` if the query has data to display. `isPending`/`isSuccess`/`isError` - * are derived booleans for convenience. + * @returns The current query result. `status` is `error` if the last fetch failed after its retries or `select` + * threw, `success` if the query has data to display (including `placeholderData`), and `pending` otherwise. A + * refetch that starts without data to display clears the error and sets `status` back to `pending`. + * `isPending`/`isSuccess`/`isError` are derived booleans for convenience. * @see {@link queryOptions} to share these options between `createQuery` and imperative APIs like `queryClient.query`. * @example * `select` derives whatever `data` a component needs from the cached value, without changing what's diff --git a/packages/vue-query/src/useQuery.ts b/packages/vue-query/src/useQuery.ts index 5f40ef1b10e..bb60fa56a45 100644 --- a/packages/vue-query/src/useQuery.ts +++ b/packages/vue-query/src/useQuery.ts @@ -47,11 +47,11 @@ export type UseQueryDefinedReturnType = UseBaseQueryReturnType< * with `initialData` known to be defined. * @param queryClient - Use this to use a custom `QueryClient`. Otherwise, the one provided by `VueQueryPlugin` * will be used. - * @returns The current query result, typed so that `status` is `success` — or `error` if a fetch attempt - * fails while keeping the existing data (`status` never resolves to `pending` in this overload's type, - * since `initialData` guarantees data upfront). `isSuccess`/`isError` are derived boolean `ref`s for - * convenience. `state` is that result as one readonly reactive object — `state.data`, `state.isPending`, and - * the rest are plain values. + * @returns The current query result, typed so that `status` is `success` or `error` (`status` never resolves + * to `pending` in this overload's type, since `initialData` guarantees data upfront). `status` is `error` if + * the last fetch failed after its retries or `select` threw, and `success` otherwise. `isSuccess`/`isError` + * are derived boolean `ref`s for convenience. `state` is that result as one readonly reactive object — + * `state.data`, `state.isPending`, and the rest are plain values. * @example * ```vue *