Loading/data/error. Part 1.

AsyncData(value), AsyncLoading(), AsyncError(error, stackTrace) — always exactly one.

Three callbacks.

async.when(data: (d)=>View(d), loading: ()=>const Spinner(), error: (e,_)=>Text('$e'));

Can't forget.

So you can't forget loading or error — it enforces complete async UI.

Sealed.

switch (async) {
  AsyncData(:final value) => View(value),
  AsyncError(:final error) => Text('$error'),
  AsyncLoading() => const Spinner(),
}

Sealed → exhaustive.

It's a sealed class; switches over it are exhaustive (compiler-checked).

valueOrNull.

final v = async.valueOrNull; // T?

Null vs throw.

.value/.valueOrNull return T?; .requireValue returns T but throws if no value.

isLoading.

onPressed: async.isLoading ? null : _submit,

No spinner flash.

Keeps showing existing data during a refresh instead of the loading widget (with preserved previous data).

whenData.

final count = listAsync.whenData((l) => l.length);

Loading/error.

It transforms the data and passes loading/error states through unchanged.

orElse.

async.maybeWhen(data: (u) => u.name, orElse: () => 'Loading…');

Stale-while-revalidate.

It carries previous data through a loading state so the UI shows old data during refresh instead of blanking.

when in switch.

switch (async) {
  AsyncData(:final value) when value.isPremium => PremiumView(value),
  AsyncData(:final value) => StandardView(value),
  _ => const Spinner(),
}

Loading + previous.

The state is loading but a previous value exists (a refresh in progress over existing data).

Every async provider.

Every async provider (Future/Stream/AsyncNotifier/StreamNotifier) exposes one, so a single set of tools handles all async state uniformly.

Parameterize. Part 2.

Turns a provider into a parameterized one — each argument gets its own independent, cached state.

(ref, id).

final userProvider = FutureProvider.autoDispose.family<User, String>(
  (ref, id) => ref.watch(userRepo).fetchById(id));

Call it.

ref.watch(userProvider('123'));

Map.

A Map keyed by the argument, with the provider state as the value.

Cache key.

The argument is the cache key; identity-based equality (fresh list/object) causes cache misses → refetch every time.

Value equality.

Pass a value-equality arg — a String/int or a record/freezed class, not a fresh List.

Record key.

final p = FutureProvider.autoDispose.family<Feed, ({String city, int page})>(
  (ref, a) => repo.fetch(a.city, a.page));
// ref.watch(p((city:'NYC', page:1)))

Structural ==.

They have value (structural) equality for free, so composite keys compare by value.

Per-arg leak.

Each argument creates a cached instance; without autoDispose they accumulate unbounded — a leak.

Provider.family.

final labelProvider = Provider.family<String, int>((ref, n) => 'Item #$n');

build(arg).

@riverpod
class TodoItem extends _$TodoItem {
  @override Future<Todo> build(String id) => ref.watch(repo).fetchById(id);
}

provider_parameters.

provider_parameters (in riverpod_lint).

Per key.

Yes — each argument is a separate cached instance with its own state/lifecycle.

p(arg).overrideWith.

userProvider('123').overrideWith((ref) => User(name: 'Test'));

Destroy when unwatched. Part 3.

Destroys the provider's state when the last listener stops watching it.

Forever.

Keep-alive — cached for the app's lifetime (until the ProviderScope is disposed).

.autoDispose.

final p = FutureProvider.autoDispose<User>((ref) => fetch());

Cache vs cleanup.

Caching for cleanup — less memory but recreate/refetch on next use.

onCancel/frame/onDispose.

onCancel → wait one frame → if still unused, onDispose (destroy); a returning listener triggers onResume (kept).

Navigation.

So quick rebuilds/navigation (brief zero-listener gaps) don't cause disposal — it only tears down when genuinely unused.

App-wide vs transient.

keep-alive, autoDispose, keep-alive, autoDispose.

Per-arg instances.

Each argument caches an instance forever otherwise; autoDispose bounds memory by destroying unused ones.

Opposite of manual.

autoDispose by default (@Riverpod(keepAlive: true) to opt out).

Named param.

final p = Provider<String>(isAutoDispose: true, (ref) => 'hi');

onCancel.

ref.onCancel.

link.close.

link.close() on the KeepAliveLink (or the provider recomputing).

Destroyed often.

They're destroyed frequently during normal use, so any resource they create without onDispose leaks each time.

keepAlive/onDispose.

No — it's the base for nuanced policies via keepAlive() (selective keep) and onDispose (cleanup).

Pin. Part 4.

Inside an autoDispose provider, prevents auto-disposal and returns a KeepAliveLink.

Unpin.

Re-enables automatic disposal (unpins the provider).

After await.

final p = FutureProvider.autoDispose<User>((ref) async {
  final u = await fetch();
  ref.keepAlive(); // only on success
  return u;
});

Nothing to prevent otherwise.

It overrides auto-disposal; a keep-alive-by-default provider never auto-disposes, so there's nothing to prevent.

keepAlive + Timer + onDispose.

extension on Ref {
  void cacheFor(Duration d) {
    final link = keepAlive();
    final t = Timer(d, link.close);
    onDispose(t.cancel);
  }
}

keepAlive not reached.

The await throws, keepAlive() isn't reached, so the failed provider stays auto-dispose and is torn down (retry next time).

Conditional vs always.

Plain keep-alive caches unconditionally forever; autoDispose + keepAlive caches conditionally (you can pin/unpin based on runtime conditions).

cacheFor.

final feed = FutureProvider.autoDispose((ref) async {
  ref.cacheFor(const Duration(minutes: 2));
  return repo.fetch();
});

Destroyed early.

If the provider is destroyed before the timer fires, the timer would dangle (and call link.close on a dead provider); onDispose(timer.cancel) cleans it up.

Unconditional.

Plain keep-alive (no autoDispose) — unconditional app-wide state.

keepAlive + listen.

final link = ref.keepAlive();
ref.listen(authProvider, (_, next) { if (next == null) link.close(); });

inside keep alive.

A riverpod_lint rule about using keepAlive outside an autoDispose context.

Store link.

Store the KeepAliveLink from keepAlive() and call link.close() from a method when the user clears the cache.

pin/hold/close.

keepAlive() to pin, hold the KeepAliveLink, link.close() to unpin when your condition says so.

Recompute. Part 5.

Discard cached state and cause the provider to recompute.

void.

void — it just marks stale.

New value.

The newly-computed value (it invalidates and reads).

invalidate.

onPressed: () => ref.invalidate(dataProvider),

refresh .future.

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

Two calls.

ref.invalidate(p); final v = ref.read(p); — refresh = invalidate + read.

Recompute on read.

It only marks stale; if watched it recomputes, else it recomputes on the next read.

p(arg) vs p.

ref.invalidate(userProvider('1')); // one
ref.invalidate(userProvider);      // all

invalidateSelf.

ref.invalidateSelf().

invalidate after write.

await repo.update(item);
ref.invalidate(itemListProvider);

Use the value?

Default to invalidate for "just refresh"; use refresh only when you need the returned value.

No watcher.

It's lazy; with no listener, it recomputes only on the next read. Use refresh/read to force it now.

Disposed.

It's disposed and recreated on the next read (if watched, it recomputes immediately).

Await.

Pull-to-refresh — you need the Future to await so the indicator spins until the new data arrives.

watch. Part 6.

ref.watch(other) inside its create/build — recomputes when other changes.

watch subtotal.

final taxProvider = Provider((ref) => ref.watch(subtotalProvider) * 0.08);

Depend vs once.

watch creates a dependency (recompute on change); read is a one-off with no dependency.

Methods.

In action methods (one-off reads); watch goes in build().

==.

Equality filtering — if a recomputed value equals the old (==), propagation stops there.

watch.

Change ref.read(source) in build logic to ref.watch(source).

listen.

ref.listen(authProvider, (prev, next) { if (next == null) logOut(); });

.future.

final user = await ref.watch(userProvider.future);

A↔B.

Two providers watching each other (A←B, B←A) — neither can initialize; Riverpod throws.

Merge/third/read.

Merge into one provider; extract a shared third provider; or use one-directional read in an action (not build).

Granular + testable.

Granular rebuilds (only downstream-of-change recompute, trimmed by ==), easy testing/overriding, and the graph documents data flow.

watch in build, read in method.

@override Cart build() => Cart.forUser(ref.watch(userProvider));
void checkout() => ref.read(checkoutRepo).submit(state);

updateShouldNotify.

Yes — override updateShouldNotify on a Notifier to control when listeners are notified.

Acyclic.

A DAG (directed acyclic graph) — no cycles.

Cleanup. Part 7.

Registers a callback that runs when the provider's state is destroyed — to clean up resources.

onDispose close.

ref.onDispose(controller.close);

onDispose cancel.

ref.onDispose(timer.cancel);

dispose().

A State's dispose() method.

Each recompute.

No — it fires whenever state is destroyed, including on every recompute (invalidate/refresh/dependency change).

Last listener vs destroyed.

onCancel = last listener left (not destroyed yet); onDispose = state actually destroyed (release resources).

New listener.

Fires when a new listener appears after onCancel — resume paused work.

sub.cancel.

final sub = stream.listen(handler);
ref.onDispose(sub.cancel);

Stream providers.

StreamProvider/StreamNotifierProvider (for the stream they expose); resources you create by hand are your responsibility.

Call twice.

ref.onDispose(timer.cancel);
ref.onDispose(controller.close); // both run on dispose, in order

Destroyed often.

They're created/destroyed frequently, so any unmanaged resource leaks each time — making onDispose essential.

Cancel dangling timer.

onDispose(timer.cancel) cancels the cache timer if the provider is destroyed before it fires, preventing a leaked timer / callback on a dead provider.

Create + onDispose.

Pair every resource creation with an ref.onDispose for it — like initState/dispose in widgets.

cancel → frame → dispose.

onCancel → wait one frame → onDispose (if still unused); onResume if a listener returns within the frame.

ref.watch(p).when(
  data: (d) => View(d),
  loading: () => const CircularProgressIndicator(),
  error: (e, _) => Column(children: [
    Text('$e'),
    ElevatedButton(onPressed: () => ref.invalidate(p), child: const Text('Retry')),
  ]),
);

final userProvider = FutureProvider.autoDispose.family<User, String>(
  (ref, id) => ref.watch(repo).fetchById(id));
// ref.watch(userProvider('1')); ref.watch(userProvider('2'));

final dashboardProvider = FutureProvider.autoDispose((ref) async {
  ref.cacheFor(const Duration(minutes: 5));
  return ref.watch(repo).fetch();
});

final profileProvider = FutureProvider.autoDispose<Profile>((ref) async {
  final p = await ref.watch(repo).fetch();
  ref.keepAlive();
  return p;
});

RefreshIndicator(
  onRefresh: () => ref.refresh(listProvider.future),
  child: /* list */,
);

final taxProvider = Provider((ref) => ref.watch(subtotalProvider) * 0.08);
final totalProvider = Provider((ref) => ref.watch(subtotalProvider) + ref.watch(taxProvider));

final pollProvider = StreamProvider.autoDispose<int>((ref) {
  final c = StreamController<int>();
  final t = Timer.periodic(const Duration(seconds: 5), (_) => c.add(0));
  ref.onDispose(() { t.cancel(); c.close(); });
  return c.stream;
});

final cacheProvider = Provider<Cache>((ref) {
  final cache = Cache();
  ref.listen(authProvider, (_, next) { if (next == null) cache.clear(); });
  ref.onDispose(cache.dispose);
  return cache;
});

Future<void> addItem(Item i) async {
  await ref.read(repoProvider).add(i);
  ref.invalidate(itemListProvider); // list recomputes
}

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

// Reusable caching policy (Part 4 + Part 7).
extension CacheForExtension on Ref {
  void cacheFor(Duration duration) {
    final link = keepAlive();
    final timer = Timer(duration, link.close);
    onDispose(timer.cancel);
  }
}

final productRepositoryProvider =
    Provider<ProductRepository>((ref) => throw UnimplementedError());

// Parameterized, auto-disposing, cached-on-success product provider.
final productProvider =
    FutureProvider.autoDispose.family<Product, String>((ref, id) async {
  final product = await ref.watch(productRepositoryProvider).fetchById(id); // Part 2/6
  ref.cacheFor(const Duration(minutes: 5)); // keepAlive + timer + onDispose (Parts 4,7)
  return product;                            // reached only on success
});

class ProductScreen extends ConsumerWidget {
  final String productId;
  const ProductScreen({super.key, required this.productId});

  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final productAsync = ref.watch(productProvider(productId)); // family + AsyncValue

    return Scaffold(
      appBar: AppBar(title: const Text('Product')),
      body: RefreshIndicator(
        onRefresh: () => ref.refresh(productProvider(productId).future), // Part 5
        child: productAsync.when(                                        // Part 1
          skipLoadingOnRefresh: true,
          loading: () => const Center(child: CircularProgressIndicator()),
          error: (e, _) => ListView(children: [
            const SizedBox(height: 200),
            Center(child: Text('Failed: $e')),
            Center(
              child: ElevatedButton(
                onPressed: () => ref.invalidate(productProvider(productId)), // retry, Part 5
                child: const Text('Retry'),
              ),
            ),
          ]),
          data: (product) => ListView(children: [
            ListTile(title: Text(product.name), subtitle: Text('\$${product.price}')),
          ]),
        ),
      ),
    );
  }
}

This capstone exercises the whole Core Concepts series: a family keyed by id (Part 2); autoDispose for per-screen memory (Part 3); keepAlive + a timer for a 5-minute cache, cleaned up via onDispose (Parts 4 & 7); the AsyncValue .when with skipLoadingOnRefresh (Part 1); invalidate for retry and refresh for pull-to-refresh (Part 5); and a dependency on the repository (Part 6). Override productRepositoryProvider with a fake to test it all.