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 global caches
property.
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
caches.match(request, options).then(function(response) { // Do something with the response });
Parameters
- request
- The
Request
you want to match. This can be aRequest
object or a URL string. - options Optional
- An object whose properties control how matching is done in the
match
operation. The available options are:
ignoreSearch
- A
Boolean
that specifies whether the matching process should ignore the query string in the url. For example, if set totrue
, the?value=bar
part ofhttp://foo.com/?value=bar
would be ignored when performing a match. It defaults tofalse
. ignoreMethod
: ABoolean
that, when set totrue
, prevents matching operations from validating theRequest
http
method (normally onlyGET
andHEAD
are allowed.) It defaults tofalse
.ignoreVary
: ABoolean
that, when set totrue,
tells the matching operation not to performVARY
header matching. In other words, if the URL matches you will get a match regardless of whether theResponse
object has aVARY
header or not. It defaults tofalse
.cacheName
: ADOMString
that represents a specific cache to search within.
- A
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 sw-test example (see [[../../../../../../../mdn.github.io/sw-test/index|sw-test 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
usingCacheStorage.match()
. If so, serve that. - If not, open the
v1
cache usingopen()
, put the default network request in the cache usingCache.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', function(event) {
event.respondWith(caches.match(event.request).then(function(response) {
// caches.match() always resolves
// but in case of success response will have value
if (response !== undefined) {
return response;
} else {
return fetch(event.request).then(function (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(function (cache) {
cache.put(event.request, responseClone);
});
return response;
}).catch(function () {
return caches.match('/sw-test/gallery/myLittleVader.jpg');
});
}
}));
});
Specifications
Specification | Status | Comment |
Service WorkersThe definition of 'CacheStorage: match' in that specification. | Working Draft | Initial definition. |
Browser compatibility
The compatibility table on this page is generated from structured data. If you'd like to contribute to the data, please check out https://github.com/mdn/browser-compat-data and send us a pull request.
Update compatibility data on GitHub
Desktop | Mobile | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
|
Chrome Full support 54 Full support 54 Partial support 40 Notes' The options parameter only supports |
Edge
Full support 16 |
Firefox Full support 44 Full support 44 Notes' Extended Support Releases (ESR) before Firefox 78 ESR do not support service workers and the Push API. |
IE
No support No |
Opera Full support 41 Full support 41 Partial support 27 Notes' The options parameter only supports |
Safari
Full support 11.1 |
WebView Android Full support 54 Full support 54 Partial support 40 Notes' The options parameter only supports |
Chrome Android Full support 54 Full support 54 Partial support 40 Notes' The options parameter only supports |
Firefox Android
Full support 44 |
Opera Android Full support 41 Full support 41 Partial support 27 Notes' The options parameter only supports |
Safari iOS
Full support Yes |
Samsung Internet Android Full support 6.0 Full support 6.0 Partial support 4.0 Notes' The options parameter only supports |
Legend
- Full support
- Full support
- No support
- No support
- Experimental. Expect behavior to change in the future.'
- Experimental. Expect behavior to change in the future.
- See implementation notes.'
- See implementation notes.
See also
CacheStorage.match() by Mozilla Contributors is licensed under CC-BY-SA 2.5.