or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

connection-management.mdcookies.mderror-handling.mdhttp-api.mdhttp-clients.mdindex.mdinterceptors.mdtesting-mocking.mdutilities.mdweb-standards.md
tile.json

tessl/npm-undici-types

A stand-alone types package for Undici HTTP client library

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/undici-types@7.15.x

To install, run

npx @tessl/cli install tessl/npm-undici-types@7.15.0

index.mddocs/

undici-types

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.

Package Information

  • Package Name: undici-types
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install undici-types

Core Imports

import { Dispatcher, Client, Pool, Agent } from "undici-types";

For specific API functions:

import { request, stream, pipeline, connect, upgrade } from "undici-types";

For web-compatible APIs:

import { fetch, Headers, Request, Response, WebSocket, FormData } from "undici-types";

Basic Usage

import { Client, request } from "undici-types";

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

// Using the request function
const response = await request("https://example.com/api", {
  method: "POST",
  headers: {
    "content-type": "application/json"
  },
  body: JSON.stringify({ message: "hello" })
});

const data = await response.body.json();

Architecture

undici-types is organized around several key architectural patterns:

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

Capabilities

Core HTTP Clients

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

class Client extends Dispatcher {
  constructor(url: string | URL, options?: Client.Options);
  readonly pipelining: number;
  readonly closed: boolean;
  readonly destroyed: boolean;
}

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

class Agent extends Dispatcher {
  constructor(options?: Agent.Options);
  readonly closed: boolean;
  readonly destroyed: boolean;
}

HTTP Clients

HTTP API Functions

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

function request(
  url: string | URL,
  options?: Dispatcher.RequestOptions
): Promise<Dispatcher.ResponseData>;

function stream(
  url: string | URL,
  options: Dispatcher.RequestOptions,
  factory: Dispatcher.StreamFactory
): Promise<Dispatcher.StreamData>;

function pipeline(
  url: string | URL,
  options: Dispatcher.PipelineOptions,
  handler: Dispatcher.PipelineHandler
): Promise<Dispatcher.PipelineData>;

HTTP API Functions

Web Standards APIs

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

function fetch(
  input: RequestInfo,
  init?: RequestInit
): Promise<Response>;

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

class FormData {
  append(name: string, value: string | Blob, fileName?: string): void;
  set(name: string, value: string | Blob, fileName?: string): void;
  get(name: string): FormDataEntryValue | null;
  has(name: string): boolean;
}

Web Standards APIs

Connection Management

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

class BalancedPool extends Dispatcher {
  constructor(url: string | URL | string[], options?: Pool.Options);
  addUpstream(upstream: string | URL): BalancedPool;
  removeUpstream(upstream: string | URL): BalancedPool;
}

class ProxyAgent extends Dispatcher {
  constructor(options: ProxyAgent.Options);
}

class EnvHttpProxyAgent extends Dispatcher {
  constructor(options?: EnvHttpProxyAgent.Options);
}

Connection Management

Error Handling

Comprehensive error hierarchy covering all HTTP operation failure modes.

class UndiciError extends Error {
  name: string;
  code: string;
}

class ConnectTimeoutError extends UndiciError {}
class HeadersTimeoutError extends UndiciError {}
class BodyTimeoutError extends UndiciError {}
class ResponseStatusCodeError extends UndiciError {
  body: any;
  status: number;
  statusText: string;
}

Error Handling

Testing and Mocking

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

class MockAgent extends Dispatcher {
  constructor(options?: MockAgent.Options);
  get(origin: string): MockClient;
  close(): Promise<void>;
  deactivate(): void;
  activate(): void;
  enableNetConnect(matcher?: string | RegExp | Function): void;
  disableNetConnect(): void;
}

class MockClient extends Dispatcher {
  intercept(options: MockInterceptor.Options): MockInterceptor;
}

Testing and Mocking

Cookie Management

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

interface Cookie {
  name: string;
  value: string;
  expires?: Date | number;
  maxAge?: number;
  domain?: string;
  path?: string;
  secure?: boolean;
  httpOnly?: boolean;
  sameSite?: 'Strict' | 'Lax' | 'None';
  unparsed?: string[];
}

function getCookies(headers: Headers): Record<string, string>;
function getSetCookies(headers: Headers): Cookie[];
function setCookie(headers: Headers, cookie: Cookie): void;
function deleteCookie(headers: Headers, name: string, attributes?: { name?: string; domain?: string; path?: string; }): void;
function parseCookie(cookie: string): Cookie | null;

Cookie Management

Interceptors and Middleware

Request/response transformation and error handling middleware system.

interface Interceptor {
  (dispatch: Dispatcher['dispatch']): Dispatcher['dispatch'];
}

namespace interceptors {
  function dump(options?: DumpInterceptorOpts): Interceptor;
  function retry(options?: RetryInterceptorOpts): Interceptor;
  function redirect(options?: RedirectInterceptorOpts): Interceptor;
  function decompress(options?: DecompressInterceptorOpts): Interceptor;
}

Interceptors

Utilities

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

function buildConnector(options?: buildConnector.Options): buildConnector.connector;

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

function parseMIMEType(input: string): MIMEType | null;
function serializeAMimeType(mimeType: MIMEType): string;

Utilities