CacheStorage: match() method
Service Workers API
Service Workers API
The match() method of the CacheStorage interface checks if a given Request or URL string is a key for a stored Response.
This method returns a Promise for a Response, or a Promise which resolves to undefined if no match is found.
You can access CacheStorage through the Window.caches property in windows or through the WorkerGlobalScope.caches property in workers.
Cache objects are searched in creation order.
[!NOTE]
caches.match()is a convenience method. Equivalent functionality is to call cache.match() on each cache (in the order returned by caches.keys()) until a Response is returned.
Syntax
match(request)
match(request, options)
Parameters
request- : The Request you want to match. This can be a Request object or a URL string.
options- : An object whose properties control how matching is done in the
matchoperation. The available options are:ignoreSearch- : A boolean value that specifies whether the
matching process should ignore the query string in the URL. For example, if set
to
true, the?value=barpart ofhttps://example.com/?value=barwould be ignored when performing a match. It defaults tofalse. ignoreMethod- : A boolean value that, when set to
true, prevents matching operations from validating the Requesthttpmethod (normally onlyGETandHEADare allowed.) It defaults tofalse. ignoreVary- : A boolean value that, when set to
true, tells the matching operation not to performVARYheader matching. In other words, if the URL matches you will get a match regardless of whether the Response object has aVARYheader or not. It defaults tofalse. cacheName- : A string that represents a specific cache to search within.
Return value
A Promise that resolves to the matching Response. If
no matching response to the specified request is found, the promise resolves
with undefined.
Examples
This example is from the MDN simple service worker example (see simple service worker running live). Here we wait for a FetchEvent to fire. We construct a custom response like so:
- Check whether a match for the request is found in the CacheStorage
using
CacheStorage.match(). If so, serve that. - If not, open the
v1cache usingopen(), put the default network request in the cache using Cache.put() and return a clone of the default network request usingreturn response.clone(). The last is necessary becauseput()consumes the response body. - If this fails (e.g., because the network is down), return a fallback response.
self.addEventListener("fetch", (event) => {
event.respondWith(
caches.match(event.request).then((response) => {
// caches.match() always resolves
// but in case of success response will have value
if (response !== undefined) {
return response;
}
return fetch(event.request)
.then((response) => {
// response may be used only once
// we need to save clone to put one copy in cache
// and serve second one
let responseClone = response.clone();
caches
.open("v1")
.then((cache) => cache.put(event.request, responseClone));
return response;
})
.catch(() => caches.match("/gallery/myLittleVader.jpg"));
}),
);
});
Specifications
Browser compatibility
See also
- Using Service Workers
- Cache
- Window.caches and WorkerGlobalScope.caches