Undici

https://undici.nodejs.org
Admin
Undici is a high-performance HTTP/1.1 client for Node.js, providing a `fetch()` implementation and...
Tokens:82,582
Snippets:1,017
Trust Score:10
Update:3 months ago
Show doc for...
Tokens:
Raw
### Use installed global classes

Source: https://undici.nodejs.org/api/GlobalInstallation.json

Demonstrates usage of various web API classes after calling install().

```mjs
import { install } from 'undici'

install()

const headers = new Headers([['content-type', 'application/json']])
const request = new Request('https://example.com')
const formData = new FormData()
const ws = new WebSocket('wss://example.com')
const eventSource = new EventSource('https://example.com/events')
```

--------------------------------

### install()

Source: https://undici.nodejs.org/index.html

The install() function adds web API classes to globalThis, enabling their use without explicit imports.

```APIDOC
## install()

### Description
Adds fetch-related and other web API classes to `globalThis`, making them available globally. This is useful for polyfilling environments or ensuring consistent behavior across Node.js versions.

### Signature
`install(): void`

### Globals Added
- **fetch** - The fetch function
- **Headers** - HTTP headers management
- **Response** - HTTP response representation
- **Request** - HTTP request representation
- **FormData** - Form data handling
- **WebSocket** - WebSocket client
- **CloseEvent, ErrorEvent, MessageEvent** - WebSocket events
- **EventSource** - Server-sent events client

### Example
```javascript
import { install } from 'undici'

// Install undici's global web APIs
install()

// Now you can use fetch classes globally
const response = await fetch('https://api.example.com/data')
```
```

--------------------------------

### install()

Source: https://undici.nodejs.org/api/GlobalInstallation.json

The install() function registers Undici's fetch implementation to the global scope. It can be used conditionally to avoid overwriting an existing global fetch.

```APIDOC
## install()

### Description
Registers Undici's fetch implementation to the global scope. It is recommended to guard this call to ensure it only runs if a global fetch is not already defined.

### Usage
```mjs
import { install } from 'undici'

if (typeof globalThis.fetch === 'undefined') {
  install()
}

const response = await fetch('https://example.com')
```
```

--------------------------------

### install()

Source: https://undici.nodejs.org/api/GlobalInstallation.json

The install() function overwrites properties on globalThis (such as fetch, Headers, Response, Request, FormData, WebSocket, etc.) with undici's implementations. This change is unconditional and persists for the lifetime of the process.

```APIDOC
## install()

### Description
Overwrites properties of `globalThis` with undici's implementations of WHATWG web APIs. This ensures that global identifiers like `fetch`, `Headers`, `Response`, `Request`, `FormData`, and `WebSocket` resolve to undici's versions.

### Signature
`install()`

### Returns
- **undefined** (undefined) - The function does not return a value.

### Usage Example
```mjs
import { install } from 'undici'

install()

// fetch, Headers, Response, Request, etc. now resolve to undici's implementations.
const response = await fetch('https://example.com')
```
```

--------------------------------

### Initializing Socks5ProxyAgent

Source: https://undici.nodejs.org/api/Socks5ProxyAgent.html

Examples of initializing the agent with various authentication and configuration options.

```javascript
import { Socks5ProxyAgent } from 'undici'

// Without authentication.
const agent = new Socks5ProxyAgent('socks5://localhost:1080')

// With credentials in the URL.
const authAgent = new Socks5ProxyAgent('socks5://user:pass@localhost:1080')

// With credentials and pool options.
const configuredAgent = new Socks5ProxyAgent('socks5://localhost:1080', {
  username: 'user',
  password: 'pass',
  connections: 10
})
```

--------------------------------

### Installing Undici Globals

Source: https://undici.nodejs.org/index.html

Using the install() function to replace global fetch and FormData with undici's versions to ensure compatibility.

```javascript
import { install } from 'undici'

install()

const body = new FormData()
body.set('name', 'some')
await fetch('https://example.com', {
  method: 'POST',
  body
})
```

--------------------------------

### Install Undici Global APIs

Source: https://undici.nodejs.org/index.html

Use the install function to make fetch, Headers, Request, and other web APIs available globally without explicit imports.

```javascript
import { install } from 'undici'

// Install undici's global web APIs
install()

// Now you can use fetch classes globally without importing
const response = await fetch('https://api.example.com/data')
const data = await response.json()

// All classes are available globally:
const headers = new Headers([['content-type', 'application/json']])
const request = new Request('https://example.com')
const formData = new FormData()
const ws = new WebSocket('wss://example.com')
const eventSource = new EventSource('https://example.com/events')
```

--------------------------------

### Install Undici

Source: https://undici.nodejs.org/getting-started.json

Install the package via npm.

```bash
npm install undici
```

--------------------------------

### Initialize and Request with Client

Source: https://undici.nodejs.org/api/Client.html

Create a new Client instance and perform a GET request to the specified origin.

```javascript
import { Client } from 'undici'

const client = new Client('http://localhost:3000')
const { statusCode, body } = await client.request({ path: '/', method: 'GET' })
```

--------------------------------

### MockClient request usage example

Source: https://undici.nodejs.org/api/MockClient.html

Demonstrates initializing a MockAgent, intercepting a request, and handling the mocked response.

```javascript
import { MockAgent } from 'undici'

const mockAgent = new MockAgent({ connections: 1 })
const mockClient = mockAgent.get('http://localhost:3000')
mockClient.intercept({ path: '/foo' }).reply(200, 'foo')

const { statusCode, body } = await mockClient.request({
  origin: 'http://localhost:3000',
  path: '/foo',
  method: 'GET'
})

console.log('response received', statusCode) // response received 200

for await (const data of body) {
  console.log('data', data.toString('utf8')) // data foo
}
```

--------------------------------

### Perform a request with Pool

Source: https://undici.nodejs.org/api/Pool.json

Demonstrates how to initialize a Pool and execute a GET request using the request method.

```mjs
import { Pool } from 'undici'

const pool = new Pool('http://localhost:3000', { connections: 10 })
const { statusCode, headers, body } = await pool.request({
  path: '/',
  method: 'GET'
})
console.log(statusCode, headers)
console.log(await body.text())
await pool.close()
```

--------------------------------

### Installing Undici as global fetch

Source: https://undici.nodejs.org/getting-started.json

Override Node.js built-in globals with Undici's implementation using the install function.

```js
import { install } from 'undici'

install()

// Global fetch, Headers, Response, Request, and FormData
// now come from undici, not the Node.js bundle
const res = await fetch('https://example.com')
```

--------------------------------

### Vary header mapping example

Source: https://undici.nodejs.org/api/CacheStore

Example of how the Vary header is mapped to a recorded object.

```HTTP
Vary: content-encoding, accept
content-encoding: utf8
accept: application/json
```

```JavaScript
{
  'content-encoding': 'utf8',
  accept: 'application/json'
}
```

--------------------------------

### Load Snapshots from Disk

Source: https://undici.nodejs.org/api/SnapshotAgent.json

Loads snapshots into memory and installs MockAgent interceptors for playback mode.

```mjs
await agent.loadSnapshots('./snapshots/api.json')
```

--------------------------------

### Conditionally install Undici fetch

Source: https://undici.nodejs.org/api/GlobalInstallation.json

Use this pattern to install Undici's fetch only if a global fetch is not already defined.

```mjs
import { install } from 'undici'

if (typeof globalThis.fetch === 'undefined') {
  install()
}

const response = await fetch('https://example.com')
```

--------------------------------

### Proxy request with fetch

Source: https://undici.nodejs.org/api/ProxyAgent.html

Example of using ProxyAgent with the fetch API to route a GET request.

```javascript
import { ProxyAgent, fetch } from 'undici'

const proxyAgent = new ProxyAgent('http://localhost:8000')

const response = await fetch('http://localhost:3000/foo', {
  dispatcher: proxyAgent,
  method: 'GET',
})

console.log('response status', response.status)
console.log('response data', await response.text())
```

--------------------------------

### client.connect

Source: https://undici.nodejs.org/api/Client.html

Starts a connection to the client's origin and tunnels a connection through it.

```APIDOC
## client.connect

### Description
Starts a connection to the client's origin and tunnels a connection through it.

### Signature
`client.connect(options, callback?): Promise | void`

### Parameters
- **options** (Object) - Required - The connect options.
- **callback** (Function) - Optional - Callback function.
```

--------------------------------

### Use a custom dispatcher with fetch

Source: https://undici.nodejs.org/api/Fetch.html

Example of routing a request through a custom Agent to handle specific connection settings.

```javascript
import { fetch, Agent } from 'undici'

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

--------------------------------

### undici.connect([url, options])

Source: https://undici.nodejs.org/index.html

Starts two-way communications using HTTP CONNECT.

```APIDOC
## undici.connect([url, options])

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

### Parameters
- **url** (string | URL | UrlObject) - Required - The target URL.
- **options** (ConnectOptions) - Optional - Configuration options.
- **callback** ((err: Error | null, data: ConnectData | null) => void) - Optional - Callback function.
```

--------------------------------

### Migrating from Built-in Fetch to Undici

Source: https://undici.nodejs.org/index.html

Examples showing how to replace built-in fetch with undici's fetch or the higher-performance request API.

```javascript
// Before: Built-in fetch
const response = await fetch('https://api.example.com/data');

// After: Undici fetch (drop-in replacement)
import { fetch } from 'undici';
const response = await fetch('https://api.example.com/data');

// Or: Undici request (better performance)
import { request } from 'undici';
const { statusCode, body } = await request('https://api.example.com/data');
const data = await body.json();
```

--------------------------------

### Import Undici fetch

Source: https://undici.nodejs.org/best-practices/undici-vs-builtin-fetch.html

Import the fetch function directly from the installed Undici package to ensure the installed version is used instead of the built-in global.

```javascript
import { fetch } from 'undici' // uses your installed version, not the built-in
```

--------------------------------

### agent.loadSnapshots([filePath])

Source: https://undici.nodejs.org/api/SnapshotAgent.json

Loads snapshots from disk into memory. In 'playback' mode, this installs MockAgent interceptors for request matching.

```APIDOC
## agent.loadSnapshots([filePath])

### Description
Loads snapshots from disk into memory. In 'playback' mode, this also installs the corresponding MockAgent interceptors so that subsequent requests are matched against the loaded snapshots.

### Parameters
- **filePath** (string) - Optional - Path to read snapshots from. Defaults to the snapshotPath provided to the constructor.

### Returns
- **Promise<void>** - Resolves when the snapshots have been loaded.
```

--------------------------------

### roundRobinPool.connect(options[, callback])

Source: https://undici.nodejs.org/api/RoundRobinPool.json

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

```APIDOC
## roundRobinPool.connect(options[, callback])

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

### Parameters
- **options** (object) - Required - Connection options.
- **callback** (function) - Optional - Callback function.
```

--------------------------------

### Install undici globals

Source: https://undici.nodejs.org/api/GlobalInstallation.json

Assigns undici implementations to globalThis for use without explicit imports.

```mjs
import { install } from 'undici'

install()

// `fetch`, `Headers`, `Response`, `Request`, etc. now resolve to undici's
// implementations.
const response = await fetch('https://example.com')
```

```cjs
const { install } = require('undici')

install()
```

--------------------------------

### dispatcher.connect

Source: https://undici.nodejs.org/api/Dispatcher.html

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

```APIDOC
## dispatcher.connect(options[, callback])

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

### Parameters
- **options** (Object) - Required - Configuration object for the connection.
  - **origin** (string|URL) - Required - The origin to connect to.
  - **path** (string) - Required - The request path.
  - **headers** (UndiciHeaders) - Optional - Request headers.
  - **signal** (AbortSignal|EventEmitter) - Optional - A signal used to abort the request.
  - **opaque** (any) - Optional - An opaque value passed through to the returned data.
  - **responseHeaders** (string) - Optional - Set to 'raw' to return headers as a raw array.
- **callback** (Function) - Optional - Invoked when the connection is established.

### Returns
- **Promise** - Resolves with an object containing statusCode, headers, socket, and opaque if no callback is provided.
```

--------------------------------

### Perform a basic fetch request

Source: https://undici.nodejs.org/api/Fetch.html

Demonstrates importing the Fetch API components from undici and performing a simple GET request to retrieve text content.

```javascript
import { fetch, Request, Response, Headers, FormData } from 'undici'

const response = await fetch('https://example.com')
const text = await response.text()
```

--------------------------------

### Perform a POST request with fetch

Source: https://undici.nodejs.org/api/Fetch.html

Example of sending a JSON payload using the fetch function.

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

--------------------------------

### Perform a request with mockPool.request

Source: https://undici.nodejs.org/api/MockPool.html

Signature and usage example for performing a request against registered mocks.

```typescript
mockPool.request(options, callback?): Promise
```

```javascript
import { MockAgent } from 'undici'

const mockAgent = new MockAgent()
const mockPool = mockAgent.get('http://localhost:3000')
mockPool.intercept({ path: '/foo', method: 'GET' }).reply(200, 'foo')

const { statusCode, body } = await mockPool.request({
  origin: 'http://localhost:3000',
  path: '/foo',
  method: 'GET'
})

console.log('response received', statusCode) // response received 200

for await (const data of body) {
  console.log('data', data.toString('utf8')) // data foo
}
```

--------------------------------

### Enable undici core debug logs

Source: https://undici.nodejs.org/api/Debug.html

Enables logs for core library activities including connection setup and request dispatch.

```bash
$ NODE_DEBUG=undici node script.js
UNDICI 16241: connecting to nodejs.org using https:h1
UNDICI 16241: connecting to nodejs.org using https:h1
UNDICI 16241: connected to nodejs.org using https:h1
UNDICI 16241: sending request to GET https://nodejs.org/
UNDICI 16241: received response to GET https://nodejs.org/ - HTTP 307
UNDICI 16241: connecting to nodejs.org using https:h1
UNDICI 16241: trailers received from GET https://nodejs.org/
UNDICI 16241: connected to nodejs.org using https:h1
UNDICI 16241: sending request to GET https://nodejs.org/en
UNDICI 16241: received response to GET https://nodejs.org/en - HTTP 200
UNDICI 16241: trailers received from GET https://nodejs.org/en
```

--------------------------------

### Initialize and use BalancedPool

Source: https://undici.nodejs.org/api/BalancedPool.html

Creates a pool instance with multiple upstreams and performs a GET request. Ensure the upstreams are reachable before dispatching requests.

```javascript
import { BalancedPool } from 'undici'

const pool = new BalancedPool([
  'http://localhost:3000',
  'http://localhost:3001',
  'http://localhost:3002',
])

const { statusCode, body } = await pool.request({
  path: '/',
  method: 'GET',
})
console.log('response received', statusCode)
for await (const chunk of body) {
  console.log('data', chunk.toString())
}
```

--------------------------------

### Define a User-Agent string

Source: https://undici.nodejs.org/best-practices/crawling.json

Example of a descriptive User-Agent string containing crawler identity and contact information.

```text
AcmeCo Crawler - acme.co - contact@acme.co
```

--------------------------------

### Perform an HTTP request with Undici

Source: https://undici.nodejs.org/api/Dispatcher.html

Demonstrates a basic GET request using the Undici Client, including handling the response body and trailers.

```javascript
import { createServer } from 'node:http'
import { Client } from 'undici'
import { once } from 'node:events'

const server = createServer((request, response) => {
  response.end('Hello, World!')
}).listen()

await once(server, 'listening')

const client = new Client(`http://localhost:${server.address().port}`)

try {
  const { body, headers, statusCode, statusText, trailers } = await client.request({
    path: '/',
    method: 'GET'
  })
  console.log(`response received ${statusCode}`)
  console.log('headers', headers)
  body.setEncoding('utf8')
  body.on('data', console.log)
  body.on('error', console.error)
  body.on('end', () => {
    console.log('trailers', trailers)
  })

  client.close()
  server.close()
} catch (error) {
  console.error(error)
}
```

--------------------------------

### Dispatching a request with a handler

Source: https://undici.nodejs.org/api/Dispatcher.html

Demonstrates using the client.dispatch method to handle request lifecycle events such as connection, response start, data chunks, and completion.

```javascript
import { createServer } from 'node:http'
import { Client } from 'undici'
import { once } from 'node:events'

const server = createServer((request, response) => {
  response.end('Hello, World!')
}).listen()

await once(server, 'listening')

const client = new Client(`http://localhost:${server.address().port}`)

const data = []

client.dispatch({
  path: '/',
  method: 'GET',
  headers: { 'x-foo': 'bar' }
}, {
  onRequestStart: () => {
    console.log('Connected!')
  },
  onResponseError: (_controller, error) => {
    console.error(error)
  },
  onResponseStart: (_controller, statusCode, headers) => {
    console.log(`statusCode: ${statusCode} | headers: ${JSON.stringify(headers)}`)
  },
  onResponseData: (_controller, chunk) => {
    data.push(chunk)
  },
  onResponseEnd: (_controller, trailers) => {
    console.log(`trailers: ${JSON.stringify(trailers)}`)
    console.log(`Data: ${Buffer.concat(data).toString('utf8')}`)
    client.close()
    server.close()
  }
})
```

--------------------------------

### Initialize a Client

Source: https://undici.nodejs.org/api/Client.html

Create a new Client instance bound to a specific origin.

```javascript
import { Client } from 'undici'

const client = new Client('http://localhost:3000')
```

--------------------------------

### Initialize and Open Cache

Source: https://undici.nodejs.org/api/CacheStorage.json

Demonstrates how to import and open a cache using both ESM and CommonJS syntax.

```mjs
import { caches } from 'undici'

const cache = await caches.open('v1')
```

```cjs
const { caches } = require('undici')

caches.open('v1').then((cache) => {
  // ...
})
```

--------------------------------

### Initialize and use WebSocket

Source: https://undici.nodejs.org/api/WebSocket.html

Establishes a connection to a WebSocket server and handles open and message events.

```javascript
import { WebSocket } from 'undici'

const ws = new WebSocket('wss://echo.websocket.events')

ws.addEventListener('open', () => {
  ws.send('Hello, world!')
})

ws.addEventListener('message', (event) => {
  console.log('received:', event.data)
})
```

--------------------------------

### Initialize WebSocket with HTTP/2

Source: https://undici.nodejs.org/api/WebSocket.html

Enable experimental HTTP/2 support by configuring the dispatcher.

```JavaScript
import { WebSocket, Agent } from 'undici'

const dispatcher = new Agent({ allowH2: true })

const ws = new WebSocket('wss://echo.websocket.events', {
  dispatcher,
  protocols: ['echo', 'chat']
})
```

--------------------------------

### Get Global Dispatcher

Source: https://undici.nodejs.org/index.html

Retrieves the currently configured global dispatcher.

```javascript
undici.getGlobalDispatcher(): void
```

--------------------------------

### Initialize a basic connector

Source: https://undici.nodejs.org/api/Connector.html

Create a connector instance using the buildConnector helper with custom TLS options.

```javascript
import { buildConnector } from 'undici'

const connector = buildConnector({ rejectUnauthorized: false })
```

--------------------------------

### Configure Client Certificate Authentication

Source: https://undici.nodejs.org/best-practices/client-certificate.json

Demonstrates setting up an HTTPS server to request client certificates and a client to provide them using Undici's connect options.

```js
const { readFileSync } = require('node:fs')
const { join } = require('node:path')
const { createServer } = require('node:https')
const { Client } = require('undici')

const serverOptions = {
  ca: [
    readFileSync(join(__dirname, 'client-ca-crt.pem'), 'utf8')
  ],
  key: readFileSync(join(__dirname, 'server-key.pem'), 'utf8'),
  cert: readFileSync(join(__dirname, 'server-crt.pem'), 'utf8'),
  requestCert: true,
  rejectUnauthorized: false
}

const server = createServer(serverOptions, (req, res) => {
  // true if client cert is valid
  if(req.client.authorized === true) {
    console.log('valid')
  } else {
    console.error(req.client.authorizationError)
  }
  res.end()
})

server.listen(0, function () {
  const tls = {
    ca: [
      readFileSync(join(__dirname, 'server-ca-crt.pem'), 'utf8')
    ],
    key: readFileSync(join(__dirname, 'client-key.pem'), 'utf8'),
    cert: readFileSync(join(__dirname, 'client-crt.pem'), 'utf8'),
    rejectUnauthorized: false,
    servername: 'agent1'
  }
  const client = new Client(`https://localhost:${server.address().port}`, {
    connect: tls
  })

  client.request({
    path: '/',
    method: 'GET'
  }, (err, { body }) => {
    body.on('data', (buf) => {})
    body.on('end', () => {
      client.close()
      server.close()
    })
  })
})
```

--------------------------------

### Initialize and use RoundRobinPool

Source: https://undici.nodejs.org/api/RoundRobinPool.json

Demonstrates creating a pool with a set number of connections and distributing requests across them.

```mjs
import { RoundRobinPool } from 'undici'

const pool = new RoundRobinPool('http://localhost:3000', {
  connections: 10
})

// Requests are distributed evenly across all 10 connections.
for (let i = 0; i < 100; i++) {
  const { body } = await pool.request({
    path: '/api/data',
    method: 'GET'
  })
  console.log(await body.json())
}

await pool.close()
```

--------------------------------

### Get Global Origin

Source: https://undici.nodejs.org/index.html

Retrieves the global origin used in fetch requests.

```javascript
undici.getGlobalOrigin(): void
```

--------------------------------

### ProxyAgent Constructor Usage

Source: https://undici.nodejs.org/api/ProxyAgent.html

Demonstrates initializing the ProxyAgent with strings, URLs, or configuration objects, including TLS settings.

```javascript
import { ProxyAgent } from 'undici'

// A string or URL is treated as the proxy uri.
const a = new ProxyAgent('http://localhost:8000')
const b = new ProxyAgent(new URL('http://localhost:8000'))

// An options object requires a `uri`.
const c = new ProxyAgent({ uri: 'http://localhost:8000' })

// With proxy TLS settings.
const d = new ProxyAgent({
  uri: 'https://secure.proxy.server',
  proxyTls: {
    signal: AbortSignal.timeout(1000),
  },
})
```

--------------------------------

### Get Cached Response

Source: https://undici.nodejs.org/api/CacheStore

Retrieves a cached response for a given request key.

```javascript
sqliteCacheStore.get(key): GetResult | undefined
```

--------------------------------

### new Client(url, options)

Source: https://undici.nodejs.org/api/Client.html

Creates a new Client instance to manage a single origin connection.

```APIDOC
## new Client(url, options)

### Description
Creates a new Client instance for the specified origin.

### Parameters
- **url** (URL | string) - Required - The origin to connect to.
- **options** (Object) - Optional - Configuration options for the client, including timeouts, connection settings, and TLS configuration.
```

--------------------------------

### Get Upstream

Source: https://undici.nodejs.org/api/BalancedPool.html

Retrieves the Pool instance associated with a specific upstream origin.

```javascript
balancedPool.getUpstream(upstream): Pool | undefined
```

--------------------------------

### pool.upgrade(options[, callback])

Source: https://undici.nodejs.org/api/Pool.json

Upgrades a connection (for example to a WebSocket) through one of the pooled clients.

```APIDOC
## pool.upgrade(options[, callback])

### Description
Upgrades a connection (for example to a WebSocket) through one of the pooled clients.

### Parameters
- **options** (Object) - Required - Upgrade options.
- **callback** (Function) - Optional - Callback function.
```

--------------------------------

### Open or Create a Cache with caches.open

Source: https://undici.nodejs.org/api/CacheStorage.json

Opens a cache by name, creating it if it does not exist. Multiple instances with the same name share the same underlying cached responses.

```mjs
import { caches } from 'undici'
import assert from 'node:assert'

const cache1 = await caches.open('v1')
const cache2 = 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'))
```

--------------------------------

### Client Constructor Signature

Source: https://undici.nodejs.org/api/Client.html

Constructor for initializing a new Client instance with an origin URL and optional configuration.

```javascript
new Client(url, options?): Client
```

--------------------------------

### fetch(input[, init])

Source: https://undici.nodejs.org/api/Fetch.html

Initiates a network request to the specified input URL, returning a Promise that resolves to a Response object.

```APIDOC
## fetch(input[, init])

### Description
Initiates a network request to the specified input URL, returning a Promise that resolves to a Response object.

### Parameters
- **input** (string|Request) - Required - The URL or Request object to fetch.
- **init** (object) - Optional - Configuration options for the request.
```

--------------------------------

### Enable call history

Source: https://undici.nodejs.org/api/MockAgent.html

Starts recording request history, which can be retrieved via getCallHistory().

```javascript
mockAgent.enableCallHistory(): MockAgent
```

```javascript
import { MockAgent } from 'undici'

const mockAgent = new MockAgent()

mockAgent.enableCallHistory()
```

--------------------------------

### Initialize RedirectHandler

Source: https://undici.nodejs.org/api/RedirectHandler.json

Demonstrates manual instantiation of RedirectHandler to manage request dispatching with redirect support.

```mjs
import { Client, RedirectHandler } from 'undici'

const client = new Client('http://example.com')
const dispatch = client.dispatch.bind(client)

const handler = new RedirectHandler(dispatch, 5, {
  method: 'GET',
  path: '/',
  origin: 'http://example.com',
}, {
  onRequestStart () {},
  onResponseStart (controller, statusCode, headers) {
    console.log(statusCode)
  },
  onResponseData (controller, chunk) {},
  onResponseEnd () {},
})

dispatch({ method: 'GET', path: '/', origin: 'http://example.com' }, handler)
```

--------------------------------

### Connect to a proxy with authentication

Source: https://undici.nodejs.org/best-practices/proxy.html

Shows how to provide proxy credentials using the proxy-authorization header in the request.

```javascript
import { Client } from 'undici'
import { createServer } from 'http'
import { createProxy } from 'proxy'

const server = await buildServer()
const proxyServer = await buildProxy()

const serverUrl = `http://localhost:${server.address().port}`
const proxyUrl = `http://localhost:${proxyServer.address().port}`

proxyServer.authenticate = function (req) {
  return req.headers['proxy-authorization'] === `Basic ${Buffer.from('user:pass').toString('base64')}`
}

server.on('request', (req, res) => {
  console.log(req.url) // '/hello?foo=bar'
  res.setHeader('content-type', 'application/json')
  res.end(JSON.stringify({ hello: 'world' }))
})

const client = new Client(proxyUrl)

const response = await client.request({
  method: 'GET',
  path: serverUrl + '/hello?foo=bar',
  headers: {
    'proxy-authorization': `Basic ${Buffer.from('user:pass').toString('base64')}`
  }
})

response.body.setEncoding('utf8')
let data = ''
for await (const chunk of response.body) {
  data += chunk
}
console.log(response.statusCode) // 200
console.log(JSON.parse(data)) // { hello: 'world' }

server.close()
proxyServer.close()
client.close()

function buildServer () {
  return new Promise((resolve, reject) => {
    const server = createServer()
    server.listen(0, () => resolve(server))
  })
}

function buildProxy () {
  return new Promise((resolve, reject) => {
    const server = createProxy(createServer())
    server.listen(0, () => resolve(server))
  })
}
```

--------------------------------

### Clean mocks with mockPool.cleanMocks

Source: https://undici.nodejs.org/api/MockPool.html

Signature and usage example for removing all registered interceptors from the mock pool.

```typescript
mockPool.cleanMocks(): undefined
```

```javascript
import { MockAgent } from 'undici'

const mockAgent = new MockAgent()
const mockPool = mockAgent.get('http://localhost:3000')

mockPool.intercept({ path: '/foo' }).reply(200, 'foo')
mockPool.cleanMocks()
```

--------------------------------

### Initialize SqliteCacheStore

Source: https://undici.nodejs.org/api/CacheStore

Configures the cache store and integrates it into the Undici dispatcher.

```javascript
import { interceptors, cacheStores, Agent, setGlobalDispatcher } from 'undici'

const store = new cacheStores.SqliteCacheStore({ location: './cache.db' })

setGlobalDispatcher(
  new Agent().compose(interceptors.cache({ store }))
)
```

--------------------------------

### Configure EventSource with Credentials

Source: https://undici.nodejs.org/api/EventSource.html

Initialize an EventSource with specific credential settings.

```javascript
import { EventSource } from 'undici'

const eventSource = new EventSource('http://localhost:3000', {
  withCredentials: true
})
```

--------------------------------

### new WebSocket(url, protocols?)

Source: https://undici.nodejs.org/api/WebSocket.html

Creates a new WebSocket instance and initiates the connection handshake.

```APIDOC
## new WebSocket(url, protocols?)

### Description
Creates a new WebSocket and begins connecting to the specified URL. The second argument can be a string, an array of subprotocols, or a WebSocketInit object for advanced configuration.

### Parameters
- **url** (URL | string) - Required - The server URL (must use ws: or wss: scheme).
- **protocols** (string | string[] | WebSocketInit) - Optional - Subprotocols to negotiate or an initialization object containing dispatcher and headers.

### Example
```javascript
import { WebSocket } from 'undici'
const ws = new WebSocket('wss://echo.websocket.events', ['echo', 'chat'])
```
```

--------------------------------

### HTTPS tunneling with ProxyAgent

Source: https://undici.nodejs.org/api/ProxyAgent.html

Example of using ProxyAgent to tunnel HTTPS requests through a secure proxy server.

```javascript
import { ProxyAgent, fetch } from 'undici'

const proxyAgent = new ProxyAgent('https://secure.proxy.server')

const response = await fetch('https://secure.endpoint.com/api/data', {
  dispatcher: proxyAgent,
  method: 'GET',
})

console.log('response status', response.status)
console.log('response data', await response.json())
```

--------------------------------

### new Response(body?, init?)

Source: https://undici.nodejs.org/api/Fetch.html

Creates a new Response instance.

```APIDOC
## new Response(body?, init?)

### Description
Creates a new Response object.

### Parameters
- **body** (string | Buffer | Uint8Array | Blob | FormData | URLSearchParams | ReadableStream | null) - Optional - The response body.
- **init** (ResponseInit) - Optional - Configuration object containing status, statusText, and headers.
```

--------------------------------

### Vary header mapping with missing header

Source: https://undici.nodejs.org/api/CacheStore

Example of how a missing header is recorded as null in the Vary map.

```JavaScript
{
  'content-encoding': 'utf8',
  accept: null
}
```

--------------------------------

### Connect to Upstream

Source: https://undici.nodejs.org/api/BalancedPool.html

Establishes a connection using the provided options.

```javascript
balancedPool.connect(options, callback?): void
```

--------------------------------

### Initialize MockClient

Source: https://undici.nodejs.org/api/MockClient.html

Obtain a MockClient instance from a MockAgent configured with connections set to 1.

```javascript
import { MockAgent } from 'undici'

// `connections: 1` makes the agent hand out `MockClient` instances.
const mockAgent = new MockAgent({ connections: 1 })
const mockClient = mockAgent.get('http://localhost:3000')
```

--------------------------------

### new Request(input, init?)

Source: https://undici.nodejs.org/api/Fetch.html

Creates a new Request instance. The input can be a URL string, a URL object, or another Request object to copy.

```APIDOC
## new Request(input, init?)

### Description
Creates a new Request instance to be used with fetch().

### Parameters
- **input** (string | URL | Request) - Required - The resource to request.
- **init** (RequestInit) - Optional - An options object with the same fields as the init argument of fetch().

### Returns
- **Request** - A new Request instance.
```

--------------------------------

### Use real Blob and File instances

Source: https://undici.nodejs.org/best-practices/migrating-from-v7-to-v8.json

Replace custom objects mimicking Blob or File with actual instances.

```js
const body = new Blob(['hello'])
```

--------------------------------

### fetch(input, init?)

Source: https://undici.nodejs.org/api/Fetch.html

The fetch function initiates a network request to the specified resource. It returns a promise that fulfills with a Response object once headers are received.

```APIDOC
## fetch(input, init?)

### Description
Starts the process of fetching a resource from the network. The promise fulfills with a Response object even for HTTP error statuses like 404.

### Parameters
- **input** (string | URL | Request) - Required - The resource to fetch.
- **init** (RequestInit) - Optional - An options object to customize the request.

### RequestInit Options
- **body** (string | Buffer | Uint8Array | Blob | FormData | URLSearchParams | ReadableStream | null) - Optional - The request body.
- **cache** (string) - Optional - The cache mode.
- **credentials** (string) - Optional - How credentials are sent.
- **dispatcher** (Dispatcher) - Optional - The dispatcher used to perform the request.
- **duplex** (string) - Optional - The duplex mode of the request.
- **headers** (Headers | Object | Array) - Optional - The request headers.
- **integrity** (string) - Optional - Subresource integrity metadata.
- **keepalive** (boolean) - Optional - Whether the connection may outlive the page.
- **method** (string) - Optional - The request method (e.g., 'GET', 'POST').
- **mode** (string) - Optional - The request mode.
- **redirect** (string) - Optional - How redirects are handled.
- **referrer** (string) - Optional - The request referrer.
- **referrerPolicy** (string) - Optional - The referrer policy.
- **signal** (AbortSignal | null) - Optional - An AbortSignal to abort the request.
- **window** (null) - Optional - Reserved by the standard.

### Response
- **Promise** - Fulfills with a Response object once response headers are received.
```

--------------------------------

### DNS Interceptor Usage

Source: https://undici.nodejs.org/api/Interceptors.html

Example of composing an Agent with the DNS interceptor configured for specific TTL, dual-stack, and affinity settings.

```javascript
import { Agent, interceptors } from 'undici'

const agent = new Agent().compose(
  interceptors.dns({
    maxTTL: 60_000, // cache for at most 60 seconds
    dualStack: true,
    affinity: 4     // prefer IPv4
  })
)
```

--------------------------------

### Manage Cache Keys

Source: https://undici.nodejs.org/api/CacheStorage.json

Shows how to open a cache and retrieve the list of available cache names.

```mjs
import { caches } from 'undici'

await caches.open('v1')
console.log(await caches.keys()) // ['v1']
```

--------------------------------

### retryAgent.dispatch(options, handler)

Source: https://undici.nodejs.org/api/RetryAgent.json

Dispatches options through the wrapped dispatcher, installing a RetryHandler that applies the configured retry policy before delegating to handler.

```APIDOC
## retryAgent.dispatch(options, handler)

### Description
Dispatches options through the wrapped dispatcher, installing a RetryHandler that applies the configured retry policy before delegating to handler. Returns false if the dispatcher is busy and the caller should wait before dispatching again, otherwise true.

### Parameters
- **options** (DispatchOptions) - Required - The dispatch options, identical to dispatcher.dispatch().
- **handler** (DispatchHandler) - Required - The dispatch handler.

### Returns
- **boolean** - Returns false if the dispatcher is busy, otherwise true.
```

--------------------------------

### Applying Interceptors to Client

Source: https://undici.nodejs.org/api/Interceptors.html

Shows how to apply a single interceptor to a Client instance.

```javascript
import { Client, interceptors } from 'undici'

const client = new Client('https://example.com').compose(
  interceptors.retry({ maxRetries: 2 })
)
```

--------------------------------

### new Agent([options])

Source: https://undici.nodejs.org/api/Agent.html

Creates a new Agent instance with optional configuration for connection management and origin limits.

```APIDOC
## new Agent([options])

### Description
Creates a new Agent instance. The agent maintains an internal map of origins to dispatchers, creating them lazily via a factory function.

### Parameters
- **options** (AgentOptions) - Optional. Extends PoolOptions. Includes `factory` (function to build dispatchers) and `maxOrigins` (number, default Infinity) to limit distinct origins.
```

--------------------------------

### Initialize WebSocket with Proxy

Source: https://undici.nodejs.org/api/WebSocket.html

Route the WebSocket connection through a custom ProxyAgent.

```JavaScript
import { WebSocket, ProxyAgent } from 'undici'

const dispatcher = new ProxyAgent('http://localhost:8080')

const ws = new WebSocket('wss://echo.websocket.events', {
  dispatcher,
  protocols: ['echo', 'chat']
})
```

--------------------------------

### new SnapshotAgent([options])

Source: https://undici.nodejs.org/api/SnapshotAgent.json

Creates a new instance of SnapshotAgent with the specified configuration options.

```APIDOC
## new SnapshotAgent([options])

### Description
Constructs a new SnapshotAgent instance. This agent records or replays HTTP interactions based on the provided mode.

### Parameters
- **options** (Object) - Optional - Configuration object.
  - **mode** (string) - Optional - The snapshot mode. One of 'record', 'playback', or 'update'. Default: 'record'.
  - **snapshotPath** (string) - Optional - Path to the snapshot file. Required when mode is 'playback' or 'update'. Default: null.
  - **maxSnapshots** (number) - Optional - Maximum number of snapshots to keep in memory. Default: Infinity.
  - **autoFlush** (boolean) - Optional - When true, snapshots are written to snapshotPath automatically as they are recorded. Default: false.
```

--------------------------------

### Connect to a proxy without authentication

Source: https://undici.nodejs.org/best-practices/proxy.html

Demonstrates initializing a Client with a proxy URL and performing a request to an upstream server.

```javascript
import { Client } from 'undici'
import { createServer } from 'http'
import { createProxy } from 'proxy'

const server = await buildServer()
const proxyServer = await buildProxy()

const serverUrl = `http://localhost:${server.address().port}`
const proxyUrl = `http://localhost:${proxyServer.address().port}`

server.on('request', (req, res) => {
  console.log(req.url) // '/hello?foo=bar'
  res.setHeader('content-type', 'application/json')
  res.end(JSON.stringify({ hello: 'world' }))
})

const client = new Client(proxyUrl)

const response = await client.request({
  method: 'GET',
  path: serverUrl + '/hello?foo=bar'
})

response.body.setEncoding('utf8')
let data = ''
for await (const chunk of response.body) {
  data += chunk
}
console.log(response.statusCode) // 200
console.log(JSON.parse(data)) // { hello: 'world' }

server.close()
proxyServer.close()
client.close()

function buildServer () {
  return new Promise((resolve, reject) => {
    const server = createServer()
    server.listen(0, () => resolve(server))
  })
}

function buildProxy () {
  return new Promise((resolve, reject) => {
    const server = createProxy(createServer())
    server.listen(0, () => resolve(server))
  })
}
```

--------------------------------

### Initialize WebSocket Connection

Source: https://undici.nodejs.org/api/WebSocket.html

Basic usage to establish a connection with specified subprotocols.

```JavaScript
import { WebSocket } from 'undici'

const ws = new WebSocket('wss://echo.websocket.events', ['echo', 'chat'])
```

--------------------------------

### h2cClient.connect(options[, callback])

Source: https://undici.nodejs.org/api/H2CClient.json

Establishes a connection using the provided options. Returns a promise or invokes a callback once the connection is established.

```APIDOC
## h2cClient.connect(options[, callback])

### Description
Invoked with (err, data) once the connection is established. If omitted, a Promise is returned instead.

### Parameters
- **options** (Object) - Required
  - **path** (string) - Required
  - **headers** (Object) - Optional - Default: null
  - **signal** (AbortSignal|EventEmitter|null) - Optional - Default: null
  - **opaque** (any) - Optional - An opaque value passed through to the returned connect data.
  - **responseHeaders** (string|null) - Optional - Set to 'raw' to return the response headers as a raw array instead of an object. Default: null
- **callback** (Function) - Optional - Invoked with (err, data) once the connection is established.
```

--------------------------------

### Initialize a new Pool

Source: https://undici.nodejs.org/api/Pool.json

Creates a new Pool instance with specified connection and pipelining settings.

```mjs
import { Pool } from 'undici'

const pool = new Pool('http://localhost:3000', {
  connections: 128,
  pipelining: 1
})
```

--------------------------------

### connector(options, callback)

Source: https://undici.nodejs.org/api/Connector.html

Establishes a socket connection based on the provided options and invokes a callback upon completion.

```APIDOC
## connector(options, callback)

### Description
Establishes a new connection for Undici requests. It opens a `net.Socket` for `http:` targets or a `tls.TLSSocket` for `https:` targets, applies TCP keep-alive and connect timeouts, and invokes the provided callback.

### Signature
`connector(options, callback): Socket | TLSSocket`

### Parameters
- **options** (Object) - Required - Per-connection configuration:
  - **hostname** (string) - Required - The host to connect to.
  - **host** (string) - Optional - The value of the request `Host` header.
  - **protocol** (string) - Required - The request protocol (e.g., 'https:' or 'http:').
  - **port** (string) - Optional - The port to connect to. Defaults to 443 for https and 80 for http.
  - **servername** (string) - Optional - The TLS Server Name Indication (SNI) value.
  - **localAddress** (string | null) - Optional - The local address to connect from.
  - **httpSocket** (Socket) - Optional - An existing socket for TLS upgrades.
- **callback** (Function) - Required - Called once the socket has connected or failed:
  - **err** (Error | null) - The connection error, or null on success.
  - **socket** (Socket | TLSSocket | null) - The connected socket, or null on failure.

### Returns
- **Socket | TLSSocket** - The socket being established.
```

--------------------------------

### Initialize and use a Pool

Source: https://undici.nodejs.org/api/Pool.json

Create a new Pool instance with a specified number of connections and perform a request. Ensure the pool is closed after use to release resources.

```mjs
import { Pool } from 'undici'

const pool = new Pool('http://localhost:3000', { connections: 10 })
const { statusCode, body } = await pool.request({ path: '/', method: 'GET' })
console.log(statusCode, await body.text())
await pool.close()
```

--------------------------------

### Initialize and use H2CClient

Source: https://undici.nodejs.org/api/H2CClient.json

Create an H2CClient instance to perform HTTP/2 requests over cleartext.

```mjs
import { H2CClient } from 'undici'

const client = new H2CClient('http://localhost:3000')

const { statusCode, body } = await client.request({ path: '/', method: 'GET' })
console.log(statusCode)
console.log(await body.text())
```

--------------------------------

### new EventSource(url, eventSourceInitDict)

Source: https://undici.nodejs.org/api/EventSource.html

Creates a new EventSource instance and initiates a connection to the specified URL.

```APIDOC
## new EventSource(url, eventSourceInitDict)

### Description
Creates a new EventSource instance and immediately begins connecting to the provided URL. The request is sent with the `Accept: text/event-stream` header.

### Parameters
- **url** (string | URL) - Required - The URL of the event stream.
- **eventSourceInitDict** (Object) - Optional - Configuration object containing `withCredentials` (boolean), `dispatcher` (Dispatcher), and `node` (Object with `dispatcher` and `reconnectionTime`).

### Example
```javascript
import { EventSource } from 'undici'
const eventSource = new EventSource('http://localhost:3000', {
  withCredentials: true
})
```
```

--------------------------------

### Initialize MockAgent

Source: https://undici.nodejs.org/api/MockAgent.html

Instantiate a new MockAgent to begin intercepting requests.

```javascript
import { MockAgent } from 'undici'

const mockAgent = new MockAgent()
```

--------------------------------

### Subscribe to undici:client:connectError

Source: https://undici.nodejs.org/api/DiagnosticsChannel.json

Listen for connection establishment failures. Use this to log or handle errors when a client fails to connect.

```mjs
import diagnosticsChannel from 'node:diagnostics_channel'

diagnosticsChannel.channel('undici:client:connectError').subscribe(({ error, socket, connectParams, connector }) => {
  console.error(`Connect failed with ${error.message}`)
})
```

--------------------------------

### Composing Interceptors with Agent

Source: https://undici.nodejs.org/api/Interceptors.html

Demonstrates how to compose multiple interceptors like retry, redirect, and decompress on an Agent instance.

```javascript
import { Agent, interceptors } from 'undici'

const { retry, redirect, decompress, dump, responseError, dns, cache, deduplicate } = interceptors

const agent = new Agent().compose([
  retry({ maxRetries: 3 }),
  redirect({ maxRedirections: 5 }),
  decompress()
])

const response = await agent.request({ origin: 'https://example.com', path: '/', method: 'GET' })
```

--------------------------------

### Constructing EnvHttpProxyAgent

Source: https://undici.nodejs.org/api/EnvHttpProxyAgent.json

Instantiate the agent with default environment variables or override them with explicit configuration options.

```mjs
import { EnvHttpProxyAgent } from 'undici'

const envHttpProxyAgent = new EnvHttpProxyAgent()
// or, overriding the environment variables explicitly:
const envHttpProxyAgentWithOpts = new EnvHttpProxyAgent({
  httpProxy: 'my.proxy.server:8080',
  httpsProxy: 'my.proxy.server:8443',
  noProxy: 'localhost'
})
```

--------------------------------

### undici.fetch(input[, init])

Source: https://undici.nodejs.org/index.html

Implements the Fetch API for making network requests.

```APIDOC
## undici.fetch(input[, init])

### Description
Implements the standard Fetch API for making network requests.

### Parameters
- **input** (string | URL | Request) - Required - The resource to fetch.
- **init** (RequestInit) - Optional - Configuration options including method, body, and headers.
```
Tokens:
Raw