336 lines
7.0 KiB
Markdown
336 lines
7.0 KiB
Markdown
---
|
|
id: MutationObserver
|
|
title: MutationObserver
|
|
---
|
|
|
|
Defined in: [packages/query-core/src/mutationObserver.ts:38](https://github.com/TanStack/query/blob/main/packages/query-core/src/mutationObserver.ts#L38)
|
|
|
|
Observes a single mutation and derives a `MutationObserverResult` from it.
|
|
A framework hook like `useMutation` creates one `MutationObserver` per hook
|
|
call, keeps it stable across re-renders, calls `setOptions` when the options
|
|
passed to the hook change, subscribes to it to re-render on updates, and
|
|
reads `getCurrentResult()` for the value to return. Calling `mutate()`
|
|
builds a new underlying `Mutation` in the `MutationCache` and executes it.
|
|
|
|
## Example
|
|
|
|
```ts
|
|
const observer = new MutationObserver(queryClient, {
|
|
mutationFn: (variables: { title: string }) => addPost(variables),
|
|
})
|
|
```
|
|
|
|
## Extends
|
|
|
|
- `Subscribable`\<`MutationObserverListener`\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>\>
|
|
|
|
## Type Parameters
|
|
|
|
### TData
|
|
|
|
`TData` = `unknown`
|
|
|
|
### TError
|
|
|
|
`TError` = [`DefaultError`](../type-aliases/DefaultError.md)
|
|
|
|
### TVariables
|
|
|
|
`TVariables` = `void`
|
|
|
|
### TOnMutateResult
|
|
|
|
`TOnMutateResult` = `unknown`
|
|
|
|
## Constructors
|
|
|
|
### Constructor
|
|
|
|
```ts
|
|
new MutationObserver<TData, TError, TVariables, TOnMutateResult>(client, options): MutationObserver<TData, TError, TVariables, TOnMutateResult>;
|
|
```
|
|
|
|
Defined in: [packages/query-core/src/mutationObserver.ts:58](https://github.com/TanStack/query/blob/main/packages/query-core/src/mutationObserver.ts#L58)
|
|
|
|
#### Parameters
|
|
|
|
##### client
|
|
|
|
`QueryClient`
|
|
|
|
##### options
|
|
|
|
[`MutationObserverOptions`](../interfaces/MutationObserverOptions.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>
|
|
|
|
#### Returns
|
|
|
|
`MutationObserver`\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>
|
|
|
|
#### Overrides
|
|
|
|
```ts
|
|
Subscribable<
|
|
MutationObserverListener<TData, TError, TVariables, TOnMutateResult>
|
|
>.constructor
|
|
```
|
|
|
|
## Properties
|
|
|
|
### listeners
|
|
|
|
```ts
|
|
protected listeners: Set<MutationObserverListener<TData, TError, TVariables, TOnMutateResult>>;
|
|
```
|
|
|
|
Defined in: [packages/query-core/src/subscribable.ts:2](https://github.com/TanStack/query/blob/main/packages/query-core/src/subscribable.ts#L2)
|
|
|
|
#### Inherited from
|
|
|
|
```ts
|
|
Subscribable.listeners
|
|
```
|
|
|
|
***
|
|
|
|
### options
|
|
|
|
```ts
|
|
options: MutationObserverOptions<TData, TError, TVariables, TOnMutateResult>;
|
|
```
|
|
|
|
Defined in: [packages/query-core/src/mutationObserver.ts:46](https://github.com/TanStack/query/blob/main/packages/query-core/src/mutationObserver.ts#L46)
|
|
|
|
## Methods
|
|
|
|
### bindMethods()
|
|
|
|
```ts
|
|
protected bindMethods(): void;
|
|
```
|
|
|
|
Defined in: [packages/query-core/src/mutationObserver.ts:75](https://github.com/TanStack/query/blob/main/packages/query-core/src/mutationObserver.ts#L75)
|
|
|
|
#### Returns
|
|
|
|
`void`
|
|
|
|
***
|
|
|
|
### getCurrentResult()
|
|
|
|
```ts
|
|
getCurrentResult(): MutationObserverResult<TData, TError, TVariables, TOnMutateResult>;
|
|
```
|
|
|
|
Defined in: [packages/query-core/src/mutationObserver.ts:155](https://github.com/TanStack/query/blob/main/packages/query-core/src/mutationObserver.ts#L155)
|
|
|
|
Returns the observer's current result, derived from the observed
|
|
mutation's state (or the default, `idle` state if no mutation has been
|
|
built yet, e.g. before the first `mutate()` call or after `reset()`).
|
|
|
|
#### Returns
|
|
|
|
[`MutationObserverResult`](../type-aliases/MutationObserverResult.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>
|
|
|
|
***
|
|
|
|
### hasListeners()
|
|
|
|
```ts
|
|
hasListeners(): boolean;
|
|
```
|
|
|
|
Defined in: [packages/query-core/src/subscribable.ts:19](https://github.com/TanStack/query/blob/main/packages/query-core/src/subscribable.ts#L19)
|
|
|
|
#### Returns
|
|
|
|
`boolean`
|
|
|
|
#### Inherited from
|
|
|
|
```ts
|
|
Subscribable.hasListeners
|
|
```
|
|
|
|
***
|
|
|
|
### mutate()
|
|
|
|
```ts
|
|
mutate(variables, options?): Promise<TData>;
|
|
```
|
|
|
|
Defined in: [packages/query-core/src/mutationObserver.ts:207](https://github.com/TanStack/query/blob/main/packages/query-core/src/mutationObserver.ts#L207)
|
|
|
|
Builds a new `Mutation` in the `MutationCache` using the observer's
|
|
current options, detaches this observer from any previously observed
|
|
mutation, attaches it to the new one, and executes it with the given
|
|
variables.
|
|
|
|
The optional per-call `options` (`onSuccess`/`onError`/`onSettled`) are
|
|
invoked once the mutation settles, in addition to any callbacks defined
|
|
on the observer's own options.
|
|
|
|
#### Parameters
|
|
|
|
##### variables
|
|
|
|
`TVariables`
|
|
|
|
##### options?
|
|
|
|
[`MutateOptions`](../interfaces/MutateOptions.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>
|
|
|
|
#### Returns
|
|
|
|
`Promise`\<`TData`\>
|
|
|
|
#### Example
|
|
|
|
```ts
|
|
await observer.mutate(
|
|
{ title: 'New post' },
|
|
{ onSuccess: (data) => console.log(data) },
|
|
)
|
|
```
|
|
|
|
***
|
|
|
|
### onSubscribe()
|
|
|
|
```ts
|
|
protected onSubscribe(): void;
|
|
```
|
|
|
|
Defined in: [packages/query-core/src/mutationObserver.ts:127](https://github.com/TanStack/query/blob/main/packages/query-core/src/mutationObserver.ts#L127)
|
|
|
|
#### Returns
|
|
|
|
`void`
|
|
|
|
#### Overrides
|
|
|
|
```ts
|
|
Subscribable.onSubscribe
|
|
```
|
|
|
|
***
|
|
|
|
### onUnsubscribe()
|
|
|
|
```ts
|
|
protected onUnsubscribe(): void;
|
|
```
|
|
|
|
Defined in: [packages/query-core/src/mutationObserver.ts:135](https://github.com/TanStack/query/blob/main/packages/query-core/src/mutationObserver.ts#L135)
|
|
|
|
#### Returns
|
|
|
|
`void`
|
|
|
|
#### Overrides
|
|
|
|
```ts
|
|
Subscribable.onUnsubscribe
|
|
```
|
|
|
|
***
|
|
|
|
### reset()
|
|
|
|
```ts
|
|
reset(): void;
|
|
```
|
|
|
|
Defined in: [packages/query-core/src/mutationObserver.ts:180](https://github.com/TanStack/query/blob/main/packages/query-core/src/mutationObserver.ts#L180)
|
|
|
|
Detaches the observer from the mutation it is currently observing (if
|
|
any) and resets the observed result back to its default, `idle` state.
|
|
|
|
This does not cancel an in-flight mutation; the mutation itself keeps
|
|
running to completion and its own callbacks still fire, but this
|
|
observer stops reflecting its state and a subsequent `mutate()` call
|
|
will build a brand new mutation.
|
|
|
|
#### Returns
|
|
|
|
`void`
|
|
|
|
#### Example
|
|
|
|
```ts
|
|
observer.reset()
|
|
```
|
|
|
|
#### See
|
|
|
|
[MutationObserver#mutate](#mutate)
|
|
|
|
***
|
|
|
|
### setOptions()
|
|
|
|
```ts
|
|
setOptions(options): void;
|
|
```
|
|
|
|
Defined in: [packages/query-core/src/mutationObserver.ts:96](https://github.com/TanStack/query/blob/main/packages/query-core/src/mutationObserver.ts#L96)
|
|
|
|
Updates the observer's options.
|
|
|
|
If the new `mutationKey` differs from the previous one (and both were
|
|
defined), the observer is reset, detaching it from the mutation it was
|
|
observing. Otherwise, if the currently observed mutation is still
|
|
`pending`, its options are updated in place as well.
|
|
|
|
#### Parameters
|
|
|
|
##### options
|
|
|
|
[`MutationObserverOptions`](../interfaces/MutationObserverOptions.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>
|
|
|
|
#### Returns
|
|
|
|
`void`
|
|
|
|
#### Example
|
|
|
|
```ts
|
|
observer.setOptions({
|
|
mutationFn: (variables: { title: string }) => addPost(variables),
|
|
onSuccess: (data) => console.log(data),
|
|
})
|
|
```
|
|
|
|
***
|
|
|
|
### subscribe()
|
|
|
|
```ts
|
|
subscribe(listener): () => void;
|
|
```
|
|
|
|
Defined in: [packages/query-core/src/subscribable.ts:8](https://github.com/TanStack/query/blob/main/packages/query-core/src/subscribable.ts#L8)
|
|
|
|
#### Parameters
|
|
|
|
##### listener
|
|
|
|
`MutationObserverListener`
|
|
|
|
#### Returns
|
|
|
|
```ts
|
|
(): void;
|
|
```
|
|
|
|
##### Returns
|
|
|
|
`void`
|
|
|
|
#### Inherited from
|
|
|
|
```ts
|
|
Subscribable.subscribe
|
|
```
|