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

mutationOptions.md

216 lines7.2 KB

1---
2id: mutationOptions
3title: mutationOptions
4---
5​
6<!-- DO NOT EDIT: this page is autogenerated from the type comments -->
7​
8## Overview
9​
10```ts
11function mutationOptions<TData = unknown, TError = Error, TVariables = void, TOnMutateResult = unknown>(options: WithRequired<CreateMutationOptions<TData, TError, TVariables, TOnMutateResult>, "mutationKey">): WithRequired<CreateMutationOptions<TData, TError, TVariables, TOnMutateResult>, "mutationKey">;
12function mutationOptions<TData = unknown, TError = Error, TVariables = void, TOnMutateResult = unknown>(options: Omit<CreateMutationOptions<TData, TError, TVariables, TOnMutateResult>, "mutationKey">): Omit<CreateMutationOptions<TData, TError, TVariables, TOnMutateResult>, "mutationKey">;
13```
14​
15- [`WithRequired<CreateMutationOptions>` β†’ `WithRequired<CreateMutationOptions>`](#call-signature-1): You can generally pass everything to `mutationOptions` that you can also pass to `injectMutation`. A `mutationKey` is required on this overload so the mutation can be looked up later, e.g. with `injectMutationState`.
16- [`Omit<CreateMutationOptions>` β†’ `Omit<CreateMutationOptions>`](#call-signature-2): You can generally pass everything to `mutationOptions` that you can also pass to `injectMutation`. No `mutationKey` is required on this overload β€” use this when you don't need to target the mutation via a `mutationKey` filter later (e.g. with `injectMutationState`); it can still be observed through other filters, such as `status`.
17​
18See also: [Parameters](#parameters-summary) Β· [Returns](#returns-summary)
19​
20<a id="call-signature-1"></a>
21​
22## Call Signature
23​
24```ts
25function mutationOptions<TData = unknown, TError = Error, TVariables = void, TOnMutateResult = unknown>(options: WithRequired<CreateMutationOptions<TData, TError, TVariables, TOnMutateResult>, "mutationKey">): WithRequired<CreateMutationOptions<TData, TError, TVariables, TOnMutateResult>, "mutationKey">;
26```
27​
28Defined in: [packages/angular-query/src/mutation-options.ts:38](https://github.com/TanStack/query/blob/main/packages/angular-query/src/mutation-options.ts#L38)
29​
30You can generally pass everything to `mutationOptions` that you can also pass to `injectMutation`. A
31`mutationKey` is required on this overload so the mutation can be looked up later, e.g. with
32`injectMutationState`.
33​
34### Type Parameters
35​
36#### TData
37​
38`TData` = `unknown`
39​
40#### TError
41​
42`TError` = `Error`
43​
44#### TVariables
45​
46`TVariables` = `void`
47​
48#### TOnMutateResult
49​
50`TOnMutateResult` = `unknown`
51​
52### Parameters
53​
54#### options
55​
56[`WithRequired`](../type-aliases/WithRequired.md)\<[`CreateMutationOptions`](../interfaces/CreateMutationOptions.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>, `"mutationKey"`\>
57​
58The mutation options to use, identical to what you'd pass to `injectMutation`, with a
59required `mutationKey`.
60​
61### Returns
62​
63[`WithRequired`](../type-aliases/WithRequired.md)\<[`CreateMutationOptions`](../interfaces/CreateMutationOptions.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>, `"mutationKey"`\>
64​
65The same options object, unchanged.
66​
67### See
68​
69[injectMutation](injectMutation.md) to run the mutation these options describe.
70​
71### Example
72​
73Looking the mutation up elsewhere via its `mutationKey`, e.g. for a global "saving…" indicator:
74```angular-ts
75import { mutationOptions, injectMutationState } from '@tanstack/angular-query'
76​
77const createPostOptions = mutationOptions({
78 mutationKey: ['posts', 'create'],
79 mutationFn: createPost,
80})
81​
82@Component({
83 selector: 'saving-indicator',
84 template: `
85 @if (isCreatingPost()) {
86 <span>Saving…</span>
87 }
88 `,
89})
90export class SavingIndicator {
91 readonly #pendingCreates = injectMutationState(() => ({
92 filters: { mutationKey: createPostOptions.mutationKey, status: 'pending' },
93 }))
94 readonly isCreatingPost = computed(() => this.#pendingCreates().length > 0)
96```
97​
98<a id="call-signature-2"></a>
99​
100## Call Signature
101​
102```ts
103function mutationOptions<TData = unknown, TError = Error, TVariables = void, TOnMutateResult = unknown>(options: Omit<CreateMutationOptions<TData, TError, TVariables, TOnMutateResult>, "mutationKey">): Omit<CreateMutationOptions<TData, TError, TVariables, TOnMutateResult>, "mutationKey">;
104```
105​
106Defined in: [packages/angular-query/src/mutation-options.ts:94](https://github.com/TanStack/query/blob/main/packages/angular-query/src/mutation-options.ts#L94)
107​
108You can generally pass everything to `mutationOptions` that you can also pass to `injectMutation`. No
109`mutationKey` is required on this overload β€” use this when you don't need to target the mutation via a
110`mutationKey` filter later (e.g. with `injectMutationState`); it can still be observed through other
111filters, such as `status`.
112​
113### Type Parameters
114​
115#### TData
116​
117`TData` = `unknown`
118​
119#### TError
120​
121`TError` = `Error`
122​
123#### TVariables
124​
125`TVariables` = `void`
126​
127#### TOnMutateResult
128​
129`TOnMutateResult` = `unknown`
130​
131### Parameters
132​
133#### options
134​
135`Omit`\<[`CreateMutationOptions`](../interfaces/CreateMutationOptions.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>, `"mutationKey"`\>
136​
137The mutation options to use, identical to what you'd pass to `injectMutation`, without a
138`mutationKey`.
139​
140### Returns
141​
142`Omit`\<[`CreateMutationOptions`](../interfaces/CreateMutationOptions.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>, `"mutationKey"`\>
143​
144The same options object, unchanged.
145​
146### Remarks
147​
148See the other overload's example for looking a mutation up via `injectMutationState`.
149​
150### See
151​
152[injectMutation](injectMutation.md) to run the mutation these options describe.
153​
154### Example
155​
156Sharing options across services, so `QueriesService` stays the single place a mutation is defined:
157```angular-ts
158import { mutationOptions, injectMutation } from '@tanstack/angular-query'
159​
160@Injectable({ providedIn: 'root' })
161export class QueriesService {
162 readonly #queryClient = inject(QueryClient)
163​
164 updatePost(id: number) {
165 return mutationOptions({
166 mutationFn: (post: Partial<Post>) => putPost(id, post),
167 onSuccess: (newPost) => this.#queryClient.setQueryData(['posts', id], newPost),
168 })
169 }
171​
172@Component({
173 selector: 'post',
174 template: `<button (click)="save()">Save</button>`,
175})
176export class Post {
177 readonly queries = inject(QueriesService)
178 readonly id = signal(0)
179 readonly updatePostMutation = injectMutation(() => this.queries.updatePost(this.id()))
180​
181 save() {
182 this.updatePostMutation.mutate({ title: 'New Title' })
183 }
185```
186​
187<a id="parameters-summary"></a>
188​
189## Parameters
190​
191### options
192​
193`Omit`\<[`CreateMutationOptions`](../interfaces/CreateMutationOptions.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>, `"mutationKey"`\>
194​
195The mutation options to use, identical to what you'd pass to `injectMutation`, without a
196`mutationKey`.
197​
198<a id="options-properties"></a>
199​
200#### `options` properties
201​
202Built from [`CreateMutationOptions`](../interfaces/CreateMutationOptions.md#properties). See the type above for what it changes.
203​
204<a id="returns-summary"></a>
205​
206## Returns
207​
208`Omit`\<[`CreateMutationOptions`](../interfaces/CreateMutationOptions.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>, `"mutationKey"`\>
209​
210The same options object, unchanged.
211​
212<a id="result-properties"></a>
213​
214### Result properties
215​
216Built from [`CreateMutationOptions`](../interfaces/CreateMutationOptions.md#properties). See the type above for what it changes.