AsyncValue<ValueT> class sealed Core

A utility for safely manipulating asynchronous data.

By using AsyncValue, you are guaranteed that you cannot forget to handle the loading/error state of an asynchronous operation.

AsyncValue is a sealed class, and is designed to be used with pattern matching to handle the different states:

/// A provider that asynchronously exposes the current user
final userProvider = StreamProvider<User>((_) async* {
  // fetch the user
});

class Example extends ConsumerWidget {
  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final AsyncValue<User> user = ref.watch(userProvider);

    return switch (user) {
      AsyncValue(hasError: true) => Text('Oops, something unexpected happened'),
      AsyncValue(:final value, hasValue: true) => Text('Hello ${value.name}'),
      _ => CircularProgressIndicator(),
    );
  }
}

If a consumer of an AsyncValue does not care about the loading/error state, consider using requireValue to read the state:

Widget build(BuildContext context, WidgetRef ref) {
  // Reading .requiredValue will be throw both on loading and error states.
  final User user = ref.watch(userProvider).requiredValue;

  ...
}

By using requireValue, we get an immediate access to the value. At the same time, if we made a mistake and the value is not available, we will get an exception. This is a good thing because it will help us to spot problem.

See also:

• FutureProvider, StreamProvider which transforms a Future into an AsyncValue.
• AsyncValue.guard, to simplify transforming a Future into an AsyncValue.