# 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`.

Source: https://voxgig.com/howto/invalidate-cached-list-after-create

- Audience: api-consumer
- Level: intermediate
- Languages: typescript
- Verified: 2026-11-20
- Published: 2026-11-20

## 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](https://www.rfc-editor.org/rfc/rfc9110.html#name-etag) | 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](https://redis.io/docs/latest/commands/scan/) | 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](https://github.com/RicoSuter/NSwag/wiki/TypeScriptClientGenerator) | 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`](https://openapi-ts.dev/openapi-fetch/api) | 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](https://github.com/voxgig/sdkgen/blob/main/docs/reference/features.md) | 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`](https://tanstack.com/query/latest/docs/framework/react/guides/query-invalidation) | 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.

```js title="list-cache.mjs"
  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`](https://redis.io/docs/latest/commands/scan/) with `MATCH` over your key prefix, then
[`UNLINK`](https://redis.io/docs/latest/commands/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.

```bash
node demo.mjs
```

```text output
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.

```bash
node ttl.mjs
```

```text output
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`](https://openapi-ts.dev/openapi-fetch/api) 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.

```js title="clients.mjs"
    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 })
```

```bash
node generators.mjs
```

```text output
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`.

```bash
node tanstack.mjs
```

```text output
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`](https://swr.vercel.app/docs/mutation) 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.

```bash
node --test list.test.mjs
```

```text output
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

- [Build cache keys that include the caller and Vary headers](/howto/cache-keys-that-include-the-caller)

- [Serve stale API responses and revalidate in the background](/howto/serve-stale-api-responses-while-revalidating)

- [Share an API response cache across many workers with Redis](/howto/share-a-response-cache-across-workers-with-redis)

- [Choose Cache-Control values for private and shared caches](/howto/choose-cache-control-directives-for-api-responses)

- [Add a response cache to a third-party SDK](/howto/cache-responses-in-a-third-party-sdk)

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

[^1]: Martin Fowler's [TwoHardThings](https://martinfowler.com/bliki/TwoHardThings.html) 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.

[^2]: Section 8.8.3 of [RFC 9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-etag) 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.