A user adds a book and the list on the next screen does not show it. The client cached
GET /books a moment ago and serves that copy. Your write path deletes the cache entry for
/books, so the unfiltered list is right, but the author filter and page two are separate entries
and still hold the old rows.
What you get
You will end up with a client-side list cache that a create, update, or delete clears for every filter and page of that collection, under three generated clients. A test reads, writes, and reads again for each view. This is for you if your users see their own writes go missing.
Short answer
After a successful write, drop every cached GET on the written collection, whatever its query
string, rather than the one unfiltered key. Put that rule in a fetch you hand the client: sdkgen’s
system.fetch, the fetch option of openapi-fetch, or NSwag’s http argument. The sdkgen cache
feature offers only its TTL, so a cached list stays wrong until it expires. An ETag on the list is always correct
and costs a 304 round trip per read.
You will need
Node 22 or later, a client that accepts a fetch function, and an API whose list endpoint takes
filter or page parameters. Verified 2026-11-20 against Node 22.23.5. The sample runs offline
against origin.mjs, a stand-in for a Bookshelf API whose GET /v1/books filters by author,
pages by two with page, sends an ETag on every list, and answers If-None-Match with 304.
Approaches compared
| Approach | When it fits | What it costs you | When to pick something else |
|---|---|---|---|
ETag on the list | The API sends a validator on lists and answers If-None-Match | A round trip on every read, even when the list has not changed | Reads dominate and the network is slow |
| Key-prefix delete in your cache | You own the cache and every write goes through it | Every write path must know which collections it changes, or a list stays stale | A write can happen where your cache cannot see it |
| NSwag http option | An NSwag TypeScript client, which takes any object with fetch | Undocumented statuses other than 204 throw, so a stray 304 becomes an exception | You need per-response hooks, which its UseTransformResultMethod setting adds |
openapi-typescript and openapi-fetch | A typed client whose createClient takes a custom fetch | Types only, so the cache, the rule, and the runtime package are yours | You want generated methods rather than typed paths |
| sdkgen cache feature | Staleness for a bounded time is acceptable | No invalidation call, so a write leaves each cached list wrong until its TTL ends | Users must see their own writes at once |
TanStack Query invalidateQueries | A front end already keeps its lists in TanStack Query | An extra library on the client, and query keys you must shape for prefix matching | The cache lives on a server, outside any UI |
Voxgig maintains sdkgen. It is one of six options here, not the recommendation.
Explicit invalidation is exact but couples every write path to every list it touches. A TTL needs
no code and stays stale after each write. ETag validators are correct by construction, because the origin
decides, and each read still pays a round trip.1
Drop the collection, not the key
list-cache.mjs is a fetch-shaped GET cache. On a successful write it removes every cached GET on
the written collection, with any query string. A write to /v1/books/b1 drops /v1/books/b1 and
the /v1/books lists that may hold it.
function drop(written, method) {
if (invalidate === 'none') return 0
// A POST adds to the collection it names. A write to an item changes the
// item and every list that holds it, so its parent collection goes too.
const collection = method === 'POST' ? written.pathname : written.pathname.replace(/\/[^/]+$/, '')
const changed = invalidate === 'exact'
? (url) => url.href === written.href
: (url) => url.origin === written.origin && (url.pathname === collection || url.pathname.startsWith(`${collection}/`))
for (const read of reading) if (changed(read.url)) read.overtaken = true
let n = 0
for (const [key, { url }] of store) {
if (changed(url)) {
store.delete(key)
n++
}
}
return n
}
The same rule marks every read of that collection still in flight. The origin may have answered
such a read before the write, so its caller gets the answer and the cache does not keep it. A
failed write drops nothing. On Redis the same rule is a
SCAN with MATCH over your key prefix, then
UNLINK on what it returns.
Compare four strategies in an sdkgen SDK
The sdkgen SDK was generated from api.json with the cache feature added. It takes a fetch as
system.fetch, so all four strategies run under one client. demo.mjs reads three views twice,
creates a book by Austen, and reads them again.
node demo.mjs
sdkgen: read three views twice, create a book, read them again
strategy all author=Austen page=2 origin GETs
cache feature, ttl 30 s STALE STALE STALE 3
exact-key delete fresh STALE STALE 4
path-prefix delete fresh fresh fresh 6
ETag revalidation fresh fresh fresh 9 (3 answered 304)
The exact-key row is the usual bug: the unfiltered list refreshed, and the filtered list and page
two did not. The prefix delete refreshes all three for three extra GETs. The ETag row needs no
invalidation code and pays a 304 for each of the three repeat reads.2
Measure how long the TTL stays wrong
The sdkgen cache feature has no invalidation call. Its documented options are ttl, max,
methods, and an injectable now(), and its writes pass through without touching the store.
ttl.mjs drives that clock to measure the gap after a create.
node ttl.mjs
ttl 30000 ms: 120 stale reads, first fresh read 30000 ms after the create
ttl 2000 ms: 8 stale reads, first fresh read 2000 ms after the create
The worst case equals the TTL, reached when the list was read just before the write. The only
lever is a shorter ttl, and every read between the write and the expiry is stale.
Hand the same fetch to openapi-fetch and NSwag
Both generators ran on api.json. openapi-typescript wrote types only, with the list’s filter
and page as query?: { author?: string; page?: number; }, and openapi-fetch takes a
custom fetch in createClient. NSwag’s TypeScript
Fetch template wrote a Client class whose constructor takes http?: { fetch(url, init) }, and
uses window when none is given.
const client = createClient({ baseUrl: base, fetch: system?.fetch ?? globalThis.fetch })
return {
list: async (query = {}) => (await client.GET('/books', { params: { query } })).data,
create: async (book) => (await client.POST('/books', { body: book })).data,
}
},
NSwag: (base, { system } = {}) => {
const client = new nswag.Client(base, { fetch: system?.fetch ?? globalThis.fetch })
node generators.mjs
the same fetch under three clients; views that show the created book
sdkgen path-prefix delete 3 of 3, origin GETs 6
sdkgen ETag revalidation 3 of 3, origin GETs 9
openapi-fetch path-prefix delete 3 of 3, origin GETs 6
openapi-fetch ETag revalidation 3 of 3, origin GETs 9
NSwag path-prefix delete 3 of 3, origin GETs 6
NSwag ETag revalidation 3 of 3, origin GETs 9
a raw 304 handed to each client
sdkgen resolved with []
openapi-fetch resolved with undefined
NSwag threw: An unexpected server error occurred.
Pick openapi-fetch when you want a cache and no generated runtime to read past. NSwag earns its
place for a team that also generates the C# client from the same document.
Invalidate by prefix in TanStack Query
TanStack Query matches query keys by prefix unless exact: true is passed, so ['books'] covers
every filter and page that starts with it. tanstack.mjs keeps the lists in @tanstack/query-core
and fetches them through openapi-fetch.
node tanstack.mjs
TanStack Query over openapi-fetch: views that show the created book
exact key ['books', {}] all origin GETs 4
prefix key ['books'] all, author=Austen, page=2 origin GETs 6
optimistic insert into all all origin GETs 3
An optimistic insert costs no request and fixes only the view it writes into. SWR’s global
mutate takes a filter function over keys for the same
prefix match.
Check it worked
Fourteen tests run. Six read, create, and read again under each client and both fixes, and assert all three views show the new book.
node --test list.test.mjs
1..14
# tests 14
# suites 0
# pass 14
# fail 0
# cancelled 0
# skipped 0
# todo 0
# duration_ms 301.204767
The rest pin the exact-key bug, staleness of exactly ttl on the injected clock, and an item write
that drops its collection and nothing else. Others cover a failed write, a write that bypassed the
cache, a read that a write overtook, and a raw 304.
When it goes wrong
The list goes empty after the ETag cache is added. A 304 reached a client that never asked for
one. sdkgen counts any status under 400 as success and resolved [], openapi-fetch returned no
data and an empty error, and NSwag threw. Turn the 304 into the stored 200 inside the fetch, as
etagFetch does.
The old rows come back a moment after a write cleared them. A read that started before the write
returned after it, and the cache stored what it carried. Mark the reads in flight when a write
finishes and do not store them, as listCache does; one test holds a read across a write.
A write made by a background job never clears the cache. The job used another client, so the drop
never ran. Route every write through the same fetch, or fall back to ETag revalidation.
When not to do this
Do not cache a list your users write to under the sdkgen cache feature alone. It has no
invalidation call, so each create leaves every cached view stale until its ttl runs out. Use it for reference
data that changes on a schedule.
Do not invalidate one key per write. A list with filters and pages lives under many keys, and the one you forget is page two.
Do not add a client cache when the API already sends ETag headers and reads are cheap. Revalidation is
correct without code, and the 304 costs less than a bug in your invalidation rule.
Do not move off openapi-fetch or NSwag to get this rule. Both take a fetch, so the rule fits
either, and the reason to keep one is its typed paths or its C# twin.
Related how-tos
Last verified
Verified 2026-11-20 against Node 22.23.5, @voxgig/create-sdkgen 0.31.9, @voxgig/sdkgen 4.44.3,
openapi-typescript 7.13.0, openapi-fetch 0.17.0, @tanstack/query-core 5.108.1, NSwag 14.8.0,
and TypeScript 5.9.3. Every output block is what the command preceding it printed. NSwag was run
once on the ASP.NET Core runtime 10.0.15, and its output is committed, because the gate has no .NET.
Footnotes
-
Martin Fowler’s TwoHardThings entry gives the saying that cache invalidation and naming things are the two hard things in computer science. It credits Phil Karlton, finds the earliest online trace on Tim Bray’s blog, and records the later variant that adds off-by-one errors as a third item of two. ↩︎ Back to text
-
Section 8.8.3 of RFC 9110 defines an entity tag as an opaque validator for telling apart representations of one resource, whether they differ over time or by negotiation. The sample’s origin uses sixteen hex characters of a SHA-256 of the body, which is one way to be opaque. ↩︎ Back to text