watchMutation<TData, TVariables, TOnMutateResult> method

MutationController<TData, TVariables, TOnMutateResult> watchMutation<TData, TVariables, TOnMutateResult>(MutationOptions<TData, TVariables, TOnMutateResult> options, { Object? id, BuildWhen<MutationResult<TData, TVariables>>? buildWhen, })

A mutation owned by this State, as a MutationController.

final rename = watchMutation(renameTask(widget.id));
// in a handler:
rename.mutate('Renamed');

Mutations are not shared: each State that asks gets its own controller, released after the frame once a build stops reading it, the way a query is, and disposed with the State. Releasing it does not cancel a run in flight; see MutationController.cancel.

One is identified by id, else by the options' mutationKey, each together with its three types; without either, by the types alone — so pass id when one State runs two mutations of the same shape. A mutationKey is a category, not a name: two reads of one identity in one build share one controller, and whichever was read last would run for both. So two such reads without id are a debug assertion when they differ in the mutation function or callbacks (onMutate, onSuccess, onError, onSettled), or in scope, retry, retryDelay, networkMode or gcTime. The same functions read twice — one stored options object, tear-offs, top-level functions — are one mutation, and so is a nested builder re-reading what build read; a function literal is a new function each time it is built, so keep it in a field or read once.

buildWhen narrows when this State rebuilds, the same predicate MutationBuilder.buildWhen takes: given the result the last build showed and the one just reported, whether this read is worth a frame. A mutation has no select, so this is the only filter a reader has.

Implementation

MutationController<TData, TVariables, TOnMutateResult>
    watchMutation<TData, TVariables, TOnMutateResult>(
  MutationOptions<TData, TVariables, TOnMutateResult> options, {
  Object? id,
  BuildWhen<MutationResult<TData, TVariables>>? buildWhen,
}) =>
        _beginRead().readMutation<TData, TVariables, TOnMutateResult>(
          _currentClient,
          options,
          id,
          buildWhen: buildWhen,
        );