API Documentation / @pinia/colada / DefineMutationOptionsTagged

Interface: DefineMutationOptionsTagged<TData, TVars, TError, TContext>

Tagged version of UseMutationOptions that includes a key with data type information. Returned by defineMutationOptions.

Extends

• UseMutationOptions<TData, TVars, TError, TContext>

Type Parameters

TData

TData = unknown

TVars

TVars = void

TError

TError = ErrorDefault

TContext

TContext extends Record<any, any> = _EmptyObject

Properties

delay?

optional delay?: number | false;

Delay in milliseconds to wait before letting the asyncStatus become 'loading'. Set to false or 0 to disable. Requires the PiniaColadaDelay or PiniaColadaDelayMutations plugin.

Default

200

Inherited from

UseMutationOptions.delay

---

gcTime?

optional gcTime?: number | false;

Time in ms after which, once the mutation is no longer being used, it will be garbage collected to free resources. Set to false to disable garbage collection (not recommended).

Default

60_000 (1 minute)

Inherited from

UseMutationOptionsGlobal.gcTime

---

key

key: _MutationKeyTagged<TData, TVars, TError>;

Optional key to identify the mutation globally and access it through other methods in the mutation cache. If you don't need to reference the mutation elsewhere, you should ignore this option.

Overrides

UseMutationOptions.key

---

meta?

optional meta?: Record<string, unknown>;

Meta information associated with the mutation. Can be used by plugins to store additional data alongside the mutation entry.

Inherited from

UseMutationOptions.meta

---

mutation

mutation: (vars, context) => Promise<TData>;

The key of the mutation. If the mutation is successful, it will invalidate the mutation with the same key and refetch it

Parameters

vars

TVars

context

_ReduceContext<NoInfer<TContext>>

Returns

Promise<TData>

Inherited from

UseMutationOptions.mutation

---

onError?

optional onError?: (error, vars, context) => unknown;

Runs if the mutation encounters an error.

Parameters

error

TError

The error thrown by the mutation.

vars

NoInfer<TVars>

The variables passed to the mutation.

context

UseMutationContextCommon<TData, TVars, TError, TContext> & | Partial<Record<never, never>> & Partial<Record<keyof _ReduceContext<NoInfer<TContext>>, never>> | UseMutationGlobalContext & _ReduceContext<NoInfer<TContext>>

The merged context from onMutate and the global context. Properties returned by onMutate can be undefined if onMutate throws.

Returns

unknown

Inherited from

UseMutationOptions.onError

---

onMutate?

optional onMutate?: (vars, context) => _Awaitable<void | TContext | null | undefined>;

Runs before the mutation is executed. It should be placed before mutation() for context to be inferred. It can return a value that will be passed to mutation, onSuccess, onError and onSettled. If it returns a promise, it will be awaited before running mutation.

Parameters

vars

TVars

The variables passed to the mutation.

context

UseMutationContextCommon<unknown, unknown, NoInfer<TError>, _EmptyObject> & UseMutationGlobalContext

Returns

_Awaitable<void | TContext | null | undefined>

Example

useMutation({
// must appear before `mutation` for `{ foo: string }` to be inferred
// within `mutation`
  onMutate() {
    return { foo: 'bar' }
  },
  mutation: (id: number, { foo }) => {
    console.log(foo) // bar
    return fetch(`/api/todos/${id}`)
  },
  onSuccess(data, vars, context) {
    console.log(context.foo) // bar
  },
})

Inherited from

UseMutationOptions.onMutate

---

onSettled?

optional onSettled?: (data, error, vars, context) => unknown;

Runs after the mutation is settled, regardless of the result.

Parameters

data

NoInfer<TData> | undefined

The result of the mutation. undefined if the mutation failed.

error

TError | undefined

The error thrown by the mutation. undefined if the mutation was successful.

vars

NoInfer<TVars>

The variables passed to the mutation.

context

UseMutationContextCommon<TData, TVars, TError, TContext> & | Partial<Record<never, never>> & Partial<Record<keyof _ReduceContext<NoInfer<TContext>>, never>> | UseMutationGlobalContext & _ReduceContext<NoInfer<TContext>>

The merged context from onMutate and the global context. Properties returned by onMutate can be undefined if onMutate throws.

Returns

unknown

Inherited from

UseMutationOptions.onSettled

---

onSuccess?

optional onSuccess?: (data, vars, context) => unknown;

Runs if the mutation is successful.

Parameters

data

NoInfer<TData>

The result of the mutation.

vars

NoInfer<TVars>

The variables passed to the mutation.

context

UseMutationContextCommon<NoInfer<TData>, NoInfer<TVars>, NoInfer<TError>, NoInfer<TContext>> & UseMutationGlobalContext & _ReduceContext<NoInfer<TContext>>

The merged context from onMutate and the global context. Properties returned by onMutate can be undefined if onMutate throws.

Returns

unknown

Inherited from

UseMutationOptions.onSuccess