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 request is made when
booksis first read. Every reader gets the same future untilgenreis assigned; then another request is made. - In code it is an ordinary future:
final books = await catalog.books;. - An answer that comes after a newer request was made is dropped.
- A failure is a state, not an exception thrown into a widget.
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.