AsyncState<T> class
sealed
A sealed union representing the lifecycle states of an asynchronous operation.
AsyncState<T> is commonly wrapped by AsyncSignal or returned by asynchronous
computed signals (computedAsync, computedFrom) to model loading, success (data),
and error outcomes.
State Hierarchy
The states are modeled as a robust hierarchy of immutable types:
- AsyncLoading: Pure loading state with no pre-existing data.
- AsyncData: Success state holding a resolved value of type
T.- AsyncDataRefreshing: Refreshing in the background (holding historical data).
- AsyncDataReloading: Reloading (holding historical data).
- AsyncError: Failure state holding an error and optional stack trace.
- AsyncErrorRefreshing: Refreshing in the background (holding historical error).
- AsyncErrorReloading: Reloading (holding historical error).
Pattern Matching & Switch Expressions
Standard Dart switch expressions provide type-safe branching across all states:
Important
Branch Matching Order & Existing Value Preservation:
Since reloading and refreshing states (e.g., AsyncDataRefreshing, AsyncDataReloading) implement both AsyncData and AsyncLoading, matching on AsyncLoading first will prematurely swallow existing data!
Always place AsyncData and AsyncError branches before AsyncLoading to ensure pre-existing data or error states are successfully rendered during refreshes:
final value = switch (state) {
AsyncDataRefreshing<int> r => 'Refreshing with value: ${r.value}',
AsyncDataReloading<int> r => 'Reloading with value: ${r.value}',
AsyncData<int> data => 'Stable value: ${data.value}',
AsyncErrorRefreshing<int> r => 'Refreshing error: ${r.error}',
AsyncErrorReloading<int> r => 'Reloading error: ${r.error}',
AsyncError<int> error => 'Stable error: ${error.error}',
AsyncLoading<int>() => 'Pure Loading State (no prior data)',
};
Standard Branching Methods (map and maybeMap)
If you prefer standard callbacks over switch expressions, use map or maybeMap:
state.map(
data: (value) => 'Value: $value',
error: (error, stackTrace) => 'Error: $error',
loading: () => 'Loading...',
);
- Available extensions
Constructors
- AsyncState.data(T data)
-
Create a state with a value
factory
- AsyncState.dataRefreshing(T data)
-
Create a state with a value that is refreshing
factory
- AsyncState.dataReloading(T data)
-
Create a state with a value that is reloading
factory
- AsyncState.error(Object error, [StackTrace? stackTrace])
-
Create a state with an error
factory
- AsyncState.errorRefreshing(Object error, [StackTrace? stackTrace])
-
Create a state with an error that is refreshing
factory
- AsyncState.errorReloading(Object error, [StackTrace? stackTrace])
-
Create a state with an error that is reloading
factory
- AsyncState.loading()
-
Create a loading state
factory
Properties
- error → Object?
-
Returns the error of the state.
no setter
- hasError → bool
-
Returns true if the state has an error
no setter
- hashCode → int
-
The hash code for this object.
no setteroverride
- hasValue → bool
-
Returns true if the state has a value
no setter
- isLoading → bool
-
Check if the state is a loading state
no setter
- isRefreshing → bool
-
Returns true if the state is refreshing with a loading flag,
has a value or error and is not the loading state
no setter
- isReloading → bool
-
Returns true if the state is reloading with having a value or error,
and is the loading state
no setter
- requireValue → T
-
Force unwrap the value of the state.
no setter
- runtimeType → Type
-
A representation of the runtime type of the object.
no setterinherited
- stackTrace → StackTrace?
-
Returns the stack trace of the state.
no setter
-
unpacked
→ Unpacked<
T> -
Available on AsyncState<
Converts the AsyncState to an Unpacked. Usefull for linearizing the flow of async operations in bodies of code. exampleT> , provided by the UnpackAsyncState extensionno setter - value → T?
-
Returns the value of the state.
no setter
Methods
-
map<
E> ({required AsyncDataBuilder< E, T> data, required AsyncErrorBuilder<E> error, required AsyncStateBuilder<E> loading, AsyncStateBuilder<E> ? reloading, AsyncStateBuilder<E> ? refreshing}) → E - Map the state to a value.
-
maybeMap<
E> ({AsyncDataBuilder< E, T> ? data, AsyncErrorBuilder<E> ? error, AsyncStateBuilder<E> ? loading, AsyncStateBuilder<E> ? reloading, AsyncStateBuilder<E> ? refreshing, required AsyncStateBuilder<E> orElse}) → E - Map the state to a value with optional or else.
-
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 ==(
covariant AsyncState< T> other) → bool -
The equality operator.
override