Cache & Data Loading

#Cache

The Cache API provides a persistent storage mechanism for Request / Response object pairs that are cached in long lived memory.

Only a subset of the standard Cache API is supported. Below are the interfaces and methods that are supported and known limitations.

#CacheStorage

The CacheStorage is exposed as the caches global object. This object allows you to open instances of a Cache. When calling caches.open if the named cache does not exist it will be created, otherwise the existing cache will be returned.

Definition

interface CacheStorage {
  open(cacheName: string): Promise<Cache>;
}

Example

const cache = await caches.open("MY_CACHE");

#Cache

The Cache object stores Request and Response objects based on header values.

Definition

interface Cache {
  put(request: RequestInfo, response: Response): Promise<void>;
  match(
    request: RequestInfo,
    options?: CacheQueryOptions,
  ): Promise<Response | undefined>;
  delete(request: RequestInfo, options?: CacheQueryOptions): Promise<boolean>;
}

interface CacheQueryOptions {
  /**
   * Not supported in development environments
   */
  ignoreMethod: boolean;
  /**
   * Always ignored
   */
  ignoreSearch: boolean;
  /**
   * Always ignored
   */
  ignoreVary: boolean;
}

At this time, the options parameter will be ignored entirely when running on in a developer environment (i.e. working copy). In non-developer environments, the ignoreMethod property is supported. All other properties will be ignored.

#Put

await cache.put(request, response);

The put() method of the Cache interface allows key/value pairs to be added to the current Cache object.

#Match

const response = await cache.match(request);

The match() method of the Cache interface returns a Promise that resolves to the Response associated with the first matching request in the Cache object. If no match is found, the Promise resolves to undefined.

#Delete

await cache.delete(request);

The delete() method of the Cache interface finds the 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.

#Headers

The following headers can be used to control the cache when adding a response using the put() method.

Cache-Control: Controls caching directives. More info
ETag: Allows cache.match() to evaluate conditional requests with If-None-Match.
Expires: A string that specifies when the resource becomes invalid.
Last-Modified: Allows cache.match() to evaluate conditional requests with If-Modified-Since.

#Examples

The below example shows how to use a cached response and populate the cache in the event there is no response already cached.

const request = new Request(`https://echo.zuplo.io`);
const cache = await caches.open("MY_CACHE");
let response = await cache.match(request);
if (!response) {
  response = await fetch(request);
  await cache.put(request, response);
}

const data = await response.json();

If you just want to store the value, just create a new simple Response and set the Cache-Control header.

const request = new Request(`https://echo.zuplo.io`);
const cache = await caches.open("MY_CACHE");
const response = await fetch(request);

// Create a new response and set new headers
const cachedResponse = new Response(response, {
  headers: {
    "Cache-Control": "max-age=604800",
  },
});

// Add the response to the cache
await cache.put(request, cachedResponse);

When adding to the cache, headers are used to control how long resources are stored. If you are reusing the response headers, make sure to account for additional cache headers that may have been sent.

const request = new Request(`https://echo.zuplo.io`);
const cache = await caches.open("MY_CACHE");
const response = await fetch(request);

// Create a new Headers object and add existing response headers
const headers = new Headers(response.headers);

// Set the cache max age
headers.set("Cache-Control", "max-age=604800");

// Just in case the original response included other cache
// headers, remove them
headers.delete("Expires");
headers.delete("ETag");
headers.delete("Last-Modified");

// Create a new request with the cache headers
const cachedResponse = new Response(response, {
  headers,
});

// Add the response to the cache
await cache.put(request, cachedResponse);

← Previous page

Runtime Extensions

ZoneCache