A `Cache` object from the browser's Cache API offers `add(request)`, `addAll(requests)` and `put(request, response)`. What does each one do, and when do you have to use `put`?

## The three write paths A `Cache` stores pairs of `Request` (the key) and `Response` (the value). There are exactly three ways to write into one. **`cache.add(request)`** takes a URL string or a `Request`, performs a `fetch()` for it, and stores the result. It is a convenience wrapper — roughly `fetch(req).then(res => cache.put(req, res))` — with one important extra rule: it rejects rather than storing a response that is not usable. **`cache.addAll(list)`** does the same for an array, and is **all-or-nothing**. Every request is fetched, and only if all of them succeed does the cache get written. If one URL 404s, the promise rejects and none of the others are stored either. That property is why it is the natural tool for pinning the assets of one application version: you never end up with a half-populated cache where three of five files exist. **`cache.put(request, response)`** stores a pair you already hold. It does no fetching and applies almost no policy. ```js const cache = await caches.open('v1'); await cache.addAll(['/', '/app.js', '/app.css']); // all or nothing const res = await fetch('/api/config'); await cache.put('/api/config', res.clone()); // keep res usable return res; ``` ## What `add`/`addAll` refuse The rejection rules are the practical difference. `add()` and `addAll()` reject with a `TypeError` when the fetch fails outright, when the response status is not an ok status (that is, outside 200–299), or when it is a `206 Partial Content`. An **opaque** response — what a cross-origin `no-cors` fetch produces — has status `0`, which is not ok, so `add()` can never store one. `put()` applies far fewer checks. It will happily store a `404`, a `500`, or an opaque response. It still enforces a few structural rules: the key request's method must be `GET`, its URL scheme must be `http` or `https`, and a `206` response is rejected here too, because a partial body is not a meaningful cache entry. So the rule of thumb is: use `add`/`addAll` when the browser fetching it for you is fine and you want failures to be loud; use `put` when you already have the response object, when the response is opaque, or when you deliberately want to store something that is not a 2xx. ## The body-consumed trap A `Response` body is a stream and can be consumed once. `cache.put()` consumes it. This is the single most common bug in this area: ```js // broken: the page gets an already-consumed body const res = await fetch(url); cache.put(url, res); return res; // TypeError: body stream already read ``` `response.clone()` produces a second readable copy, and it must be called **before** either copy is read. Which one you cache and which one you return does not matter; what matters is that two independent bodies exist. The same applies to `Request` objects when you need to both inspect and forward one. ## Storing something you made yourself `put()` accepts any `Response`, including a constructed one. That is how offline fallbacks are usually pinned without a network round trip: ```js await cache.put( '/offline', new Response('<h1>Offline</h1>', { headers: { 'Content-Type': 'text/html' } }) ); ``` ## Overwrite semantics `put()` replaces any existing entry whose key matches the new request — matching uses the same rules a lookup does, including `Vary`. There is no duplicate-key error and no append mode; the last write for a given key wins. To remove an entry explicitly you call `cache.delete(request)`, which resolves to `true` if something was removed. ## Reading back what you wrote `cache.keys()` resolves with the stored `Request` objects in insertion order — the fastest way to see what a cache actually contains while debugging, because the keys are requests, not bare URL strings. Reading is always `match()`/`matchAll()`; there is no index-based access.