The Offline Mutation Queue

1. 1
   Change

   The user acts. Generate an idempotency key and capture the base version of the entity they were looking at.

   fails by Capturing neither, which makes every later step guesswork: retries duplicate and conflicts are undetectable.

2. 2
   Persist

   Write the intent to IndexedDB in a transaction. Only then update local state and tell the user it is saved on this device.

   fails by Keeping it in memory, or telling the user first — a tab close between the two loses work the UI already confirmed.

3. 3
   Reconnect

   Detect that your origin is actually reachable — a successful request, not an online event — and elect a single flusher across tabs.

   fails by Flushing on the event, so the first attempts fail; or flushing from every tab, so everything is sent several times.

4. 4
   Sync

   Send entries in per-entity order with the key and the base version. Record each outcome independently and delete each entry in the transaction that records its success.

   fails by Treating the batch as one unit, so a failure at item six loses or repeats the first five (Partial Failure: When 3 of 5 Succeed in API Design).

5. 5
   Resolve

   For a rejected write, apply the policy this field has: overwrite, merge, or ask. Show the user what happened either way.

   fails by Having no policy, which means last-write-wins by accident, applied to every field including the ones where it destroys work.

Nothing here is browser-specific. It is the client-side shape of a problem that Distributed Systems states in general terms and that the user experiences as "did my edit survive?".

1type Pending = {
2  id: string          // idempotency key, generated when the user acted
3  entity: string      // ordering domain: 'task:812'. NOT a global sequence.
4  seq: number         // order within that entity
5  op: 'update' | 'create' | 'delete'
6  payload: unknown
7  baseVersion: string | null   // the ETag/revision the user was looking at
8  createdAt: number
9  attempts: number
10  state: 'pending' | 'failed' | 'conflict'
11}
12 
13// 1. Persist BEFORE showing success. This ordering is the lesson.
14async function enqueue(entry: Pending) {
15  await db.put('queue', entry)     // durable
16  applyLocally(entry)              // then optimistic UI
17  void flush()                     // then, maybe, the network
18}
19 
20async function flushEntity(entity: string) {
21  const entries = (await db.byEntity('queue', entity)).sort((a, b) => a.seq - b.seq)
22 
23  for (const entry of entries) {
24    const res = await send(entry)  // sets Idempotency-Key and If-Match
25 
26    if (res.ok) {
27      await db.delete('queue', entry.id)      // outcome + removal, one txn
28      continue
29    }
30    if (res.status === 409 || res.status === 412) {
31      await db.put('queue', { ...entry, state: 'conflict' })
32      return                       // stop THIS entity; others keep going
33    }
34    if (res.retryable && entry.attempts < MAX_ATTEMPTS) {
35      await db.put('queue', { ...entry, attempts: entry.attempts + 1 })
36      return                       // backoff with jitter, retry later
37    }
38    await db.put('queue', { ...entry, state: 'failed' })  // needs a human
39    return
40  }
41}

Two things are load-bearing and easy to miss. return rather than continue on failure preserves order within the entity. And the flush is per entity, so a poison entry on task:812 never blocks task:900.