offline-sync-engine

A door scanner that keeps working when the venue's WiFi dies. Pull the plug. Scan a few people. Plug it back in. Every admit lands in the server exactly once.

npm version downloads per month GitHub stars

Try this →
  1. Admit a few guests. Flip WiFi OFFLINE. Admit more.
  2. Watch them stack in the Pending Queue column.
  3. Flip WiFi back ONLINE. Queue drains into the server ledger.
  4. Now flip Use offline-sync-engine off and try the same flow.
  5. Watch duplicates pile up — the ack-lost race a real flaky network produces.

Door Scanner

library mode

Tap a guest to admit them.

Pending Queue

0

In IndexedDB — survives reload.

No items waiting.
Items waiting on the network show up here with their idempotency key.

Server Ledger

0 admits

Server is empty.
Admits committed by the server land here, newest first.

What's happening under the hood?

Library OFF — naive baseline

  • Admits go to an in-memory array. Refresh the tab while offline and they're gone.
  • No idempotency key on the server. When a response gets lost in transit, the retry inserts the same admit a second time.
  • You'll see the duplicate counter climb every few drains.

Library ON

  • Each mutation gets a ULID at creation, persisted to IndexedDB. Survives reload, crash, tab close.
  • Server's IdempotencyStore reserves the key, runs the handler at most once, and caches the result for any retry with the same key.
  • Lost response? Retry returns the cached commit. Duplicates impossible.

Everything in this demo — scanner, queue, server, network — runs in your browser. The WiFi button gates outgoing requests. The simulated server also drops ~25% of responses in transit when online (an "ack-lost" event) — that's the realistic flaky-network failure that idempotency keys exist to solve. Source code at github.com/grahamzemel/offline-sync-engine.