AsyncValue<T> class abstract

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, WidgetRef ref) {
    final AsyncValue<User> user = ref.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 value to read the state:

Widget build(BuildContext context, WidgetRef ref) {
  // reads the data state directly – will be throw during loading/error states
  final User user = ref.watch(userProvider).value;

  return Text('Hello ${user.name}');
}

Constructors

AsyncValue.data(T value): Creates an AsyncValue with a data.
const

factory
AsyncValue.error(Object error, {StackTrace? stackTrace}): Creates an AsyncValue in 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 in loading/error state.
no setter
data → AsyncData<T>?: Available on AsyncValue<T>, provided by the AsyncValueX extension
Upcast AsyncValue into an AsyncData, or return null if the AsyncValue is in loading/error state.
no setter
hashCode → int: The hash code for this object.
no setterinherited
runtimeType → Type: A representation of the runtime type of the object.
no setterinherited
value → T?: Available on AsyncValue<T>, provided by the AsyncValueX extension
Attempts to synchronously.
no setter

Methods

map<R>({required R data(AsyncData<T> data), required R error(AsyncError<T> error), required R loading(AsyncLoading<T> loading)}) → R: Available on AsyncValue<T>, provided by the AsyncValueX extension
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>({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.
inherited
when<R>({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>({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.
inherited

Static Methods

guard<T>(Future<T> future()) → Future<AsyncValue<T>>: Transforms a Future that may fail into something that is safe to read.