Skip to content
Source
Sign inSign up
TanStack/query
Open History to see the last commit

Mutation.md

257 lines6.4 KB

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```