--- id: Mutation title: Mutation --- Defined in: [packages/query-core/src/mutation.ts:135](https://github.com/TanStack/query/blob/main/packages/query-core/src/mutation.ts#L135) Represents a single mutation attempt. A `Mutation` holds the mutation's options, state (data/error/status), and the `MutationObserver`s currently subscribed to it. Instances are created and managed internally by `MutationCache`; application code typically interacts with mutations indirectly through `QueryClient` or a framework hook like `useMutation`. Direct access to a `Mutation` instance is possible via `mutationCache.find()`/`getAll()` for inspecting cache state. ## Example ```ts const mutationCache = queryClient.getMutationCache() const mutation = mutationCache.find({ mutationKey: ['addPost'] }) ``` ## Extends - `Removable` ## Type Parameters ### TData `TData` = `unknown` ### TError `TError` = [`DefaultError`](../type-aliases/DefaultError.md) ### TVariables `TVariables` = `unknown` ### TOnMutateResult `TOnMutateResult` = `unknown` ## Constructors ### Constructor ```ts new Mutation(config): Mutation; ``` Defined in: [packages/query-core/src/mutation.ts:152](https://github.com/TanStack/query/blob/main/packages/query-core/src/mutation.ts#L152) #### Parameters ##### config `MutationConfig`\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\> #### Returns `Mutation`\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\> #### Overrides ```ts Removable.constructor ``` ## Properties ### gcTime ```ts gcTime: number; ``` Defined in: [packages/query-core/src/removable.ts:7](https://github.com/TanStack/query/blob/main/packages/query-core/src/removable.ts#L7) #### Inherited from ```ts Removable.gcTime ``` *** ### mutationId ```ts readonly mutationId: number; ``` Defined in: [packages/query-core/src/mutation.ts:143](https://github.com/TanStack/query/blob/main/packages/query-core/src/mutation.ts#L143) *** ### options ```ts options: MutationOptions; ``` Defined in: [packages/query-core/src/mutation.ts:142](https://github.com/TanStack/query/blob/main/packages/query-core/src/mutation.ts#L142) *** ### state ```ts state: MutationState; ``` Defined in: [packages/query-core/src/mutation.ts:141](https://github.com/TanStack/query/blob/main/packages/query-core/src/mutation.ts#L141) ## Accessors ### meta #### Get Signature ```ts get meta(): Record | undefined; ``` Defined in: [packages/query-core/src/mutation.ts:179](https://github.com/TanStack/query/blob/main/packages/query-core/src/mutation.ts#L179) The `meta` object passed in the mutation's options, if any. ##### Returns `Record`\<`string`, `unknown`\> \| `undefined` ## Methods ### clearGcTimeout() ```ts protected clearGcTimeout(): void; ``` Defined in: [packages/query-core/src/removable.ts:32](https://github.com/TanStack/query/blob/main/packages/query-core/src/removable.ts#L32) #### Returns `void` #### Inherited from ```ts Removable.clearGcTimeout ``` *** ### continue() ```ts continue(): Promise; ``` Defined in: [packages/query-core/src/mutation.ts:243](https://github.com/TanStack/query/blob/main/packages/query-core/src/mutation.ts#L243) Resumes a mutation that is currently paused or was restored from a dehydrated, still-`pending` state. - If this mutation has an active retryer (it paused mid-attempt, e.g. due to the network mode or scope-based queuing), its retryer is resumed. - Otherwise, if the mutation's status is still `pending` (e.g. it was dehydrated while an attempt was in flight and never got a retryer in this instance), `execute` is called again with the last known variables. - Otherwise the mutation has already settled and this resolves immediately without running anything again. #### Returns `Promise`\<`unknown`\> #### Example ```ts // typically driven by reconnect handling, e.g. queryClient.resumePausedMutations() const mutation = mutationCache.find({ mutationKey: ['addPost'] }) await mutation?.continue() ``` #### See [Mutation#execute](#execute) *** ### destroy() ```ts destroy(): void; ``` Defined in: [packages/query-core/src/removable.ts:10](https://github.com/TanStack/query/blob/main/packages/query-core/src/removable.ts#L10) #### Returns `void` #### Inherited from ```ts Removable.destroy ``` *** ### execute() ```ts execute(variables): Promise; ``` Defined in: [packages/query-core/src/mutation.ts:284](https://github.com/TanStack/query/blob/main/packages/query-core/src/mutation.ts#L284) Runs the mutation function for the given variables through a retryer, and drives the mutation's state and lifecycle callbacks through to settlement. If this mutation's state is already `pending` when `execute` is called (i.e. it was restored, still in-flight, from a dehydrated state), the `onMutate` step is skipped and a `continue` action is dispatched to unpause it; otherwise a `pending` action is dispatched first, then the mutation cache's `onMutate` and the mutation's own `onMutate` option are awaited in that order, and the resulting context is stored. The mutation function is then run (subject to `retry`/`retryDelay`/ `networkMode`, and to the mutation cache's scope-based serialization). On success, the cache's `onSuccess`/`onSettled` callbacks run before the mutation's own `onSuccess`/`onSettled` options, a `success` action is dispatched, and the resolved data is returned. On failure, the same cache-then-option ordering is used for `onError`/`onSettled`, but each of those four callbacks is individually caught so that a throwing callback cannot mask the original error; an `error` action is then dispatched and the original error is re-thrown. #### Parameters ##### variables `TVariables` #### Returns `Promise`\<`TData`\> #### Example ```ts // Called internally by `MutationObserver.mutate` and `Mutation.continue` — // applications normally trigger mutations through those, not this method. const data = await mutation.execute(variables) ``` #### See [Mutation#continue](#continue) *** ### optionalRemove() ```ts protected optionalRemove(): void; ``` Defined in: [packages/query-core/src/mutation.ts:212](https://github.com/TanStack/query/blob/main/packages/query-core/src/mutation.ts#L212) #### Returns `void` #### Overrides ```ts Removable.optionalRemove ``` *** ### scheduleGc() ```ts protected scheduleGc(): void; ``` Defined in: [packages/query-core/src/removable.ts:14](https://github.com/TanStack/query/blob/main/packages/query-core/src/removable.ts#L14) #### Returns `void` #### Inherited from ```ts Removable.scheduleGc ``` *** ### updateGcTime() ```ts protected updateGcTime(newGcTime): void; ``` Defined in: [packages/query-core/src/removable.ts:24](https://github.com/TanStack/query/blob/main/packages/query-core/src/removable.ts#L24) #### Parameters ##### newGcTime `number` | `undefined` #### Returns `void` #### Inherited from ```ts Removable.updateGcTime ```