MutationResult<TData, TVariables> class sealed Mutations

The result of observing one mutation: what a MutationObserver reports and what the Flutter binding's mutation helpers hand a widget.

Sealed, with one variant per MutationStatus:

switch on it and the data or error is simply there:

return switch (result) {
  MutationIdle() => SaveButton(onPressed: () => result.mutate(draft)),
  MutationPending() => const SaveButton(onPressed: null),
  MutationSuccess(:final data) => Text('Saved as ${data.id}'),
  MutationError(:final error) => ErrorView(error, retry: result.reset),
};

Every variant carries mutate, mutateAsync and reset, so a widget can submit from any of them. (TanStack Query: MutationObserverResult.)

Implementers
Annotations
  • @immutable

Properties

dataOrNull → TData?
The data this result carries, if any. Prefer pattern matching; this exists for the cases where a nullable read is genuinely what you want.
no setter
errorOrNull → Object?
The error this result carries — set only on a MutationError, null on every other variant.
no setter
failureCount → int
How many attempts of the current run have failed so far. Reset when a new run starts.
final
failureReason → Object?
What the latest failed attempt threw, kept while retries continue. null once an attempt succeeds or a new run starts.
final
hashCode → int
The hash code for this object.
no setteroverride
hasVariables → bool
Whether variables means anything: false while idle, and the only way to tell a real null from none when TVariables is nullable.
final
isError → bool
Whether this is a MutationError: the last run failed for good, and errorOrNull holds why.
no setter
isIdle → bool
Whether this is a MutationIdle: nothing has been submitted since the observer was created or reset.
no setter
isPaused → bool
Whether the run is parked rather than running. Three things park it: the network (under NetworkMode.online a mutation submitted offline sits here until the device is back, when a mounted client resumes it through resumePausedMutations), focus (a retry waits for the app to return to the foreground), and its MutationScope — a mutation queued behind another in its scope is pending with isPaused until its turn. Show "waiting" rather than "saving" while it is set.
final
isPending → bool
Whether this is a MutationPending: a run is in flight or paused. Handy for disabling a submit button.
no setter
isSuccess → bool
Whether this is a MutationSuccess: the last run succeeded, and dataOrNull holds what it returned.
no setter
mutate → void Function(TVariables variables)
Starts a new run with the given variables and returns at once: errors go to the callbacks and to the next result, never to the caller.
final
mutateAsync → Future<TData> Function(TVariables variables)
Starts a new run with the given variables and completes with its data, or throws its error, once the run's callbacks have run.
final
reset → void Function()
Detaches from the mutation and goes back to MutationIdle — to clear an error message, say. The mutation itself keeps running and still fires its callbacks; only this observer stops reflecting it.
final
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
status → MutationStatus
Which variant this is, as a MutationStatus — for callers that store or compare it rather than pattern-match.
no setter
submittedAt → DateTime?
When the current run was submitted. null while idle.
final
variables → TVariables?
The variables of the run in flight or last finished.
final

Methods

noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
toString() → String
The variant, then the variables once a run has set them, the data or the error, and paused while the run waits — MutationSuccess<int, String>(variables: draft, data: 1).
override

Operators

operator ==(Object other) → bool
The equality operator.
override