Skip to main content

mutation_queue 0.1.0 copy "mutation_queue: ^0.1.0" to clipboard
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.

CI License: MIT

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

License #

MIT

0
likes
160
points
64
downloads

Documentation

API reference

Publisher

unverified uploader

Weekly Downloads

Offline-first mutation queue for Dart and Flutter: enqueue writes that persist before returning, drain FIFO with retry limits and dead-lettering.

Repository (GitHub)
View/report issues

Topics

#offline-first #queue #sync #flutter #dart

License

MIT (license)

More

Packages that depend on mutation_queue