
# Effects

An `@Effect` method runs once when the bean is made, and again each time something it read changes: a field or a computed value of its own bean or of another.

## Why

Some work follows state without being asked for: saving the basket when it changes, recalculating a price. Written by hand it is a listener to add, to remove, and to keep in step with what the method really reads. An effect follows what it read.

## Example

```dart
@Effect()                          // runs again whenever items changes
void save() => storage.write(items);
```

```dart
@Effect()
void recalc() {
  final user = untracked(() => session.user);   // read, not followed
  price = pricing.of(basket.items, user);        // runs for basket.items only
}
```

## The rules

- An effect is a public method without parameters that returns nothing.
- It follows everything it reads, except what it reads inside `untracked(() => ...)`.
- It stops when the bean is destroyed (see [The lifetime of state](lifetime.md)).
- The debug tab says how often each ran.

## When an effect runs

An effect runs at once when what it read is assigned: at the end of the method that assigned it, not in a later frame. So after `basket.add(book)` returns, `save` has already run.

## An effect that throws

An effect that throws does not fail the assignment that ran it. The error is reported (`FlutterError.reportError`, as for a listener of a `ChangeNotifier`), the field keeps the new value, the code that assigned goes on, and the effect runs again at the next change of what it followed. One that throws on its first run, as the bean is made, stops the bean from being made.

A `@Computed` getter that throws fails its reader with what it threw. The failure is not kept: the next read computes again.

An effect may assign what it reads (to keep a value within bounds): it runs again until nothing changes.

## One change for a method

A method of a bean with such members is one change, whatever it assigns:

```dart
void clear() {
  items.clear();
  coupon = null;
}                    // readers are told once, when it returns
```

An effect that reads both runs once, and never sees the state between the two. A widget that reads both is built once. A setter that is no followed field is one change too.

An asynchronous method is one change up to its first `await`; after it each assignment is its own (wrap them in `batch` to tell them together). A method that throws still tells what it assigned, once, and the error is its caller's.

For several calls from outside, `batch(() { ... })` does the same:

```dart
batch(() {
  basket.add(dune);
  basket.apply('TEN');
});
```

`batch` and `untracked` are the two functions of `signals_core` the starter re-exports.

## With a transaction or another advice

A bean with followed state may carry other advice too (`@Transactional`, `@Cacheable`, an aspect). Both run, in one proxy:

```dart
@Service()
class Checkout {
  @Signal()
  OrderStatus status = OrderStatus.open;

  @Transactional()
  Future<void> pay(Order order) async {
    await orders.save(order);
    status = OrderStatus.paid;     // after the work that may fail
  }
}
```

- **A rollback does not undo the fields.** The transaction rolls the database back; a field keeps what the method assigned, and its readers were told. Assign after the work that may fail, or assign the old value back in a `catch`.
- **Other advice skips the bean's own calls**, as in any bean and as in Spring: `@Transactional` on a method applies to a call from outside, not to one the bean makes on itself. The state is followed either way.
- **On a `@Computed` member the other advice runs when the value is computed**, not for each read of the kept one: a transaction is opened once per load.
- **`@PreAuthorize` on a `@Computed` member is checked for every read.** Method security runs before every other advice, so a kept value is never handed to someone who may not read it.
- **A guard protects the member it is on, not what is under it.** A plain `@Signal` field under a guarded value is anybody's to read and assign: guard the methods that assign it as well. A value another member of the same bean makes from the guarded one is not guarded; put the guard on what callers read.
- **A check on an `@Effect` is on whoever changes the state.** Nobody calls an effect: it runs as the bean is made, then for whoever assigns what it read. For a caller the check refuses it does not run (the refusal is reported), and with no user at the start the bean is not made. A check belongs on the methods that change the state.

The advice that follows state is outside every advice of the default order. An advice with an earlier order (method security, an aspect with `@Order`) is outside it, and runs for every read.

## See also

- [Fields and computed values](fields-and-computed.md)
- [The lifetime of state](lifetime.md)
- [The debug tab and the log](debug-tab.md)
