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
: ABoolean
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.
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 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 Workers The 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.
Desktop | Mobile | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
match | Chrome
Full support
54
| Edge Full support 16 | Firefox
Full support
44
| IE No support No | Opera
Full support
41
| Safari Full support 11.1 | WebView Android
Full support
54
| Chrome Android
Full support
54
| Firefox Android Full support 44 | Opera Android
Full support
41
| Safari iOS Full support Yes | Samsung Internet Android
Full support
6.0
|
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.