Fetch

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.

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])

• 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 to detect failures.

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.

import { fetch, Agent } from 'undici'

const response = await fetch('https://example.com', {
  dispatcher: new Agent({ connect: { rejectUnauthorized: false } }),
})

Class: FormData

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()

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])

• 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(), append() keeps any existing values for name.

formData.delete(name)

• name {string} The name of the field to remove.

Deletes all values associated with name.

formData.get(name)

• 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)

• 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)

• 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])

• 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

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

new Response([body[, init]])

• 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()

• Returns: {Response} A network-error response.

Returns a new Response representing a network error, with its type set to 'error'.

Static method: Response.json(data[, init])

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

import { Response } from 'undici'

const response = Response.json({ ok: true }, { status: 201 })

Static method: Response.redirect(url[, status])

• 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()

• 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

• Type: {string} The response type. One of 'basic', 'cors', 'default', 'error', 'opaque', or 'opaqueredirect'.

response.url

• Type: {string} The final URL of the response after any redirects, or the empty string if not available.

response.redirected

• Type: {boolean} true if the response is the result of one or more redirects.

response.status

• Type: {number} The HTTP status code of the response.

response.ok

• Type: {boolean} true when status is in the range 200–299.

response.statusText

• Type: {string} The status message corresponding to the status code.

response.headers

• Type: {Headers} The {Headers} object associated with the response.

Class: Request

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

new Request(input[, init])

• 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().
• Returns: {Request}

Creates a new Request.

request.clone()

• 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

• Type: {string} The request method, for example 'GET'.

request.url

• Type: {string} The serialized URL of the request.

request.headers

• Type: {Headers} The {Headers} object associated with the request.

request.destination

• Type: {string} The request destination, indicating the type of content being requested, for example '', 'image', or 'script'.

request.referrer

• Type: {string} The referrer of the request. May be 'about:client' or a URL string.

request.referrerPolicy

• Type: {string} The referrer policy of the request.

request.mode

• Type: {string} The mode of the request. One of 'cors', 'navigate', 'no-cors', or 'same-origin'.

request.credentials

• Type: {string} The credentials mode of the request. One of 'omit', 'include', or 'same-origin'.

request.cache

• Type: {string} The cache mode of the request.

request.redirect

• Type: {string} The redirect mode of the request. One of 'error', 'follow', or 'manual'.

request.integrity

• Type: {string} The subresource integrity metadata of the request.

request.keepalive

• Type: {boolean} Whether the request may outlive the environment that created it.

request.isReloadNavigation

• Type: {boolean} true if the request is a reload navigation.

request.isHistoryNavigation

• Type: {boolean} true if the request is a history navigation.

request.signal

• Type: {AbortSignal} The {AbortSignal} associated with the request.

request.duplex

• Type: {string} The duplex mode of the request. Always 'half'.

Class: Headers

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])

• 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)

• 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)

• name {string} The name of the header to remove.

Removes the header named name.

headers.get(name)

• 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)

• name {string} The name of the header to look up.
• Returns: {boolean} true if the header is present.

headers.set(name, value)

• 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()

• 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 becomes true and calling another consuming method throws a TypeError.

body.arrayBuffer()

• Returns: {Promise} Fulfills with an {ArrayBuffer} containing the body bytes.

body.blob()

• Returns: {Promise} Fulfills with a {Blob} containing the body.

body.bytes()

• Returns: {Promise} Fulfills with a {Uint8Array} containing the body bytes.

body.formData()

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:

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()

• Returns: {Promise} Fulfills with the result of parsing the body as JSON.

body.text()

• Returns: {Promise} Fulfills with a {string} containing the body decoded as UTF-8.

body.textStream()

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

• Type: {ReadableStream|null} The body as a {ReadableStream}, or null if the message has no body.

body.bodyUsed

• Type: {boolean} true once the body has been read.