Mutations topic

Mutations change data on the server. MutationOptions describe one (the mutation function and its onMutate/onSuccess/onError/onSettled callbacks), MutationResult reports it, and a MutationScope runs related mutations one at a time.

Classes

MutateCallbacks<TData, TVariables, TOnMutateResult>

Callbacks a caller can attach to a single mutate call, on top of the ones in the options — for what only that call site cares about, such as closing a dialog or showing a snack bar.

Mutation<TData, TVariables, TOnMutateResult>

One mutation: its options, its state, and one run of its mutation function.

MutationError<TData, TVariables>

The run failed for good: retries, if any, are spent, and the error callbacks have run. error holds why; a cancelled run fails with a CancelledError.

MutationFunctionContext<TOnMutateResult>

What a MutationFnWithContext is told about the run it is part of.

MutationIdle<TData, TVariables>

Nothing has been submitted yet, or the observer was reset since: no variables, no data, no error. Call mutate to start a run.

MutationOptions<TData, TVariables, TOnMutateResult>

Everything that describes a mutation: the write it performs, its callbacks, and how it retries, pauses and queues.

MutationPending<TData, TVariables>

A run has been submitted and has not settled yet: onMutate, the mutation function or the settling callbacks are running, or the run is paused (isPaused) waiting for the network, the foreground or its MutationScope. variables holds what it was called with — what an optimistic UI shows meanwhile.

MutationResult<TData, TVariables>

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

MutationScope

Mutations sharing a scope run one at a time, in the order they started.

MutationState<TData, TVariables, TOnMutateResult>

A mutation's state at one point in time: its status, the variables of the current or last run, its data or error, and retry bookkeeping.

MutationSuccess<TData, TVariables>

The mutation function returned, and the success callbacks have run; data holds what it returned.

Enums

MutationStatus

Where a mutation is in its life: idle before the first run, pending while running (or paused), then success or error until the next run or a reset.

Typedefs

MutationFn<TData, TVariables> = FutureOr<TData> Function(TVariables variables)

The function a mutation runs: it performs the write for variables and returns (or completes with) the server's answer, which becomes the mutation's data. Throwing, or completing with an error, fails the attempt. Set through MutationOptions.mutationFn.

MutationFnWithContext<TData, TVariables, TOnMutateResult> = FutureOr<TData> Function(TVariables variables, MutationFunctionContext<TOnMutateResult> context)

A MutationFn that also receives the MutationFunctionContext of its run. Set through MutationOptions.mutationFnWithContext.

OnMutate<TVariables, TOnMutateResult> = FutureOr<TOnMutateResult?> Function(TVariables variables)

The signature of MutationOptions.onMutate: runs before the mutation function with its variables, and what it returns is the onMutateResult the other callbacks receive — typically a snapshot to roll an optimistic update back to. A returned future is awaited.

OnMutationError<TVariables, TOnMutateResult> = FutureOr<void> Function(Object error, StackTrace stackTrace, TVariables variables, TOnMutateResult? onMutateResult)

The signature of MutationOptions.onError and MutateCallbacks.onError: the error and where it was thrown, the variables, and what onMutate returned (null when onMutate itself threw or there is none).

OnMutationSettled<TData, TVariables, TOnMutateResult> = FutureOr<void> Function(TData? data, Object? error, StackTrace? stackTrace, TVariables variables, TOnMutateResult? onMutateResult)

The signature of MutationOptions.onSettled and MutateCallbacks.onSettled: whichever of data and error applies (the other is null), the error's stack trace, the variables, and what onMutate returned.

OnMutationSuccess<TData, TVariables, TOnMutateResult> = FutureOr<void> Function(TData data, TVariables variables, TOnMutateResult? onMutateResult)

The signature of MutationOptions.onSuccess and MutateCallbacks.onSuccess: the data, the variables, and what onMutate returned.