Function cache

Creates a caching middleware.

The generated middleware replays what it holds for a GET or HEAD exchange while the freshness it is held under lasts, that is the one the origin server stated or, where it stated none, the one its Last-Modified implies or the ttl option assumes, revalidates it with the stored validators once that time is up, replaying the held content again when the origin server answers 304, and relays the exchange to the wrapped Fetch implementation whenever it holds nothing usable, keeping what comes back. A successful mutating request invalidates the entries for its target, so a client that both reads and writes doesn't serve what it has just overwritten.

A response answered from the store restates the exchange as it was retrieved, its URL, status and reason phrase included, so that a client reading it draws the same conclusions it draws from a freshly retrieved one. The age is the one departure: an Age header field states how long the content has been held since the origin server delivered it, so that whoever receives it judges for itself how much of its freshness is left. A successful revalidation restarts the age from what the 304 states, as the delivery it confirms supersedes the one the entry was reporting.

Invalidation gives up every variant held for a target and extends to the URIs named by the Location and Content-Location header fields of the response, when they share the origin of the target, so that a server reports what else a mutating request has changed. No other entry is given up: a target and its query string variants are distinct resources, and nothing states that one goes stale when another is written.

Exchanges targeting a scheme other than http and https and exchanges stating a Range are relayed untouched and never stored, as are the responses that are partial or set a cookie, so that a complete response answering a complete request is the only thing ever replayed.

A target the skip option selects is relayed untouched and never stored, so that a resource the consumer holds back stays out of the cache whatever the origin server states about it. Invalidation is unaffected: a successful unsafe exchange for a skipped target still gives up the entries the response reports as changed.

Every numeric option is removed by a value less than or equal to 0, as the defaults do: entries are then retained for the life of the middleware and reuse rests on what the origin server reports alone.

The ttl option states a single freshness budget, that is how long a response is worth reusing: the origin server overrides it by stating less, and it governs where the response reports nothing to derive a freshness from, so that a response carrying no expiration is reused rather than revalidated on every exchange. Freshness is assumed only for the status codes RFC 9110 § 15.1 defines as heuristically cacheable, and only where no Cache-Control no-cache, max-age, must-revalidate or proxy-revalidate directive and no Expires header field is stated: a stated expiration keeps winning, however short it is.

A response stating no expiration but reporting when its content last changed is reused for a tenth of the interval it had gone unchanged, so that a resource edited a minute ago is revalidated sooner than one untouched for a year; ttl caps that share as it caps a stated expiration, and supplies the freshness where no usable Last-Modified is reported.