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

asData AsyncData<T>?

Available on AsyncValue<T>, provided by the AsyncValueX extension

Upcast AsyncValue into an AsyncData, or return null if the AsyncValue is an AsyncLoading/AsyncError.
no setter
asError AsyncError<T>?

Available on AsyncValue<T>, provided by the AsyncValueX extension

Upcast AsyncValue into an AsyncError, or return null if the AsyncValue is an AsyncLoading/AsyncData.
no setter
error Object?
The error.
no setter
hasError bool

Available on AsyncValue<T>, provided by the AsyncValueX extension

Whether error is not null.
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
isRefreshing bool

Available on AsyncValue<T>, provided by the AsyncValueX extension

Whether the associated provider was forced to recompute even though none of its dependencies has changed, after at least one value/error was emitted.
no setter
isReloading bool

Available on AsyncValue<T>, provided by the AsyncValueX extension

Whether the associated provider was recomputed because of a dependency change (using Ref.watch), after at least one value/error was emitted.
no setter
requireValue → T

Available on AsyncValue<T>, provided by the AsyncValueX extension

If hasValue is true, returns the value. Otherwise if hasError, rethrows the error. Finally if in loading state, throws a StateError.
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
valueOrNull → T?

Available on AsyncValue<T>, provided by the AsyncValueX extension

Return the value or previous value if in loading/error state.
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.
mapOrNull<R>({R? data(AsyncData<T> data)?, R? error(AsyncError<T> error)?, R? loading(AsyncLoading<T> loading)?}) → R?

Available on AsyncValue<T>, provided by the AsyncValueX extension

Perform some actions based on the state of the AsyncValue, or return null if the current state wasn't tested.
maybeMap<R>({R data(AsyncData<T> data)?, R error(AsyncError<T> error)?, R loading(AsyncLoading<T> loading)?, required R orElse()}) → R

Available on AsyncValue<T>, provided by the AsyncValueX extension

Perform some actions based on the state of the AsyncValue, or call orElse if the current state was not tested.
maybeWhen<R>({bool skipLoadingOnReload = false, bool skipLoadingOnRefresh = true, bool skipError = false, R data(T data)?, R error(Object error, StackTrace stackTrace)?, R loading()?, required R orElse()}) → R

Available on AsyncValue<T>, provided by the AsyncValueX extension

Switch-case over the state of the AsyncValue while purposefully not handling some cases.
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.
when<R>({bool skipLoadingOnReload = false, bool skipLoadingOnRefresh = true, bool skipError = false, required R data(T data), required R error(Object error, StackTrace stackTrace), required R loading()}) → R

Available on AsyncValue<T>, provided by the AsyncValueX extension

Performs an action based on the state of the AsyncValue.
whenData<R>(R cb(T value)) AsyncValue<R>

Available on AsyncValue<T>, provided by the AsyncValueX extension

Shorthand for when to handle only the data case.
whenOrNull<R>({bool skipLoadingOnReload = false, bool skipLoadingOnRefresh = true, bool skipError = false, R? data(T data)?, R? error(Object error, StackTrace stackTrace)?, R? loading()?}) → R?

Available on AsyncValue<T>, provided by the AsyncValueX extension

Perform actions conditionally based on the state of the AsyncValue.

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.