AsyncValue<T> class
abstract
An 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.
It also expose some utilities to nicely convert an AsyncValue to
a different object.
For example, a Flutter Widget may use when
to convert an AsyncValue
into either a progress indicator, an error screen, or to show the data:
/// A provider that asynchronously expose the current user
final userProvider = StreamProvider<User>((_) async* {
// fetch the user
});
class Example extends ConsumerWidget {
@override
Widget build(BuildContext context, ScopedReader watch) {
final AsyncValue<User> user = watch(userProvider);
return user.when(
loading: () => CircularProgressIndicator(),
error: (error, stack) => Text('Oops, something unexpected happened'),
data: (value) => Text('Hello ${user.name}'),
);
}
}
If a consumer of an AsyncValue does not care about the loading/error state, consider using data to read the state:
Widget build(BuildContext context, ScopedReader watch) {
// reads the data state directly – will be null during loading/error states
final User user = watch(userProvider).data?.value;
return Text('Hello ${user?.name}');
}
See also:
- FutureProvider and StreamProvider, which transforms a Future into an AsyncValue.
- AsyncValue.guard, to simplify transforming a Future into an AsyncValue.
- The package Freezed (https://github.com/rrousselgit/freezed), which have
generated this AsyncValue class and explains how
map
/when
works.
- Annotations
-
- @freezed
- @sealed
Constructors
- AsyncValue.data(T value)
-
Creates an AsyncValue with a data.
constfactory
- AsyncValue.error(Object error, [StackTrace? stackTrace])
-
Creates an AsyncValue in error state.
factory
- AsyncValue.loading()
-
Creates an AsyncValue in loading state.
constfactory
Properties
Methods
-
map<
TResult extends Object?> ({required TResult data(AsyncData< T> value), required TResult loading(AsyncLoading<T> value), required TResult error(AsyncError<T> value)}) → TResult -
inherited
-
maybeMap<
TResult extends Object?> ({TResult data(AsyncData< T> value)?, TResult loading(AsyncLoading<T> value)?, TResult error(AsyncError<T> value)?, required TResult orElse()}) → TResult -
inherited
-
maybeWhen<
TResult extends Object?> ({TResult data(T value)?, TResult loading()?, TResult error(Object error, StackTrace? stackTrace)?, required TResult orElse()}) → TResult -
inherited
-
noSuchMethod(
Invocation invocation) → dynamic -
Invoked when a nonexistent method or property is accessed.
inherited
-
toString(
) → String -
A string representation of this object.
inherited
-
when<
TResult extends Object?> ({required TResult data(T value), required TResult loading(), required TResult error(Object error, StackTrace? stackTrace)}) → TResult -
inherited
-
whenData<
R> (R cb(T value)) → AsyncValue< R> -
Shorthand for
when
to handle only thedata
case.
Operators
-
operator ==(
Object other) → bool -
The equality operator.
inherited
Static Methods
-
guard<
T> (Future< T> future()) → Future<AsyncValue< T> > - Transforms a Future that may fail into something that is safe to read.