Write flow stays explicit.
Define mutations as provider methods, monitor state with MutationToken, and execute through ref.invoke(call).
Mutation Building Blocks
A mutation is a Call<R, State> returned from mutate(token, body, concurrency: ...).
Token
late final renameMut = mutation<void>(#rename)
Execution
await ref.invoke(provider.rename(...))
State
Idle / Pending / Success / Error via ref.watch(token)
Note
Unlike notifier.method() style APIs, miniriverpod makes mutation execution a first-class call object.
Execute a mutation
Use ref.invoke so cancellation and drop behaviors are surfaced to the caller.
Run
await ref.invoke(userProvider.rename('Alice'));
Concurrency options
concurrent : run all calls in parallel (default).
queue : FIFO; keep running queued calls even after an error.
restart : cancel previous run, keep only latest call.
dropLatest : drop incoming calls while one is running.
Example: optimistic update + restart
A common write pattern updates AsyncData optimistically, then syncs with server response.
user_provider.dart
class UserProvider extends AsyncProvider<User?> {
UserProvider() : super.args(null);
late final renameMut = mutation<void>(#rename);
Call<void, AsyncValue<User?>> rename(String newName) => mutate(
renameMut,
(ref) async {
final cur = ref.watch(this).valueOrNull;
ref.state = AsyncData((cur ?? const User()).copyWith(name: newName), isRefreshing: true);
final api = ref.watch(apiProvider);
await api.rename(newName);
ref.state = AsyncData(await api.me());
},
concurrency: Concurrency.restart,
);
}
restart may throw CancelledMutation to older callers.
dropLatest may throw DroppedMutation while busy.
Catch these in UI when you want to suppress transient cancellation errors.
aglay marahil
Flutter API
Bind mutation state to UI using ConsumerWidget or ConsumerStatefulWidget.
Open Flutter API