AsyncValue<T> class

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:

Implementers
Annotations

Constructors

AsyncValue.data(@nullable T value)
Creates an AsyncValue with a data. [...]
const
factory
AsyncValue.error(Object error, [StackTrace stackTrace])
Creates an AsyncValue in error state. [...]
factory
AsyncValue.loading()
Creates an AsyncValue in loading state. [...]
const
factory

Properties

data AsyncData<T>
The current data, or null if in loading/error. [...]
read-only
hashCode int
The hash code for this object. [...]
read-only, inherited
runtimeType Type
A representation of the runtime type of the object.
read-only, inherited

Methods

map<Result extends Object>({Result data(AsyncData<T> value), Result loading(AsyncLoading<T> value), Result error(AsyncError<T> value)}) → Result
@optionalTypeArgs, inherited
maybeMap<Result extends Object>({Result data(AsyncData<T> value), Result loading(AsyncLoading<T> value), Result error(AsyncError<T> value), Result orElse()}) → Result
@optionalTypeArgs, inherited
maybeWhen<Result extends Object>({Result data(T value), Result loading(), Result error(Object error, StackTrace stackTrace), Result orElse()}) → Result
@optionalTypeArgs, inherited
noSuchMethod(Invocation invocation) → dynamic
Invoked when a non-existent method or property is accessed. [...]
inherited
toString() String
Returns a string representation of this object.
inherited
when<Result extends Object>({Result data(T value), Result loading(), Result error(Object error, StackTrace stackTrace)}) → Result
@optionalTypeArgs, inherited
whenData<R>(R cb(T value)) AsyncValue<R>
Shorthand for when to handle only the data 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. [...]