Cache-Control behavior
Cache entry lifetimes are controlled via the Cache-Control header on the response you pass to put(). The same directives that govern HTTP caching apply here. For the full directive list, see Cache-Control on MDN.
await cache.put(
`${url.origin}/example.html`,
new Response("content", {
headers: { "Cache-Control": "max-age=60" },
}),
);
content under the key /example.html for 60 seconds.
Instance Methods
Delete
The delete() method finds the Cache entry whose key matches the request and removes it, returning true if an entry was found and deleted, or false if there was no matching entry.
Syntax
await cache.delete(request);
ignoreSearch, ignoreMethod, ignoreVary). To get equivalent behaviour, normalize the key at put() time — e.g. strip query strings from the URL before calling put().
Parameters
request
The Request you are looking to delete. This can be a Request object or a URL.
Return Value
A Promise that resolves to true if a matching entry was found and removed, or false if no entry existed. After the promise resolves, a subsequent cache.match() for the same key will miss.
Exceptions
Can throw an exception if there is an issue accessing the underlying cache storage.
Example
const cache = await caches.open("cache:v1");
const deleted = await cache.delete(`${url.origin}/example.html`);
DELETE as a purge endpoint.
Match
The match() method of the Cache returns a Promise that resolves to the Response associated with the first matching request in the Cache object. If no match is found, the Promise resolves to undefined.
Syntax
await cache.match(request);
ignoreSearch, ignoreMethod, ignoreVary). You can accomplish equivalent behaviour by removing query strings or unwanted headers from the key at put() time.
Parameters
request
The Request for which you are attempting to find responses in the Cache. This can be a Request object or a URL.
Return Value
A Promise that resolves to the first Response that matches the request or to undefined if no match is found.
Exceptions
Can throw an exception if there is an issue accessing the underlying cache storage.
Example
const cache = await caches.open("cache:v1");
const hit = await cache.match(`${url.origin}/example.html`);
if (hit) return hit;
match() lookup with an HTMLRewriter transform.
Put
The put() method of the Cache allows key/value pairs to be added to the current Cache object.
Syntax
await cache.put(request, response);
Parameters
request
The Request object or URL that you want to add to the cache.
response
The Response you want to match up to the request.
Return Value
A Promise that resolves with undefined.
Exceptions
Can throw an exception if there is an issue accessing the underlying cache storage.
Example
const cache = await caches.open("cache:v1");
// clone() so the response body can still be returned to the caller.
await cache.put(`${url.origin}/example.html`, response.clone());
References
- Examples — end-to-end recipes: cache-aside, middleware writes, refresh and purge.
- Managing caches — the global
caches object and named cache instances.
- Cache API overview — regional behavior, limitations, and API surface.
Last modified on July 1, 2026
