mutation_queue 0.1.0
mutation_queue: ^0.1.0 copied to clipboard
Offline-first mutation queue for Dart and Flutter: enqueue writes that persist before returning, drain FIFO with retry limits and dead-lettering.
mutation_queue #
Offline-first mutation queue for Dart & Flutter.
Field crews work in basements, on ships, on remote sites — the network is gone
for hours and comes back for thirty seconds. Every write flows through this
queue: persisted before enqueue returns, drained FIFO when connectivity
returns, retried with a per-item attempt limit, and dead-lettered when it
exhausts its budget.
Why #
Making an app work offline is mostly making writes work offline. The
scattered ad-hoc versions of this logic (a list, some isOnline checks, a
retry loop that maybe survives a restart) miss the hard parts:
| Guarantee | How |
|---|---|
| Nothing is lost | enqueue persists to your storage before returning — a crash can never lose a write |
| FIFO drain | flush sends in order; a restored queue from yesterday drains before today's |
| Retry with a limit | Failures requeue for the next flush; after maxAttempts the item is parked |
| Never silently dropped | Dead-lettered items stay visible via deadLetter() until you revive() or discard() them |
| One drain | Concurrent flush() calls share a single in-flight drain — nothing double-sends |
| Yours at the edges | Storage and delivery are injected functions — shared_preferences, a file, SQLite, whatever |
Extracted from the author's offline-first React Native field app (crewops-rn); this is the same engine, distilled to pure Dart.
Usage #
final queue = MutationQueue(
store: (json) => prefs.setString('queue', jsonEncode(json)),
load: () => jsonDecode(prefs.getString('queue') ?? '[]') as List,
send: (mutation) => dio.post('/sync', data: mutation.toJson()),
maxAttempts: 3,
);
await queue.restore();
// UI: enqueue everywhere, never await the network
checkInButton.onPressed = () => queue.enqueue('checkin', {'site': 'A'});
// Connectivity returns → drain
connectivity.onStatusChanged.listen((status) {
if (status == ConnectivityResult.online) queue.flush();
});
// Badge: "3 pending · 1 sending · 0 failed"
queue.addListener(() => setState(() => stats = queue.snapshot()));
Testing #
10 deterministic tests: persist-before-return, FIFO order, retry-after-outage,
dead-letter after max attempts, revive/discard semantics, single shared
drain under concurrent flushes, startup restore, listener events, and JSON
round-trip through storage.
dart test