CacheStorage.match()
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 value 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
: A boolean value that, when set totrue
, prevents matching operations from validating theRequest
http
method (normally onlyGET
andHEAD
are allowed.) It defaults tofalse
. -
ignoreVary
: A boolean value 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 |
---|
Service Workers 1 # cache-storage-match |
Browser compatibility
BCD tables only load in the browser