SnowLuma/.pnpm-store/v11/files/31/c9777904cf4707c0890f43fceb3c38326de3b3b6a2974cddf7000dabda1527c54d0870603c05f8a2d4b20dfd0ee15c09f5a49acdbe65eff20f62fa44353867

# Fetch

<!--introduced_in=v1.0.0-->
<!--type=module-->
<!-- source_link=lib/web/fetch/index.js -->

> Stability: 2 - Stable

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.

```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.

### `formData.append(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)

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`.

### `formData.delete(name)`

<!-- YAML
added: v1.0.0
-->

* `name` {string} The name of the field to remove.

Deletes all values associated with `name`.

### `formData.get(name)`

<!-- YAML
added: v1.0.0
-->

* `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.

### `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:

```mjs
import { Busboy } from '@fastify/busboy'
import { Readable } from 'node:stream'

const response = await fetch('...')
const busboy = new Busboy({
  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/