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

Mutation.md

259 lines6.5 KB

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