@yanglaofish/fishtools 0.5.1 → 0.5.3

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

@@ -1,653 +1,41 @@
 # Fetch
 
-<!--introduced_in=v1.0.0-->
-<!--type=module-->
-<!-- source_link=lib/web/fetch/index.js -->
+Undici exposes a fetch() method starts the process of fetching a resource from the network.
 
-> Stability: 2 - Stable
+Documentation and examples can be found on [MDN](https://developer.mozilla.org/en-US/docs/Web/API/fetch).
 
-undici implements the [WHATWG Fetch Standard][], providing `fetch()` together
-with the `Request`, `Response`, `Headers`, and `FormData` classes that mirror
-the browser APIs. The implementation follows the standard, so the
-[MDN Fetch documentation][] applies as well.
+## FormData
 
-```mjs
-import { fetch, Request, Response, Headers, FormData } from 'undici'
-
-const response = await fetch('https://example.com')
-const text = await response.text()
-```
-
-When mixing these classes, keep them from the same implementation: use the
-global `fetch()` with the global `FormData`, `Request`, `Response`, and
-`Headers`, and use undici's `fetch()` with undici's classes. Passing a value
-created by one implementation to the other can throw.
-
-## `fetch(input[, init])`
-
-<!-- YAML
-added: v5.6.0
-changes:
-  - version: v5.6.1
-    pr-url: https://github.com/nodejs/undici/pull/1529
-    description: No default value is assigned to `init.method`.
--->
-
-* `input` {string|URL|Request} The resource to fetch. A string or {URL} is
-  treated as the URL to request; a {Request} is used as the request template.
-* `init` {RequestInit} (optional) An options object that customizes the
-  request.
-  * `body` {string|Buffer|Uint8Array|Blob|FormData|URLSearchParams|ReadableStream|null}
-    The request body. **Default:** `null`.
-  * `cache` {string} The cache mode. One of `'default'`, `'force-cache'`,
-    `'no-cache'`, `'no-store'`, `'only-if-cached'`, or `'reload'`.
-  * `credentials` {string} How credentials are sent. One of `'omit'`,
-    `'include'`, or `'same-origin'`.
-  * `dispatcher` {Dispatcher} The {Dispatcher} used to perform the request.
-    **Default:** the global dispatcher.
-  * `duplex` {string} The duplex mode of the request. Must be `'half'` when a
-    streaming `body` is provided.
-  * `headers` {Headers|Object|Array} The request headers, as a {Headers}
-    instance, a plain object, or an array of `[name, value]` pairs.
-  * `integrity` {string} The subresource integrity metadata of the request.
-  * `keepalive` {boolean} Whether the connection may outlive the page.
-    **Default:** `false`.
-  * `method` {string} The request method, for example `'GET'` or `'POST'`.
-  * `mode` {string} The request mode. One of `'cors'`, `'navigate'`,
-    `'no-cors'`, or `'same-origin'`.
-  * `redirect` {string} How redirects are handled. One of `'error'`,
-    `'follow'`, or `'manual'`.
-  * `referrer` {string} The request referrer.
-  * `referrerPolicy` {string} The referrer policy. One of `''`,
-    `'no-referrer'`, `'no-referrer-when-downgrade'`, `'origin'`,
-    `'origin-when-cross-origin'`, `'same-origin'`, `'strict-origin'`,
-    `'strict-origin-when-cross-origin'`, or `'unsafe-url'`.
-  * `signal` {AbortSignal|null} An {AbortSignal} used to abort the request.
-    **Default:** `null`.
-  * `window` {null} Can only be `null`; reserved by the standard.
-* Returns: {Promise} Fulfills with a {Response} once the response headers have
-  been received.
-
-Starts the process of fetching a resource from the network and returns a
-promise that fulfills with a {Response}. The promise rejects only on network
-failures; an HTTP error status such as `404` still fulfills the promise, so
-inspect [`response.ok`](#responseok) to detect failures.
-
-```mjs
-import { fetch } from 'undici'
-
-const response = await fetch('https://example.com', {
-  method: 'POST',
-  headers: { 'content-type': 'application/json' },
-  body: JSON.stringify({ hello: 'world' }),
-})
-
-console.log(response.status)
-console.log(await response.json())
-```
-
-To route the request through a custom {Dispatcher} (for example a `ProxyAgent`
-or `Agent` with specific options), pass it as `init.dispatcher`.
-
-```mjs
-import { fetch, Agent } from 'undici'
-
-const response = await fetch('https://example.com', {
-  dispatcher: new Agent({ connect: { rejectUnauthorized: false } }),
-})
-```
-
-## Class: `FormData`
-
-<!-- YAML
-added: v4.4.4
--->
-
-A set of key/value pairs representing form fields and their values, suitable
-for use as a `fetch()` request `body`. The implementation follows the
-[WHATWG Fetch Standard][]; see the [MDN `FormData` documentation][].
-
-When using `FormData` as a request body, keep `fetch` and `FormData` from the
-same implementation: use the global `FormData` with the global `fetch()`, and
-undici's `FormData` with undici's `fetch()`.
-
-### `new FormData()`
-
-<!-- YAML
-added: v4.4.4
--->
-
-Creates a new, empty `FormData` instance. Passing any argument other than
-`undefined` throws; in particular, an `HTMLFormElement` argument is not
-supported in this environment.
+This API is implemented as per the standard, you can find documentation on [MDN](https://developer.mozilla.org/en-US/docs/Web/API/FormData).
 
-### `formData.append(name, value[, filename])`
+If any parameters are passed to the FormData constructor other than `undefined`, an error will be thrown. Other parameters are ignored.
 
-<!-- YAML
-added: v1.0.0
--->
+## Response
 
-* `name` {string} The name of the field.
-* `value` {string|Blob} The value of the field.
-* `filename` {string} The filename reported to the server when `value` is a
-  {Blob}. (optional)
+This API is implemented as per the standard, you can find documentation on [MDN](https://developer.mozilla.org/en-US/docs/Web/API/Response)
 
-Appends a new value to an existing key, or adds the key if it does not exist.
-Unlike [`formData.set()`](#formdatasetname-value-filename), `append()` keeps
-any existing values for `name`.
+## Request
 
-### `formData.delete(name)`
+This API is implemented as per the standard, you can find documentation on [MDN](https://developer.mozilla.org/en-US/docs/Web/API/Request)
 
-<!-- YAML
-added: v1.0.0
--->
+## Header
 
-* `name` {string} The name of the field to remove.
+This API is implemented as per the standard, you can find documentation on [MDN](https://developer.mozilla.org/en-US/docs/Web/API/Headers)
 
-Deletes all values associated with `name`.
+# Body Mixins
 
-### `formData.get(name)`
+`Response` and `Request` body inherit body mixin methods. These methods include:
 
-<!-- YAML
-added: v1.0.0
--->
+- [`.arrayBuffer()`](https://fetch.spec.whatwg.org/#dom-body-arraybuffer)
+- [`.blob()`](https://fetch.spec.whatwg.org/#dom-body-blob)
+- [`.bytes()`](https://fetch.spec.whatwg.org/#dom-body-bytes)
+- [`.formData()`](https://fetch.spec.whatwg.org/#dom-body-formdata)
+- [`.json()`](https://fetch.spec.whatwg.org/#dom-body-json)
+- [`.text()`](https://fetch.spec.whatwg.org/#dom-body-text)
 
-* `name` {string} The name of the field to read.
-* Returns: {string|File|null} The first value associated with `name`, or
-  `null` if there is none.
+There is an ongoing discussion regarding `.formData()` and its usefulness and performance in server environments. It is recommended to use a dedicated library for parsing `multipart/form-data` bodies, such as [Busboy](https://www.npmjs.com/package/busboy) or [@fastify/busboy](https://www.npmjs.com/package/@fastify/busboy).
 
-### `formData.getAll(name)`
-
-<!-- YAML
-added: v1.0.0
--->
-
-* `name` {string} The name of the field to read.
-* Returns: {Array} All values associated with `name`, as an array of
-  {string} and {File} entries.
-
-### `formData.has(name)`
-
-<!-- YAML
-added: v1.0.0
--->
-
-* `name` {string} The name of the field to look up.
-* Returns: {boolean} `true` if at least one value is associated with `name`.
-
-### `formData.set(name, value[, filename])`
-
-<!-- YAML
-added: v1.0.0
--->
-
-* `name` {string} The name of the field.
-* `value` {string|Blob} The value of the field.
-* `filename` {string} The filename reported to the server when `value` is a
-  {Blob}. (optional)
-
-Sets a new value for an existing key, or adds the key if it does not exist,
-replacing any values previously associated with `name`.
-
-## Class: `Response`
-
-<!-- YAML
-added: v4.4.0
--->
-
-* Extends: {BodyMixin}
-
-Represents the response to a request. Instances are typically obtained by
-awaiting `fetch()`, but can also be constructed directly. The implementation
-follows the [WHATWG Fetch Standard][]; see the
-[MDN `Response` documentation][]. `Response` inherits the body-reading methods
-described in [Body mixin](#body-mixin).
-
-### `new Response([body[, init]])`
-
-<!-- YAML
-added: v4.4.0
--->
-
-* `body` {string|Buffer|Uint8Array|Blob|FormData|URLSearchParams|ReadableStream|null}
-  The response body. **Default:** `null`.
-* `init` {ResponseInit} (optional)
-  * `status` {number} The response status code. **Default:** `200`.
-  * `statusText` {string} The response status message. **Default:** `''`.
-  * `headers` {Headers|Object|Array} The response headers.
-
-Creates a new `Response`.
-
-### Static method: `Response.error()`
-
-<!-- YAML
-added: v1.0.0
--->
-
-* Returns: {Response} A network-error response.
-
-Returns a new `Response` representing a network error, with its
-[`type`](#responsetype) set to `'error'`.
-
-### Static method: `Response.json(data[, init])`
-
-<!-- YAML
-added: v1.0.0
--->
-
-* `data` {any} The value to serialize as JSON.
-* `init` {ResponseInit} (optional)
-  * `status` {number} The response status code. **Default:** `200`.
-  * `statusText` {string} The response status message. **Default:** `''`.
-  * `headers` {Headers|Object|Array} The response headers.
-* Returns: {Response} A response whose body is the JSON serialization of
-  `data` and whose `Content-Type` is `application/json`.
-
-```mjs
-import { Response } from 'undici'
-
-const response = Response.json({ ok: true }, { status: 201 })
-```
-
-### Static method: `Response.redirect(url[, status])`
-
-<!-- YAML
-added: v1.0.0
--->
-
-* `url` {string|URL} The URL to redirect to.
-* `status` {number} The redirect status code. One of `301`, `302`, `303`,
-  `307`, or `308`. **Default:** `302`.
-* Returns: {Response} A redirect response with the `Location` header set to
-  `url`.
-
-### `response.clone()`
-
-<!-- YAML
-added: v1.0.0
--->
-
-* Returns: {Response} A copy of the response.
-
-Creates a clone of the response. Throws a `TypeError` if the body has already
-been read or is locked.
-
-### `response.type`
-
-<!-- YAML
-added: v1.0.0
--->
-
-* Type: {string} The response type. One of `'basic'`, `'cors'`, `'default'`,
-  `'error'`, `'opaque'`, or `'opaqueredirect'`.
-
-### `response.url`
-
-<!-- YAML
-added: v1.0.0
--->
-
-* Type: {string} The final URL of the response after any redirects, or the
-  empty string if not available.
-
-### `response.redirected`
-
-<!-- YAML
-added: v1.0.0
--->
-
-* Type: {boolean} `true` if the response is the result of one or more
-  redirects.
-
-### `response.status`
-
-<!-- YAML
-added: v1.0.0
--->
-
-* Type: {number} The HTTP status code of the response.
-
-### `response.ok`
-
-<!-- YAML
-added: v1.0.0
--->
-
-* Type: {boolean} `true` when [`status`](#responsestatus) is in the range
-  `200`–`299`.
-
-### `response.statusText`
-
-<!-- YAML
-added: v1.0.0
--->
-
-* Type: {string} The status message corresponding to the status code.
-
-### `response.headers`
-
-<!-- YAML
-added: v1.0.0
--->
-
-* Type: {Headers} The {Headers} object associated with the response.
-
-## Class: `Request`
-
-<!-- YAML
-added: v1.0.0
--->
-
-* Extends: {BodyMixin}
-
-Represents a resource request. Instances can be passed to `fetch()` in place
-of a URL string. The implementation follows the [WHATWG Fetch Standard][]; see
-the [MDN `Request` documentation][]. `Request` inherits the body-reading
-methods described in [Body mixin](#body-mixin).
-
-### `new Request(input[, init])`
-
-<!-- YAML
-added: v1.0.0
--->
-
-* `input` {string|URL|Request} The resource to request, as a URL string,
-  {URL}, or another {Request} to copy.
-* `init` {RequestInit} (optional) An options object with the same fields as
-  the `init` argument of [`fetch()`](#fetchinput-init).
-* Returns: {Request}
-
-Creates a new `Request`.
-
-### `request.clone()`
-
-<!-- YAML
-added: v1.0.0
--->
-
-* Returns: {Request} A copy of the request.
-
-Creates a clone of the request. Throws a `TypeError` if the body has already
-been read or is locked.
-
-### `request.method`
-
-<!-- YAML
-added: v1.0.0
--->
-
-* Type: {string} The request method, for example `'GET'`.
-
-### `request.url`
-
-<!-- YAML
-added: v1.0.0
--->
-
-* Type: {string} The serialized URL of the request.
-
-### `request.headers`
-
-<!-- YAML
-added: v1.0.0
--->
-
-* Type: {Headers} The {Headers} object associated with the request.
-
-### `request.destination`
-
-<!-- YAML
-added: v1.0.0
--->
-
-* Type: {string} The request destination, indicating the type of content being
-  requested, for example `''`, `'image'`, or `'script'`.
-
-### `request.referrer`
-
-<!-- YAML
-added: v1.0.0
--->
-
-* Type: {string} The referrer of the request. May be `'about:client'` or a URL
-  string.
-
-### `request.referrerPolicy`
-
-<!-- YAML
-added: v1.0.0
--->
-
-* Type: {string} The referrer policy of the request.
-
-### `request.mode`
-
-<!-- YAML
-added: v1.0.0
--->
-
-* Type: {string} The mode of the request. One of `'cors'`, `'navigate'`,
-  `'no-cors'`, or `'same-origin'`.
-
-### `request.credentials`
-
-<!-- YAML
-added: v1.0.0
--->
-
-* Type: {string} The credentials mode of the request. One of `'omit'`,
-  `'include'`, or `'same-origin'`.
-
-### `request.cache`
-
-<!-- YAML
-added: v1.0.0
--->
-
-* Type: {string} The cache mode of the request.
-
-### `request.redirect`
-
-<!-- YAML
-added: v1.0.0
--->
-
-* Type: {string} The redirect mode of the request. One of `'error'`,
-  `'follow'`, or `'manual'`.
-
-### `request.integrity`
-
-<!-- YAML
-added: v1.0.0
--->
-
-* Type: {string} The subresource integrity metadata of the request.
-
-### `request.keepalive`
-
-<!-- YAML
-added: v1.0.0
--->
-
-* Type: {boolean} Whether the request may outlive the environment that created
-  it.
-
-### `request.isReloadNavigation`
-
-<!-- YAML
-added: v1.0.0
--->
-
-* Type: {boolean} `true` if the request is a reload navigation.
-
-### `request.isHistoryNavigation`
-
-<!-- YAML
-added: v1.0.0
--->
-
-* Type: {boolean} `true` if the request is a history navigation.
-
-### `request.signal`
-
-<!-- YAML
-added: v1.0.0
--->
-
-* Type: {AbortSignal} The {AbortSignal} associated with the request.
-
-### `request.duplex`
-
-<!-- YAML
-added: v1.0.0
--->
-
-* Type: {string} The duplex mode of the request. Always `'half'`.
-
-## Class: `Headers`
-
-<!-- YAML
-added: v4.4.0
--->
-
-Represents the header list of a request or response and provides methods to
-read and modify it. The implementation follows the [WHATWG Fetch Standard][];
-see the [MDN `Headers` documentation][]. `Headers` is iterable, yielding
-`[name, value]` pairs sorted by name.
-
-### `new Headers([init])`
-
-<!-- YAML
-added: v4.4.0
--->
-
-* `init` {Headers|Object|Array} (optional) Initial headers, as a {Headers}
-  instance, a plain object of name/value pairs, or an array of `[name, value]`
-  pairs.
-
-Creates a new `Headers` object.
-
-### `headers.append(name, value)`
-
-<!-- YAML
-added: v1.0.0
--->
-
-* `name` {string} The name of the header.
-* `value` {string} The value of the header.
-
-Appends a value to a header, or adds the header if it does not exist. Existing
-values for `name` are preserved.
-
-### `headers.delete(name)`
-
-<!-- YAML
-added: v1.0.0
--->
-
-* `name` {string} The name of the header to remove.
-
-Removes the header named `name`.
-
-### `headers.get(name)`
-
-<!-- YAML
-added: v1.0.0
--->
-
-* `name` {string} The name of the header to read.
-* Returns: {string|null} The combined values of the header, or `null` if it is
-  not present.
-
-### `headers.has(name)`
-
-<!-- YAML
-added: v1.0.0
--->
-
-* `name` {string} The name of the header to look up.
-* Returns: {boolean} `true` if the header is present.
-
-### `headers.set(name, value)`
-
-<!-- YAML
-added: v1.0.0
--->
-
-* `name` {string} The name of the header.
-* `value` {string} The value of the header.
-
-Sets a header to a single value, replacing any existing values for `name`.
-
-### `headers.getSetCookie()`
-
-<!-- YAML
-added: v1.0.0
--->
-
-* Returns: {string[]} An array of the values of all `Set-Cookie` headers.
-
-Returns each `Set-Cookie` header as a separate string, without combining them.
-
-## Body mixin
-
-`Request` and `Response` both extend {BodyMixin}, which provides methods and
-properties for reading a body. Each consuming method reads the body once; after
-the body has been consumed, [`bodyUsed`](#bodybodyused) becomes `true` and
-calling another consuming method throws a `TypeError`.
-
-> [!WARNING]
-> The `arrayBuffer()`, `blob()`, `bytes()`, `formData()`, `json()`, and `text()`
-> methods buffer the entire body in memory before returning. Where applicable,
-> they also decode or parse the payload and retain that representation in
-> memory. Calling these methods therefore means trusting that the body is small
-> enough to fit in the available memory. Do not use them for bodies received
-> from untrusted or user-controlled sources. Instead, process `body.body` or
-> `body.textStream()` incrementally and enforce an application-specific size
-> limit.
-
-### `body.arrayBuffer()`
-
-<!-- YAML
-added: v1.0.0
--->
-
-* Returns: {Promise} Fulfills with an {ArrayBuffer} containing the body bytes.
-
-### `body.blob()`
-
-<!-- YAML
-added: v1.0.0
--->
-
-* Returns: {Promise} Fulfills with a {Blob} containing the body.
-
-### `body.bytes()`
-
-<!-- YAML
-added: v1.0.0
--->
-
-* Returns: {Promise} Fulfills with a {Uint8Array} containing the body bytes.
-
-### `body.formData()`
-
-<!-- YAML
-added: v1.0.0
--->
-
-> Stability: 0 - Deprecated
-
-* Returns: {Promise} Fulfills with a {FormData} parsed from the body.
-
-Buffers and parses the entire body as `multipart/form-data` or
-`application/x-www-form-urlencoded`. Because multipart parsing has inherent
-security risks and the whole body is buffered, this method must only be called
-on responses from trusted servers.
-
-For responses from untrusted or user-controlled servers, use a dedicated
-streaming parser such as [@fastify/busboy][] and apply application-specific
-limits:
+These libraries can be interfaced with fetch with the following example code:
 
 ```mjs
 import { Busboy } from '@fastify/busboy'
@@ -655,67 +43,10 @@ import { Readable } from 'node:stream'
 
 const response = await fetch('...')
 const busboy = new Busboy({
-  headers: { 'content-type': response.headers.get('content-type') },
+  headers: {
+    'content-type': response.headers.get('content-type')
+  }
 })
 
-// Handle the events emitted by `busboy`.
-
 Readable.fromWeb(response.body).pipe(busboy)
 ```
-
-### `body.json()`
-
-<!-- YAML
-added: v1.0.0
--->
-
-* Returns: {Promise} Fulfills with the result of parsing the body as JSON.
-
-### `body.text()`
-
-<!-- YAML
-added: v1.0.0
--->
-
-* Returns: {Promise} Fulfills with a {string} containing the body decoded as
-  UTF-8.
-
-### `body.textStream()`
-
-<!-- YAML
-added: v1.0.0
--->
-
-> Stability: 1 - Experimental
-
-* Returns: {ReadableStream} A {ReadableStream} of {string} chunks produced by
-  decoding the body as UTF-8.
-
-An undici-specific extension that exposes the body as a stream of decoded text
-chunks rather than buffering it. It is not part of the [WHATWG Fetch
-Standard][].
-
-### `body.body`
-
-<!-- YAML
-added: v1.0.0
--->
-
-* Type: {ReadableStream|null} The body as a {ReadableStream}, or `null` if the
-  message has no body.
-
-### `body.bodyUsed`
-
-<!-- YAML
-added: v1.0.0
--->
-
-* Type: {boolean} `true` once the body has been read.
-
-[@fastify/busboy]: https://www.npmjs.com/package/@fastify/busboy
-[MDN Fetch documentation]: https://developer.mozilla.org/en-US/docs/Web/API/fetch
-[MDN `FormData` documentation]: https://developer.mozilla.org/en-US/docs/Web/API/FormData
-[MDN `Headers` documentation]: https://developer.mozilla.org/en-US/docs/Web/API/Headers
-[MDN `Request` documentation]: https://developer.mozilla.org/en-US/docs/Web/API/Request
-[MDN `Response` documentation]: https://developer.mozilla.org/en-US/docs/Web/API/Response
-[WHATWG Fetch Standard]: https://fetch.spec.whatwg.org/