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