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

MutationObserver.md

293 lines7.1 KB

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