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

mutationOptions.ts

92 lines3.1 KB

1import type { DefaultError, WithRequired } from '@tanstack/query-core'
2import type { UseMutationOptions } from './types'
3​
4/**
5 * You can generally pass everything to `mutationOptions` that you can also pass to `useMutation`. A
6 * `mutationKey` is required on this overload so the mutation can be looked up later, e.g. with
7 * `useMutationState`.
8 * @param options - The mutation options to use, identical to what you'd pass to `useMutation`, with a
9 * required `mutationKey`.
10 * @returns The same options object, unchanged.
11 * @see {@link useMutation} to run the mutation these options describe.
12 * @example
13 * Looking the mutation up elsewhere via its `mutationKey`, e.g. for a global "saving…" indicator:
14 * ```tsx
15 * import { mutationOptions, useMutationState } from '@tanstack/react-query'
16 *
17 * const createPostOptions = mutationOptions({
18 * mutationKey: ['posts', 'create'],
19 * mutationFn: createPost,
20 * })
21 *
22 * function SavingIndicator() {
23 * const isCreatingPost = useMutationState({
24 * filters: { mutationKey: createPostOptions.mutationKey, status: 'pending' },
25 * }).length > 0
26 *
27 * return isCreatingPost ? <span>Saving…</span> : null
28 * }
29 * ```
30 */
31export function mutationOptions<
32 TData = unknown,
33 TError = DefaultError,
34 TVariables = void,
35 TOnMutateResult = unknown,
36>(
37 options: WithRequired<
38 UseMutationOptions<TData, TError, TVariables, TOnMutateResult>,
39 'mutationKey'
40 >,
41): WithRequired<
42 UseMutationOptions<TData, TError, TVariables, TOnMutateResult>,
43 'mutationKey'
45/**
46 * You can generally pass everything to `mutationOptions` that you can also pass to `useMutation`. No
47 * `mutationKey` is required on this overload — use this when you don't need to target the mutation via a
48 * `mutationKey` filter later (e.g. with `useMutationState`); it can still be observed through other filters,
49 * such as `status`.
50 * @param options - The mutation options to use, identical to what you'd pass to `useMutation`, without a
51 * `mutationKey`.
52 * @returns The same options object, unchanged.
53 * @remarks See the other overload's example for looking a mutation up via `useMutationState`.
54 * @see {@link useMutation} to run the mutation these options describe.
55 * @example
56 * ```tsx
57 * import { mutationOptions, useMutation } from '@tanstack/react-query'
58 *
59 * export const createPostOptions = mutationOptions({
60 * mutationFn: createPost,
61 * })
62 *
63 * function CreatePost() {
64 * const mutation = useMutation(createPostOptions)
65 * return <button onClick={() => mutation.mutate({ title: 'Hello' })}>Create</button>
66 * }
67 * ```
68 */
69export function mutationOptions<
70 TData = unknown,
71 TError = DefaultError,
72 TVariables = void,
73 TOnMutateResult = unknown,
74>(
75 options: Omit<
76 UseMutationOptions<TData, TError, TVariables, TOnMutateResult>,
77 'mutationKey'
78 >,
79): Omit<
80 UseMutationOptions<TData, TError, TVariables, TOnMutateResult>,
81 'mutationKey'
83export function mutationOptions<
84 TData = unknown,
85 TError = DefaultError,
86 TVariables = void,
87 TOnMutateResult = unknown,
88>(
89 options: UseMutationOptions<TData, TError, TVariables, TOnMutateResult>,
90): UseMutationOptions<TData, TError, TVariables, TOnMutateResult> {
91 return options