CacheStorage

Stability: 2 - Stable

undici provides a spec-compliant implementation of the W3C Service Worker CacheStorage and Cache interfaces. A CacheStorage is a named collection of Cache objects, each of which stores Request/Response pairs.

The class itself is not exported; instead, undici exposes a single shared CacheStorage instance named caches. Import it from 'undici':

import { caches } from 'undici'

const cache = await caches.open('v1')

const { caches } = require('undici')

caches.open('v1').then((cache) => {
  // ...
})

caches

• Type: {CacheStorage}

The shared CacheStorage instance exported by undici. All caches opened through caches live for the lifetime of the process.

import { caches } from 'undici'

await caches.open('v1')
console.log(await caches.keys()) // ['v1']

Class: CacheStorage

Represents the storage for Cache objects. Each CacheStorage keeps a mapping of cache names to their backing list of cached responses.

The constructor is not public: attempting to instantiate CacheStorage directly throws a TypeError. Use the exported caches instance instead.

caches.match(request[, options])

• request {Request|string} The request to match against. A string is treated as a URL.
• options {Object} (optional)
  • ignoreSearch {boolean} When true, ignores the query string of the URL when matching. Default: false.
  • ignoreMethod {boolean} When true, prevents matching operations from validating the Request http method. Default: false.
  • ignoreVary {boolean} When true, ignores the Vary header when matching. Default: false.
  • cacheName {string} When set, restricts the search to the cache with this name. Default: undefined.
• Returns: {Promise} Fulfills with the first matching {Response}, or undefined if no response matched.

Searches the caches for a response matching request. When options.cacheName is provided, only that cache is searched; otherwise every cache is searched in insertion order and the first match is returned.

import { caches } from 'undici'

const response = await caches.match('https://example.com/data', {
  cacheName: 'v1'
})

caches.has(cacheName)

• cacheName {string} The name of the cache to look up.
• Returns: {Promise} Fulfills with true if a cache named cacheName exists, otherwise false.

Checks whether a cache with the given name exists in the storage.

import { caches } from 'undici'

await caches.open('v1')
console.log(await caches.has('v1')) // true
console.log(await caches.has('v2')) // false

caches.open(cacheName)

• cacheName {string} The name of the cache to open.
• Returns: {Promise} Fulfills with the {Cache} named cacheName.

Opens the cache named cacheName, creating it if it does not already exist.

Each call returns a new Cache object, but caches opened with the same name share their underlying list of cached responses. As a result, a response stored through one instance is visible through another instance with the same name.

import { caches } from 'undici'
import assert from 'node:assert'

const cache1 = await caches.open('v1')
const cache2 = await caches.open('v1')

// open() returns distinct objects,
assert(cache1 !== cache2)
// but they share the same cached responses.
assert.deepStrictEqual(await cache1.match('/req'), await cache2.match('/req'))

caches.delete(cacheName)

• cacheName {string} The name of the cache to delete.
• Returns: {Promise} Fulfills with true if the cache existed and was deleted, otherwise false.

Removes the cache named cacheName from the storage. Any Cache objects already obtained for that name, along with the Request/Response pairs they returned, remain usable after deletion.

import { caches } from 'undici'

const cache = await caches.open('v1')
const response = await cache.match('/req')

await caches.delete('v1')

// The already-retrieved response is still usable.
await response.text()

caches.keys()

• Returns: {Promise} Fulfills with a {string[]} of cache names in insertion order.

Returns the names of all caches currently held by the storage.

import { caches } from 'undici'

await caches.open('v1')
await caches.open('v2')
console.log(await caches.keys()) // ['v1', 'v2']