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 errorstates.
  final User user2 = ref.watch(userProvider).requiredValue;

  ...
}

See also:

Implementers
Available Extensions
Annotations
  • @sealed
  • @immutable

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.
read-only
hashCode → int
The hash code for this object.
read-onlyoverride
hasValue → bool
Whether value is set.
read-only
isLoading → bool
Whether some new value is currently asynchronously loading.
read-only
runtimeType → Type
A representation of the runtime type of the object.
read-onlyinherited
stackTrace → StackTrace?
The stacktrace of error.
read-only
value → T?
The value currently exposed.
read-only

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()) → Future<AsyncValue<T>>
Transforms a Future that may fail into something that is safe to read.