Caching Computed Results with the Cache API

The Cache API is the right tool for memoizing expensive computed results inside a service worker — but it only stores Request/Response pairs, not arbitrary objects. This page explains the full pattern: opening a named cache, serializing computed values into Response bodies, choosing a stable cache key, handling versioning, and avoiding the gotchas that break it in production.

This page is part of the Service Workers for Computation reference, within High-Performance Computation Patterns.

Minimal Reproducible Example

This is the complete, smallest typed example. Everything below is a walkthrough of the pieces.

// sw.ts — full cache-first computation pattern

const CACHE_NAME = 'computed-v1';

/** Serialize a plain object into a cacheable Response */
function toResponse(data: unknown): Response {
  return new Response(JSON.stringify(data), {
    status: 200,
    headers: {
      'Content-Type': 'application/json',
      'X-Cached-At': new Date().toISOString(),
    },
  });
}

/** Build a stable, synthetic cache key from computation parameters */
function buildKey(params: Record<string, string>): Request {
  const qs = new URLSearchParams(params).toString();
  return new Request(`/cache-key/compute?${qs}`, { method: 'GET' });
}

/** Look up a cached result, or compute it and store it */
async function cachedCompute(
  params: Record<string, string>,
  compute: () => Promise<unknown>
): Promise<Response> {
  const cache = await caches.open(CACHE_NAME);
  const key = buildKey(params);

  const hit = await cache.match(key);
  if (hit) return hit;

  const result = await compute();
  const response = toResponse(result);
  // Always cache a clone — the original is consumed when returned
  await cache.put(key, response.clone());
  return response;
}

// Usage inside a fetch handler
self.addEventListener('fetch', (event: FetchEvent) => {
  const url = new URL(event.request.url);
  if (url.pathname !== '/api/transform') return;

  event.respondWith(
    cachedCompute(
      { dataset: url.searchParams.get('dataset') ?? '', version: '1' },
      async () => {
        const body = await event.request.clone().arrayBuffer();
        return expensiveTransform(body);
      }
    )
  );
});

function expensiveTransform(buffer: ArrayBuffer): number[] {
  const view = new Float64Array(buffer);
  const out: number[] = [];
  for (let i = 0; i < view.length; i++) out.push(view[i] * 2.0);
  return out;
}

Line-by-Line Walkthrough

caches.open(name) — getting a named cache

caches.open() returns a Promise<Cache>. It creates the named cache if it does not exist, or opens the existing one. The name is an opaque string scoped to the origin. Choose names that embed a version so you can evict them cleanly:

const cache = await caches.open('computed-v1');
// Later, in the activate handler, delete 'computed-v0', 'computed-v2-beta', etc.

You may open multiple named caches per origin (e.g., one for network assets, one for computed results). They do not share quota — both count toward the same origin storage budget.

cache.put(request, response) — writing a result

cache.put() stores the Request/Response pair. Both arguments must be actual Request and Response objects — you cannot pass a plain string or a plain object directly.

The Response body is a one-time-readable stream. If you pass the response directly to cache.put() and also return it from respondWith, one of them gets an empty body. Always clone before storing:

const response = toResponse(result);
await cache.put(key, response.clone()); // clone goes to cache
return response;                         // original goes to the page

cache.match(request) — reading a result

cache.match() performs a URL + method lookup. By default it ignores query-string differences when the ignoreSearch option is set, but the default is to match the full URL including the query string — which is what you want for parameter-keyed computation results:

const hit = await cache.match(key); // undefined if not found
if (hit) {
  const data = await hit.json(); // deserialize from Response body
  return data;
}

Round-trip time for caches.match() is 0.3–1ms in Chrome 124 (measured via performance.now() in a SW fetch handler on a modern laptop; expect 1–3ms on a mid-range mobile device).

Synthetic Request keys — stable cache keys for computed results

The cache key does not need to be a real URL that the network would respond to. A synthetic URL like /cache-key/compute?dataset=abc&version=1 is perfectly valid as a Request. The important properties are:

• Stability — the same logical input always produces the same key string.
• No collision — different inputs produce different key strings. Use URLSearchParams to percent-encode values rather than string-concatenating them manually.
• No real network match — prefix synthetic keys with a path like /cache-key/ that your fetch handler explicitly skips, so a cache miss never accidentally falls through to a real network request.

function buildKey(params: Record<string, string>): Request {
  // URLSearchParams sorts keys deterministically in insertion order,
  // so ensure you pass params in a consistent order.
  const sorted = Object.fromEntries(
    Object.entries(params).sort(([a], [b]) => a.localeCompare(b))
  );
  return new Request(`/cache-key/compute?${new URLSearchParams(sorted).toString()}`);
}

Gotchas & Edge Cases

Gotcha 1 — The Cache API stores Responses, not arbitrary objects

This is the most common mistake. You cannot write:

// BROKEN — TypeError: cache.put() requires a Response
await cache.put(key, myResultObject);

You must wrap the result in a Response:

// For JSON-serializable data
await cache.put(key, new Response(JSON.stringify(myResultObject), {
  headers: { 'Content-Type': 'application/json' },
}));

// For binary data (ArrayBuffer)
await cache.put(key, new Response(myArrayBuffer, {
  headers: { 'Content-Type': 'application/octet-stream' },
}));

When reading back, you must deserialize:

const hit = await cache.match(key);
if (hit) {
  const obj = await hit.json();         // for JSON
  // or:
  const buf = await hit.arrayBuffer();  // for binary
}

Gotcha 2 — Response bodies are single-use streams

A Response body is a ReadableStream. Once you consume it (via .json(), .text(), .arrayBuffer(), or by passing it to respondWith()), it is drained and cannot be read again. The fix is always to clone before storing:

const response = new Response(body, headers);
await cache.put(key, response.clone()); // cache gets a fresh stream
return response;                         // caller gets the original

Forgetting .clone() results in either an empty body reaching the page or an empty body stored in the cache — both silent failures that are hard to debug.

Gotcha 3 — Cache eviction is not automatic

Unlike localStorage, the Cache API does not have a size limit that throws an error — it just consumes origin storage quota. Browsers may evict cache entries under severe storage pressure, but this is unpredictable. Your code must handle cache misses even for entries you recently stored.

For computation results that grow unboundedly (e.g., one entry per unique dataset + parameter combination), implement active eviction:

async function pruneCache(maxEntries: number): Promise<void> {
  const cache = await caches.open(CACHE_NAME);
  const keys = await cache.keys();
  if (keys.length <= maxEntries) return;
  // Delete oldest entries (keys() returns in insertion order)
  const toDelete = keys.slice(0, keys.length - maxEntries);
  await Promise.all(toDelete.map(k => cache.delete(k)));
}

Gotcha 4 — Cache versioning requires explicit cleanup

Changing the computation algorithm (a new model version, a bug fix) invalidates all previously cached results. If you bump CACHE_NAME from computed-v1 to computed-v2 but forget to delete computed-v1, both caches accumulate, doubling storage usage. Delete stale caches in the activate event:

const CACHE_NAME = 'computed-v2'; // bump this when results change

self.addEventListener('activate', (event: ExtendableEvent) => {
  event.waitUntil(
    (async () => {
      const keys = await caches.keys();
      await Promise.all(
        keys
          .filter(k => k.startsWith('computed-') && k !== CACHE_NAME)
          .map(k => caches.delete(k))
      );
      await (self as ServiceWorkerGlobalScope).clients.claim();
    })()
  );
});

Concrete Performance Rule of Thumb

A caches.match() call completes in 0.3–1ms on desktop Chrome and 1–3ms on a mid-range Android device (measured with performance.now() bracketing the call in a SW fetch handler). A computation that previously took 300ms therefore returns 100–1000× faster from cache on the second request.

Cache writes via cache.put() are slightly slower (1–5ms on desktop, 3–10ms on mobile) because they involve a disk write. The write happens after you return the response to the page, so it does not add to the user-visible latency of the first request.

For the Data Parsing & Serialization pattern, this means: parse a large dataset once (200–800ms on mobile), cache the result (3–10ms write), and return it in under 3ms on every subsequent request — across all open tabs, across navigation, even after the user closes and reopens the tab.