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}');
}

See also:

• FutureProvider and StreamProvider, which transforms a Future into an AsyncValue.
• AsyncValue.guard, to simplify transforming a Future into an AsyncValue.

Implementers

• AsyncData
• AsyncError
• AsyncLoading

Available Extensions

• AsyncValueX

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 error state.

const

factory

AsyncValue.loading()

Creates an AsyncValue in loading state.

const

factory

Properties

hashCode → int

The hash code for this object.

no setter, inherited

runtimeType → Type

A representation of the runtime type of the object.

no setter, inherited

Methods

noSuchMethod(Invocation invocation) → dynamic

Invoked when a nonexistent method or property is accessed.

inherited

toString() → String

A string representation of this object.

inherited

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.