
# Changes of rows

Some stores report the changes of their rows as they are committed. A repository gives them two ways, as two kinds of derived methods: `changes…By`, a stream of the changes that concern the conditions, and `watch…By`, the query's result, emitted again after every such change.

## Why

A screen that shows a list wants to know when the list changed, not to ask every few seconds. Stores can tell: the in-memory store knows its own commits, and a store of another package can listen to its database (the `supabase` store does, through Realtime). One type for a change and one meaning of "concerns this query" let the same code work on any of them.

## Example

```dart
abstract interface class Tasks implements CrudRepository<Task, int> {
  // The result of the query, emitted when the stream is listened to and
  // again after every change that concerns it.
  Stream<List<Task>> watchByListIdOrderByPositionAsc(int listId);

  // Every task: nothing after `By`, as `findAllBy()`.
  Stream<List<Task>> watchAllBy(Sort sort);

  // The inserts, updates and deletes of the rows the conditions match,
  // each with the row after and before.
  Stream<RowChange<Task>> changesByListId(int listId);
}
```

```dart
tasks.watchByListIdOrderByPositionAsc(7).listen(show);

tasks.changesByListId(7).listen((change) {
  if (change.kind == RowChangeKind.delete) {
    remove(change.id);
  } else {
    put(change.row!);
  }
});
```

## RowChange

A `RowChange<T>` is one change of a row of an entity's table, reported once the change is committed:

| Member | Meaning |
|---|---|
| `kind` | `RowChangeKind.insert`, `update` or `delete`. |
| `row` | The row after the change: the new row of an insert or an update; `null` for a delete. |
| `previous` | The row before the change, when the store knows it; `null` for an insert. Some stores report only the id of a deleted row, or nothing of an updated row's past. |
| `id` | The id of the row, as the store holds it; `null` when the store does not tell. |

## Which stores

A store that reports changes says `changes` in its [capabilities](stores.md) and implements `ChangeStreamDataStore`.

| Store | Changes |
|---|---|
| in memory | yes: at commit, never from a transaction that rolls back |
| SQL (SQLite, PostgreSQL) | no |
| `supabase` ([spring_boot_starter_supabase](../spring-boot-starter-supabase/realtime.md)) | yes, with Realtime |

A repository with a `watch…By` or a `changes…By` method on a store without them fails when it is created, and at build time when the build knows the store.

## The two kinds of methods

They are derived methods, read like a [derived query](derived-queries.md):

| Prefix | Returns | Takes |
|---|---|---|
| `watch…By` | `Stream<List<T>>`: the query's result, kept up to date | What a find takes: `First` / `Top`, `Distinct`, `OrderBy`, a `Sort` or a `Pageable` parameter. |
| `changes…By` | `Stream<RowChange<T>>`: the changes of the rows the conditions match | Conditions only: no `First`, `Top`, `Distinct` or `OrderBy` in its name, no `Sort` or `Pageable` parameter. |

- **Any other return type is a build error**, naming the expected one.
- **Nothing after `By` means every row:** `watchAllBy()`, `changesAllBy()`.
- **No `@Lock`** on a watch method: it reads outside the caller's transaction.
- `stream…By` keeps its meaning: the result once, as a stream.

The generator writes each as a constant `PartTree` and a call of `operations.watch` or `operations.changes`, described below.

## A stream of changes

`RepositoryOperations.changes(tree, arguments)` is the stream of the committed changes that concern the conditions of a derived query, from the moment it is listened to until the subscription is cancelled.

- **A change concerns the conditions** when the row after it or the row before it matches. So a row that stops matching is reported too.
- A change whose rows the store does not know always concerns them.
- **A store filters as far as it can.** One that cannot apply all of the conditions says so (`filtersChanges`), and the operations test each change themselves, with `CriteriaMatcher`.
- Cancelling the subscription stops the store's reporting.

## A result kept up to date

`RepositoryOperations.watch(tree, arguments, sort:, pageable:)` emits the query's result when it is listened to, and again after every committed change that may concern it, by running the query again.

- **The queries never overlap.** Changes that arrive while one runs are answered by exactly one more query after it, however many they are. So the last list emitted is always read after the last change.
- **A list is emitted after each query**, also when it equals the one before.
- **An error does not end the stream:** an error of a query or of the store's changes is forwarded, and the next change queries again.
- **A paused subscription queries nothing** and catches up with one query when it resumes. The stream has one listener.
- **Outside the caller's transaction.** The queries run outside the transaction of the code that listens: listen outside a transaction, or expect the committed rows only.

## By hand

Without generated code (a library, a test) the two operations are called with the `PartTree` of a derived query:

```dart
const byGenre = PartTree('changesByGenre', [
  OrPart([Part('genre')]),
]);
const watchByGenre = PartTree(
  'watchByGenreOrderByTitle',
  [
    OrPart([Part('genre')]),
  ],
  sort: Sort([SortOrder.asc('title')]),
);

final books = RepositoryFactory(
  mappingContext: mappingContext,
  converter: converter,
  stores: [store],
).operations<Book, int>('Books', annotations: [UseStore(store.name)]);

books.changes(byGenre, [Genre.science]).listen(apply);
books.watch(watchByGenre, [Genre.science]).listen(show);
```

## CriteriaMatcher

`CriteriaMatcher` tests an instance, a row or a `RowChange` against a `Criteria` without a database. It is what the in-memory store finds with, and what filters a stream of changes the store could not filter itself.

```dart
final matcher = CriteriaMatcher<Book>(
  entity,
  Criteria(tree.predicate, ['Dune']),
  converter: converter,
);
matcher.matches(book);                                  // an instance
matcher.matchesRow({'title': 'Dune', 'year': 1965});    // a row
matcher.concerns(change);                               // a RowChange
```

The conditions follow SQL: a comparison with `null` is false (`IsNull` and `IsNotNull` aside), `IgnoreCase` lower-cases both sides, `Like` takes `%` and `_` with `\` to escape them, `Between` is inclusive, a reference is compared by its id. A property that is not a column of the entity is an `InvalidDataAccessApiUsageException` when the matcher is made.

## A store that reports changes

```dart
abstract interface class ChangeStreamDataStore implements DataStore {
  Stream<RowChange<T>> changes<T extends Object>(
    PersistentEntity<T> entity, {
    Criteria? criteria,
  });

  bool filtersChanges<T extends Object>(
    PersistentEntity<T> entity,
    Criteria criteria,
  );
}
```

`changes` reports from the moment the stream is listened to, each change after it is committed, until the subscription is cancelled. `filtersChanges` is `false` when the store cannot apply all of the criteria: the stream then holds more, and the caller tests each change itself.

## In Spring (Java)

None in Spring Data JDBC. The nearest is Spring Data MongoDB's change streams (`ChangeStreamEvent`, `ReactiveMongoOperations.changeStream`).

## See also

- [Stores and their capabilities](stores.md)
- [Derived queries](derived-queries.md)
- [The generator and data](../spring-core-dart-generator/data.md)
- [Supabase Realtime](../spring-boot-starter-supabase/realtime.md)
