MutationConfig

Defined in: react/src/types.ts:779

Configuration for createMutation and useActorMutation.

Extends

• Omit<UseMutationOptions<ReactorReturnOk<Service, Method, Transform>, ReactorReturnErr<Service, Method, Transform>, ReactorArgs<Service, Method, Transform>, TOnMutateResult>, "mutationFn">

Type Parameters

Service

Service = BaseActor

Method

Method extends FunctionName<Service> = FunctionName<Service>

Transform

Transform extends TransformKey = "candid"

TOnMutateResult

TOnMutateResult = unknown

The value onMutate returns, which onSuccess, onError and onSettled receive. TypeScript infers it from onMutate.

Properties

functionName

functionName: Method

Defined in: react/src/types.ts:794

The method to call on the canister

---

callConfig?

optional callConfig?: CallConfig

Defined in: react/src/types.ts:796

Call configuration for the actor method

---

invalidateQueries?

optional invalidateQueries?: InvalidationTarget<Service, Transform>[]

Defined in: react/src/types.ts:812

Queries to invalidate upon successful mutation, before onSuccess runs. The mutation stays pending until the invalidated queries in use have refetched, so onSuccess reads the refetched data.

Each entry is a query key, a query object or query factory, or a { functionName, args? } method of this mutation’s reactor; see InvalidationTarget. undefined entries are skipped, so [maybeQuery] is safe when the optional query object is absent.

Example

invalidateQueries: [getPosts, { functionName: "get_posts_count" }]

---

onCanisterError?

optional onCanisterError?: (error, variables) => void

Defined in: react/src/types.ts:835

Callback for canister-level business logic errors. Called when the canister returns a Result { Err: E } variant.

This is separate from onError which handles all errors including network failures, agent errors, etc.

Parameters

error

CanisterError<TransformReturnRegistry<ErrResult<ActorMethodReturnType<Service[Method]>>, Service>[Transform]>

The CanisterError containing the typed error value

variables

ReactorArgs<Service, Method, Transform>

The arguments passed to the mutation

Returns

void

Example

createMutation(reactor, {
  functionName: "transfer",
  onCanisterError: (error, variables) => {
    // error.err contains the typed Err value
    // error.code contains the variant key (e.g., "InsufficientFunds")
    console.error(`Transfer failed: ${error.code}`, error.err)
  },
})