Asynchronous state

A @Computed getter that returns a Future or a Stream is asynchronous state: the request is made when the value is first read, and again when what it depends on changes.

Why

A screen that shows loaded data keeps three things by hand: the data, whether a load is running, and the last error. And it must ask again when the filter changes, and drop the answer of the request before. Here the getter is the request, and the rest follows.

Example

@Component()
class Catalog {
  Catalog(this.client);

  final CatalogClient client;

  @Signal()
  String genre = 'fiction';

  @Computed()
  Future<List<Book>> get books => client.byGenre(genre);
}

How it behaves

The state

The state is an extension on what the getter returned: catalog.books.state, an AsyncValue<List<Book>>.

Member of AsyncValue<T> Meaning
isLoading Whether a load is running: the first one, or a refresh()
hasValue Whether there is a value: of this load, or the last one kept while another runs or after it failed
value The value, null when there is none
requireValue The value; throws the error when the load failed without one, and a StateError while the first load runs
error, stackTrace, hasError What the last load threw
isRefreshing Whether a load runs while the last value is still shown
when(data: ..., loading: ..., error: ...) One of three: data when there is a value (also while it is refreshed), else error, else loading
final state = catalog.books.state;
return state.when(
  data: (books) => BookList(books),
  loading: () => const Spinner(),
  error: (error, _) => Text('$error'),
);

Read in a widget's build (a Spring widget, a Watch, an AsyncView), the state rebuilds the widget when it moves.

state is for the value of a @Computed getter of a bean as the container hands it out. On any other future it throws a StateError that says so.

Asking again

Call What it does
catalog.books.refresh() Asks again and keeps the last value on screen meanwhile (isRefreshing)
catalog.books.reload() Asks again from nothing: the state is loading meanwhile

Both complete when the new answer is there. A change of what the value depends on (genre assigned) starts from nothing too.

A stream

A Stream is the same:

@Computed()
Stream<double> get price => client.prices(genre);

catalog.price.state is its last event: loading before the first, then data, or the error. A new genre gives a new stream. The starter listens to the stream itself, so a single-subscription stream must not be listened to a second time.

What it depends on is read before the first await

What the value depends on must be read before the first await. After an await nothing is followed any more. This is how signals work, not a limit of the starter:

@Computed()
Future<List<Book>> get books async {
  final genre = this.genre;                 // read first: followed
  final token = await auth.token();
  return client.byGenre(genre, token);      // `this.genre` here would not be
}

The build does not check this: a field read after an await compiles, and the value is then not loaded again when that field changes.

Showing it

AsyncView shows the data, the load or the failure: see In widgets.

See also