This is an experimental technology
Check the Browser compatibility table carefully before using this in production.
The match()
method of the CacheStorage
interface (available globally as caches
) checks if a given Request
or url string is a key for a stored Response
. This method returns a Promise
for a Response
, or undefined
if no match is found.
Cache objects are searched in creation order.
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.
caches.match(event.request).then(function(response) { return response || fetch(event.request).then(function(r) { caches.open('v1').then(function(cache) { cache.put(event.request, r); }); return r.clone(); }); }).catch(function() { return caches.match('/sw-test/gallery/myLittleVader.jpg'); });
Specifications
Specification | Status | Comment |
---|---|---|
Service Workers The definition of 'CacheStorage' in that specification. |
Editor's Draft | Initial definition. |
Browser compatibility
Feature | Chrome | Edge | Firefox (Gecko) | Internet Explorer | Opera | Safari |
---|---|---|---|---|---|---|
Basic support | 40[1] | (Yes) | 44 (44)[2] | No support | 27 | No support |
All options supported | 54 | ? | (Yes) | No support | 41 | No support |
Feature | Android Webview | Chrome for Android | Firefox Mobile (Gecko) | IE Mobile | Opera Mobile | Safari Mobile |
---|---|---|---|---|---|---|
Basic support | 40[1] | 40[1] | 44.0 (44) | (Yes) | 27 | (Yes) |
All options supported | 54 | 54 | (Yes) | (Yes) | 41 | (Yes) |
- [1] The options parameter only supports
ignoreSearch
, andcacheName
. - [2] Service workers (and Push) have been disabled in the Firefox 45 & 52 Extended Support Releases (ESR.)