更新処理を明示的に管理する。
mutation は provider メソッドとして定義し、MutationToken で状態を監視、ref.invoke(call) で実行します。
Mutation の構成要素
mutate(token, body, concurrency: ...) が Call<R, State> を返します。
Token
late final renameMut = mutation<void>(#rename)
実行
await ref.invoke(provider.rename(...))
状態
Idle / Pending / Success / Error を ref.watch(token) で監視
ポイント
notifier.method() 直呼びではなく、実行自体を Call オブジェクトとして扱う点が特徴です。
Mutationを実行する
ref.invoke を使うことで cancel/drop の挙動を呼び出し側で制御できます。
実行
await ref.invoke(userProvider.rename('Alice'));
並行制御オプション
concurrent : すべて並列実行（既定）。
queue : FIFOで直列実行。途中エラー後も後続を継続。
restart : 旧実行をキャンセルし、最新だけを有効化。
dropLatest : 実行中の新規呼び出しを即時破棄。
例: 楽観更新 + restart
先に AsyncData を更新し、サーバー結果で最終確定するのが一般的な書き方です。
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 では古い呼び出しに CancelledMutation が返る場合があります。
dropLatest では実行中の新規呼び出しが DroppedMutation になります。
UI側で try/catch し、キャンセル系エラーを通知しない方針も選べます。