Realtime — Flutter SDK

Subscribe

final sub = bunbase.realtime.subscribe(
  'collection:posts',
  onEvent: (RealtimeEvent<Map<String, dynamic>> event) {
    switch (event.event) {
      case RealtimeEventType.create:
        print('New post: ${event.record}');
      case RealtimeEventType.update:
        print('Updated: ${event.record}');
      case RealtimeEventType.delete:
        print('Deleted: ${event.record}');
    }
  },
);

// Unsubscribe when done:
sub.cancel();

Typed subscribe

Decode records directly into your model:

final sub = bunbase.realtime.subscribeTyped<Post>(
  'collection:posts',
  Post.fromJson,
  onEvent: (RealtimeEvent<Post> event) {
    print(event.record.title);
  },
);

Filter options

final sub = bunbase.realtime.subscribe(
  'collection:posts',
  options: SubscribeOptions(
    events: [RealtimeEventType.create, RealtimeEventType.update],
    filter: {'status': 'published'},
    ids: ['rec_01J...', 'rec_02K...'], // multi-record subscription
  ),
  onEvent: (e) { ... },
);

SubscribeOptions fields

Field	Type	Description
events	List<RealtimeEventType>?	Limit to these event types
filter	Map<String, String>?	Server-side field filter
ids	List<String>?	Subscribe to specific record IDs

Channel patterns

Pattern	Scope
collection:<name>	All changes on a collection
collection:<name>:mine	Auth user’s own records
record:<name>:<id>	Single record
records:<name>	Multiple records (use ids option)

Eager connect

Open the WebSocket before the first subscription:

bunbase.realtime.connect();

Disconnect

bunbase.realtime.disconnect(); // cancels all reconnect timers

Ping / heartbeat

await bunbase.realtime.ping(); // throws TimeoutError after 5 s by default

Presence

Query which users are currently subscribed to a channel:

final users = await bunbase.realtime.presence('collection:posts');
// List<String> of user IDs

List active subscriptions

final channels = await bunbase.realtime.getSubscriptions();

Auth revocation

When the server sends a session-revocation event (password change, account deletion, etc.) the RealtimeClient automatically clears tokens and calls onAuthRevoked. BunBaseClient wires this to auth.currentUser automatically, so your ValueListenableBuilder will react and redirect to the login page.

Reconnect strategy

Attempt	Delay
1	500 ms
2	1 s
3	2 s
…	doubles each time
cap	30 s

Reconnect fires automatically when the socket closes unexpectedly. Active subscriptions are re-sent on each successful reconnect.