AsyncValue<StateT> class sealed Core

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.

AsyncValue is a sealed class, and is designed to be used with pattern matching to handle the different states:

/// 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 switch (user) {
      AsyncValue(hasError: true) => Text('Oops, something unexpected happened'),
      AsyncValue(:final value, hasValue: true) => Text('Hello ${value.name}'),
      _ => CircularProgressIndicator(),
    );
  }
}

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

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

  ...
}

By using requireValue, we get an immediate access to the value. At the same time, if we made a mistake and the value is not available, we will get an exception. This is a good thing because it will help us to spot problem.

Constructors

AsyncValue.data(StateT 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({num progress}): Creates an AsyncValue in loading state.
const

factory

Properties

asData → AsyncData<StateT>?: Upcast AsyncValue into an AsyncData, or return null if the AsyncValue is an AsyncLoading/AsyncError.
no setter
asError → AsyncError<StateT>?: 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: 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
isFromCache → bool: Whether the value was obtained using Riverpod's offline-persistence feature.
no setter
isLoading → bool: Whether some new value is currently asynchronously loading.
no setter
isRefreshing → bool: 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: Whether the associated provider was recomputed because of a dependency change (using Ref.watch), after at least one value/error was emitted.
no setter
progress → num?: The current progress of the asynchronous operation.
no setter
requireValue → StateT: 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 → StateT?: The value currently exposed.
no setter

Methods

copyWithPrevious(AsyncValue<StateT> previous, {bool isRefresh = true}) → AsyncValue<StateT>: Clone an AsyncValue, merging it with previous.
map<R>({required R data(AsyncData<StateT> data), required R error(AsyncError<StateT> error), required R loading(AsyncLoading<StateT> loading)}) → R: Perform some action based on the current state of the AsyncValue.
mapOrNull<R>({R? data(AsyncData<StateT> data)?, R? error(AsyncError<StateT> error)?, R? loading(AsyncLoading<StateT> loading)?}) → R?: 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<StateT> data)?, R error(AsyncError<StateT> error)?, R loading(AsyncLoading<StateT> loading)?, required R orElse()}) → R: 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(StateT data)?, R error(Object error, StackTrace stackTrace)?, R loading()?, required R orElse()}) → R: 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<StateT>: 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(StateT data), required R error(Object error, StackTrace stackTrace), required R loading()}) → R: Performs an action based on the state of the AsyncValue.
whenData<R>(R cb(StateT value)) → AsyncValue<R>: Shorthand for when to handle only the data case.
whenOrNull<R>({bool skipLoadingOnReload = false, bool skipLoadingOnRefresh = true, bool skipError = false, R? data(StateT data)?, R? error(Object error, StackTrace stackTrace)?, R? loading()?}) → R?: 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.