6 min read

Realtime Events Should Invalidate the Cache, Not Carry State

Let socket events say what changed and let the server say what it is now: one projection, no client drift, and a polling fallback that is the same code path.
a tower with a sunset in the background
Photo by Ken on Unsplash

I recently built a live dashboard: a handful of screens that show a queue, how long people have been waiting, and which numbers need attention. Several people look at it at once, and when one of them changes something, everyone else's screen should catch up within a second or two. The server pushes events over a websocket. The question was what those events should do when they arrive.

The answer I landed on is almost boring: an event tells the client what changed, the client throws away its cached copy of the affected view, and refetches it from the server. The event carries no state the UI is allowed to apply. This post is about why that beats the more obvious design, and the two places where I bent the rule.

The tempting design: events as reducer actions

The event spec I started from looked like instructions for a reducer. "Item created" came with the item's id, its group and its position. "Status changed" came with the old status, the new status, and a timestamp. The natural implementation is to keep a client-side store, apply each payload as it arrives, and never refetch. It feels efficient. No extra round trip, instant updates, and the socket does all the work.

The trouble is that the dashboard is not a list of rows. The server returns a computed view: an average wait measured over everything handled so far today, a comparison against the same time yesterday, a projected wait for the next person, and a rule that decides when a group gets highlighted as needing attention. Those are aggregates and judgement calls, and they live in one tested function on the server.

Apply "item created" locally and you now have to recompute all of that in the browser, from a payload that doesn't contain the inputs. You cannot update an average over the whole day from one new item. So you end up with one of two outcomes:

  • a client that approximates the server and slowly drifts from it, or
  • a second implementation of the projection that has to be kept in step with the first, forever.

Neither is acceptable for a screen people make decisions from.

The idea: the socket is a doorbell, not a delivery

Instead, the event is a hint. It says "the dashboard view is out of date" or "this group's list changed", and the client invalidates the matching query in its cache. The query library notices the view is stale and refetches it. Server-computed state stays server-computed.

With TanStack Query and a socket.io client, the core of it is small:

const COALESCE_MS = 250;

function coalesce(fn, ms) {
  let timer = null;
  return () => {
    clearTimeout(timer);
    timer = setTimeout(fn, ms);
  };
}

const refreshDashboard = coalesce(
  () => queryClient.invalidateQueries({ queryKey: ['dashboard'] }),
  COALESCE_MS,
);

socket.on('item.created', refreshDashboard);
socket.on('item.status', refreshDashboard);

The handlers ignore their payloads entirely. That is the point.

Why the debounce

One human action often emits several events. Pressing a single "next" button in my case produced a status change for the item and a status change for the person handling it, back to back. Invalidating per event meant two or three fetches of the same view for one tap. On a weak network that is worse than the fraction of a second of staleness it removes. A 250ms debounce per view coalesces the burst into one refetch, and also puts a hard ceiling on load: at most one fetch per view, per client, every quarter second, however busy things get. If that ceiling ever becomes a problem, the fix is a longer debounce, not moving the projection into the browser.

The payoff I didn't expect: the fallback is the same code

The requirement was that the dashboard stays fully usable when the socket can't connect. Hostile proxies and flaky wifi are normal, not edge cases. With reducer-style events, the polling fallback is a second path: some code that fetches the whole view and reconciles it against a store that normally gets patched incrementally. It's the path nobody runs day to day, so it's the one that breaks.

With invalidation, polling is just refetchInterval on the same query. A socket event and a poll tick end in the identical fetch and the identical render. There is no second path to remember to test, because there is no second path.

A few details made this hold up in practice:

  • Polling never fully stops. Even with the socket connected, the view polls slowly, about once a minute. A socket that's "connected" through a proxy holding a dead connection open looks exactly like a quiet afternoon. The slow poll is what tells "nothing is happening" apart from "nothing is arriving".
  • When the socket gives up, polling speeds up. I cap reconnection at a few attempts with fixed delays rather than letting the client back off forever, then switch the UI to an honest "live updates unavailable" state and raise the poll rate. The numbers get more current exactly when someone has stopped trusting them.
  • A reconnect refetches. Every event during the gap went nowhere, so the cache is stale by however long the outage lasted. On reconnect I invalidate everything the socket normally covers, through the same debounce, so any backlog of events that arrives at once still produces one fetch. I skip this on the very first connect, because the screen has just fetched.
  • A server-initiated disconnect needs a manual reconnect. socket.io deliberately doesn't retry when the server closes the connection. If your server kicks clients so they re-handshake with new permissions, the client has to call connect() itself, or it sits on polling and nobody notices, because polling keeps the screen correct.

The cost

Every change costs one extra round trip for everyone who didn't make it. That's real, and I accepted it on purpose. The person who acts sees their own change instantly through an optimistic update; the server's response confirms it. Everyone else needs the change to be correct more than they need it in 30 milliseconds. It also helps that the view is cheap to compute. If it took seconds, I'd be having a different conversation.

The two exceptions

A rule with no exceptions usually means nobody looked hard. I wrote down two.

1. An event whose payload is the whole answer. A reorder event carried the complete resulting order of a list: ids in sequence, nothing derived. That isn't a projection, so applying it directly can't drift. It also mattered for timing: the drag-and-drop list was open precisely when a refetch would fight the user's hand. So that screen used the order directly. Honestly, this one didn't last. Once the same event also covered changes the order alone couldn't describe (a flag that changes how a row looks, not just where it sits), applying the ids was wrong again, and I went back to invalidating. The person dragging was already covered by their own optimistic update. The lesson I took: if you apply a payload, be sure it really is the complete state of that thing, and recheck that every time the event grows.

2. Invalidate less than you could. Some changes are meant to be invisible to some people. One event changed how work would be shared out in future, and the requirement was that the person affected sees no repaint and no notification. Their next action simply follows the new rule. Refreshing their view would redraw a screen while they're in the middle of using it. So that event invalidates the overview only, and there's an end-to-end test that asserts the other screen doesn't move. Invalidation is a routing decision too: which views refresh is as deliberate as what's in them.

Takeaway

If the screen shows anything the server computes (averages, comparisons, rules), let realtime events say what changed and let the server say what it is now. You get one source of truth, a socket that's a small, uniform surface, and an offline fallback that is just the normal code path running on a timer.