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:

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...',
);

@link https://dartsignals.dev/async/state

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<T>, provided by the UnpackAsyncState extension

Converts the AsyncState to an Unpacked. Usefull for linearizing the flow of async operations in bodies of code. example
no 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