Offline Queue — Flutter SDK

Overview

The offline queue captures write operations (create, update, delete) that fail due to no connectivity and replays them automatically when the device comes back online.

It uses connectivity_plus to detect connectivity changes and shared_preferences to persist the queue across app restarts.

Setup

Call startMonitoring() once at app startup:

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await bunbase.auth.restoreSession();
  await bunbase.offlineQueue.startMonitoring(); // restore + watch connectivity
  runApp(MyApp());
}

Enqueue a mutation

Instead of calling collection.create() directly, enqueue it:

bunbase.offlineQueue.enqueue(
  'POST',
  '/api/v1/posts',
  body: {'title': 'Written offline', 'body': 'Will sync later'},
);

Manual flush

Trigger a flush attempt at any time (e.g., after the user taps “Sync now”):

await bunbase.offlineQueue.flush();

Flush result callback

React to each replayed item:

bunbase.offlineQueue.onFlushResult = (id, error) {
  if (error == null) {
    print('[$id] synced successfully');
  } else {
    print('[$id] failed: $error');
  }
};

Retry behavior

Response	Behavior
2xx	Remove from queue (success)
4xx	Remove from queue (permanent failure) — onFlushResult called with error
5xx	Stop flush, keep item — retry on next connectivity event
Network error	Stop flush, keep item — retry on next connectivity event

Inspect the queue

print('Pending: ${bunbase.offlineQueue.pendingCount}');
for (final item in bunbase.offlineQueue.items) {
  print('${item.method} ${item.path} (enqueued: ${item.enqueuedAt})');
}

Clear the queue

Discard all pending items without executing them:

bunbase.offlineQueue.clear();

Stop monitoring

Cancel the connectivity subscription (e.g., during testing or logout):

bunbase.offlineQueue.stopMonitoring();

QueuedMutation fields

Field	Type	Description
id	String	Unique item ID
method	String	HTTP method (POST, PATCH, DELETE)
path	String	API path, e.g. /api/v1/posts
body	Object?	JSON-serializable payload
enqueuedAt	DateTime	When the item was enqueued

Persistence

The queue is persisted in shared_preferences under the key bunbase_offline_queue. It survives app restarts and is restored automatically by startMonitoring().