This version (v0.7) has not been published to npm yet.
Skip to content

Reference / @getenginex/sdk-react / useEnginexMutation

useEnginexMutation() ​

useEnginexMutation<I, R, TOnMutateResult>(options, overrides?): UseMutationResult<R, EnginexError, I, TOnMutateResult>

TanStack useMutation over the options of an SDK mutation, with the error typed as EnginexError. On success it invalidates exactly the keys of invalidates(input, result), waits for the refetches to finish and only then calls the app's onSuccess (in overrides): mutateAsync and isPending end up with the data already updated. On error it invalidates nothing and the app's onError receives the EnginexError. An app onSuccess that throws does not prevent the invalidation (it has already happened) and moves the mutation to the error state, as in TanStack; in that case onError and error receive the error it threw, which is not necessarily an EnginexError (the EnginexError type describes the failures of mutationFn).

overrides with an undefined value are ignored, and the options' mutationFn cannot be replaced. TOnMutateResult is the return of onMutate, delivered typed to onSuccess, onError and onSettled.

The Idempotency-Key is kept per hook instance: it survives a re-render (the options are recreated on every render) and TanStack's retry, and is only reused for the same method and the same content after an ambiguous failure (network, timeout, 5xx, KEY_IN_USE or VALIDATION_ERROR after a 2xx). Two hook instances never share a key. Pass the adjustments in overrides: spreading the options ({ ...m.deposits.createPix(), retry: 1 }) loses the SDK call and, with it, the per-instance attempt. Options without the SDK call (a synthetic mutation) use their own mutationFn. The options' gcTime (0 on mutations with credentials) is kept.

Type Parameters ​

I ​

I

R ​

R

TOnMutateResult ​

TOnMutateResult = unknown

Parameters ​

options ​

EnginexMutationOptions<I, R>

Options of a mutation (m.deposits.createPix()).

overrides? ​

Omit<UseMutationOptions<R, EnginexError, I, TOnMutateResult>, "mutationFn">

useMutation options (onSuccess, onError, retry...); not mutationFn.

Returns ​

UseMutationResult<R, EnginexError, I, TOnMutateResult>

The useMutation result, with error typed as EnginexError.

Throws ​

If called outside an EnginexProvider (or a QueryClientProvider).

Example ​

ts
const m = useEnginexMutations()
const pix = useEnginexMutation(m.deposits.createPix(), {
  onSuccess: (deposit) => router.push(`/deposito/${deposit.id}`),
})
pix.mutate({ amount: 5000 })