189 lines
4.8 KiB
Plaintext
189 lines
4.8 KiB
Plaintext
# CacheStorage
|
|
|
|
<!--introduced_in=v5.22.1-->
|
|
<!--type=module-->
|
|
<!-- source_link=lib/web/cache/cachestorage.js -->
|
|
|
|
> 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'`:
|
|
|
|
```mjs
|
|
import { caches } from 'undici'
|
|
|
|
const cache = await caches.open('v1')
|
|
```
|
|
|
|
```cjs
|
|
const { caches } = require('undici')
|
|
|
|
caches.open('v1').then((cache) => {
|
|
// ...
|
|
})
|
|
```
|
|
|
|
## `caches`
|
|
|
|
<!-- YAML
|
|
added: v5.22.1
|
|
-->
|
|
|
|
* Type: {CacheStorage}
|
|
|
|
The shared [`CacheStorage`](#class-cachestorage) instance exported by undici.
|
|
All caches opened through `caches` live for the lifetime of the process.
|
|
|
|
```mjs
|
|
import { caches } from 'undici'
|
|
|
|
await caches.open('v1')
|
|
console.log(await caches.keys()) // ['v1']
|
|
```
|
|
|
|
## Class: `CacheStorage`
|
|
|
|
<!-- YAML
|
|
added: v5.22.1
|
|
-->
|
|
|
|
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`](#caches) instance
|
|
instead.
|
|
|
|
### `caches.match(request[, options])`
|
|
|
|
<!-- YAML
|
|
added: v5.22.1
|
|
-->
|
|
|
|
* `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.
|
|
|
|
```mjs
|
|
import { caches } from 'undici'
|
|
|
|
const response = await caches.match('https://example.com/data', {
|
|
cacheName: 'v1'
|
|
})
|
|
```
|
|
|
|
### `caches.has(cacheName)`
|
|
|
|
<!-- YAML
|
|
added: v5.22.1
|
|
-->
|
|
|
|
* `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.
|
|
|
|
```mjs
|
|
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)`
|
|
|
|
<!-- YAML
|
|
added: v5.22.1
|
|
-->
|
|
|
|
* `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.
|
|
|
|
```mjs
|
|
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)`
|
|
|
|
<!-- YAML
|
|
added: v5.22.1
|
|
-->
|
|
|
|
* `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.
|
|
|
|
```mjs
|
|
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()`
|
|
|
|
<!-- YAML
|
|
added: v5.22.1
|
|
-->
|
|
|
|
* Returns: {Promise} Fulfills with a {string[]} of cache names in insertion
|
|
order.
|
|
|
|
Returns the names of all caches currently held by the storage.
|
|
|
|
```mjs
|
|
import { caches } from 'undici'
|
|
|
|
await caches.open('v1')
|
|
await caches.open('v2')
|
|
console.log(await caches.keys()) // ['v1', 'v2']
|
|
```
|
|
|
|
[W3C Service Worker `CacheStorage`]: https://w3c.github.io/ServiceWorker/#cachestorage-interface
|
|
[`Cache`]: https://w3c.github.io/ServiceWorker/#cache-interface
|