The Cache API

## What a lookup actually compares `cache.match(request, options)` runs a matching algorithm, not a string equality test on a URL. Understanding the four inputs to that algorithm explains essentially every mysterious miss. The key stored in a `Cache` is a whole `Request`, so a lookup compares the **serialised URL** (scheme, host, port, path *and* query string, with the fragment ignored), the **method**, and — if the stored *response* says so — a set of **request headers**. ## Cause 1: the query string is part of the key This is by far the most common surprise. `/api/items` and `/api/items?page=2` are two different keys, as are `?a=1&b=2` and `?b=2&a=1`, because the comparison is on the serialised URL, not on a parsed parameter set. A cache-busting suffix such as `/app.js?v=1749` likewise makes the entry unreachable from a request for `/app.js`. ```js await cache.put('/api/items', res); await cache.match('/api/items?page=2'); // undefined await cache.match('/api/items?page=2', { ignoreSearch: true }); // hit ``` `ignoreSearch: true` strips the query from both sides before comparing. Be deliberate about it: if the query genuinely selects different content, ignoring it returns the wrong body. ## Cause 2: `Vary` is enforced during lookup The Cache API ignores freshness headers entirely, but it *does* consult one header — `Vary` — and it does so on the **stored response**. If the stored response carries `Vary: Accept-Encoding, Accept-Language`, then a candidate entry only matches when the incoming request's values for those header names equal the values on the request that was originally stored. That produces misses that look impossible, because nothing about the URL changed: - A response stored during a fetch from a service worker had no `Accept-Language`, while the page's navigation request has one. - An API returns `Vary: Accept`, and one call asked for `application/json` while another sent the default. - `Vary: *` never matches anything, by definition. `{ ignoreVary: true }` disables the check. Use it when you know the variation does not affect the bytes you stored; otherwise fix the key instead — for example by storing under a synthetic URL that encodes the variant. ## Cause 3: only GET matches A `Cache` key must be a GET request with an http or https URL — `put()` rejects anything else. Matching enforces the method too, so passing a `Request` built with `method: 'POST'` or `'HEAD'` finds nothing. `{ ignoreMethod: true }` makes the algorithm skip the method comparison, which is mainly useful for looking up a HEAD request against a stored GET entry. ## Cause 4: the wrong cache `cache.match()` searches exactly one named `Cache`. If a deploy bumped the name from `static-v3` to `static-v4`, a handler still opening `static-v3` will read from an empty or stale generation. `caches.match(request)` searches every cache of the origin in creation order and returns the first hit, and accepts `{ cacheName: 'static-v4' }` to narrow it. All the other options pass through: ```js const hit = await caches.match(request, { ignoreSearch: true, cacheName: 'static-v4' }); ``` ## Debugging technique When a lookup misbehaves, stop guessing and print the keys: ```js const cache = await caches.open('static-v4'); console.log((await cache.keys()).map((r) => `${r.method} ${r.url}`)); ``` `cache.keys()` resolves with the actual stored `Request` objects in insertion order. Seeing `GET https://example.com/app.js?v=1749` next to a lookup for `/app.js` ends the investigation instantly. `cache.matchAll(request, options)` is the companion for the opposite problem — several entries matching one request, typically when `ignoreSearch` or `ignoreVary` is in play — and returns all of them rather than the first. ## The mirror-image failure The same options cause *false hits*. `ignoreSearch: true` on a paginated API returns page 1's body for a page-2 request. `ignoreVary: true` on a content-negotiated endpoint can hand JSON to a request that asked for HTML. Treat both as narrow tools for cases where you have proved the variation is irrelevant, not as a default that makes lookups "work".