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

MutationObserver.md

291 lines7.1 KB

1---
2id: MutationObserver
3title: MutationObserver
4---
5​
6Defined in: [packages/query-core/src/mutationObserver.ts:37](https://github.com/TanStack/query/blob/main/packages/query-core/src/mutationObserver.ts#L37)
7​
8Observes a single mutation and derives a `MutationObserverResult` from it.
9A framework hook like `useMutation` creates one `MutationObserver` per hook
10call, keeps it stable across re-renders, calls `setOptions` when the options
11passed to the hook change, subscribes to it to re-render on updates, and
12reads `getCurrentResult()` for the value to return. Calling `mutate()`
13builds a new underlying `Mutation` in the `MutationCache` and executes it.
14​
15## Example
16​
17```ts
18const observer = new MutationObserver(queryClient, {
19 mutationFn: (variables: { title: string }) => addPost(variables),
20})
21```
22​
23## Extends
24​
25- `Subscribable`\<`MutationObserverListener`\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>\>
26​
27## Type Parameters
28​
29### TData
30​
31`TData` = `unknown`
32​
33### TError
34​
35`TError` = [`DefaultError`](../type-aliases/DefaultError.md)
36​
37### TVariables
38​
39`TVariables` = `void`
40​
41### TOnMutateResult
42​
43`TOnMutateResult` = `unknown`
44​
45## Constructors
46​
47### Constructor
48​
49```ts
50new MutationObserver<TData, TError, TVariables, TOnMutateResult>(client: QueryClient, options: MutationObserverOptions<TData, TError, TVariables, TOnMutateResult>): MutationObserver<TData, TError, TVariables, TOnMutateResult>;
51```
52​
53Defined in: [packages/query-core/src/mutationObserver.ts:57](https://github.com/TanStack/query/blob/main/packages/query-core/src/mutationObserver.ts#L57)
54​
55#### Parameters
56​
57##### client
58​
59[`QueryClient`](QueryClient.md)
60​
61##### options
62​
63[`MutationObserverOptions`](../interfaces/MutationObserverOptions.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>
64​
65#### Returns
66​
67`MutationObserver`\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>
68​
69#### Overrides
70​
71```ts
72Subscribable<
73 MutationObserverListener<TData, TError, TVariables, TOnMutateResult>
74>.constructor
75```
76​
77## Properties
78​
79### options
80​
81```ts
82options: MutationObserverOptions<TData, TError, TVariables, TOnMutateResult>;
83```
84​
85Defined in: [packages/query-core/src/mutationObserver.ts:45](https://github.com/TanStack/query/blob/main/packages/query-core/src/mutationObserver.ts#L45)
86​
87## Methods
88​
89### getCurrentResult()
90​
91```ts
92getCurrentResult(): MutationObserverResult<TData, TError, TVariables, TOnMutateResult>;
93```
94​
95Defined in: [packages/query-core/src/mutationObserver.ts:165](https://github.com/TanStack/query/blob/main/packages/query-core/src/mutationObserver.ts#L165)
96​
97Returns the observer's current result, derived from the observed
98mutation's state (or the default, `idle` state if no mutation has been
99built yet, e.g. before the first `mutate()` call or after `reset()`).
100​
101#### Returns
102​
103[`MutationObserverResult`](../type-aliases/MutationObserverResult.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>
104​
105The observer's latest result.
106​
107***
108​
109### hasListeners()
110​
111```ts
112hasListeners(): boolean;
113```
114​
115Defined in: [packages/query-core/src/subscribable.ts:43](https://github.com/TanStack/query/blob/main/packages/query-core/src/subscribable.ts#L43)
116​
117Returns `true` while at least one listener is registered, `false` once they have all unsubscribed.
118​
119#### Returns
120​
121`boolean`
122​
123`true` if at least one listener is registered.
124​
125#### Inherited from
126​
127```ts
128Subscribable.hasListeners
129```
130​
131***
132​
133### mutate()
134​
135```ts
136mutate(variables: TVariables, options?: MutateOptions<TData, TError, TVariables, TOnMutateResult>): Promise<TData>;
137```
138​
139Defined in: [packages/query-core/src/mutationObserver.ts:217](https://github.com/TanStack/query/blob/main/packages/query-core/src/mutationObserver.ts#L217)
140​
141Builds a new `Mutation` in the `MutationCache` using the observer's
142current options, detaches this observer from any previously observed
143mutation, attaches it to the new one, and executes it with the given
144variables.
145​
146The optional per-call `options` (`onSuccess`/`onError`/`onSettled`) are
147invoked once the mutation settles, in addition to any callbacks defined
148on the observer's own options.
149​
150#### Parameters
151​
152##### variables
153​
154`TVariables`
155​
156The variables passed to the `mutationFn`.
157​
158##### options?
159​
160[`MutateOptions`](../interfaces/MutateOptions.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>
161​
162Per-call `onSuccess`, `onError`, and `onSettled` callbacks.
163​
164#### Returns
165​
166`Promise`\<`TData`\>
167​
168A promise that resolves with the mutation's data, or rejects with its error.
169​
170#### Example
171​
172```ts
173await observer.mutate(
174 { title: 'New post' },
175 { onSuccess: (data) => console.log(data) },
177```
178​
179***
180​
181### reset()
182​
183```ts
184reset(): void;
185```
186​
187Defined in: [packages/query-core/src/mutationObserver.ts:188](https://github.com/TanStack/query/blob/main/packages/query-core/src/mutationObserver.ts#L188)
188​
189Detaches the observer from the mutation it is currently observing (if
190any) and resets the observed result back to its default, `idle` state.
191​
192This does not cancel an in-flight mutation; the mutation itself keeps
193running to completion and its own callbacks still fire, but this
194observer stops reflecting its state and a subsequent `mutate()` call
195will build a brand new mutation.
196​
197#### Returns
198​
199`void`
200​
201#### See
202​
203[MutationObserver#mutate](#mutate)
204​
205#### Example
206​
207```ts
208observer.reset()
209```
210​
211***
212​
213### setOptions()
214​
215```ts
216setOptions(options: MutationObserverOptions<TData, TError, TVariables, TOnMutateResult>): void;
217```
218​
219Defined in: [packages/query-core/src/mutationObserver.ts:100](https://github.com/TanStack/query/blob/main/packages/query-core/src/mutationObserver.ts#L100)
220​
221Updates the observer's options.
222​
223If the new `mutationKey` differs from the previous one (and both were
224defined), the observer is reset, detaching it from the mutation it was
225observing. Otherwise, if the currently observed mutation is still
226`pending`, its options are updated in place as well.
227​
228#### Parameters
229​
230##### options
231​
232[`MutationObserverOptions`](../interfaces/MutationObserverOptions.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>
233​
234The new mutation observer options. They are defaulted with [QueryClient#defaultMutationOptions](QueryClient.md#defaultmutationoptions) before being applied.
235​
236#### Returns
237​
238`void`
239​
240#### Example
241​
242```ts
243observer.setOptions({
244 mutationFn: (variables: { title: string }) => addPost(variables),
245 onSuccess: (data) => console.log(data),
246})
247```
248​
249***
250​
251### subscribe()
252​
253```ts
254subscribe(listener: MutationObserverListener): () => void;
255```
256​
257Defined in: [packages/query-core/src/subscribable.ts:28](https://github.com/TanStack/query/blob/main/packages/query-core/src/subscribable.ts#L28)
258​
259Registers a listener to be called on every update this object notifies about. Returns a function
260that removes the listener again β€” call it to stop listening. The base class never drops a listener
261on its own, though some subclasses clear all of theirs in `destroy()`.
262​
263#### Parameters
264​
265##### listener
266​
267`MutationObserverListener`
268​
269Called on each update, with whatever the subclass passes to its subscribers.
270​
271#### Returns
272​
273A function that removes the listener.
274​
275() => `void`
276​
277#### Example
278​
279```ts
280const unsubscribe = subscribable.subscribe(() => {
281 // react to the update
282})
283​
284unsubscribe()
285```
286​
287#### Inherited from
288​
289```ts
290Subscribable.subscribe
291```