@yanglaofish/fishtools 0.5.2 → 0.6.0

package/node_modules/undici/docs/docs/api/CacheStorage.md

@@ -1,188 +1,30 @@
 # CacheStorage
 
-<!--introduced_in=v5.22.1-->
-<!--type=module-->
-<!-- source_link=lib/web/cache/cachestorage.js -->
+Undici exposes a W3C spec-compliant implementation of [CacheStorage](https://developer.mozilla.org/en-US/docs/Web/API/CacheStorage) and [Cache](https://developer.mozilla.org/en-US/docs/Web/API/Cache).
 
-> Stability: 2 - Stable
+## Opening a Cache
 
-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.
+Undici exports a top-level CacheStorage instance. You can open a new Cache, or duplicate a Cache with an existing name, by using `CacheStorage.prototype.open`. If you open a Cache with the same name as an already-existing Cache, its list of cached Responses will be shared between both instances.
 
 ```mjs
 import { caches } from 'undici'
-import assert from 'node:assert'
 
-const cache1 = await caches.open('v1')
-const cache2 = await caches.open('v1')
+const cache_1 = await caches.open('v1')
+const cache_2 = 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'))
+// Although .open() creates a new instance,
+assert(cache_1 !== cache_2)
+// The same Response is matched in both.
+assert.deepStrictEqual(await cache_1.match('/req'), await cache_2.match('/req'))
 ```
 
-### `caches.delete(cacheName)`
+## Deleting a Cache
 
-<!-- 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.
+If a Cache is deleted, the cached Responses/Requests can still be used.
 
 ```mjs
-import { caches } from 'undici'
-
-const cache = await caches.open('v1')
-const response = await cache.match('/req')
-
+const response = await cache_1.match('/req')
 await caches.delete('v1')
 
-// The already-retrieved response is still usable.
-await response.text()
+await response.text() // the Response's body
 ```
-
-### `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