MutationScope class final Mutations

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

Use a scope when several writes to the same record must reach the server in order — an offline queue replaying three edits concurrently could reorder them. Set it through MutationOptions.scope:

MutationOptions<Task, Task, void>(
  mutationFn: (Task task) => api.saveTask(task),
  // Every save of this task queues behind the one before it.
  scope: MutationScope('task-$taskId'),
)

What waits for the scope is the mutation function, not onMutate:

  • onMutate — the cache-wide one and the mutation's own — runs when the mutation is submitted, while an earlier mutation of the scope may still be running. An optimistic patch, a snapshot for rolling it back, a cancelQueries all happen then, not when the function's turn comes. A snapshot taken there predates the writes still queued ahead of it, so a rollback that restores it whole also undoes those; roll back only what this mutation changed.
  • The scope is held until the running mutation has finished, callbacks included: the cache's and its options' onSuccess/onError and onSettled run, and the next mutation starts only once the future onSettled returned has completed. An onSettled that returns an invalidation's future holds the scope until that refetch is done; one that should not, .ignore()s it.

While it waits, a queued mutation is pending with isPaused set. No hook runs at the moment the scope admits a mutation; to undo an optimistic update safely, roll back per item rather than restoring a whole snapshot.

TanStack Query spells this scope: { id }, with the same order.

Annotations
  • @immutable

Constructors

MutationScope(Object id)
Creates the scope named id. Scopes with equal ids are the same scope, so two MutationScope('task-1') values queue together.
const

Properties

hashCode → int
The hash code for this object.
no setteroverride
id → Object
The scope's identity. Any value with value equality; a string naming the record being edited is the usual choice.
final
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited

Methods

noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
toString() → String
A string representation of this object.
override

Operators

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