Local Storage and Offline

Local storage on a device does two separate jobs, and keeping them apart makes the rest of this lesson tractable. The first is a cache: a copy of server data so a screen has something to show immediately, including when there is no connection. The second is a queue: a record of changes the user has made that have not reached the server yet.

The cache can be thrown away without consequence. The queue cannot — it holds work the user believes is done. Treating both as "the local database" is how apps end up clearing a cache and silently deleting someone's visit notes with it.

One warning before the mechanics: synchronising data between a device and a server is genuinely hard. Not fiddly, hard. It is one of the few areas in application development where a reasonable-looking design can lose user data without producing an error anywhere. What follows is honest about where the difficulty sits.

{
  "id": "chg_0f3a91",
  "createdAt": "2025-03-04T08:12:09Z",
  "intent": "updateEmployeeSite",
  "method": "PATCH",
  "resource": "/api/employees/482",
  "idempotencyKey": "chg_0f3a91",
  "baseVersion": 41,
  "body": {
    "siteCode": "NTH-12"
  },
  "attempts": 2,
  "lastAttemptAt": "2025-03-04T09:40:11Z",
  "status": "pending"
}

• This is a record of intent, not a saved HTTP request. It says what the user meant to change, which is what you need in order to retry it, explain it, or reconcile it days later.
• The idempotency key is stored with the change rather than generated at send time. That is the whole reason a queued change can be retried safely: attempt five carries the same key as attempt one, so the server can recognise it as the same change.
• baseVersion is the version of the record the user was looking at when they made the edit. Send it with the change and the server can tell whether anybody else has touched the record since. Without it, you are asking the server to overwrite blindly, and it has no way to warn you.
• attempts and lastAttemptAt drive backoff and, more importantly, let you tell the user something true. A change that has failed twenty times over two days is not "syncing", and pretending otherwise is how a queue silently becomes a graveyard.
• status is explicit: pending, sending, conflicted, failed. A queue with no failure states either loses entries or retries them forever, and both look like the app working until someone checks.

interface PendingChange {
  id: string;
  resource: string;
  baseVersion: number;
  body: Record<string, unknown>;
}

type SendResult =
  | { outcome: "applied"; version: number }
  | { outcome: "conflict"; serverVersion: number; server: Record<string, unknown> }
  | { outcome: "rejected"; reason: string }
  | { outcome: "retryLater" };

interface DrainReport {
  applied: string[];
  conflicts: { change: PendingChange; server: Record<string, unknown> }[];
  rejected: { change: PendingChange; reason: string }[];
  stopped: boolean;
}

export async function drainQueue(
  queue: PendingChange[],
  send: (change: PendingChange) => Promise<SendResult>,
): Promise<DrainReport> {
  const report: DrainReport = {
    applied: [],
    conflicts: [],
    rejected: [],
    stopped: false,
  };

  for (const change of queue) {
    const result = await send(change);

    if (result.outcome === "applied") {
      report.applied.push(change.id);
    } else if (result.outcome === "conflict") {
      // Keep it. Do not overwrite, do not discard, do not guess.
      report.conflicts.push({ change, server: result.server });
    } else if (result.outcome === "rejected") {
      report.rejected.push({ change, reason: result.reason });
    } else {
      report.stopped = true; // Still offline. Preserve order, try again later.
      break;
    }
  }

  return report;
}

• The shape is the lesson. Whatever storage and HTTP client you use, a queue drain looks like this: in order, one at a time, with an explicit outcome per entry and a report at the end.
• In order and one at a time matters. Two changes to the same record sent in parallel apply in whichever order the server happens to process them, so an edit the user made second can land first. Sequential sending keeps the user's own intent in sequence, and the cost is throughput nobody on a device is measuring.
• Stopping on retryLater rather than skipping ahead preserves that order. Skipping a blocked change to send a later one is how a queue reorders a user's edits, and the effect is a record that ends up in a state the user never asked for.
• A conflict is neither success nor failure, so it gets its own outcome and the change stays in the queue. The one thing this function refuses to do is decide what the merged record should be. That decision needs either a rule specific to the field, or the user.
• rejected is separate from both. A 422 means the change will never apply, so it has to leave the queue and be shown to the user rather than retried forever. A queue that cannot express "this will never work" grows until it is useless.
• The report is what the UI reads. It is how a sync indicator can say "12 sent, 1 needs your attention" instead of a spinner that means nothing.