How-to › Make calls that survive failure

How to invalidate a cached list after a create call#

Make a record you created show in every cached view of its list, filtered or paged, by dropping the collection's keys on write or revalidating with an `ETag`.

Audience
API consumer
Level
intermediate
Topic
Cache API responses
Languages
TypeScript
Verified

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

ApproachWhen it fitsWhat it costs youWhen to pick something else
ETag on the listThe API sends a validator on lists and answers If-None-MatchA round trip on every read, even when the list has not changedReads dominate and the network is slow
Key-prefix delete in your cacheYou own the cache and every write goes through itEvery write path must know which collections it changes, or a list stays staleA write can happen where your cache cannot see it
NSwag http optionAn NSwag TypeScript client, which takes any object with fetchUndocumented statuses other than 204 throw, so a stray 304 becomes an exceptionYou need per-response hooks, which its UseTransformResultMethod setting adds
openapi-typescript and openapi-fetchA typed client whose createClient takes a custom fetchTypes only, so the cache, the rule, and the runtime package are yoursYou want generated methods rather than typed paths
sdkgen cache featureStaleness for a bounded time is acceptableNo invalidation call, so a write leaves each cached list wrong until its TTL endsUsers must see their own writes at once
TanStack Query invalidateQueriesA front end already keeps its lists in TanStack QueryAn extra library on the client, and query keys you must shape for prefix matchingThe 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.

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

  1. 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

  2. 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

Read this page as markdown · All how-to guides

Generate the client instead of writing it#

Retries, timeouts, pagination and auth are the same problems in every client. Voxgig generates them from your OpenAPI description, in 23 languages, from one model.

Listen to Fireside, the Voxgig podcast

Since 2018, Richard Rodger has talked with developer advocates, event organizers, and the people who build developer-facing companies about the specifics of the work.