This is an experimental technology
Check the Browser compatibility table carefully before using this in production.
The Cache
interface provides a storage mechanism for Request
/ Response
object pairs that are cached, for example as part of the ServiceWorker
life cycle. Note that the Cache
interface is exposed to windowed scopes as well as workers. You don't have to use it in conjunction with service workers, even though it is defined in the service worker spec.
An origin can have multiple, named Cache
objects. You are responsible for implementing how your script (e.g. in a ServiceWorker
) handles Cache
updates. Items in a Cache
do not get updated unless explicitly requested; they don’t expire unless deleted. Use CacheStorage.open()
to open a specific named Cache
object and then call any of the Cache
methods to maintain the Cache
.
You are also responsible for periodically purging cache entries. Each browser has a hard limit on the amount of cache storage that a given origin can use. Cache quota usage estimates are available via the StorageEstimate
API. The browser does its best to manage disk space, but it may delete the Cache storage for an origin. The browser will generally delete all of the data for an origin or none of the data for an origin. Make sure to version caches by name and use the caches only from the version of the script that they can safely operate on. See Deleting old caches for more information.
Note: Initial Cache implementations (in both Blink and Gecko) resolve Cache.add
, Cache.addAll
, and Cache.put
promises when the response body is fully written to storage. More recent spec versions state that the browser can resolve the promise as soon as the entry is recorded in the database even if the response body is still streaming in.
Note: The key matching algorithm depends on the VARY header in the value. So matching a new key requires looking at both key and value for entries in the Cache.
Note: The caching API doesn't honor HTTP caching headers.
Cache.match(request, options)
Promise
that resolves to the response associated with the first matching request in the Cache
object.Cache.matchAll(request, options)
Promise
that resolves to an array of all matching requests in the Cache
object.Cache.add(request)
Cache.addAll(requests)
Cache.put(request, response)
Cache.delete(request, options)
Cache
entry whose key is the request, and if found, deletes the Cache
entry and returns a Promise
that resolves to true
. If no Cache
entry is found, it resolves to false
.Cache.keys(request, options)
Promise
that resolves to an array of Cache
keys.This code snippet is from the service worker selective caching sample. (see selective caching live) The code uses CacheStorage.open()
to open any Cache
objects with a Content-Type
header that starts with font/
.
The code then uses Cache.match()
to see if there's already a matching font in the cache, and if so, returns it. If there isn't a matching font, the code fetches the font from the network and uses Cache.put()
to cache the fetched resource.
The code handles exceptions thrown from the fetch()
operation. Note that an HTTP error response (e.g., 404) will not trigger an exception. It will return a normal response object that has the appropriate error code.
The code snippet also shows a best practice for versioning caches used by the service worker. Though there's only one cache in this example, the same approach can be used for multiple caches. It maps a shorthand identifier for a cache to a specific, versioned cache name. The code also deletes all caches that aren't named in CURRENT_CACHES
.
In the code example, "caches" is an attribute of the service worker's WorkerGlobalScope
. It holds the CacheStorage
object, by which by can access the CacheStorage
interface.
var CACHE_VERSION = 1; // Shorthand identifier mapped to specific versioned cache. var CURRENT_CACHES = { font: 'font-cache-v' + CACHE_VERSION }; self.addEventListener('activate', function(event) { var expectedCacheNames = Object.keys(CURRENT_CACHES).map(function(key) { return CURRENT_CACHES[key]; }); // Active worker won't be treated as activated until promise // resolves successfully. event.waitUntil( caches.keys().then(function(cacheNames) { return Promise.all( cacheNames.map(function(cacheName) { if (expectedCacheNames.indexOf(cacheName) === -1) { console.log('Deleting out of date cache:', cacheName); return caches.delete(cacheName); } }) ); }) ); }); self.addEventListener('fetch', function(event) { console.log('Handling fetch event for', event.request.url); event.respondWith( // Opens Cache objects that start with 'font'. caches.open(CURRENT_CACHES['font']).then(function(cache) { return cache.match(event.request).then(function(response) { if (response) { console.log('Found response in cache:', response); return response; } }).catch(function(error) { // Handles exceptions that arise from match() or fetch(). console.error('Error in fetch handler:', error); throw error; }); }) ); });
Specification | Status | Comment |
---|---|---|
Service Workers The definition of 'Cache' in that specification. | Editor's Draft | Initial definition. |
Feature | Chrome | Edge | Firefox (Gecko) | Internet Explorer | Opera | Safari (WebKit) |
---|---|---|---|---|---|---|
Basic support | 40 | (Yes) | 39 (39)[1] | No support | 27 | No support |
add() | 44 | (Yes) | (Yes)[1] | No support | 31 | No support |
addAll() | 46 | (Yes) | (Yes)[1] | No support | 33 | No support |
matchAll() | 47 | (Yes) | (Yes)[1] | No support | 34 | No support |
On global scope | 43 | (Yes) | (Yes)[1] | No support | 30 | No support |
Require HTTPS for add() , addAll() , and put()
| 46 | (Yes) | (Yes)[1] | No support | 33 | No support |
Feature | Android Webview | Chrome for Android | Firefox Mobile (Gecko) | Firefox OS | IE Mobile | Opera Mobile | Safari Mobile |
---|---|---|---|---|---|---|---|
Basic support | 40 | 40 | 39.0 (39) | ? | No support | 27 | No support |
add() | 44 | 44 | (Yes) | ? | No support | 31 | No support |
addAll() | 46 | 46 | (Yes) | ? | No support | 33 | No support |
matchAll() | 47 | 47 | (Yes) | ? | No support | 34 | No support |
On global scope | 43 | 43 | (Yes) | ? | No support | 30 | No support |
Require HTTPS for add() , addAll() , and put()
| 46 | 46 | (Yes) | ? | No support | 33 | No support |
[1] Service workers (and Push) have been disabled in the Firefox 45 & 52 Extended Support Releases (ESR.)
Promise
© 2005–2018 Mozilla Developer Network and individual contributors.
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.
https://developer.mozilla.org/en-US/docs/Web/API/Cache