Class HttpHeaders

Cross-runtime HTTP headers implementation compatible with the WHATWG Fetch spec Headers interface. Supports guard-based mutation control, RFC 7230 validation, and rich typed accessors.

Differences from WHATWG Headers:

Supports clone, freeze, merge, pick, omit, redact, diff
Preserves original header-name casing via toHTTP1String
Multi-value headers (Set-Cookie) are always kept separate, never joined
Guards are enforced synchronously

Hierarchy (View Summary)

HttpHeaders
- RichHeaders

Index

Constructors

constructor

new HttpHeaders(
    init?:
        | HeadersInit
        | Record<string, string | string[]>
        | HttpHeaders
        | null,
    guard?: HeadersGuard,
): HttpHeaders
Parameters
- Optionalinit: HeadersInit | Record<string, string | string[]> | HttpHeaders | null
  Optional initial headers (WHATWG Headers, HttpHeaders, plain object, or [name, value][] array)
- guard: HeadersGuard = "none"
  Guard mode (default: "none")
Returns HttpHeaders
- Defined in src/headers.ts:420

Accessors

[toStringTag]

get "[toStringTag]"(): string
Returns string
The string tag "HttpHeaders"
- Defined in src/headers.ts:606

size

get size(): number
Number of distinct header names.

Returns number
- Defined in src/headers.ts:746

Methods

append

append(name: string, value: string): void
Append a value to an existing header (or create it). Unlike set, this does NOT overwrite existing values.
Parameters
- name: string
  Header name (case-insensitive)
- value: string
  Header value (leading/trailing OWS stripped)
Returns void
Throws
TypeError If the guard forbids mutation or name/value is invalid
- Defined in src/headers.ts:476

delete

delete(name: string): void
Delete a header by name.
Parameters
- name: string
  Header name (case-insensitive)
Returns void
Throws
TypeError If the guard forbids deletion
- Defined in src/headers.ts:494

get

get(name: string): string | null
Return the combined value of a header. Multiple values are joined with ", " except for Set-Cookie / WWW-Authenticate / Proxy-Authenticate, which return only the first value.
Parameters
- name: string
  Header name (case-insensitive)
Returns string | null
The combined header value, or null if absent
- Defined in src/headers.ts:507

getAll

getAll(name: string): string[]
Return all values for a header as an array (useful for Set-Cookie).
Parameters
- name: string
  Header name (case-insensitive)
Returns string[]
Array of values (empty if absent)
- Defined in src/headers.ts:520

has

has(name: string): boolean
Check if a header exists.
Parameters
- name: string
  Header name (case-insensitive)
Returns boolean
true if the header is set
- Defined in src/headers.ts:530

set

set(name: string, value: string): void
Set a header, overwriting any existing values for that name.
Parameters
- name: string
  Header name (case-insensitive)
- value: string
  Header value (leading/trailing OWS stripped)
Returns void
Throws
TypeError If the guard forbids mutation or name/value is invalid
- Defined in src/headers.ts:541

forEach

forEach(
callback: (value: string, name: string, headers: HttpHeaders) => void,
thisArg?: unknown,
): void
Execute a callback for each header entry. Multi-value headers are joined with ", " for the callback, except for Set-Cookie (each value is called separately).
Parameters
- callback: (value: string, name: string, headers: HttpHeaders) => void
  Called once per combined value with (value, name, headers)
- OptionalthisArg: unknown
  Value for this inside the callback
Returns void
- Defined in src/headers.ts:556

keys

keys(): IterableIterator<string>
Iterator over all header names (lowercased).

Returns IterableIterator<string>
- Defined in src/headers.ts:569

values

values(): IterableIterator<string>
Iterator over all header values. Multi-value headers are joined with ", " except Set-Cookie.

Returns IterableIterator<string>
- Defined in src/headers.ts:577

entries

entries(): IterableIterator<[string, string]>
Iterator over [name, value] tuples (WHATWG Headers-compatible).

Returns IterableIterator<[string, string]>
- Defined in src/headers.ts:590

[iterator]

"[iterator]"(): IterableIterator<[string, string]>
Returns IterableIterator<[string, string]>
See
entries
- Defined in src/headers.ts:601

toObject

toObject(): Record<string, string | string[]>
Convert to a plain object. Multi-value headers become arrays.

Returns Record<string, string | string[]>
- Defined in src/headers.ts:613

toFlatObject

toFlatObject(): Record<string, string>
Convert to a flat object. Multi-value headers are joined with ", ".

Returns Record<string, string>
- Defined in src/headers.ts:623

toWebHeaders

toWebHeaders(): Headers
Convert to WHATWG Headers (when available in the runtime).

Returns Headers
Throws
If WHATWG Headers is not available in this runtime
- Defined in src/headers.ts:636

toHTTP1String

toHTTP1String(): string
Serialize as HTTP/1.1 header block (CRLF-delimited).

Returns string
- Defined in src/headers.ts:648

clone

clone(guard?: HeadersGuard): HttpHeaders
Clone this headers object.
Parameters
- Optionalguard: HeadersGuard
Returns HttpHeaders
- Defined in src/headers.ts:659

freeze

freeze(): HttpHeaders
Return a new immutable copy.

Returns HttpHeaders
- Defined in src/headers.ts:664

merge

merge(
other: Record<string, string | string[]> | HttpHeaders,
options?: { append?: boolean },
): this
Merge another headers source into this one. Existing values are overwritten unless append is true.
Parameters
- other: Record<string, string | string[]> | HttpHeaders
- options: { append?: boolean } = {}
Returns this
- Defined in src/headers.ts:674

pick

pick(...names: string[]): HttpHeaders
Return a new HttpHeaders containing only the listed header names.
Parameters
- ...names: string[]
Returns HttpHeaders
- Defined in src/headers.ts:692

omit

omit(...names: string[]): HttpHeaders
Return a new HttpHeaders without the listed header names.
Parameters
- ...names: string[]
Returns HttpHeaders
- Defined in src/headers.ts:705

redact

redact(...names: string[]): HttpHeaders
Redact sensitive header values (replace with "REDACTED"). Useful for logging.
Parameters
- ...names: string[]
Returns HttpHeaders
- Defined in src/headers.ts:715

diff

diff(other: HttpHeaders): HttpHeaders
Returns headers present in other that differ from this instance (by combined value). Useful for diffing request/response headers.
Parameters
- other: HttpHeaders
Returns HttpHeaders
- Defined in src/headers.ts:731

Class HttpHeaders

Hierarchy (View Summary)

Index

Constructors

Accessors

Methods

Constructors

constructor

Parameters

Returns HttpHeaders

Accessors

[toStringTag]

Returns string

size

Returns number

Methods

append

Parameters

Returns void

Throws

delete

Parameters

Returns void

Throws

get

Parameters

Returns string | null

getAll

Parameters

Returns string[]

has

Parameters

Returns boolean

set

Parameters

Returns void

Throws

forEach

Parameters

Returns void

keys

Returns IterableIterator<string>

values

Returns IterableIterator<string>

entries

Returns IterableIterator<[string, string]>

[iterator]

Returns IterableIterator<[string, string]>

See

toObject

Returns Record<string, string | string[]>

toFlatObject

Returns Record<string, string>

toWebHeaders

Returns Headers

Throws

toHTTP1String

Returns string

clone

Parameters

Returns HttpHeaders

freeze

Returns HttpHeaders

merge

Parameters

Returns this

pick

Parameters

Returns HttpHeaders

omit

Parameters

Returns HttpHeaders

redact

Parameters

Returns HttpHeaders

diff

Parameters

Returns HttpHeaders

Settings

On This Page