CacheStorage: match() method
============================

 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
------


```js
match(request)
match(request, options)
```

### Parameters

`request`

 The `Request` you want to match. This can be a `Request`
 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
 to `true`, the `?value=bar` part of
 `http://foo.com/?value=bar` would be ignored when performing a match.
 It defaults to `false`.


`ignoreMethod`

 A boolean value that, when set to
 `true`, prevents matching operations from validating the
 `Request` `http` method (normally only `GET`
 and `HEAD` are allowed.) It defaults to `false`.


`ignoreVary`

 A boolean value that, when set to
 `true,` tells the matching operation not to perform `VARY`
 header matching. In other words, if the URL matches you will get a match
 regardless of whether the `Response` object has a `VARY`
 header or not. It defaults to `false`.


`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:

1. Check whether a match for the request is found in the `CacheStorage`
 using `CacheStorage.match()`. If so, serve that.
2. If not, open the `v1` cache using `open()`, put the default
 network request in the cache using `Cache.put()` and return a
 clone of the default network request using `return response.clone()`. The
 last is necessary because `put()` consumes the response body.
3. If this fails (e.g., because the network is down), return a fallback response.


```js
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;
      } else {
        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
--------------

| Specification |
| --- |
| Service Workers # cache-storage-match |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* Using Service Workers
* `Cache`
* `caches`