The design rule is: one cache entry per piece of server data, many widgets reading it, and invalidation that is as narrow as what the edit actually changed. Twelve widgets should never mean twelve requests: each widget subscribes to a shared query by key and derives its own view from the result. Volatile numbers are refreshed by one poll per key, not per widget. After a user edits an item, patch the entries that the server's response already describes, refetch the entries the server computes, and either mark stale or drop the entries nobody is looking at. A broad "invalidate everything" is the simplest correct answer, and it is the one that makes a quiet network noisy.
The demo runs 12 widgets (5 reading the item list, 4 reading stats, 3 reading item 2) under TanStack Query v5.59.0 against a fake server that counts requests per key, with intervals scaled down to milliseconds. Run in a node:22 container (Node 22.23.3, React 18.3.1, jsdom), it prints:
The bounds in case 5 are loose on purpose, because timer scheduling varies from run to run.
The calls in the demo do the following. setQueryData writes a value straight into the cache. invalidateQueries marks matching entries stale and refetches the ones a mounted widget is reading; matching is by prefix, so the key ['items'] also matches ['items', { status: 'open' }]. refetchType: 'none' marks entries stale without fetching now. A predicate is a function that picks which of the matching entries to act on. removeQueries deletes entries from the cache.
Two practical points follow. First, cancel or ignore any in-flight request (one that has been sent and not yet answered) for a key before writing a patch to it, because an older response that lands afterwards would overwrite the newer patch. Second, for an optimistic edit (patch the cache before the server answers, so the screen shows the change at once), keep the previous value so you can restore it if the request fails; this adds one step to targeted patching and nothing else changes.
js
import { JSDOM } from 'jsdom';
import assert from 'node:assert/strict';
const dom = new JSDOM('<!doctype html><body></body>', { url: 'http://localhost/' });
globalThis.window = dom.window;
globalThis.document = dom.window.document;
Object.defineProperty(globalThis, 'navigator', { value: dom.window.navigator });
globalThis.IS_REACT_ACT_ENVIRONMENT = true;
const React = (await import('react')).default;
const { useState, useEffect, useMemo, useCallback, useRef, memo, useReducer } = React;
const { render, screen, fireEvent, cleanup, act, waitFor } = await import('@testing-library/react');
const h = React.createElement;
globalThis.IS_REACT_ACT_ENVIRONMENT = false; // data arrives from timers outside act(), as in a browser
const { QueryClient, QueryClientProvider, useQuery } = await import('@tanstack/react-query');
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
// Fake server: three items; stats are computed on the server from the items.
const db = { items: [{ id: 1, name: 'Alpha', amount: 10 }, { id: 2, name: 'Beta', amount: 20 }, { id: 3, name: 'Gamma', amount: 30 }] };
const hits = {}; // requests per key name
const net = async (name, value) => { hits[name] = (hits[name] || 0) + 1; await sleep(10); return structuredClone(value()); };
const api = {
items: (f) => net(f ? 'items:' + JSON.stringify(f) : 'items', () => (f?.sort === 'name' ? [...db.items].sort((a, b) => a.name.localeCompare(b.name)) : db.items)),
item: (id) => net('item:' + id, () => db.items.find((i) => i.id === id)),
stats: () => net('stats', () => ({ total: db.items.reduce((s, i) => s + i.amount, 0) })),
edit: async (id, patch) => { Object.assign(db.items.find((i) => i.id === id), patch); await sleep(10); return structuredClone(db.items.find((i) => i.id === id)); },
};
const resetHits = () => { for (const k of Object.keys(hits)) delete hits[k]; };
// Shared hooks: widgets never call fetch themselves, they read the same keys.
const useItems = (select) => useQuery({ queryKey: ['items'], queryFn: () => api.items(), staleTime: 30_000, select });
const useItem = (id) => useQuery({ queryKey: ['item', id], queryFn: () => api.item(id), staleTime: 30_000 });
const useStats = (extra = {}) => useQuery({ queryKey: ['stats'], queryFn: () => api.stats(), staleTime: 30_000, ...extra });
// Twelve widgets: 5 derive from the items list, 4 read stats, 3 read item 2.
const widgets = [
...[0, 1, 2, 3, 4].map((i) => function W() { const q = useItems((d) => d.length + ':' + d.map((x) => x.name)[i % 3]); return h('li', { 'data-w': 'items' + i }, q.data ?? '..'); }),
...[0, 1, 2, 3].map((i) => function W() { const q = useStats(globalThis.pollMs ? { refetchInterval: globalThis.pollMs } : {}); return h('li', { 'data-w': 'stats' + i }, q.data ? 'total ' + q.data.total : '..'); }),
...[0, 1, 2].map((i) => function W() { const q = useItem(2); return h('li', { 'data-w': 'item' + i }, q.data ? q.data.name : '..'); }),
];
const Dashboard = () => h('ul', null, widgets.map((W, i) => h(W, { key: i })));
const shown = () => [...document.querySelectorAll('[data-w]')].map((e) => e.textContent);
// 1. Twelve widgets, three distinct keys: three requests.
globalThis.pollMs = 0;
let client = new QueryClient({ defaultOptions: { queries: { retry: false } } });
let view = render(h(QueryClientProvider, { client }, h(Dashboard)));
await waitFor(() => assert.ok(!shown().includes('..')));
console.log('1. 12 widgets mounted -> requests per key:', JSON.stringify(hits));
assert.deepEqual(hits, { items: 1, stats: 1, 'item:2': 1 });
const sumHits = Object.values(hits).reduce((a, b) => a + b, 0);
assert.equal(sumHits, 3);
// 2. After an edit to item 2: patch what the response already contains, refetch what the server computes.
const before = { ...hits };
async function editItem2(strategy) {
const saved = await api.edit(2, { name: 'Beta v2', amount: 25 });
if (strategy === 'targeted') {
client.setQueryData(['item', 2], saved); // patch: the response is the new truth
client.setQueryData(['items'], (old) => old.map((i) => (i.id === 2 ? saved : i))); // patch the same row inside the list
await client.invalidateQueries({ queryKey: ['stats'] }); // refetch: the server computes totals
await client.invalidateQueries({ // mark other cached lists stale, fetch nothing now
queryKey: ['items'], predicate: (q) => q.queryKey.length > 1, refetchType: 'none' });
} else {
await client.invalidateQueries(); // broad: everything cached is refetched if active
}
}
resetHits();
await editItem2('targeted');
await waitFor(() => assert.ok(shown().includes('total 65')));
console.log('2. targeted edit -> screen:', JSON.stringify([...new Set(shown())]), ' requests:', JSON.stringify(hits));
assert.deepEqual(hits, { stats: 1 });
assert.equal(shown().filter((s) => s === '3:Beta v2').length, 2); // both list-derived widgets that show item 2
assert.equal(shown().filter((s) => s === 'Beta v2').length, 3);
// 3. The same edit with one broad invalidation, for comparison.
view.unmount();
db.items[1] = { id: 2, name: 'Beta', amount: 20 };
client = new QueryClient({ defaultOptions: { queries: { retry: false } } });
view = render(h(QueryClientProvider, { client }, h(Dashboard)));
await waitFor(() => assert.ok(!shown().includes('..')));
resetHits();
await editItem2('broad');
await waitFor(() => assert.ok(shown().includes('total 65')));
console.log('3. broad invalidateQueries() -> requests:', JSON.stringify(hits));
assert.deepEqual(hits, { items: 1, stats: 1, 'item:2': 1 });
view.unmount();
// 4. Cached entries nobody is looking at: mark stale (refetch on next use) or drop.
db.items[1] = { id: 2, name: 'Beta', amount: 20 };
client = new QueryClient({ defaultOptions: { queries: { retry: false } } });
await client.fetchQuery({ queryKey: ['items', { status: 'open' }], queryFn: () => api.items({ status: 'open' }), staleTime: 30_000 });
await client.fetchQuery({ queryKey: ['items', { sort: 'name' }], queryFn: () => api.items({ sort: 'name' }), staleTime: 30_000 });
resetHits();
await api.edit(2, { name: 'Zeta' });
client.invalidateQueries({ queryKey: ['items', { status: 'open' }], refetchType: 'none' }); // stale, kept on screen if reopened
client.removeQueries({ queryKey: ['items', { sort: 'name' }] }); // the order is now wrong: drop it
console.log('4. after edit, requests for hidden lists:', JSON.stringify(hits));
assert.deepEqual(hits, {});
function Tab({ filter, label }) {
const q = useQuery({ queryKey: ['items', filter], queryFn: () => api.items(filter), staleTime: 30_000 });
return h('p', { id: label, 'data-fetching': String(q.isFetching) }, q.data ? q.data.map((i) => i.name).join(',') : 'loading');
}
const tabs = render(h(QueryClientProvider, { client }, h(Tab, { filter: { status: 'open' }, label: 'open' }), h(Tab, { filter: { sort: 'name' }, label: 'sorted' })));
const first = { open: document.getElementById('open').textContent, sorted: document.getElementById('sorted').textContent };
console.log(' reopened, first paint:', JSON.stringify(first));
assert.equal(first.open, 'Alpha,Beta,Gamma'); // stale copy shown at once, revalidating
assert.equal(first.sorted, 'loading'); // dropped: nothing to show
await waitFor(() => assert.equal(document.getElementById('open').textContent, 'Alpha,Zeta,Gamma'));
console.log(' after revalidation:', document.getElementById('open').textContent, '| requests:', JSON.stringify(hits));
// 4b. The mounted list is the case refetchType decides: 'none' keeps it from refetching right now.
resetHits();
await client.invalidateQueries({ queryKey: ['items', { status: 'open' }], refetchType: 'none' });
await sleep(50);
console.log(' mounted list, refetchType none -> requests:', JSON.stringify(hits));
assert.deepEqual(hits, {});
await client.invalidateQueries({ queryKey: ['items', { status: 'open' }] });
console.log(' mounted list, default refetchType -> requests:', JSON.stringify(hits));
assert.deepEqual(hits, { 'items:{"status":"open"}': 1 });
tabs.unmount();
// 5. Polling the shared stats key from four widgets: one timer's worth of requests, not four.
globalThis.pollMs = 60;
db.items[1] = { id: 2, name: 'Beta', amount: 20 };
client = new QueryClient({ defaultOptions: { queries: { retry: false } } });
resetHits();
view = render(h(QueryClientProvider, { client }, h(Dashboard)));
await waitFor(() => assert.ok(!shown().includes('..')));
await sleep(400);
const polls = hits.stats;
view.unmount();
console.log('5. stats polled every 60 ms by 4 widgets for ~400 ms: stats requests within [4, 9]:', polls >= 4 && polls <= 9);
assert.ok(polls >= 4 && polls <= 9, 'one poll per interval, not one per widget');
console.log('all assertions passed');
process.exit(0);