supabase / supabase-flutter / 32036696049

88%

push

github

refactor(realtime)!: replace listener callbacks with streams (#1706)

## What

Converts the callback-based listener APIs in `realtime_client` to
broadcast streams, following the precedent set by
`RealtimeClient.onHeartbeat` (#1517).

### `RealtimeClient`

The `onOpen`, `onClose`, `onError`, and `onMessage`
callback-registration methods are now `Stream` getters (the internal
`stateChangeCallbacks` registry is gone):

```dart
client.onOpen.listen((_) => print('socket opened'));
client.onClose.listen((event) => print('socket closed: $event'));
client.onError.listen((error) => print('socket error: $error'));
client.onMessage.listen((message) => print('message: $message'));
```

### `RealtimeChannel`

`onPostgresChanges` and `onBroadcast` no longer take a `callback` and
instead return typed streams, and `onPresenceSync`, `onPresenceJoin`,
`onPresenceLeave`, and `onSystemEvents` are now stream getters.
`onSystemEvents` also emits a typed `RealtimeSystemPayload` instead of a
raw payload:

```dart
final channel = supabase.channel('room');
channel
    .onPostgresChanges(
      event: PostgresChangeEvent.insert,
      schema: 'public',
      table: 'messages',
    )
    .listen((payload) => print(payload.newRecord));
channel.onBroadcast(event: 'cursor-pos').listen(print);
channel.onPresenceSync.listen((_) => print(channel.presenceState()));
channel.subscribe();
```

`subscribe()` no longer takes a status callback. Status changes (with
the error that caused a `channelError`) are exposed on the new
`onStatusChange` stream via the new `RealtimeSubscribeStatusChange`
class:

```dart
channel.onStatusChange.listen((change) {
  print('${change.status} ${change.error ?? ''}');
});
channel.subscribe();
```

All channel streams complete when the channel closes.

## Why

Streams are the idiomatic Dart shape for event listeners: consumers get
`listen`/`map`/`where`/`firstWhere`/`timeout`, multiple subscribers,
and, most importantly, easy listener removal via
`StreamSubscri... (continued)

109 of 122 new or added lines in 4 files covered. (89.34%)

5767 of 6540 relevant lines covered (88.18%)

4.14 hits per line