LogoSignals.dart
Copy Markdown
rodydavis/signals.dart ★9999⑂99

Type: AsyncState

API reference and details for AsyncState from signals.dart.

AsyncState#

Kind: class  |  Package: package:signals_core

Class: AsyncState#

A sealed union representing the lifecycle states of an asynchronous operation.

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

Members of AsyncState#

Member Type Signature Description
AsyncState constructor dart AsyncState()
AsyncState.dataReloading constructor dart AsyncState.dataReloading(T data) Create a state with a value that is reloading
AsyncState.dataRefreshing constructor dart AsyncState.dataRefreshing(T data) Create a state with a value that is refreshing
AsyncState.data constructor dart AsyncState.data(T data) Create a state with a value
AsyncState.errorReloading constructor dart AsyncState.errorReloading(Object error, [StackTrace? stackTrace]) Create a state with an error that is reloading
AsyncState.errorRefreshing constructor dart AsyncState.errorRefreshing(Object error, [StackTrace? stackTrace]) Create a state with an error that is refreshing
AsyncState.error constructor dart AsyncState.error(Object error, [StackTrace? stackTrace]) Create a state with an error
AsyncState.loading constructor dart AsyncState.loading() Create a loading state
hasValue method dart bool hasValue Returns true if the state has a value
hasError method dart bool hasError Returns true if the state has an error
isLoading method dart bool isLoading Check if the state is a loading state
isRefreshing method dart bool isRefreshing Returns true if the state is refreshing with a loading flag,
isReloading method dart bool isReloading Returns true if the state is reloading with having a value or error,
requireValue method dart T requireValue Force unwrap the value of the state.
value method dart T? value Returns the value of the state.
error method dart Object? error Returns the error of the state.
stackTrace method dart StackTrace? stackTrace Returns the stack trace of the state.
map method dart E map({required AsyncDataBuilder<E, T> data, required AsyncErrorBuilder error, required AsyncStateBuilder loading, AsyncStateBuilder? reloading, AsyncStateBuilder? refreshing}) Map the state to a value.
maybeMap method dart E maybeMap({AsyncDataBuilder<E, T>? data, AsyncErrorBuilder ? error, AsyncStateBuilder ? loading, AsyncStateBuilder ? reloading, AsyncStateBuilder? refreshing, required AsyncStateBuilder orElse}) Map the state to a value with optional or else.
== method dart bool ==(covariant AsyncState other)
hashCode method dart int hashCode

References#

The AsyncState type is referenced and used in the following pages: