supabase / supabase-flutter / 39624049069

93%

push

github

feat(supabase): add typed onTableChanges for postgres changes (#2003)

Resolves SDK-2311.

The typed `stream()` and `streamOnly()` cover "the current rows, kept up
to date". For event-shaped use cases (reacting to an insert, comparing
old and new values, listening to one event type, or skipping the initial
fetch on a high-volume table), users still had to drop down to the
untyped `onPostgresChanges`, with string table and column names and
`Map<String, dynamic>` records.

This adds a typed counterpart as an extension on `RealtimeChannel`, in
`packages/supabase` so `supabase_realtime` keeps no dependency on
postgrest:

```dart
final channel = supabase.channel('room-200');
channel
    .onTableChanges(Messages.table, filters: [Messages.roomId.eq(200)])
    .listen((change) {
      switch (change) {
        case TypedPostgresInsert(:final newRow):
          showToast(newRow.body);
        case TypedPostgresUpdate(:final newRow, :final oldRow):
          if (oldRow.read(Messages.status) != newRow.status) {
            // ...
          }
        case TypedPostgresDelete(:final oldRow):
          remove(oldRow.read(Messages.id));
      }
    });
channel.subscribe();
```

## Changes

- `onTableChanges(table, event:, filters:)` emits a sealed
`TypedPostgresChange<Row, Element>`: `TypedPostgresInsert`,
`TypedPostgresUpdate` or `TypedPostgresDelete`. The new row is decoded
through `PostgrestTable.rowFromJson`.
- `onTableChangesOnly(table, columns:, ...)` sends `columns` plus the
primary key as the realtime `select`, and the new row is a
`PostgrestPartialRow` read through those columns, mirroring
`streamOnly`.
- `oldRow` is a `PostgrestPartialRow`, because realtime sends only the
primary key unless the table has `REPLICA IDENTITY FULL` and no row
level security. A new internal `PostgrestPartialRow.fromPresentColumns`
makes any stored column the payload holds readable, and reading a
missing one throws the usual `StateError` listing the columns that are
there.
- The... (continued)

102 of 119 new or added lines in 7 files covered. (85.71%)

10704 of 11665 relevant lines covered (91.76%)

5.39 hits per line