Value kind × mutability. Part 1.

Value kind (sync / Future / Stream) and mutability (read-only / has methods). 3×2 = 6 providers.

Three pairs.

Provider, FutureProvider, StreamProvider (read-only); NotifierProvider, AsyncNotifierProvider, StreamNotifierProvider (mutable).

Read-only sync.

A read-only, cached synchronous value (no mutation methods).

Return a String.

final baseUrlProvider = Provider<String>((ref) => 'https://api.example.com');

Derive/DI/combine.

Derived values, dependency injection (services/repos), and combining providers.

watch + fold.

final cartTotalProvider = Provider<double>((ref) =>
  ref.watch(cartItemsProvider).fold(0.0, (s, i) => s + i.price));

watch dio.

final dioProvider = Provider((ref) => Dio());
final userRepoProvider = Provider((ref) => UserRepository(ref.watch(dioProvider)));

Cache once.

It's computed once and cached, recomputed only on dependency change; all widgets share the result — less duplication, more testable.

Mutable.

A NotifierProvider — Provider is read-only; wanting a mutation method means you want a Notifier.

Async.

FutureProvider (read-only) or AsyncNotifierProvider (mutable) — for async values.

watch both.

final dashboardProvider = Provider((ref) =>
  DashboardData(ref.watch(userProvider), ref.watch(settingsProvider)));

Lazy.

Lazily on first read, then cached (recomputed on dependency change/invalidation).

Explicit + testable.

Dependencies are explicit in the graph, instances are shared/cached, and each layer is overridable for tests — clean boundaries without prop drilling.

Chain.

final loggerProvider = Provider((ref) => Logger());
final serviceProvider = Provider((ref) => Service(ref.watch(loggerProvider)));

Sealed type.

An AsyncValue (loading/data/error) — covered deeply in Series 3.

Right = left + methods.

The mutable column is the read-only column plus methods; each row only changes the value kind (sync/Future/Stream).

A Future. Part 2.

An async function returning a Future<T>; it exposes the result as an AsyncValue<T>.

async.

final userProvider = FutureProvider<User>((ref) async =>
  ref.watch(userRepoProvider).fetch());

Not the raw value.

An AsyncValue<T>, not the raw T.

loading/error/data.

ref.watch(userProvider).when(
  loading: () => const CircularProgressIndicator(),
  error: (e, _) => Text('$e'),
  data: (u) => Text(u.name));

Loading/data/error.

AsyncLoading, AsyncData(value), AsyncError(error, stack).

Sealed.

switch (ref.watch(userProvider)) {
  AsyncData(:final value) => Text(value.name),
  AsyncError(:final error) => Text('$error'),
  _ => const CircularProgressIndicator(),
}

Cache + states.

It caches the result (one fetch shared, not re-fired on rebuild), handles loading/data/error in one .when, auto-retries, and is testable/overridable.

.future.

final w = FutureProvider((ref) async {
  final city = await ref.watch(cityProvider.future);
  return ref.watch(weatherRepo).fetch(city);
});

AsyncValue vs Future.

ref.watch(p) gives the current AsyncValue (to inspect state); ref.watch(p.future) gives the underlying Future (to await and chain).

refresh/invalidate.

onRefresh: () => ref.refresh(userProvider.future),

No flicker.

Keeps showing existing data (no spinner flash) during a refresh, rather than reverting to the loading widget.

valueOrNull.

final user = ref.watch(userProvider).valueOrNull; // User?

Read-only.

It's read-only — no methods to mutate the fetched data. For mutations, use AsyncNotifierProvider.

Auto-retry.

It auto-retries with exponential backoff by default (configurable via the retry parameter).

Stream → AsyncValue. Part 3.

A Stream<T>; ref.watch returns an AsyncValue<T> that updates on every event.

Stream.periodic.

final tick = StreamProvider<int>((ref) =>
  Stream.periodic(const Duration(seconds: 1), (i) => i));

Same AsyncValue.

Both expose AsyncValue and are read-only, handled identically with .when/switch; the source differs (Stream vs Future).

Before first event.

After subscribing but before the first event arrives.

Subscription.

The StreamSubscription — subscribe on first watch, cancel on dispose. No manual dispose/cancel, no leak.

snapshots().map.

final userDoc = StreamProvider<User>((ref) =>
  firestore.collection('users').doc(uid).snapshots().map((s) => User.fromMap(s.data()!)));

watch input.

final messages = StreamProvider((ref) {
  final id = ref.watch(roomIdProvider);
  return ref.watch(chatRepo).messageStream(id);
});

Dispose + re-subscribe.

Riverpod disposes the old subscription and re-runs the function, subscribing to the new stream.

User?.

final authState = StreamProvider<User?>((ref) => FirebaseAuth.instance.authStateChanges());

AsyncError.

The provider's state becomes AsyncError, handled by the error: branch of .when/switch.

Cache + no leak.

It caches the latest value (shared across watchers), auto-manages the subscription (no leak), and isn't re-created on rebuild like a StreamBuilder placed in build.

.future.

final first = await ref.watch(messagesProvider.future);

Read-only.

Read-only — it exposes the stream but offers no mutation methods. Combine stream + actions with StreamNotifierProvider.

read-only vs mutable.

Price feed → StreamProvider; chat → StreamNotifierProvider.

build(). Part 4.

build(), returning the initial (synchronous) state.

state++.

class Counter extends Notifier<int> {
  @override int build() => 0;
  void increment() => state++;
}
final counterProvider = NotifierProvider<Counter, int>(Counter.new);

state =.

Assign to the state property (state = ...); it notifies listeners and rebuilds watchers.

watch / read.notifier.

final n = ref.watch(counterProvider);                       // state
onPressed: () => ref.read(counterProvider.notifier).increment();

Class + state.

The Notifier class C and the state type T; construct with C.new.

spread.

void add(Todo t) => state = [...state, t];

== filtering.

It mutates in place; the list identity doesn't change, so Riverpod's == update-filter may skip notifying listeners (stale UI). Assign a new list.

copyWith in a new list.

state = [for (final t in state) t.id == id ? t.copyWith(done: !t.done) : t];

Property.

It's a class property — use ref.watch/ref.read anywhere without passing it in.

watch in build.

@override
List<Item> build() {
  final all = ref.watch(allItemsProvider);
  return all.where(/* ... */).toList();
}

build() re-runs when the dependency changes.

State object.

A State object — build() ≈ initial state, state = ≈ setState, methods ≈ actions — but app-wide in a provider.

Sync vs await.

Notifier if build() returns state synchronously; AsyncNotifier if build() must await.

bool.

class ThemeN extends Notifier<bool> {
  @override bool build() => false;
  void toggle() => state = !state;
}
final isDarkProvider = NotifierProvider<ThemeN, bool>(ThemeN.new);

Loop.

Mutating state during build triggers a rebuild that mutates again → infinite loop. Mutations belong in callbacks/listeners/lifecycle.

state = initial.

void reset() => state = 0; // or rebuild via ref.invalidateSelf()

copyWith + ==.

It generates copyWith and value ==/hashCode for immutable state classes — exactly what immutable state = updates and == filtering need.

state property.

void addOne() => state = state + 1; // `state` reads current value directly

(Inside the notifier, just use state; no ref.read needed for own state.)

==, updateShouldNotify.

It compares old/new state with ==; override updateShouldNotify in the Notifier to customize when listeners are notified.

Async build. Part 5.

build() is async (returns FutureOr<T>) and state is an AsyncValue<T>.

FutureOr.

class TodoC extends AsyncNotifier<List<Todo>> {
  @override
  FutureOr<List<Todo>> build() => ref.watch(todoRepo).fetchAll();
}
final todoProvider = AsyncNotifierProvider<TodoC, List<Todo>>(TodoC.new);

AsyncValue.

An AsyncValue<T> (loading/data/error), handled with .when/switch.

loading + guard.

state = const AsyncLoading();
state = await AsyncValue.guard(() async {
  await repo.add(x);
  return repo.fetchAll();
});

Try/catch → AsyncValue.

Runs an async function and returns AsyncData on success or AsyncError on failure — automatic error handling, no try/catch.

copyWithPrevious.

state = const AsyncLoading<List<Todo>>().copyWithPrevious(state);

Show progress.

To reflect the in-progress action in the UI (spinner/disabled state) while the async work runs.

when.

ref.watch(todoProvider).when(
  loading: () => const CircularProgressIndicator(),
  error: (e, _) => Text('$e'),
  data: (todos) => TodoList(todos));

Mutate.

When you need to mutate the fetched data (add/edit/delete/refresh) with per-action loading/error.

invalidate.

onRefresh: () => ref.invalidate(todoProvider), // re-runs build()

set AsyncData, catch → restore.

final prev = state.valueOrNull ?? [];
state = AsyncData([for (final t in prev) t.id==id ? t.copyWith(done:!t.done) : t]);
try { await repo.toggle(id); } catch (_) { state = AsyncData(prev); }

Action.

Mutation methods are event-handler-like actions; use ref.read to grab the repo without creating a reactive dependency (watch belongs in build).

Action controller.

A controller for actions with no meaningful data state (e.g. auth sign-in) — build initializes, methods perform async operations and reflect loading/error via state.

guard signIn.

Future<void> signIn() async {
  state = const AsyncLoading();
  state = await AsyncValue.guard(ref.read(authRepo).signIn);
}

copyWithPrevious.

copyWithPrevious(state) on the loading state — together they keep showing old data during a refresh/mutation ("stale-while-revalidate").

Sync-mutable / async-mutable / async-read-only.

Notifier = sync mutable; AsyncNotifier = async mutable (CRUD); FutureProvider = async read-only fetch.

Stream. Part 6.

A Stream<T>; the provider exposes a live AsyncValue<T> plus methods.

• methods.

It's StreamProvider plus mutation methods (live stream + actions).

periodic.

class Ticker extends StreamNotifier<int> {
  @override Stream<int> build() => Stream.periodic(const Duration(seconds: 1), (i) => i);
}
final tickerProvider = StreamNotifierProvider<Ticker, int>(Ticker.new);

build returns stream; method writes.

class ChatC extends StreamNotifier<List<Message>> {
  @override Stream<List<Message>> build() => ref.watch(chatRepo).messageStream();
  Future<void> sendMessage(String t) => ref.read(chatRepo).send(t);
}

watch / read.notifier.

ref.watch(provider) for the live AsyncValue; ref.read(provider.notifier).method() for actions.

Riverpod.

Riverpod — subscribe on watch, cancel on dispose (like StreamProvider).

Stream emits.

When the underlying stream re-emits with the new message — you usually don't set state manually (the stream is the source of truth).

One feature.

When the live data and actions are one cohesive feature (chat/collaborative doc) — the controller encapsulates both, methods can read current streamed state, and it's one testable unit.

when + onSend.

ref.watch(chatProvider).when(
  data: (m) => MessageList(m), loading: () => const Spinner(), error: (e,_) => Text('$e'));
// onSend: (t) => ref.read(chatProvider.notifier).sendMessage(t)

Notifier trio.

NotifierProvider, AsyncNotifierProvider, StreamNotifierProvider.

State*/Change*. Part 7.

StateProvider, StateNotifierProvider, ChangeNotifierProvider.

Import.

A separate legacy import (package:flutter_riverpod/legacy.dart).

Notifier.

NotifierProvider.

Notifier class.

class C extends Notifier<int> { @override int build()=>0; void inc()=>state++; }
final p = NotifierProvider<C,int>(C.new);

build().

Overriding build() to return the initial state.

.new.

final p = NotifierProvider<Todos, List<Todo>>(Todos.new);

(plus TodosSN extends StateNotifier → Todos extends Notifier, super([])→build()=>[])

watch same.

No — ref.watch(provider) is unchanged; only writes change from .notifier.state = to named methods.

AsyncNotifier.

AsyncNotifier + AsyncNotifierProvider.

Mutable + notifyListeners.

ChangeNotifier mutates fields in place and calls notifyListeners() — opposite of Riverpod's immutable state = model; a Notifier with immutable state is more predictable.

Property.

A property (in StateNotifier you had to pass ref in) — cleaner access to dependencies.

Uniform + codegen.

Any two: uniform model mirroring read-only providers; ref as property; better @riverpod code-gen; immutable-state discipline; unified auto-dispose.

Opportunistic.

No — they still work. Use the modern Notifier family for new code and migrate legacy opportunistically when you touch that code.

final dioProvider = Provider((ref) => Dio());
final apiProvider = Provider((ref) => ApiClient(ref.watch(dioProvider)));
final postRepoProvider = Provider((ref) => PostRepository(ref.watch(apiProvider)));

final postsProvider = FutureProvider((ref) => ref.watch(postRepoProvider).fetchAll());
// build: ref.watch(postsProvider).when(loading:..., error:..., data: (p)=>PostList(p));

final connectivityProvider = StreamProvider<bool>((ref) =>
  Connectivity().onConnectivityChanged.map((r) => r != ConnectivityResult.none));

class Counter extends Notifier<int> { @override int build()=>0; void inc()=>state++; }
final counterProvider = NotifierProvider<Counter,int>(Counter.new);
// Text('${ref.watch(counterProvider)}'); onPressed: ()=>ref.read(counterProvider.notifier).inc();

class FilterN extends Notifier<String> { @override String build()=>''; void set(String s)=>state=s; }
final filterProvider = NotifierProvider<FilterN,String>(FilterN.new);
final visibleProvider = Provider((ref) {
  final q = ref.watch(filterProvider);
  return ref.watch(itemsProvider).where((i) => i.contains(q)).toList();
});

class TodoC extends AsyncNotifier<List<Todo>> {
  @override FutureOr<List<Todo>> build() => ref.watch(repo).fetchAll();
  Future<void> add(String t) async {
    state = const AsyncLoading();
    state = await AsyncValue.guard(() async { await ref.read(repo).add(t); return ref.read(repo).fetchAll(); });
  }
}

Future<void> delete(String id) async {
  final prev = state.valueOrNull ?? [];
  state = AsyncData(prev.where((t) => t.id != id).toList());
  try { await ref.read(repo).delete(id); } catch (_) { state = AsyncData(prev); }
}

class ChatC extends StreamNotifier<List<Message>> {
  @override Stream<List<Message>> build() => ref.watch(chatRepo).stream();
  Future<void> send(String t) => ref.read(chatRepo).send(t);
}
final chatProvider = StreamNotifierProvider<ChatC, List<Message>>(ChatC.new);

class Cart extends Notifier<CartData> {
  @override CartData build() => CartData.empty();
  void addItem(Item i) => state = state.copyWith(items: [...state.items, i]);
}
final cartProvider = NotifierProvider<Cart, CartData>(Cart.new);

super(...) → build(), CartSN() → Cart.new, method preserved.

import 'dart:async';
import 'package:flutter/material.dart';
import 'package:flutter_riverpod/flutter_riverpod.dart';

class Todo {
  final String id; final String title; final bool done;
  Todo(this.id, this.title, {this.done = false});
  Todo copyWith({bool? done}) => Todo(id, title, done: done ?? this.done);
}

// DI: the repository (swap for a fake in tests via override).
abstract class TodoRepository {
  Future<List<Todo>> fetchAll();
  Future<void> add(String title);
  Future<void> toggle(String id);
  Future<void> remove(String id);
}
final todoRepositoryProvider = Provider<TodoRepository>((ref) => /* real impl */ throw UnimplementedError());

// Async, mutable state controller — the heart of the feature.
class TodoListController extends AsyncNotifier<List<Todo>> {
  TodoRepository get _repo => ref.read(todoRepositoryProvider);

  @override
  FutureOr<List<Todo>> build() => ref.watch(todoRepositoryProvider).fetchAll();

  Future<void> add(String title) async {
    state = const AsyncLoading<List<Todo>>().copyWithPrevious(state); // keep old data
    state = await AsyncValue.guard(() async {
      await _repo.add(title);
      return _repo.fetchAll();
    });
  }

  Future<void> toggle(String id) async {
    final prev = state.valueOrNull ?? [];
    state = AsyncData([                                   // optimistic
      for (final t in prev) t.id == id ? t.copyWith(done: !t.done) : t,
    ]);
    try {
      await _repo.toggle(id);
    } catch (_) {
      state = AsyncData(prev);                            // rollback
    }
  }

  Future<void> remove(String id) async {
    final prev = state.valueOrNull ?? [];
    state = AsyncData(prev.where((t) => t.id != id).toList());
    try { await _repo.remove(id); } catch (_) { state = AsyncData(prev); }
  }
}

final todoListProvider =
    AsyncNotifierProvider<TodoListController, List<Todo>>(TodoListController.new);

class TodoScreen extends ConsumerWidget {
  const TodoScreen({super.key});
  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final todosAsync = ref.watch(todoListProvider);       // WATCH async state
    final controller = ref.read(todoListProvider.notifier); // for actions

    return Scaffold(
      appBar: AppBar(title: const Text('Todos')),
      body: todosAsync.when(                               // loading/data/error
        loading: () => const Center(child: CircularProgressIndicator()),
        error: (e, _) => Center(child: Text('Error: $e')),
        data: (todos) => RefreshIndicator(
          onRefresh: () async => ref.invalidate(todoListProvider), // re-fetch
          child: ListView(children: [
            for (final t in todos)
              CheckboxListTile(
                value: t.done,
                title: Text(t.title),
                onChanged: (_) => controller.toggle(t.id),
                secondary: IconButton(
                  icon: const Icon(Icons.delete),
                  onPressed: () => controller.remove(t.id),
                ),
              ),
          ]),
        ),
      ),
      floatingActionButton: FloatingActionButton(
        onPressed: () => controller.add('New todo'),
        child: const Icon(Icons.add),
      ),
    );
  }
}

This capstone exercises the whole series: DI via Provider (Part 1); async fetch with the AsyncValue model (Part 2); a mutable AsyncNotifier with the AsyncLoading → AsyncValue.guard idiom, copyWithPrevious, and optimistic updates with rollback (Part 5); reading state via watch and actions via read(.notifier) (Part 4); and invalidate for refresh. Override todoRepositoryProvider with a fake to test it all (Foundation Part 3).