
# 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

```dart
@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 `books` is first read. Every reader gets the same future until `genre` is 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` |

```dart
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:

```dart
@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:

```dart
@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](widgets.md#asyncview).

## See also

- [In widgets](widgets.md)
- [Fields and computed values](fields-and-computed.md)
- [What the build checks](build-checks.md)
