AsyncValue<T> class abstract

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.

It also exposes 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 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 user.when(
      loading: () => CircularProgressIndicator(),
      error: (error, stack) => Text('Oops, something unexpected happened'),
      data: (user) => Text('Hello ${user.name}'),
    );
  }
}

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

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

  // Reading .value will be throw both on loading and error states.
  final User user2 = ref.watch(userProvider).requiredValue;

  ...
}

See also:

Available extensions
Annotations

Constructors

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

Properties

error Object?
The error.
no setter
hashCode int
The hash code for this object.
no setteroverride
hasValue bool
Whether value is set.
no setter
isLoading bool
Whether some new value is currently asynchronously loading.
no setter
runtimeType Type
A representation of the runtime type of the object.
no setterinherited
stackTrace StackTrace?
The stacktrace of error.
no setter
value → T?
The value currently exposed.
no setter

Methods

copyWithPrevious(AsyncValue<T> previous, {bool isRefresh = true}) AsyncValue<T>
Clone an AsyncValue, merging it with previous.
map<R>({required R data(AsyncData<T> data), required R error(AsyncError<T> error), required R loading(AsyncLoading<T> loading)}) → R
Perform some action based on the current state of the AsyncValue.
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
toString() String
A string representation of this object.
override
unwrapPrevious() AsyncValue<T>
The opposite of copyWithPrevious, reverting to the raw AsyncValue with no information on the previous state.

Operators

operator ==(Object other) bool
The equality operator.
override

Static Methods

guard<T>(Future<T> future(), [bool test(Object)?]) Future<AsyncValue<T>>
Transforms a Future that may fail into something that is safe to read.