From a hook-based server-state library

1// The pattern this page is about — not any single library, but the
2// shape nearly every "server state" hook library converges on:
3// declare a query key, get caching, deduping, and refetch-on-focus
4// for free, declare a mutation, get optimistic updates and
5// invalidation for free.
6 
7function ServicesList() {
8  const { data, isLoading } = useQuery({
9    queryKey: ['services'],
10    queryFn: () => fetch('/api/services').then(r => r.json()),
11    staleTime: 5 * 60 * 1000,
12  })
13 
14  const mutation = useMutation({
15    mutationFn: (update) => fetch('/api/services/' + update.id, {
16      method: 'PATCH',
17      body: JSON.stringify(update),
18    }),
19    onMutate: async (update) => {
20      await queryClient.cancelQueries(['services'])
21      const prev = queryClient.getQueryData(['services'])
22      queryClient.setQueryData(['services'], (old) =>
23        old.map(s => s.id === update.id ? { ...s, ...update } : s)
24      )
25      return { prev }
26    },
27    onError: (err, update, context) => {
28      queryClient.setQueryData(['services'], context.prev)
29    },
30    onSettled: () => queryClient.invalidateQueries(['services']),
31  })
32 
33  if (isLoading) return <Spinner />
34  return <List data={data} onEdit={mutation.mutate} />
35}
36 
37// This works, and for a huge range of apps it is genuinely the right
38// tool. The gap this page is about is specifically what happens at
39// the edges of this model: reload, offline, and multi-tab.

1// Where the two models overlap almost one-to-one — this is NOT a
2// "replace everything" migration, it is a "here's what changes and
3// why" migration. Query keys and Flux channels are doing structurally
4// the same job.
5 
6// BEFORE
7useQuery({ queryKey: ['services'], queryFn: fetchServices })
8 
9// AFTER
10flux.register({
11  store: servicesStore,
12  channel: 'services',
13  idbKey: 'services:list',
14  ttl: 'medium',
15})
16// data now lives in servicesStore (Zustand/Redux/Jotai/Stunk),
17// read via your state manager's own hook, not a Flux-specific
18// one. There is no useFluxQuery(channel) — the store IS the cache,
19// and your components already know how to read it.

1// The first real gap: staleTime controls how long data is
2// considered fresh WITHIN a session, but a hard reload throws
3// everything away — every hook-based server-state library's
4// in-memory cache dies with the tab. staleTime: 5 minutes still
5// means a full network refetch on every reload, every time, for
6// every user, forever.
7 
8// BEFORE — fast the 2nd, 3rd, 4th time you view a page in the SAME
9// session, slow again on every literal page reload:
10useQuery({
11  queryKey: ['services'],
12  queryFn: fetchServices,
13  staleTime: 5 * 60 * 1000, // only helps until the tab reloads
14})
15 
16// AFTER — ttl plays the same role staleTime does (how long before
17// data is considered stale enough to refetch), but the cache itself
18// is IndexedDB, not a JS object living in the tab's memory. A reload
19// hydrates instantly from disk instead of re-fetching, and only
20// refetches over the network once ttl has genuinely elapsed:
21flux.register({
22  store: servicesStore,
23  channel: 'services',
24  idbKey: 'services:list',
25  ttl: 'medium', // short/medium/long map to configured ms
26})

1// refetchOnWindowFocus is the second gap — it exists in hook-based
2// libraries precisely because there is no other freshness signal
3// available. It works, but it means every tab switch is a network
4// round trip, even when nothing changed.
5 
6// BEFORE
7useQuery({
8  queryKey: ['services'],
9  queryFn: fetchServices,
10  refetchOnWindowFocus: true, // network call on every single focus
11})
12 
13// AFTER — focus/visibility still triggers a staleness CHECK
14// (Flux's revalidation loop), but if a realtime adapter is
15// registered, the loop holds instead of firing an HTTP refetch
16// immediately, giving the live channel a chance to prove the data is
17// already current. Most focus events resolve with ZERO network
18// calls once realtime is wired — only genuinely stale, unconfirmed
19// channels fall through to a refetch:
20import { createSupabaseAdapter } from '@tsworldtech/flux_supabase'
21 
22const flux = createFlux({
23  adapter: createSupabaseAdapter(supabaseClient),
24})
25 
26flux.register({
27  store: servicesStore,
28  channel: 'services',
29  event: 'UPDATE',
30  idbKey: 'services:list',
31  ttl: 'medium',
32})
33// no refetchOnWindowFocus flag anywhere — this behavior is
34// structural, not opted into per-query

1// The gap that matters most in practice: what happens to a mutation
2// fired while offline. Hook-based server-state libraries generally
3// have no answer to this beyond onError — the mutation fails, the
4// optimistic update rolls back, and the user's edit is gone unless
5// you build your own persistence layer on top.
6 
7// BEFORE — offline mutation just... fails:
8const mutation = useMutation({
9  mutationFn: (update) => fetch('/api/services/' + update.id, {
10    method: 'PATCH',
11    body: JSON.stringify(update),
12  }),
13  onError: (err, update, context) => {
14    // rollback happens, but the user's edit is now just gone —
15    // there is no queue, nothing retries this automatically
16    queryClient.setQueryData(['services'], context.prev)
17  },
18})
19 
20// ────────────────────────────────────────────────────────────────
21 
22// AFTER — the mutation is queued to IndexedDB BEFORE any network
23// attempt, survives a full page reload while offline, and replays
24// automatically the moment the connection returns — no onError branch
25// needed for the offline case at all:
26flux.register({
27  store: servicesStore,
28  channel: 'services',
29  idbKey: 'services:list',
30  ttl: 'medium',
31  optimistic: { rollbackOnError: true },
32  queueConfig: {
33    storeName: 'services_updates',
34    replayEndpoint: '/api/services/batch_update',
35    replayStrategy: 'handshake', // detects server-side conflicts
36    conflictStrategy: 'reject',  // before overwriting on reconnect
37  },
38})
39 
40// the mutation call itself
41flux.replay('services') // or let the automatic triggers handle it
42// (initial load, online event, focus, visibilitychange)

1// The gap that is easy to miss until a user files a confusing bug
2// report: hook-based server-state libraries have no cross-tab
3// awareness by default. Two tabs open on the same page both hold
4// independent in-memory caches, both fetch independently, and an
5// optimistic update in one tab has no way to reach the other.
6 
7// BEFORE — open the same page in two tabs, get two independent
8// fetches, two independent caches, no communication between them
9// unless you wire up a BroadcastChannel yourself:
10useQuery({ queryKey: ['services'], queryFn: fetchServices })
11// tab 2, same query key, completely separate cache instance,
12// completely separate network request
13 
14// AFTER — one leader tab performs the fetch, every other tab
15// hydrates from IDB on the SAME page load with zero network calls,
16// and a write in any tab mirrors to every other tab via
17// BroadcastChannel with no extra code:
18flux.bootstrap({
19  endpoint: '/api/bootstrap/public',
20  map: { services: servicesStore },
21})
22// this one call is safe to fire from every tab — only the elected
23// leader actually hits the network, followers hydrate from disk

1// invalidateQueries has a direct equivalent, worth mapping
2// explicitly since the naming differs slightly and the underlying
3// mechanism (force a refetch, bypass freshness checks) is the same
4// idea either way.
5 
6// BEFORE
7queryClient.invalidateQueries(['services'])
8 
9// AFTER
10await flux.invalidate('services')
11// clears this channel's IDB entry and marks it for refetch on next
12// access — same intent, same "I know something changed, don't trust
13// the cache" escape hatch

1// What doesn't change, and doesn't need to: request-level concerns
2// that were never Flux's job or the hook library's job either.
3 
4// - Request deduplication for concurrent identical calls WITHIN a
5//   single render pass — this is a React rendering concern, handled
6//   the same way regardless of which caching layer sits underneath.
7 
8// - Pagination cursor management, infinite-scroll accumulation logic
9//   — Flux's PAGINATED ingestion type is deferred; for now, this
10//   stays exactly as it was.
11 
12// - Non-cacheable, single-use requests — a one-time file upload
13//   response, a signed URL that is read once and discarded. Nothing
14//   about a caching layer helps something that is read exactly once,
15//   regardless of which library is doing the caching.
16 
17// - Client-side request/response transformation, retries for reasons
18//   OTHER than "was offline" (e.g. exponential backoff on a flaky
19//   third-party API) — these are orthogonal concerns worth keeping
20//   wherever they currently live.

1// Signals this migration is not worth it for a given screen, at
2// least not yet:
3 
4// - The data is genuinely ephemeral and per-request — a live search-
5//   as-you-type autocomplete result. staleTime: 0 and no caching at
6//   all is often already the correct choice here; an IDB round trip
7//   adds latency a hook library's in-memory Map does not have.
8 
9// - The screen has no offline story worth building regardless of
10//   caching layer — an admin tool nobody uses on a train.
11 
12// - You are deep in a codebase with hundreds of existing useQuery
13//   call sites and no near-term reload/offline/multi-tab pain. This
14//   is a real migration with real surface area — see the "when to
15//   migrate incrementally" note below before doing it all at once.

1// Both models can coexist in the same app during migration — Flux
2// does not require an all-or-nothing swap. A common path: migrate the
3// screens that actually suffer from the reload/offline/multi-tab
4// gaps first (dashboards, anything with a mutation a user would be
5// upset to lose), leave low-stakes or genuinely ephemeral queries on
6// the hook library, and let the two approaches sit side by side for
7// as long as makes sense.
8 
9// Nothing about Flux's registration model requires the whole app to
10// go through flux.bootstrap() — a store can be registered and
11// populated by its own bootstrap call independent of every other
12// registered store (per-scope bootstrap calls apply the same principle
13// to migration order, not just to global vs. user data).