Open History to see the last commit
1---
2id: Mutation
3title: Mutation
4---
5β
6Defined in: [packages/query-core/src/mutation.ts:138](https://github.com/TanStack/query/blob/main/packages/query-core/src/mutation.ts#L138)
7β
8Represents a single mutation attempt. A `Mutation` holds the mutation's
9options, state (data/error/status), and the `MutationObserver`s currently
10subscribed to it.
11β
12Instances are created and managed internally by `MutationCache`; application
13code typically interacts with mutations indirectly through `QueryClient` or
14a framework hook like `useMutation`. Direct access to a `Mutation` instance
15is possible via `mutationCache.find()`/`getAll()` for inspecting cache state.
16β
17## Example
18β
19```ts
20const mutationCache = queryClient.getMutationCache()
21β
22const mutation = mutationCache.find({ mutationKey: ['addPost'] })
23```
24β
25## Extends
26β
27- `Removable`
28β
29## Type Parameters
30β
31### TData
32β
33`TData` = `unknown`
34β
35### TError
36β
37`TError` = [`DefaultError`](../type-aliases/DefaultError.md)
38β
39### TVariables
40β
41`TVariables` = `unknown`
42β
43### TOnMutateResult
44β
45`TOnMutateResult` = `unknown`
46β
47## Constructors
48β
49### Constructor
50β
51```ts
52new Mutation<TData, TError, TVariables, TOnMutateResult>(config: MutationConfig<TData, TError, TVariables, TOnMutateResult>): Mutation<TData, TError, TVariables, TOnMutateResult>;
53```
54β
55Defined in: [packages/query-core/src/mutation.ts:155](https://github.com/TanStack/query/blob/main/packages/query-core/src/mutation.ts#L155)
56β
57#### Parameters
58β
59##### config
60β
61`MutationConfig`\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>
62β
63#### Returns
64β
65`Mutation`\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>
66β
67#### Overrides
68β
69```ts
70Removable.constructor
71```
72β
73## Properties
74β
75### gcTime
76β
77```ts
78gcTime: number;
79```
80β
81Defined in: [packages/query-core/src/removable.ts:11](https://github.com/TanStack/query/blob/main/packages/query-core/src/removable.ts#L11)
82β
83#### Inherited from
84β
85```ts
86Removable.gcTime
87```
88β
89***
90β
91### mutationId
92β
93```ts
94readonly mutationId: number;
95```
96β
97Defined in: [packages/query-core/src/mutation.ts:146](https://github.com/TanStack/query/blob/main/packages/query-core/src/mutation.ts#L146)
98β
99***
100β
101### options
102β
103```ts
104options: MutationOptions<TData, TError, TVariables, TOnMutateResult>;
105```
106β
107Defined in: [packages/query-core/src/mutation.ts:145](https://github.com/TanStack/query/blob/main/packages/query-core/src/mutation.ts#L145)
108β
109***
110β
111### state
112β
113```ts
114state: MutationState<TData, TError, TVariables, TOnMutateResult>;
115```
116β
117Defined in: [packages/query-core/src/mutation.ts:144](https://github.com/TanStack/query/blob/main/packages/query-core/src/mutation.ts#L144)
118β
119## Accessors
120β
121### meta
122β
123#### Get Signature
124β
125```ts
126get meta(): Record<string, unknown> | undefined;
127```
128β
129Defined in: [packages/query-core/src/mutation.ts:187](https://github.com/TanStack/query/blob/main/packages/query-core/src/mutation.ts#L187)
130β
131The `meta` object passed in the mutation's options, if any.
132β
133##### Returns
134β
135`Record`\<`string`, `unknown`\> \| `undefined`
136β
137The mutation's `meta`, or `undefined` if none was set.
138β
139## Methods
140β
141### continue()
142β
143```ts
144continue(): Promise<unknown>;
145```
146β
147Defined in: [packages/query-core/src/mutation.ts:260](https://github.com/TanStack/query/blob/main/packages/query-core/src/mutation.ts#L260)
148β
149Resumes a mutation that is currently paused or was restored from a
150dehydrated, still-`pending` state.
151β
152- If this mutation has an active retryer (it paused mid-attempt, e.g. due
153 to the network mode or scope-based queuing), its retryer is resumed.
154- Otherwise, if the mutation's status is still `pending` (e.g. it was
155 dehydrated while an attempt was in flight and never got a retryer in
156 this instance), `execute` is called again with the last known variables.
157- Otherwise the mutation has already settled and this resolves immediately
158 without running anything again.
159β
160#### Returns
161β
162`Promise`\<`unknown`\>
163β
164A promise that settles with the resumed mutation: it rejects if the mutation fails.
165It resolves immediately if the mutation has already settled.
166β
167#### See
168β
169[Mutation#execute](#execute)
170β
171#### Example
172β
173```ts
174// typically driven by reconnect handling, e.g. queryClient.resumePausedMutations()
175const mutation = mutationCache.find({ mutationKey: ['addPost'] })
176await mutation?.continue()
177```
178β
179***
180β
181### destroy()
182β
183```ts
184destroy(): void;
185```
186β
187Defined in: [packages/query-core/src/removable.ts:19](https://github.com/TanStack/query/blob/main/packages/query-core/src/removable.ts#L19)
188β
189Clears the pending garbage collection timeout, so the entry is no longer scheduled for removal.
190A subclass may override this to release what it holds on to as well β `Query` also cancels any
191in-flight fetch.
192β
193#### Returns
194β
195`void`
196β
197#### Inherited from
198β
199```ts
200Removable.destroy
201```
202β
203***
204β
205### execute()
206β
207```ts
208execute(variables: TVariables): Promise<TData>;
209```
210β
211Defined in: [packages/query-core/src/mutation.ts:301](https://github.com/TanStack/query/blob/main/packages/query-core/src/mutation.ts#L301)
212β
213Runs the mutation function for the given variables through a retryer, and
214drives the mutation's state and lifecycle callbacks through to settlement.
215β
216If this mutation's state is already `pending` when `execute` is called
217(i.e. it was restored, still in-flight, from a dehydrated state), the
218`onMutate` step is skipped and a `continue` action is dispatched to
219unpause it; otherwise a `pending` action is dispatched first, then the
220mutation cache's `onMutate` and the mutation's own `onMutate` option are
221awaited in that order, and the resulting context is stored.
222β
223The mutation function is then run (subject to `retry`/`retryDelay`/
224`networkMode`, and to the mutation cache's scope-based serialization).
225On success, the cache's `onSuccess`/`onSettled` callbacks run before the
226mutation's own `onSuccess`/`onSettled` options, a `success` action is
227dispatched, and the resolved data is returned. On failure, the same
228cache-then-option ordering is used for `onError`/`onSettled`, but each of
229those four callbacks is individually caught so that a throwing callback
230cannot mask the original error; an `error` action is then dispatched and
231the original error is re-thrown.
232β
233#### Parameters
234β
235##### variables
236β
237`TVariables`
238β
239The variables passed to the `mutationFn`.
240β
241#### Returns
242β
243`Promise`\<`TData`\>
244β
245A promise that resolves with the mutation's data, or rejects with its error.
246β
247#### See
248β
249[Mutation#continue](#continue)
250β
251#### Example
252β
253```ts
254// Called internally by `MutationObserver.mutate` and `Mutation.continue` β
255// applications normally trigger mutations through those, not this method.
256const data = await mutation.execute(variables)
257```