From 01abab33f866299afa2aeebfd4e00fd0c2bbc4c8 Mon Sep 17 00:00:00 2001 From: Wonsuk Choi Date: Sun, 4 Oct 2026 12:29:23 +0900 Subject: [PATCH] docs(*): note that 'throwOnError' makes the hook rethrow the errors of 'mutate' (#11877) * docs(*): note that 'throwOnError' makes the hook rethrow the errors of 'mutate' * docs(angular-query-experimental/types): mention that 'injectMutation' emits the error on 'ngZone.onError' before rethrowing it --- .../angular/reference/interfaces/BaseMutationNarrowing.md | 2 +- .../reference/type-aliases/CreateBaseMutationResult.md | 2 +- .../reference/type-aliases/CreateMutateAsyncFunction.md | 2 +- .../angular/reference/type-aliases/CreateMutateFunction.md | 5 +++-- .../angular/reference/type-aliases/CreateMutationResult.md | 2 +- .../preact/reference/type-aliases/UseBaseMutationResult.md | 2 +- .../preact/reference/type-aliases/UseMutateAsyncFunction.md | 2 +- .../preact/reference/type-aliases/UseMutateFunction.md | 5 +++-- .../preact/reference/type-aliases/UseMutationResult.md | 2 +- .../react/reference/type-aliases/UseBaseMutationResult.md | 2 +- .../react/reference/type-aliases/UseMutateAsyncFunction.md | 2 +- .../react/reference/type-aliases/UseMutateFunction.md | 5 +++-- .../react/reference/type-aliases/UseMutationResult.md | 2 +- .../solid/reference/type-aliases/UseBaseMutationResult.md | 2 +- .../solid/reference/type-aliases/UseMutateAsyncFunction.md | 2 +- .../solid/reference/type-aliases/UseMutateFunction.md | 5 +++-- .../solid/reference/type-aliases/UseMutationResult.md | 2 +- packages/angular-query-experimental/src/types.ts | 3 ++- packages/preact-query/src/types.ts | 3 ++- packages/react-query/src/types.ts | 3 ++- packages/solid-query/src/types.ts | 3 ++- 21 files changed, 33 insertions(+), 25 deletions(-) diff --git a/docs/framework/angular/reference/interfaces/BaseMutationNarrowing.md b/docs/framework/angular/reference/interfaces/BaseMutationNarrowing.md index 4f60ea620f..3ff7534e61 100644 --- a/docs/framework/angular/reference/interfaces/BaseMutationNarrowing.md +++ b/docs/framework/angular/reference/interfaces/BaseMutationNarrowing.md @@ -3,7 +3,7 @@ id: BaseMutationNarrowing title: BaseMutationNarrowing --- -Defined in: [packages/angular-query-experimental/src/types.ts:314](https://github.com/TanStack/query/blob/main/packages/angular-query-experimental/src/types.ts#L314) +Defined in: [packages/angular-query-experimental/src/types.ts:315](https://github.com/TanStack/query/blob/main/packages/angular-query-experimental/src/types.ts#L315) The `isSuccess`/`isError`/`isPending`/`isIdle` methods on a mutation result. Each is both a `Signal` (its current boolean value is read reactively without calling it) and a type-guard function you can diff --git a/docs/framework/angular/reference/type-aliases/CreateBaseMutationResult.md b/docs/framework/angular/reference/type-aliases/CreateBaseMutationResult.md index e97ece225f..e6c2d3f283 100644 --- a/docs/framework/angular/reference/type-aliases/CreateBaseMutationResult.md +++ b/docs/framework/angular/reference/type-aliases/CreateBaseMutationResult.md @@ -9,7 +9,7 @@ type CreateBaseMutationResult = Over }> & object; ``` -Defined in: [packages/angular-query-experimental/src/types.ts:271](https://github.com/TanStack/query/blob/main/packages/angular-query-experimental/src/types.ts#L271) +Defined in: [packages/angular-query-experimental/src/types.ts:272](https://github.com/TanStack/query/blob/main/packages/angular-query-experimental/src/types.ts#L272) The pre-`Signal` shape [CreateMutationResult](CreateMutationResult.md) is built from — not what `injectMutation` actually returns. Same as [MutationObserverResult](MutationObserverResult.md) from `@tanstack/query-core`, with `mutate` narrowed to the diff --git a/docs/framework/angular/reference/type-aliases/CreateMutateAsyncFunction.md b/docs/framework/angular/reference/type-aliases/CreateMutateAsyncFunction.md index 9362687d33..8ae62742de 100644 --- a/docs/framework/angular/reference/type-aliases/CreateMutateAsyncFunction.md +++ b/docs/framework/angular/reference/type-aliases/CreateMutateAsyncFunction.md @@ -7,7 +7,7 @@ title: CreateMutateAsyncFunction type CreateMutateAsyncFunction = MutateFunction; ``` -Defined in: [packages/angular-query-experimental/src/types.ts:254](https://github.com/TanStack/query/blob/main/packages/angular-query-experimental/src/types.ts#L254) +Defined in: [packages/angular-query-experimental/src/types.ts:255](https://github.com/TanStack/query/blob/main/packages/angular-query-experimental/src/types.ts#L255) The type of `mutateAsync`, as returned by `injectMutation`. Similar to [CreateMutateFunction](CreateMutateFunction.md), but returns a promise which can be awaited. diff --git a/docs/framework/angular/reference/type-aliases/CreateMutateFunction.md b/docs/framework/angular/reference/type-aliases/CreateMutateFunction.md index e7f3b7bc0c..0c4414d648 100644 --- a/docs/framework/angular/reference/type-aliases/CreateMutateFunction.md +++ b/docs/framework/angular/reference/type-aliases/CreateMutateFunction.md @@ -7,11 +7,12 @@ title: CreateMutateFunction type CreateMutateFunction = (...args: Parameters>) => void; ``` -Defined in: [packages/angular-query-experimental/src/types.ts:234](https://github.com/TanStack/query/blob/main/packages/angular-query-experimental/src/types.ts#L234) +Defined in: [packages/angular-query-experimental/src/types.ts:235](https://github.com/TanStack/query/blob/main/packages/angular-query-experimental/src/types.ts#L235) The type of `mutate`, as returned by `injectMutation`. Forwards the variables (and an optional per-call `onSuccess`/`onError`/`onSettled`) to the underlying `mutate` call. Fire-and-forget — errors are surfaced -through the mutation result, not thrown. +through the mutation result instead of being thrown by `mutate`, unless `throwOnError` makes +`injectMutation` rethrow them after emitting them on `ngZone.onError`. ## Type Parameters diff --git a/docs/framework/angular/reference/type-aliases/CreateMutationResult.md b/docs/framework/angular/reference/type-aliases/CreateMutationResult.md index a0ba8bc26b..b2ab2cecf5 100644 --- a/docs/framework/angular/reference/type-aliases/CreateMutationResult.md +++ b/docs/framework/angular/reference/type-aliases/CreateMutationResult.md @@ -7,7 +7,7 @@ title: CreateMutationResult type CreateMutationResult = BaseMutationNarrowing & MapToSignals>; ``` -Defined in: [packages/angular-query-experimental/src/types.ts:401](https://github.com/TanStack/query/blob/main/packages/angular-query-experimental/src/types.ts#L401) +Defined in: [packages/angular-query-experimental/src/types.ts:402](https://github.com/TanStack/query/blob/main/packages/angular-query-experimental/src/types.ts#L402) The result of `injectMutation`. Based on [CreateBaseMutationResult](CreateBaseMutationResult.md), but value fields are exposed as a `Signal` — read them with `mutation.data()`, not `mutation.data` — while function fields (`mutate`, diff --git a/docs/framework/preact/reference/type-aliases/UseBaseMutationResult.md b/docs/framework/preact/reference/type-aliases/UseBaseMutationResult.md index 6d3f70b13a..18758dc974 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:451](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L451) +Defined in: [packages/preact-query/src/types.ts:452](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L452) 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 4a42eedc81..a8c3067eb4 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:435](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L435) +Defined in: [packages/preact-query/src/types.ts:436](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L436) 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 2c2d2b9012..f79f3821f6 100644 --- a/docs/framework/preact/reference/type-aliases/UseMutateFunction.md +++ b/docs/framework/preact/reference/type-aliases/UseMutateFunction.md @@ -7,11 +7,12 @@ title: UseMutateFunction type UseMutateFunction = (...args: Parameters>) => void; ``` -Defined in: [packages/preact-query/src/types.ts:415](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L415) +Defined in: [packages/preact-query/src/types.ts:416](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L416) 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 -through the mutation result, not thrown. +through the mutation result instead of being thrown by `mutate`, unless `throwOnError` makes `useMutation` +rethrow them. ## Type Parameters diff --git a/docs/framework/preact/reference/type-aliases/UseMutationResult.md b/docs/framework/preact/reference/type-aliases/UseMutationResult.md index 71914475aa..5f1770030e 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:479](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L479) +Defined in: [packages/preact-query/src/types.ts:480](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L480) The result of `useMutation`. Same as [UseBaseMutationResult](UseBaseMutationResult.md). diff --git a/docs/framework/react/reference/type-aliases/UseBaseMutationResult.md b/docs/framework/react/reference/type-aliases/UseBaseMutationResult.md index 51d7b34f7a..d51480247c 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:452](https://github.com/TanStack/query/blob/main/packages/react-query/src/types.ts#L452) +Defined in: [packages/react-query/src/types.ts:453](https://github.com/TanStack/query/blob/main/packages/react-query/src/types.ts#L453) 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 aa9a28b68d..e901426fea 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:436](https://github.com/TanStack/query/blob/main/packages/react-query/src/types.ts#L436) +Defined in: [packages/react-query/src/types.ts:437](https://github.com/TanStack/query/blob/main/packages/react-query/src/types.ts#L437) 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 d91f6f4cf6..f9c974e0eb 100644 --- a/docs/framework/react/reference/type-aliases/UseMutateFunction.md +++ b/docs/framework/react/reference/type-aliases/UseMutateFunction.md @@ -7,11 +7,12 @@ title: UseMutateFunction type UseMutateFunction = (...args: Parameters>) => void; ``` -Defined in: [packages/react-query/src/types.ts:416](https://github.com/TanStack/query/blob/main/packages/react-query/src/types.ts#L416) +Defined in: [packages/react-query/src/types.ts:417](https://github.com/TanStack/query/blob/main/packages/react-query/src/types.ts#L417) 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 -through the mutation result, not thrown. +through the mutation result instead of being thrown by `mutate`, unless `throwOnError` makes `useMutation` +rethrow them. ## Type Parameters diff --git a/docs/framework/react/reference/type-aliases/UseMutationResult.md b/docs/framework/react/reference/type-aliases/UseMutationResult.md index 96e66f8cb4..83022fc0d2 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:480](https://github.com/TanStack/query/blob/main/packages/react-query/src/types.ts#L480) +Defined in: [packages/react-query/src/types.ts:481](https://github.com/TanStack/query/blob/main/packages/react-query/src/types.ts#L481) The result of `useMutation`. Same as [UseBaseMutationResult](UseBaseMutationResult.md). diff --git a/docs/framework/solid/reference/type-aliases/UseBaseMutationResult.md b/docs/framework/solid/reference/type-aliases/UseBaseMutationResult.md index ab9640a875..acfb151b98 100644 --- a/docs/framework/solid/reference/type-aliases/UseBaseMutationResult.md +++ b/docs/framework/solid/reference/type-aliases/UseBaseMutationResult.md @@ -9,7 +9,7 @@ type UseBaseMutationResult = Overrid }> & object; ``` -Defined in: [packages/solid-query/src/types.ts:311](https://github.com/TanStack/query/blob/main/packages/solid-query/src/types.ts#L311) +Defined in: [packages/solid-query/src/types.ts:312](https://github.com/TanStack/query/blob/main/packages/solid-query/src/types.ts#L312) 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/solid/reference/type-aliases/UseMutateAsyncFunction.md b/docs/framework/solid/reference/type-aliases/UseMutateAsyncFunction.md index 2687cdcaa7..7641ed4c55 100644 --- a/docs/framework/solid/reference/type-aliases/UseMutateAsyncFunction.md +++ b/docs/framework/solid/reference/type-aliases/UseMutateAsyncFunction.md @@ -7,7 +7,7 @@ title: UseMutateAsyncFunction type UseMutateAsyncFunction = MutateFunction; ``` -Defined in: [packages/solid-query/src/types.ts:295](https://github.com/TanStack/query/blob/main/packages/solid-query/src/types.ts#L295) +Defined in: [packages/solid-query/src/types.ts:296](https://github.com/TanStack/query/blob/main/packages/solid-query/src/types.ts#L296) 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/solid/reference/type-aliases/UseMutateFunction.md b/docs/framework/solid/reference/type-aliases/UseMutateFunction.md index c421280b9a..53cfcb7e00 100644 --- a/docs/framework/solid/reference/type-aliases/UseMutateFunction.md +++ b/docs/framework/solid/reference/type-aliases/UseMutateFunction.md @@ -7,11 +7,12 @@ title: UseMutateFunction type UseMutateFunction = (...args: Parameters>) => void; ``` -Defined in: [packages/solid-query/src/types.ts:275](https://github.com/TanStack/query/blob/main/packages/solid-query/src/types.ts#L275) +Defined in: [packages/solid-query/src/types.ts:276](https://github.com/TanStack/query/blob/main/packages/solid-query/src/types.ts#L276) 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 -through the mutation result, not thrown. +through the mutation result instead of being thrown by `mutate`, unless `throwOnError` makes `useMutation` +rethrow them. ## Type Parameters diff --git a/docs/framework/solid/reference/type-aliases/UseMutationResult.md b/docs/framework/solid/reference/type-aliases/UseMutationResult.md index 6f6695656d..13c872565f 100644 --- a/docs/framework/solid/reference/type-aliases/UseMutationResult.md +++ b/docs/framework/solid/reference/type-aliases/UseMutationResult.md @@ -7,7 +7,7 @@ title: UseMutationResult type UseMutationResult = UseBaseMutationResult; ``` -Defined in: [packages/solid-query/src/types.ts:339](https://github.com/TanStack/query/blob/main/packages/solid-query/src/types.ts#L339) +Defined in: [packages/solid-query/src/types.ts:340](https://github.com/TanStack/query/blob/main/packages/solid-query/src/types.ts#L340) The result of `useMutation`. Same as [UseBaseMutationResult](UseBaseMutationResult.md). diff --git a/packages/angular-query-experimental/src/types.ts b/packages/angular-query-experimental/src/types.ts index b8c9befc01..268315555e 100644 --- a/packages/angular-query-experimental/src/types.ts +++ b/packages/angular-query-experimental/src/types.ts @@ -224,7 +224,8 @@ export interface CreateMutationOptions< /** * The type of `mutate`, as returned by `injectMutation`. Forwards the variables (and an optional per-call * `onSuccess`/`onError`/`onSettled`) to the underlying `mutate` call. Fire-and-forget — errors are surfaced - * through the mutation result, not thrown. + * through the mutation result instead of being thrown by `mutate`, unless `throwOnError` makes + * `injectMutation` rethrow them after emitting them on `ngZone.onError`. * @template TData - The type your mutation function resolves to. * @template TError - The type of errors your mutation function may throw. * @template TVariables - The type of the variable passed to `mutate`. diff --git a/packages/preact-query/src/types.ts b/packages/preact-query/src/types.ts index 49faaf155c..a9fd882269 100644 --- a/packages/preact-query/src/types.ts +++ b/packages/preact-query/src/types.ts @@ -405,7 +405,8 @@ export interface UseMutationOptions< /** * 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 - * through the mutation result, not thrown. + * through the mutation result instead of being thrown by `mutate`, unless `throwOnError` makes `useMutation` + * rethrow them. * @template TData - The type your mutation function resolves to. * @template TError - The type of errors your mutation function may throw. * @template TVariables - The type of the variable passed to `mutate`. diff --git a/packages/react-query/src/types.ts b/packages/react-query/src/types.ts index 7a4e5c52bd..8d6b23a02e 100644 --- a/packages/react-query/src/types.ts +++ b/packages/react-query/src/types.ts @@ -406,7 +406,8 @@ export interface UseMutationOptions< /** * 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 - * through the mutation result, not thrown. + * through the mutation result instead of being thrown by `mutate`, unless `throwOnError` makes `useMutation` + * rethrow them. * @template TData - The type your mutation function resolves to. * @template TError - The type of errors your mutation function may throw. * @template TVariables - The type of the variable passed to `mutate`. diff --git a/packages/solid-query/src/types.ts b/packages/solid-query/src/types.ts index 5bf5f7ca79..bc9161dcdc 100644 --- a/packages/solid-query/src/types.ts +++ b/packages/solid-query/src/types.ts @@ -265,7 +265,8 @@ export type UseMutationOptions< /** * 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 - * through the mutation result, not thrown. + * through the mutation result instead of being thrown by `mutate`, unless `throwOnError` makes `useMutation` + * rethrow them. * @template TData - The type your mutation function resolves to. * @template TError - The type of errors your mutation function may throw. * @template TVariables - The type of the variable passed to `mutate`.