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:
- FutureProvider, StreamProvider which transforms a Future into an AsyncValue.
- AsyncValue.guard, to simplify transforming a Future into an AsyncValue.
- Available extensions
- Annotations
-
- @sealed
- @immutable
Constructors
- AsyncValue.data(T value)
-
Creates an AsyncValue with a data.
constfactory
- AsyncValue.error(Object error, StackTrace stackTrace)
-
Creates an AsyncValue in the error state.
constfactory
- AsyncValue.loading()
-
Creates an AsyncValue in loading state.
constfactory
Properties
-
asData
→ AsyncData<
T> ? -
Available on AsyncValue<
Upcast AsyncValue into an AsyncData, or return null if the AsyncValue is an AsyncLoading/AsyncError.T> , provided by the AsyncValueX extensionno setter -
asError
→ AsyncError<
T> ? -
Available on AsyncValue<
Upcast AsyncValue into an AsyncError, or return null if the AsyncValue is an AsyncLoading/AsyncData.T> , provided by the AsyncValueX extensionno setter - error → Object?
-
The error.
no setter
- hasError → bool
-
Available on AsyncValue<
Whether error is not null.T> , provided by the AsyncValueX extensionno 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<
Whether the associated provider was forced to recompute even though none of its dependencies has changed, after at least one value/error was emitted.T> , provided by the AsyncValueX extensionno setter - isReloading → bool
-
Available on AsyncValue<
Whether the associated provider was recomputed because of a dependency change (using Ref.watch), after at least one value/error was emitted.T> , provided by the AsyncValueX extensionno setter - requireValue → T
-
Available on AsyncValue<
If hasValue is true, returns the value. Otherwise if hasError, rethrows the error. Finally if in loading state, throws a StateError.T> , provided by the AsyncValueX extensionno 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<
Return the value or previous value if in loading/error state.T> , provided by the AsyncValueX extensionno 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<
Perform some actions based on the state of the AsyncValue, or return null if the current state wasn't tested.T> , provided by the AsyncValueX extension -
maybeMap<
R> ({R data(AsyncData< T> data)?, R error(AsyncError<T> error)?, R loading(AsyncLoading<T> loading)?, required R orElse()}) → R -
Available on AsyncValue<
Perform some actions based on the state of the AsyncValue, or call orElse if the current state was not tested.T> , provided by the AsyncValueX extension -
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<
Switch-case over the state of the AsyncValue while purposefully not handling some cases.T> , provided by the AsyncValueX extension -
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<
Performs an action based on the state of the AsyncValue.T> , provided by the AsyncValueX extension -
whenData<
R> (R cb(T value)) → AsyncValue< R> -
Available on AsyncValue<
Shorthand for when to handle only theT> , provided by the AsyncValueX extensiondata
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<
Perform actions conditionally based on the state of the AsyncValue.T> , provided by the AsyncValueX extension
Operators
-
operator ==(
Object other) → bool -
The equality operator.
override