0
# undici-types
1

2
TypeScript type definitions package for the Undici HTTP client library. This standalone package provides comprehensive type declarations for all Undici APIs without the runtime implementation, making it ideal for projects that need type safety when using Undici or requiring Undici types without bundling the library itself.
3

4
## Package Information
5

6
- **Package Name**: undici-types
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install undici-types`
10

11
## Core Imports
12

13
```typescript
14
import { Dispatcher, Client, Pool, Agent } from "undici-types";
15
```
16

17
For specific API functions:
18

19
```typescript
20
import { request, stream, pipeline, connect, upgrade } from "undici-types";
21
```
22

23
For web-compatible APIs:
24

25
```typescript
26
import { fetch, Headers, Request, Response, WebSocket, FormData } from "undici-types";
27
```
28

29
## Basic Usage
30

31
```typescript
32
import { Client, request } from "undici-types";
33

34
// Using the Client class
35
const client = new Client("https://example.com");
36

37
// Using the request function
38
const response = await request("https://example.com/api", {
39
  method: "POST",
40
  headers: {
41
    "content-type": "application/json"
42
  },
43
  body: JSON.stringify({ message: "hello" })
44
});
45

46
const data = await response.body.json();
47
```
48

49
## Architecture
50

51
undici-types is organized around several key architectural patterns:
52

53
- **Dispatcher Pattern**: Core abstraction (`Dispatcher`) for all HTTP operations, with specialized implementations (`Client`, `Pool`, `Agent`, `BalancedPool`)
54
- **HTTP/1.1 and HTTP/2 Support**: Full support for both protocols including H2C (HTTP/2 cleartext) connections
55
- **Web Standards Compatibility**: Complete implementations of `fetch`, `WebSocket`, `FormData`, and other web APIs
56
- **Connection Management**: Sophisticated pooling and connection lifecycle management with load balancing
57
- **Testing Infrastructure**: Comprehensive mocking system for unit testing HTTP interactions
58
- **Interceptor System**: Pluggable request/response transformation and error handling
59
- **Proxy Support**: Full HTTP and HTTPS proxy support with environment-based configuration
60

61
## Capabilities
62

63
### Core HTTP Clients
64

65
HTTP client implementations providing different connection management strategies and performance characteristics.
66

67
```typescript { .api }
68
class Client extends Dispatcher {
69
  constructor(url: string | URL, options?: Client.Options);
70
  readonly pipelining: number;
71
  readonly closed: boolean;
72
  readonly destroyed: boolean;
73
}
74

75
class Pool extends Dispatcher {
76
  constructor(url: string | URL, options?: Pool.Options);
77
  readonly closed: boolean;
78
  readonly destroyed: boolean;
79
}
80

81
class Agent extends Dispatcher {
82
  constructor(options?: Agent.Options);
83
  readonly closed: boolean;
84
  readonly destroyed: boolean;
85
}
86
```
87

88
[HTTP Clients](./http-clients.md)
89

90
### HTTP API Functions
91

92
Convenience functions for common HTTP operations without requiring explicit client instantiation.
93

94
```typescript { .api }
95
function request(
96
  url: string | URL,
97
  options?: Dispatcher.RequestOptions
98
): Promise<Dispatcher.ResponseData>;
99

100
function stream(
101
  url: string | URL,
102
  options: Dispatcher.RequestOptions,
103
  factory: Dispatcher.StreamFactory
104
): Promise<Dispatcher.StreamData>;
105

106
function pipeline(
107
  url: string | URL,
108
  options: Dispatcher.PipelineOptions,
109
  handler: Dispatcher.PipelineHandler
110
): Promise<Dispatcher.PipelineData>;
111
```
112

113
[HTTP API Functions](./http-api.md)
114

115
### Web Standards APIs
116

117
Web-compatible implementations of fetch, WebSocket, FormData and related APIs.
118

119
```typescript { .api }
120
function fetch(
121
  input: RequestInfo,
122
  init?: RequestInit
123
): Promise<Response>;
124

125
class WebSocket extends EventTarget {
126
  constructor(url: string | URL, protocols?: string | string[], options?: WebSocketInit);
127
  readonly readyState: number;
128
  readonly url: string;
129
  send(data: string | ArrayBuffer | ArrayBufferView): void;
130
  close(code?: number, reason?: string): void;
131
}
132

133
class FormData {
134
  append(name: string, value: string | Blob, fileName?: string): void;
135
  set(name: string, value: string | Blob, fileName?: string): void;
136
  get(name: string): FormDataEntryValue | null;
137
  has(name: string): boolean;
138
}
139
```
140

141
[Web Standards APIs](./web-standards.md)
142

143
### Connection Management
144

145
Advanced connection pooling, load balancing, and proxy support for high-performance applications.
146

147
```typescript { .api }
148
class BalancedPool extends Dispatcher {
149
  constructor(url: string | URL | string[], options?: Pool.Options);
150
  addUpstream(upstream: string | URL): BalancedPool;
151
  removeUpstream(upstream: string | URL): BalancedPool;
152
}
153

154
class ProxyAgent extends Dispatcher {
155
  constructor(options: ProxyAgent.Options);
156
}
157

158
class EnvHttpProxyAgent extends Dispatcher {
159
  constructor(options?: EnvHttpProxyAgent.Options);
160
}
161
```
162

163
[Connection Management](./connection-management.md)
164

165
### Error Handling
166

167
Comprehensive error hierarchy covering all HTTP operation failure modes.
168

169
```typescript { .api }
170
class UndiciError extends Error {
171
  name: string;
172
  code: string;
173
}
174

175
class ConnectTimeoutError extends UndiciError {}
176
class HeadersTimeoutError extends UndiciError {}
177
class BodyTimeoutError extends UndiciError {}
178
class ResponseStatusCodeError extends UndiciError {
179
  body: any;
180
  status: number;
181
  statusText: string;
182
}
183
```
184

185
[Error Handling](./error-handling.md)
186

187
### Testing and Mocking
188

189
Complete mocking system for testing HTTP interactions without real network calls.
190

191
```typescript { .api }
192
class MockAgent extends Dispatcher {
193
  constructor(options?: MockAgent.Options);
194
  get(origin: string): MockClient;
195
  close(): Promise<void>;
196
  deactivate(): void;
197
  activate(): void;
198
  enableNetConnect(matcher?: string | RegExp | Function): void;
199
  disableNetConnect(): void;
200
}
201

202
class MockClient extends Dispatcher {
203
  intercept(options: MockInterceptor.Options): MockInterceptor;
204
}
205
```
206

207
[Testing and Mocking](./testing-mocking.md)
208

209
### Cookie Management
210

211
HTTP cookie parsing, manipulation, and header integration utilities with full RFC compliance.
212

213
```typescript { .api }
214
interface Cookie {
215
  name: string;
216
  value: string;
217
  expires?: Date | number;
218
  maxAge?: number;
219
  domain?: string;
220
  path?: string;
221
  secure?: boolean;
222
  httpOnly?: boolean;
223
  sameSite?: 'Strict' | 'Lax' | 'None';
224
  unparsed?: string[];
225
}
226

227
function getCookies(headers: Headers): Record<string, string>;
228
function getSetCookies(headers: Headers): Cookie[];
229
function setCookie(headers: Headers, cookie: Cookie): void;
230
function deleteCookie(headers: Headers, name: string, attributes?: { name?: string; domain?: string; path?: string; }): void;
231
function parseCookie(cookie: string): Cookie | null;
232
```
233

234
[Cookie Management](./cookies.md)
235

236
### Interceptors and Middleware
237

238
Request/response transformation and error handling middleware system.
239

240
```typescript { .api }
241
interface Interceptor {
242
  (dispatch: Dispatcher['dispatch']): Dispatcher['dispatch'];
243
}
244

245
namespace interceptors {
246
  function dump(options?: DumpInterceptorOpts): Interceptor;
247
  function retry(options?: RetryInterceptorOpts): Interceptor;
248
  function redirect(options?: RedirectInterceptorOpts): Interceptor;
249
  function decompress(options?: DecompressInterceptorOpts): Interceptor;
250
}
251
```
252

253
[Interceptors](./interceptors.md)
254

255
### Utilities
256

257
Helper functions and utilities for HTTP operations, header manipulation, and content processing.
258

259
```typescript { .api }
260
function buildConnector(options?: buildConnector.Options): buildConnector.connector;
261

262
namespace util {
263
  function parseHeaders(headers: string[]): Record<string, string | string[]>;
264
  function headerNameToString(value: string): string;
265
}
266

267
function parseMIMEType(input: string): MIMEType | null;
268
function serializeAMimeType(mimeType: MIMEType): string;
269
```
270

271
[Utilities](./utilities.md)