Rollback and Reconciliation

try {
  await save(next)
  // success: the optimistic value stays.
  //   server trimmed the name        -> cache is wrong
  //   server assigned a real id      -> cache holds "tmp-8f21"
  //   server stamped updatedAt       -> cache holds our guess
  //   server appended "(2)"          -> user never finds out
} catch {
  cache.write(key, snapshot)
  // failure: revert everything.
  //   a revalidation landed since    -> reverted too
  //   the user edited another field  -> reverted too
  //   the request actually succeeded -> now client and server disagree
  toast('Something went wrong')
}

const outcome = await attempt(save, next)

switch (outcome.kind) {
  case 'accepted':
    cache.write(key, outcome.server)          // authoritative for every field
    if (differsVisibly(next, outcome.server))
      announce(explain(next, outcome.server)) // "Saved as Reports (2)"
    break

  case 'conflict':
    cache.write(key, outcome.current)         // the server's current value
    openConflict({ mine: next, theirs: outcome.current })
    break                                     // the user chooses; we do not

  case 'rejected':
    cache.restoreFields(key, snapshot, changedFields)  // only what we changed
    showInlineError(outcome.reason)           // next to the control, keeps input
    break

  case 'unknown':
    await cache.refetch(key)                  // we do not know. Go and look.
    break
}

The four branches are not defensive padding; they are four genuinely different states of the world, and each one has a different correct value to display. Collapsing them into two forces the client to guess in the two cases where it has been given information — the differed case, where the server told you the answer, and the conflict case, where the server told you someone else got there first.

1type Outcome<T> =
2  | { kind: 'accepted'; server: T }
3  | { kind: 'conflict'; current: T; changedBy?: string }
4  | { kind: 'rejected'; reason: 'validation' | 'authorization'; detail: string }
5  | { kind: 'unknown' }                 // transport failed; it may have applied
6 
7async function attempt<T>(send: () => Promise<Response>, body: T): Promise<Outcome<T>> {
8  let res: Response
9  try {
10    res = await send()
11  } catch {
12    return { kind: 'unknown' }          // network error, abort, tab suspended
13  }
14 
15  if (res.ok) return { kind: 'accepted', server: (await res.json()) as T }
16 
17  switch (res.status) {
18    case 409: {
19      const { current, changedBy } = await res.json()
20      return { kind: 'conflict', current, changedBy }
21    }
22    case 422:
23    case 400:
24      return { kind: 'rejected', reason: 'validation', detail: await res.text() }
25    case 401:
26    case 403:
27      return { kind: 'rejected', reason: 'authorization', detail: await res.text() }
28    default:
29      return { kind: 'unknown' }        // a 5xx may or may not have applied
30  }
31}

Modelling this as a discriminated union rather than a try/catch is what makes the fourth case unforgettable: an exhaustive switch will not compile until unknown is handled, and unknown is the branch every hand-written implementation omits (TypeScript in the Build).