{ "type": "module", "source": "doc/api/index.md", "miscs": [ { "textRaw": "undici", "name": "undici", "type": "misc", "desc": "

\"Node \"neostandard \"npm \"codecov\"

\n

An HTTP/1.1 client, written from scratch for Node.js.

\n
\n

Undici means eleven in Italian. 1.1 -> 11 -> Eleven -> Undici.\nIt is also a Stranger Things reference.

\n
", "miscs": [ { "textRaw": "How to get involved", "name": "how_to_get_involved", "type": "misc", "desc": "

Have a question about using Undici? Open a Q&A Discussion or join our official OpenJS Slack channel.

\n

Looking to contribute? Start by reading the contributing guide

", "displayName": "How to get involved" }, { "textRaw": "Install", "name": "install", "type": "misc", "desc": "
npm i undici\n
", "displayName": "Install" }, { "textRaw": "Benchmarks", "name": "benchmarks", "type": "misc", "desc": "

The benchmark is a simple getting data example using\n50 TCP connections with a pipelining depth of 10 running on Node 24.14.1.

", "modules": [ { "textRaw": "HTTP/1.1", "name": "http/1.1", "type": "module", "desc": "
┌────────────────────────┬─────────┬────────────────────┬────────────┬─────────────────────────┐\n│  Tests                 │ Samples │ Result             │ Tolerance  │ Difference with slowest │\n├────────────────────────┼─────────┼────────────────────┼────────────┼─────────────────────────┤\n│  'node-fetch'          │ 50      │ '4711.86 req/sec'  │ '± 2.92 %' │ '-'                     │\n│  'undici - fetch'      │ 75      │ '5438.50 req/sec'  │ '± 2.97 %' │ '+ 15.42 %'             │\n│  'axios'               │ 45      │ '5448.08 req/sec'  │ '± 2.98 %' │ '+ 15.62 %'             │\n│  'request'             │ 65      │ '5809.63 req/sec'  │ '± 2.90 %' │ '+ 23.30 %'             │\n│  'http - no keepalive' │ 35      │ '5910.77 req/sec'  │ '± 2.87 %' │ '+ 25.44 %'             │\n│  'got'                 │ 50      │ '6047.80 req/sec'  │ '± 2.91 %' │ '+ 28.35 %'             │\n│  'superagent'          │ 60      │ '7534.53 req/sec'  │ '± 2.97 %' │ '+ 59.91 %'             │\n│  'http - keepalive'    │ 75      │ '9343.41 req/sec'  │ '± 2.90 %' │ '+ 98.30 %'             │\n│  'undici - pipeline'   │ 65      │ '13470.70 req/sec' │ '± 2.93 %' │ '+ 185.89 %'            │\n│  'undici - request'    │ 80      │ '16850.87 req/sec' │ '± 2.93 %' │ '+ 257.63 %'            │\n│  'undici - stream'     │ 101     │ '18488.56 req/sec' │ '± 3.81 %' │ '+ 292.38 %'            │\n│  'undici - dispatch'   │ 101     │ '20786.44 req/sec' │ '± 3.08 %' │ '+ 341.15 %'            │\n└────────────────────────┴─────────┴────────────────────┴────────────┴─────────────────────────┘\n
", "displayName": "HTTP/1.1" }, { "textRaw": "HTTP/1.1 over HTTPS", "name": "http/1.1_over_https", "type": "module", "desc": "

Using benchmark-https.js against an h1-over-TLS server (50 connections, pipelining depth 10, Node 24.14.1).

\n
┌────────────────────────┬─────────┬───────────────────┬────────────┬─────────────────────────┐\n│  Tests                 │ Samples │ Result            │ Tolerance  │ Difference with slowest │\n├────────────────────────┼─────────┼───────────────────┼────────────┼─────────────────────────┤\n│  'https - no keepalive'│ 10      │ '1358.40 req/sec' │ '± 1.99 %' │ '-'                     │\n│  'undici - fetch'      │ 30      │ '3721.76 req/sec' │ '± 2.97 %' │ '+ 173.98 %'            │\n│  'https - keepalive'   │ 35      │ '5633.91 req/sec' │ '± 2.84 %' │ '+ 314.75 %'            │\n│  'undici - pipeline'   │ 15      │ '6254.05 req/sec' │ '± 2.80 %' │ '+ 360.40 %'            │\n│  'undici - request'    │ 25      │ '6669.80 req/sec' │ '± 2.73 %' │ '+ 391.01 %'            │\n│  'undici - stream'     │ 25      │ '7019.04 req/sec' │ '± 2.77 %' │ '+ 416.71 %'            │\n│  'undici - dispatch'   │ 20      │ '7361.85 req/sec' │ '± 2.90 %' │ '+ 441.95 %'            │\n└────────────────────────┴─────────┴───────────────────┴────────────┴─────────────────────────┘\n
", "displayName": "HTTP/1.1 over HTTPS" }, { "textRaw": "HTTP/2", "name": "http/2", "type": "module", "desc": "

Using benchmark-http2.js against an h2 server (50 connections, pipelining depth 10, Node 24.14.1).

\n
┌────────────────────────┬─────────┬───────────────────┬────────────┬─────────────────────────┐\n│  Tests                 │ Samples │ Result            │ Tolerance  │ Difference with slowest │\n├────────────────────────┼─────────┼───────────────────┼────────────┼─────────────────────────┤\n│  'undici - fetch'      │ 45      │ '3499.03 req/sec' │ '± 2.93 %' │ '-'                     │\n│  'native - http2'      │ 25      │ '4904.58 req/sec' │ '± 2.81 %' │ '+ 40.17 %'             │\n│  'undici - pipeline'   │ 60      │ '5836.82 req/sec' │ '± 2.99 %' │ '+ 66.81 %'             │\n│  'undici - request'    │ 65      │ '6831.25 req/sec' │ '± 2.83 %' │ '+ 95.23 %'             │\n│  'undici - stream'     │ 55      │ '6874.30 req/sec' │ '± 2.91 %' │ '+ 96.46 %'             │\n│  'undici - dispatch'   │ 55      │ '7791.23 req/sec' │ '± 2.96 %' │ '+ 122.67 %'            │\n└────────────────────────┴─────────┴───────────────────┴────────────┴─────────────────────────┘\n
", "displayName": "HTTP/2" } ], "displayName": "Benchmarks" }, { "textRaw": "Undici vs. Fetch", "name": "undici_vs._fetch", "type": "misc", "modules": [ { "textRaw": "Overview", "name": "overview", "type": "module", "desc": "

Node.js includes a built-in fetch() implementation powered by undici starting from Node.js v18. However, there are important differences between using the built-in fetch and installing undici as a separate module.

", "displayName": "Overview" }, { "textRaw": "Built-in Fetch (Node.js v18+)", "name": "built-in_fetch_(node.js_v18+)", "type": "module", "desc": "

Node.js's built-in fetch is powered by a bundled version of undici:

\n
// Available globally in Node.js v18+\nconst response = await fetch('https://api.example.com/data');\nconst data = await response.json();\n\n// Check the bundled undici version\nconsole.log(process.versions.undici); // e.g., \"5.28.4\"\n
\n

Pros:

\n\n

Cons:

\n", "displayName": "Built-in Fetch (Node.js v18+)" }, { "textRaw": "Undici Module", "name": "undici_module", "type": "module", "desc": "

Installing undici as a separate module gives you access to the latest features and APIs:

\n
npm install undici\n
\n
import { request, fetch, Agent, setGlobalDispatcher } from 'undici';\n\n// Use undici.request for maximum performance\nconst { statusCode, headers, body } = await request('https://api.example.com/data');\nconst data = await body.json();\n\n// Or use undici.fetch with custom configuration\nconst agent = new Agent({ keepAliveTimeout: 10000 });\nsetGlobalDispatcher(agent);\nconst response = await fetch('https://api.example.com/data');\n
\n

Pros:

\n\n

Cons:

\n", "displayName": "Undici Module" }, { "textRaw": "When to Use Each", "name": "when_to_use_each", "type": "module", "modules": [ { "textRaw": "Use Built-in Fetch When:", "name": "use_built-in_fetch_when:", "type": "module", "desc": "", "displayName": "Use Built-in Fetch When:" }, { "textRaw": "Use Undici Module When:", "name": "use_undici_module_when:", "type": "module", "desc": "", "displayName": "Use Undici Module When:" } ], "displayName": "When to Use Each" }, { "textRaw": "Performance Comparison", "name": "performance_comparison", "type": "module", "desc": "

Based on benchmarks, here's the typical performance hierarchy:

\n
    \n
  1. undici.request() - Fastest, most efficient
    2. \n
  2. undici.fetch() - Good performance, standard compliance
    3. \n
  3. Node.js http/https - Baseline performance
    4. \n
", "displayName": "Performance Comparison" }, { "textRaw": "Migration Guide", "name": "migration_guide", "type": "module", "desc": "

If you're currently using built-in fetch and want to migrate to undici:

\n
// Before: Built-in fetch\nconst response = await fetch('https://api.example.com/data');\n\n// After: Undici fetch (drop-in replacement)\nimport { fetch } from 'undici';\nconst response = await fetch('https://api.example.com/data');\n\n// Or: Undici request (better performance)\nimport { request } from 'undici';\nconst { statusCode, body } = await request('https://api.example.com/data');\nconst data = await body.json();\n
", "displayName": "Migration Guide" }, { "textRaw": "Keep `fetch` and `FormData` together", "name": "keep_`fetch`_and_`formdata`_together", "type": "module", "desc": "

When you send a FormData body, keep fetch and FormData from the same\nimplementation.

\n

Use one of these patterns:

\n
// Built-in globals\nconst body = new FormData()\nbody.set('name', 'some')\nawait fetch('https://example.com', {\n  method: 'POST',\n  body\n})\n
\n
// undici module imports\nimport { fetch, FormData } from 'undici'\n\nconst body = new FormData()\nbody.set('name', 'some')\nawait fetch('https://example.com', {\n  method: 'POST',\n  body\n})\n
\n

If you want the installed undici package to provide the globals, call\ninstall() first:

\n
import { install } from 'undici'\n\ninstall()\n\nconst body = new FormData()\nbody.set('name', 'some')\nawait fetch('https://example.com', {\n  method: 'POST',\n  body\n})\n
\n

install() replaces the global fetch, Headers, Response, Request, and\nFormData implementations with undici's versions, so they all match. It also\ninstalls undici's WebSocket, CloseEvent, ErrorEvent, MessageEvent, and\nEventSource globals.

\n

Avoid mixing a global FormData with undici.fetch(), or undici.FormData\nwith the built-in global fetch().

", "displayName": "Keep `fetch` and `FormData` together" }, { "textRaw": "Version Compatibility", "name": "version_compatibility", "type": "module", "desc": "

You can check which version of undici is bundled with your Node.js version:

\n
console.log(process.versions.undici);\n
\n

Installing undici as a module allows you to use a newer version than what's bundled with Node.js, giving you access to the latest features and performance improvements.

", "displayName": "Version Compatibility" } ], "displayName": "Undici vs. Fetch" }, { "textRaw": "Quick Start", "name": "quick_start", "type": "misc", "modules": [ { "textRaw": "Basic Request", "name": "basic_request", "type": "module", "desc": "
import { request } from 'undici'\n\nconst {\n  statusCode,\n  headers,\n  trailers,\n  body\n} = await request('http://localhost:3000/foo')\n\nconsole.log('response received', statusCode)\nconsole.log('headers', headers)\n\nfor await (const data of body) { console.log('data', data) }\n\nconsole.log('trailers', trailers)\n
", "displayName": "Basic Request" }, { "textRaw": "Using Cache Interceptor", "name": "using_cache_interceptor", "type": "module", "desc": "

Undici provides a powerful HTTP caching interceptor that follows HTTP caching best practices. Here's how to use it:

\n
import { fetch, Agent, interceptors, cacheStores } from 'undici';\n\n// Create a client with cache interceptor\nconst client = new Agent().compose(interceptors.cache({\n  // Optional: Configure cache store (defaults to MemoryCacheStore)\n  store: new cacheStores.MemoryCacheStore({\n    maxSize: 100 * 1024 * 1024, // 100MB\n    maxCount: 1000,\n    maxEntrySize: 5 * 1024 * 1024 // 5MB\n  }),\n  \n  // Optional: Specify which HTTP methods to cache (default: ['GET', 'HEAD'])\n  methods: ['GET', 'HEAD']\n}));\n\n// Set the global dispatcher to use our caching client\nsetGlobalDispatcher(client);\n\n// Now all fetch requests will use the cache\nasync function getData() {\n  const response = await fetch('https://api.example.com/data');\n  // The server should set appropriate Cache-Control headers in the response\n  // which the cache will respect based on the cache policy\n  return response.json();\n}\n\n// First request - fetches from origin\nconst data1 = await getData();\n\n// Second request - served from cache if within max-age\nconst data2 = await getData();\n
", "modules": [ { "textRaw": "Key Features:", "name": "key_features:", "type": "module", "desc": "", "displayName": "Key Features:" } ], "displayName": "Using Cache Interceptor" } ], "displayName": "Quick Start" }, { "textRaw": "Global Installation", "name": "global_installation", "type": "misc", "desc": "

Undici provides an install() function to add fetch-related and other web API classes to globalThis, making them available globally:

\n
import { install } from 'undici'\n\n// Install undici's global web APIs\ninstall()\n\n// Now you can use fetch classes globally without importing\nconst response = await fetch('https://api.example.com/data')\nconst data = await response.json()\n\n// All classes are available globally:\nconst headers = new Headers([['content-type', 'application/json']])\nconst request = new Request('https://example.com')\nconst formData = new FormData()\nconst ws = new WebSocket('wss://example.com')\nconst eventSource = new EventSource('https://example.com/events')\n
\n

The install() function adds the following classes to globalThis:

\n\n

When you call install(), these globals come from the same undici\nimplementation. For example, global fetch and global FormData will both be\nundici's versions, and WebSocket and EventSource will also come from\nundici, which is the recommended setup if you want to use undici through\nglobals.

\n

This is useful for:

\n", "displayName": "Global Installation" }, { "textRaw": "Body Mixins", "name": "body_mixins", "type": "misc", "desc": "

The body mixins are the most common way to format the request/response body. Mixins include:

\n\n
\n

[!NOTE]\nThe body returned from undici.request does not implement .formData().

\n
\n
\n

[!WARNING]\nCalling body.formData() on a fetch response causes undici to buffer and parse the entire body. Since this is dictated by the spec, body.formData() must only be called on responses from trusted servers.

\n
\n

Example usage:

\n
import { request } from 'undici'\n\nconst {\n  statusCode,\n  headers,\n  trailers,\n  body\n} = await request('http://localhost:3000/foo')\n\nconsole.log('response received', statusCode)\nconsole.log('headers', headers)\nconsole.log('data', await body.json())\nconsole.log('trailers', trailers)\n
\n

Note: Once a mixin has been called then the body cannot be reused, thus calling additional mixins on .body, e.g. .body.json(); .body.text() will result in an error TypeError: unusable being thrown and returned through the Promise rejection.

\n

Should you need to access the body in plain-text after using a mixin, the best practice is to use the .text() mixin first and then manually parse the text to the desired format.

\n

For more information about their behavior, please reference the body mixin from the Fetch Standard.

", "displayName": "Body Mixins" }, { "textRaw": "Common API Methods", "name": "common_api_methods", "type": "misc", "desc": "

This section documents our most commonly used API methods. Additional APIs are documented in their own files within the docs folder and are accessible via the navigation list on the left side of the docs site.

", "methods": [ { "textRaw": "`undici.request([url, options])`", "name": "request", "type": "method", "signatures": [ { "params": [ { "textRaw": "`url` {string|URL|UrlObject}", "name": "url", "type": "string|URL|UrlObject", "optional": true }, { "textRaw": "`options` {RequestOptions} See `RequestOptions`.", "name": "options", "type": "RequestOptions", "desc": "See `RequestOptions`.", "options": [ { "textRaw": "`dispatcher` {Dispatcher} **Default:** getGlobalDispatcher.", "name": "dispatcher", "type": "Dispatcher", "default": "getGlobalDispatcher" }, { "textRaw": "`method` {string} **Default:** `PUT` if `options.body`, otherwise `GET`.", "name": "method", "type": "string", "default": "`PUT` if `options.body`, otherwise `GET`" } ], "optional": true } ], "return": { "textRaw": "Returns: {Promise} A promise with the result of the `Dispatcher.request` method.", "name": "return", "type": "Promise", "desc": "A promise with the result of the `Dispatcher.request` method." } } ], "desc": "

Calls options.dispatcher.request(options).

\n

See Dispatcher.request for more details, and request examples for examples.

" }, { "textRaw": "`undici.stream([url, options, ]factory)`", "name": "stream", "type": "method", "signatures": [ { "params": [ { "textRaw": "`url` {string|URL|UrlObject}", "name": "url", "type": "string|URL|UrlObject", "optional": true }, { "textRaw": "`options` {StreamOptions} See `StreamOptions`.", "name": "options", "type": "StreamOptions", "desc": "See `StreamOptions`.", "options": [ { "textRaw": "`dispatcher` {Dispatcher} **Default:** getGlobalDispatcher.", "name": "dispatcher", "type": "Dispatcher", "default": "getGlobalDispatcher" }, { "textRaw": "`method` {string} **Default:** `PUT` if `options.body`, otherwise `GET`.", "name": "method", "type": "string", "default": "`PUT` if `options.body`, otherwise `GET`" } ], "optional": true }, { "textRaw": "`factory` {Function} `Dispatcher.stream.factory`.", "name": "factory", "type": "Function", "desc": "`Dispatcher.stream.factory`." } ], "return": { "textRaw": "Returns: {Promise} A promise with the result of the `Dispatcher.stream` method.", "name": "return", "type": "Promise", "desc": "A promise with the result of the `Dispatcher.stream` method." } } ], "desc": "

Calls options.dispatcher.stream(options, factory).

\n

See Dispatcher.stream for more details.

" }, { "textRaw": "`undici.pipeline([url, options, ]handler)`", "name": "pipeline", "type": "method", "signatures": [ { "params": [ { "textRaw": "`url` {string|URL|UrlObject}", "name": "url", "type": "string|URL|UrlObject", "optional": true }, { "textRaw": "`options` {PipelineOptions} See `PipelineOptions`.", "name": "options", "type": "PipelineOptions", "desc": "See `PipelineOptions`.", "options": [ { "textRaw": "`dispatcher` {Dispatcher} **Default:** getGlobalDispatcher.", "name": "dispatcher", "type": "Dispatcher", "default": "getGlobalDispatcher" }, { "textRaw": "`method` {string} **Default:** `PUT` if `options.body`, otherwise `GET`.", "name": "method", "type": "string", "default": "`PUT` if `options.body`, otherwise `GET`" } ], "optional": true }, { "textRaw": "`handler` {Function} `Dispatcher.pipeline.handler`.", "name": "handler", "type": "Function", "desc": "`Dispatcher.pipeline.handler`." } ], "return": { "textRaw": "Returns: {Duplex} A `stream.Duplex`.", "name": "return", "type": "Duplex", "desc": "A `stream.Duplex`." } } ], "desc": "

Calls options.dispatch.pipeline(options, handler).

\n

See Dispatcher.pipeline for more details.

" }, { "textRaw": "`undici.connect([url, options])`", "name": "connect", "type": "method", "signatures": [ { "params": [ { "textRaw": "`url` {string|URL|UrlObject}", "name": "url", "type": "string|URL|UrlObject", "optional": true }, { "textRaw": "`options` {ConnectOptions} See `ConnectOptions`.", "name": "options", "type": "ConnectOptions", "desc": "See `ConnectOptions`.", "options": [ { "textRaw": "`dispatcher` {Dispatcher} **Default:** getGlobalDispatcher.", "name": "dispatcher", "type": "Dispatcher", "default": "getGlobalDispatcher" } ], "optional": true } ], "return": { "textRaw": "Returns: {Promise} A promise with the result of the `Dispatcher.connect` method.", "name": "return", "type": "Promise", "desc": "A promise with the result of the `Dispatcher.connect` method." } } ], "desc": "

Starts two-way communications with the requested resource using HTTP CONNECT.

\n

Calls options.dispatch.connect(options).

\n

See Dispatcher.connect for more details.

" }, { "textRaw": "`undici.fetch(input[, init])`", "name": "fetch", "type": "method", "signatures": [ { "params": [ { "name": "input" }, { "name": "init", "optional": true } ] } ], "desc": "

Implements fetch.

\n\n

Basic usage example:

\n
import { fetch } from 'undici'\n\n\nconst res = await fetch('https://example.com')\nconst json = await res.json()\nconsole.log(json)\n
\n

You can pass an optional dispatcher to fetch as:

\n
import { fetch, Agent } from 'undici'\n\nconst res = await fetch('https://example.com', {\n  // Mocks are also supported\n  dispatcher: new Agent({\n    keepAliveTimeout: 10,\n    keepAliveMaxTimeout: 10\n  })\n})\nconst json = await res.json()\nconsole.log(json)\n
", "properties": [ { "textRaw": "`request.body`", "name": "body", "type": "property", "desc": "

A body can be of the following types:

\n\n

In this implementation of fetch, request.body now accepts Async Iterables. It is not present in the Fetch Standard.

\n
import { fetch } from 'undici'\n\nconst data = {\n  async *[Symbol.asyncIterator]() {\n    yield 'hello'\n    yield 'world'\n  },\n}\n\nawait fetch('https://example.com', { body: data, method: 'POST', duplex: 'half' })\n
\n

FormData besides text data and buffers can also utilize streams via Blob objects:

\n
import { openAsBlob } from 'node:fs'\n\nconst file = await openAsBlob('./big.csv')\nconst body = new FormData()\nbody.set('file', file, 'big.csv')\n\nawait fetch('http://example.com', { method: 'POST', body })\n
" }, { "textRaw": "`request.duplex`", "name": "duplex", "type": "property", "desc": "\n

In this implementation of fetch, request.duplex must be set if request.body is ReadableStream or Async Iterables, however, even though the value must be set to 'half', it is actually a full duplex. For more detail refer to the Fetch Standard.

" }, { "textRaw": "`response.body`", "name": "body", "type": "property", "desc": "

Nodejs has two kinds of streams: web streams, which follow the API of the WHATWG web standard found in browsers, and an older Node-specific streams API. response.body returns a readable web stream. If you would prefer to work with a Node stream you can convert a web stream using .fromWeb().

\n
import { fetch } from 'undici'\nimport { Readable } from 'node:stream'\n\nconst response = await fetch('https://example.com')\nconst readableWebStream = response.body\nconst readableNodeStream = Readable.fromWeb(readableWebStream)\n
" } ] } ], "displayName": "Common API Methods" }, { "textRaw": "Specification Compliance", "name": "specification_compliance", "type": "misc", "desc": "

This section documents parts of the HTTP/1.1 and Fetch Standard that Undici does\nnot support or does not fully implement.

", "modules": [ { "textRaw": "CORS", "name": "cors", "type": "module", "desc": "

Unlike browsers, Undici does not implement CORS (Cross-Origin Resource Sharing) checks by default. This means:

\n\n

This behavior is intentional for server-side environments where CORS restrictions are typically unnecessary. If your application requires CORS-like protections, you will need to implement these checks manually.

", "displayName": "CORS" }, { "textRaw": "Garbage Collection", "name": "garbage_collection", "type": "module", "desc": "\n

The Fetch Standard allows users to skip consuming the response body by relying on\ngarbage collection to release connection resources.

\n

Garbage collection in Node is less aggressive and deterministic\n(due to the lack of clear idle periods that browsers have through the rendering refresh rate)\nwhich means that leaving the release of connection resources to the garbage collector can lead\nto excessive connection usage, reduced performance (due to less connection re-use), and even\nstalls or deadlocks when running out of connections.\nTherefore, it is important to always either consume or cancel the response body anyway.

\n
// Do\nconst { body, headers } = await fetch(url);\nfor await (const chunk of body) {\n  // force consumption of body\n}\n\n// Do not\nconst { headers } = await fetch(url);\n
\n

However, if you want to get only headers, it might be better to use HEAD request method. Usage of this method will obviate the need for consumption or cancelling of the response body. See MDN - HTTP - HTTP request methods - HEAD for more details.

\n
const headers = await fetch(url, { method: 'HEAD' })\n  .then(res => res.headers)\n
\n

Note that consuming the response body is mandatory for request:

\n
// Do\nconst { body, headers } = await request(url);\nawait body.dump(); // force consumption of body\n\n// Do not\nconst { headers } = await request(url);\n
", "displayName": "Garbage Collection" }, { "textRaw": "Forbidden and Safelisted Header Names", "name": "forbidden_and_safelisted_header_names", "type": "module", "desc": "\n

The Fetch Standard requires implementations to exclude certain headers from requests and responses. In browser environments, some headers are forbidden so the user agent remains in full control over them. In Undici, these constraints are removed to give more control to the user.

", "displayName": "Forbidden and Safelisted Header Names" }, { "textRaw": "Content-Encoding", "name": "content-encoding", "type": "module", "desc": "\n

Undici limits the number of Content-Encoding layers in a response to 5 to prevent resource exhaustion attacks. If a server responds with more than 5 content-encodings (e.g., Content-Encoding: gzip, gzip, gzip, gzip, gzip, gzip), the fetch will be rejected with an error. This limit matches the approach taken by curl and urllib3.

", "displayName": "Content-Encoding" }, { "textRaw": "`UrlObject`", "name": "`urlobject`", "type": "module", "desc": "", "modules": [ { "textRaw": "Expect", "name": "expect", "type": "module", "desc": "

Undici does not support the Expect request header field. The request\nbody is always immediately sent and the 100 Continue response will be\nignored.

\n

Refs: https://tools.ietf.org/html/rfc7231#section-5.1.1

", "displayName": "Expect" }, { "textRaw": "Pipelining", "name": "pipelining", "type": "module", "desc": "

Undici will only use pipelining if configured with a pipelining factor\ngreater than 1. Also it is important to pass blocking: false to the\nrequest options to properly pipeline requests.

\n

Undici always assumes that connections are persistent and will immediately\npipeline requests, without checking whether the connection is persistent.\nHence, automatic fallback to HTTP/1.0 or HTTP/1.1 without pipelining is\nnot supported.

\n

Undici will immediately pipeline when retrying requests after a failed\nconnection. However, Undici will not retry the first remaining requests in\nthe prior pipeline and instead error the corresponding callback/promise/stream.

\n

Undici will abort all running requests in the pipeline when any of them are\naborted.

\n", "displayName": "Pipelining" }, { "textRaw": "Manual Redirect", "name": "manual_redirect", "type": "module", "desc": "

Since it is not possible to manually follow an HTTP redirect on the server-side,\nUndici returns the actual response instead of an opaqueredirect filtered one\nwhen invoked with a manual redirect. This aligns fetch() with the other\nimplementations in Deno and Cloudflare Workers.

\n

Refs: https://fetch.spec.whatwg.org/#atomic-http-redirect-handling

", "displayName": "Manual Redirect" } ], "displayName": "`UrlObject`" }, { "textRaw": "Workarounds", "name": "workarounds", "type": "module", "modules": [ { "textRaw": "Network address family autoselection.", "name": "network_address_family_autoselection.", "type": "module", "desc": "

If you experience problem when connecting to a remote server that is resolved by your DNS servers to a IPv6 (AAAA record)\nfirst, there are chances that your local router or ISP might have problem connecting to IPv6 networks. In that case\nundici will throw an error with code UND_ERR_CONNECT_TIMEOUT.

\n

If the target server resolves to both a IPv6 and IPv4 (A records) address and you are using a compatible Node version\n(18.3.0 and above), you can fix the problem by providing the autoSelectFamily option (support by both undici.request\nand undici.Agent) which will enable the family autoselection algorithm when establishing the connection.

", "displayName": "Network address family autoselection." } ], "displayName": "Workarounds" } ], "methods": [ { "textRaw": "`undici.upgrade([url, options])`", "name": "upgrade", "type": "method", "signatures": [ { "params": [ { "textRaw": "`url` {string|URL|UrlObject}", "name": "url", "type": "string|URL|UrlObject", "optional": true }, { "textRaw": "`options` {UpgradeOptions} See `UpgradeOptions`.", "name": "options", "type": "UpgradeOptions", "desc": "See `UpgradeOptions`.", "options": [ { "textRaw": "`dispatcher` {Dispatcher} **Default:** getGlobalDispatcher.", "name": "dispatcher", "type": "Dispatcher", "default": "getGlobalDispatcher" } ], "optional": true } ], "return": { "textRaw": "Returns: {Promise} A promise with the result of the `Dispatcher.upgrade` method.", "name": "return", "type": "Promise", "desc": "A promise with the result of the `Dispatcher.upgrade` method." } } ], "desc": "

Upgrade to a different protocol. See MDN - HTTP - Protocol upgrade mechanism for more details.

\n

Calls options.dispatcher.upgrade(options).

\n

See Dispatcher.upgrade for more details.

" }, { "textRaw": "`undici.setGlobalDispatcher(dispatcher)`", "name": "setGlobalDispatcher", "type": "method", "signatures": [ { "params": [ { "textRaw": "`dispatcher` {Dispatcher}", "name": "dispatcher", "type": "Dispatcher" } ] } ], "desc": "

Sets the global dispatcher used by Common API Methods. Global dispatcher is shared among compatible undici modules,\nincluding undici that is bundled internally with node.js.

\n

Undici stores this dispatcher under Symbol.for('undici.globalDispatcher.2').

\n

setGlobalDispatcher() also mirrors the configured dispatcher to\nSymbol.for('undici.globalDispatcher.1') using Dispatcher1Wrapper, so Node.js built-in fetch\ncan keep using the legacy handler contract while Undici uses the new handler API.

" }, { "textRaw": "`undici.getGlobalDispatcher()`", "name": "getGlobalDispatcher", "type": "method", "signatures": [ { "params": [], "return": { "textRaw": "Returns: {Dispatcher}", "name": "return", "type": "Dispatcher" } } ], "desc": "

Gets the global dispatcher used by Common API Methods.

" }, { "textRaw": "`undici.setGlobalOrigin(origin)`", "name": "setGlobalOrigin", "type": "method", "signatures": [ { "params": [ { "textRaw": "`origin` {string|URL|undefined}", "name": "origin", "type": "string|URL|undefined" } ] } ], "desc": "

Sets the global origin used in fetch.

\n

If undefined is passed, the global origin will be reset. This will cause Response.redirect, new Request(), and fetch to throw an error when a relative path is passed.

\n
setGlobalOrigin('http://localhost:3000')\n\nconst response = await fetch('/api/ping')\n\nconsole.log(response.url) // http://localhost:3000/api/ping\n
" }, { "textRaw": "`undici.getGlobalOrigin()`", "name": "getGlobalOrigin", "type": "method", "signatures": [ { "params": [], "return": { "textRaw": "Returns: {URL}", "name": "return", "type": "URL" } } ], "desc": "

Gets the global origin used in fetch.

" } ], "displayName": "Specification Compliance" }, { "textRaw": "Collaborators", "name": "collaborators", "type": "misc", "desc": "", "displayName": "Collaborators" }, { "textRaw": "Past Collaborators", "name": "past_collaborators", "type": "misc", "desc": "", "modules": [ { "textRaw": "Releasers", "name": "releasers", "type": "module", "desc": "", "displayName": "Releasers" } ], "displayName": "Past Collaborators" }, { "textRaw": "Long Term Support", "name": "long_term_support", "type": "misc", "desc": "

Undici aligns with the Node.js LTS schedule. The following table shows the supported versions:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
Undici VersionBundled in Node.jsNode.js Versions SupportedEnd of Life
5.x18.x≥14.0 (tested: 14, 16, 18)2024-04-30
6.x20.x, 22.x≥18.17 (tested: 18, 20, 21, 22)2027-04-30
7.x24.x≥20.18.1 (tested: 20, 22, 24)2028-04-30
8.x26.x≥22.19.0 (tested: 22, 24, 26)2029-04-30
", "displayName": "Long Term Support" }, { "textRaw": "License", "name": "license", "type": "misc", "desc": "

MIT

", "displayName": "License" } ] } ] }