Headers.ts

Headers.ts overview

Models HTTP headers for the unstable HTTP client and server modules.

Headers values are immutable maps keyed by lowercase header name. This module converts common header inputs into that shape, provides helpers for reading and updating header values, and redacts configured sensitive headers when values are inspected.

Since v4.0.0

---

Exports Grouped by Category

• combinators
  • get
  • has
  • merge
  • redact
  • remove
  • removeMany
  • set
  • setAll
• constructors
  • empty
  • fromInput
  • fromRecordUnsafe
• fiber refs
  • CurrentRedactedNames
• instances
  • Equivalence
• models
  • Headers (interface)
  • Input (type alias)
• refinements
  • isHeaders
• schemas
  • HeadersSchema
  • HeadersSchema (interface)
• type IDs
  • TypeId
  • TypeId (type alias)

---

combinators

get

Gets a header value by name safely.

Details

The lookup lowercases the provided header name and returns Option.none() when absent.

Signature

declare const get: {
  (key: string): (self: Headers) => Option.Option<string>
  (self: Headers, key: string): Option.Option<string>
}

Source

Since v4.0.0

has

Returns true when a header with the given name is present.

Details

The lookup lowercases the provided header name.

Signature

declare const has: { (key: string): (self: Headers) => boolean; (self: Headers, key: string): boolean }

Source

Since v4.0.0

merge

Returns a new Headers collection containing headers from both collections.

Details

Headers from the second collection override headers from the first collection with the same name.

Signature

declare const merge: { (headers: Headers): (self: Headers) => Headers; (self: Headers, headers: Headers): Headers }

Source

Since v4.0.0

redact

Returns a plain record with selected header values wrapped in Redacted.

Details

String keys are normalized to lowercase before matching; regular expressions are tested against the stored header names.

Signature

declare const redact: {
  (key: string | RegExp | ReadonlyArray<string | RegExp>): (self: Headers) => Record<string, string | Redacted.Redacted>
  (self: Headers, key: string | RegExp | ReadonlyArray<string | RegExp>): Record<string, string | Redacted.Redacted>
}

Source

Since v4.0.0

remove

Returns a new Headers collection with the named header removed.

Details

The provided header name is normalized to lowercase before removal.

Signature

declare const remove: { (key: string): (self: Headers) => Headers; (self: Headers, key: string): Headers }

Source

Since v4.0.0

removeMany

Returns a new Headers collection with each named header removed.

Details

Each provided header name is normalized to lowercase before removal.

Signature

declare const removeMany: {
  (keys: Iterable<string>): (self: Headers) => Headers
  (self: Headers, keys: Iterable<string>): Headers
}

Source

Since v4.0.0

set

Returns a new Headers collection with the given header set.

Details

The header name is normalized to lowercase.

Signature

declare const set: {
  (key: string, value: string): (self: Headers) => Headers
  (self: Headers, key: string, value: string): Headers
}

Source

Since v4.0.0

setAll

Returns a new Headers collection with all provided headers set.

Details

Input headers are normalized with fromInput and override existing headers with the same lowercase name.

Signature

declare const setAll: { (headers: Input): (self: Headers) => Headers; (self: Headers, headers: Input): Headers }

Source

Since v4.0.0

constructors

empty

An empty Headers collection.

Signature

declare const empty: Headers

Source

Since v4.0.0

fromInput

Creates Headers from a record or iterable of header entries.

Details

Header names are normalized to lowercase. Array values in record input are joined with ", ", and undefined values are omitted.

Signature

declare const fromInput: (input?: Input) => Headers

Source

Since v4.0.0

fromRecordUnsafe

Treats an existing record as Headers unsafely.

Gotchas

This mutates the record’s prototype and does not normalize header names; callers must provide the expected lowercase keys.

Signature

declare const fromRecordUnsafe: (input: Record.ReadonlyRecord<string, string>) => Headers

Source

Since v4.0.0

fiber refs

CurrentRedactedNames

Context reference listing header names or patterns that should be redacted when Headers are inspected or rendered.

Details

Defaults include authorization, cookie, set-cookie, and x-api-key.

Signature

declare const CurrentRedactedNames: Context.Reference<ReadonlyArray<string | RegExp>>

Source

Since v4.0.0

instances

Equivalence

Provides an Equivalence instance that compares Headers by header names and string values.

Signature

declare const Equivalence: Equ.Equivalence<Headers>

Source

Since v4.0.0

models

Headers (interface)

Represents an immutable HTTP header collection keyed by lowercase header name.

Details

Headers values also support redaction through the Redactable protocol.

Signature

export interface Headers extends Redactable.Redactable {
  readonly [TypeId]: TypeId
  readonly [key: string]: string
}

Source

Since v4.0.0

Input (type alias)

Input accepted when constructing headers.

Details

Records may contain string values, string arrays, or undefined; arrays are joined with ", ", and undefined values are omitted.

Signature

type Input =
  | Record.ReadonlyRecord<string, string | ReadonlyArray<string> | undefined>
  | Iterable<readonly [string, string]>

Source

Since v4.0.0

refinements

isHeaders

Returns true if the provided value is a Headers value.

Signature

declare const isHeaders: (u: unknown) => u is Headers

Source

Since v4.0.0

schemas

HeadersSchema

Schema for Headers values encoded as records of string header values.

Details

Decoding normalizes header names through fromInput; encoding returns a plain record.

Signature

declare const HeadersSchema: HeadersSchema

Source

Since v4.0.0

HeadersSchema (interface)

Schema interface for Headers values encoded as records of string header values.

Signature

export interface HeadersSchema extends Schema.declare<Headers, { readonly [x: string]: string }> {}

Source

Since v4.0.0

type IDs

TypeId

Runtime type identifier for Headers values.

Signature

declare const TypeId: unique symbol

Source

Since v4.0.0

TypeId (type alias)

Type of the unique symbol used to brand Headers values.

Signature

type TypeId = typeof TypeId

Source

Since v4.0.0