210-use-mutation

Instruction file imported from Razor25000/Analyse-web-pro-v2 (.cursor/rules/project/210-use-mutation.mdc). Copyright stays with the author.

description: How to use useMutation is my application globs: *.tsx

Usage with server-action

Server-action is method that finish with "action" suffix.

You can use it like this :

import { resolveActionResult } from "@/lib/actions/actions-utils";
import { useMutation } from "@tanstack/react-query";
import { LoadingButton } from "@/features/form/submit-button";

const mutationWithName = useMutation({
  mutationFn: async ({ someParams }: { someParams: string }) => {
    // You always need to call the action INSIDE the resolveActionResult WITHOUT await
    return resolveActionResult(someAction({ someParams }));
  },
  // Error is equal to "serverError" of someAction
  onError: (error) => {
    toast.error(error.message);
  },
  // Data is equal to "data" of someAction, data is required
  onSuccess: (data) => {
    toast.success("Invoice marked as paid");
    // Optionally refresh data or update state
  },
});

return <LoadingButton loading={mutationWithName.isPending}>Save</LoadingButton>;

API

const {
  data,
  error,
  isError,
  isIdle,
  isPending,
  isPaused,
  isSuccess,
  failureCount,
  failureReason,
  mutate,
  mutateAsync,
  reset,
  status,
  submittedAt,
  variables,
} = useMutation(
  {
    mutationFn,
    gcTime,
    meta,
    mutationKey,
    networkMode,
    onError,
    onMutate,
    onSettled,
    onSuccess,
    retry,
    retryDelay,
    scope,
    throwOnError,
  },
  queryClient,
);

mutate(variables, {
  onError,
  onSettled,
  onSuccess,
});

Parameter1 (Options)

• mutationFn: (variables: TVariables) => Promise<TData>
  • Required, but only if no default mutation function has been defined
  • A function that performs an asynchronous task and returns a promise.
  • variables is an object that mutate will pass to your mutationFn
• gcTime: number | Infinity
  • The time in milliseconds that unused/inactive cache data remains in memory. When a mutation's cache becomes unused or inactive, that cache data will be garbage collected after this duration. When different cache times are specified, the longest one will be used.
  • If set to Infinity, will disable garbage collection
  • Note: the maximum allowed time is about 24 days. See more.
• mutationKey: unknown[]
  • Optional
  • A mutation key can be set to inherit defaults set with queryClient.setMutationDefaults.
• networkMode: 'online' | 'always' | 'offlineFirst
  • Optional
  • defaults to 'online'
  • see Network Mode for more information.
• onMutate: (variables: TVariables) => Promise<TContext | void> | TContext | void
  • Optional
  • This function will fire before the mutation function is fired and is passed the same variables the mutation function would receive
  • Useful to perform optimistic updates to a resource in hopes that the mutation succeeds
  • The value returned from this function will be passed to both the onError and onSettled functions in the event of a mutation failure and can be useful for rolling back optimistic updates.
• onSuccess: (data: TData, variables: TVariables, context: TContext) => Promise<unknown> | unknown
  • Optional
  • This function will fire when the mutation is successful and will be passed the mutation's result.
  • If a promise is returned, it will be awaited and resolved before proceeding
• onError: (err: TError, variables: TVariables, context?: TContext) => Promise<unknown> | unknown
  • Optional
  • This function will fire if the mutation encounters an error and will be passed the error.
  • If a promise is returned, it will be awaited and resolved before proceeding
• onSettled: (data: TData, error: TError, variables: TVariables, context?: TContext) => Promise<unknown> | unknown
  • Optional
  • This function will fire when the mutation is either successfully fetched or encounters an error and be passed either the data or error
  • If a promise is returned, it will be awaited and resolved before proceeding
• retry: boolean | number | (failureCount: number, error: TError) => boolean
  • Defaults to 0.
  • If false, failed mutations will not retry.
  • If true, failed mutations will retry infinitely.
  • If set to an number, e.g. 3, failed mutations will retry until the failed mutations count meets that number.
• retryDelay: number | (retryAttempt: number, error: TError) => number
  • This function receives a retryAttempt integer and the actual Error and returns the delay to apply before the next attempt in milliseconds.
  • A function like attempt => Math.min(attempt > 1 ? 2 ** attempt * 1000 : 1000, 30 * 1000) applies exponential backoff.
  • A function like attempt => attempt * 1000 applies linear backoff.
• scope: { id: string }
  • Optional
  • Defaults to a unique id (so that all mutations run in parallel)
  • Mutations with the same scope id will run in serial
• throwOnError: undefined | boolean | (error: TError) => boolean
  • Defaults to the global query config's throwOnError value, which is undefined
  • Set this to true if you want mutation errors to be thrown in the render phase and propagate to the nearest error boundary
  • Set this to false to disable the behavior of throwing errors to the error boundary.
  • If set to a function, it will be passed the error and should return a boolean indicating whether to show the error in an error boundary (true) or return the error as state (false)
• meta: Record<string, unknown>
  • Optional
  • If set, stores additional information on the mutation cache entry that can be used as needed. It will be accessible wherever the mutation is available (eg. onError, onSuccess functions of the MutationCache).

Parameter2 (QueryClient)

• queryClient?: QueryClient,
  • Use this to use a custom QueryClient. Otherwise, the one from the nearest context will be used.

Returns

• mutate: (variables: TVariables, { onSuccess, onSettled, onError }) => void
  • The mutation function you can call with variables to trigger the mutation and optionally hooks on additional callback options.
  • variables: TVariables
    • Optional
    • The variables object to pass to the mutationFn.
  • onSuccess: (data: TData, variables: TVariables, context: TContext) => void
    • Optional
    • This function will fire when the mutation is successful and will be passed the mutation's result.
    • Void function, the returned value will be ignored
  • onError: (err: TError, variables: TVariables, context: TContext | undefined) => void
    • Optional
    • This function will fire if the mutation encounters an error and will be passed the error.
    • Void function, the returned value will be ignored
  • onSettled: (data: TData | undefined, error: TError | null, variables: TVariables, context: TContext | undefined) => void
    • Optional
    • This function will fire when the mutation is either successfully fetched or encounters an error and be passed either the data or error
    • Void function, the returned value will be ignored
  • If you make multiple requests, onSuccess will fire only after the latest call you've made.
• mutateAsync: (variables: TVariables, { onSuccess, onSettled, onError }) => Promise<TData>
  • Similar to mutate but returns a promise which can be awaited.
• status: string
  • Will be:
    • idle initial status prior to the mutation function executing.
    • pending if the mutation is currently executing.
    • error if the last mutation attempt resulted in an error.
    • success if the last mutation attempt was successful.
• isIdle, isPending, isSuccess, isError: boolean variables derived from status
• isPaused: boolean
  • will be true if the mutation has been paused
  • see Network Mode for more information.
• data: undefined | unknown
  • Defaults to undefined
  • The last successfully resolved data for the mutation.
• error: null | TError
  • The error object for the query, if an error was encountered.
• reset: () => void
  • A function to clean the mutation internal state (i.e., it resets the mutation to its initial state).
• failureCount: number
  • The failure count for the mutation.
  • Incremented every time the mutation fails.
  • Reset to 0 when the mutation succeeds.
• failureReason: null | TError
  • The failure reason for the mutation retry.
  • Reset to null when the mutation succeeds.
• submittedAt: number
  • The timestamp for when the mutation was submitted.
  • Defaults to 0.
• variables: undefined | TVariables
  • The variables object passed to the mutationFn.
  • Defaults to undefined.