Headers unstable
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.
It also parses and formats the values of standard headers, such as HTTP
dates and Retry-After, with the tolerance the RFCs allow and nothing more.
The string codecs for those values live in Schema, for example
Schema.DateTimeUtcFromHttpDate and Schema.RetryAfterFromString.
Combinators
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<string>; (self: Headers, key: string): Option<string>;}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;}isRedactedName
unstableChecks whether a header name matches one of the redaction patterns.
Details
String patterns are compared case-insensitively against the header name;
regular expressions are tested against it. Use to avoid the record copy of
redact when only a membership check is needed.
Signature
declare function isRedactedName(name: string, patterns: readonly Array<string | RegExp>): booleanReturns 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;}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 | readonly Array<string | RegExp>): (self: Headers) => Record<string, string | Redacted.Redacted>; (self: Headers, key: string | RegExp | readonly Array<string | RegExp>): Record<string, string | Redacted.Redacted>;}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;}removeMany
unstableReturns 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;}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;}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;}Constructors
An empty Headers collection.
Signature
declare const empty: HeadersCreates 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) => HeadersfromRecordUnsafe
unstableTreats 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 function fromRecordUnsafe(input: Record.ReadonlyRecord<string, string>): HeadersretryAfterDateTime
unstableCreates a Retry-After value from an HTTP date.
Signature
declare function retryAfterDateTime(dateTime: Utc): RetryAfterretryAfterDuration
unstableCreates a Retry-After value from a delay.
Details
Infinite durations, positive or negative, have no header form and throw. That check runs first; a finite negative duration then becomes zero. Fractional seconds are kept, and formatRetryAfter rounds them up so the header never asks for a shorter wait.
A plain number is read as milliseconds, as everywhere in Duration: pass
"120 seconds" or Duration.seconds(120) for a two-minute delay.
Signature
declare function retryAfterDuration(input: Input): RetryAfterErrors
HeaderParseError
unstableError returned when a header value does not match its grammar.
Details
Inspect reason to find the header that failed and the rejected input.
Signature
declare class HeaderParseError extends YieldableError<this> & { readonly _tag: "HeaderParseError";} & Readonly<{ readonly reason: HeaderParseErrorReason;}> { constructor(args: { readonly reason: HeaderParseErrorReason; }); readonly "~effect/http/Headers/HeaderParseError": "~effect/http/Headers/HeaderParseError"; message: string; static fromReason(reason: "InvalidHttpDate" | "InvalidRetryAfter", input: string): HeaderParseError;}HeaderParseErrorReason
unstableError reason describing which header value failed to parse.
Details
input is the raw header value that was rejected.
Signature
declare class HeaderParseErrorReason extends Error<{ readonly _tag: "InvalidHttpDate" | "InvalidRetryAfter"; readonly input: string;}> { constructor(args: { readonly _tag: "InvalidHttpDate" | "InvalidRetryAfter"; readonly input: string; });}Guards
isHeaderParseError
unstableChecks whether a value is a HeaderParseError.
Signature
declare function isHeaderParseError(u: unknown): u is HeaderParseErrorReturns true if the provided value is a Headers value.
Signature
declare function isHeaders(u: unknown): u is HeadersHeader Values
formatHttpDate
unstableFormats a DateTime as an IMF-fixdate HTTP date, such as
Sun, 06 Nov 1994 08:49:37 GMT.
Signature
declare function formatHttpDate(self: DateTime): stringformatRetryAfter
unstableFormats a Retry-After value as a header value: the delay as whole
seconds, or the date as an IMF-fixdate.
Details
A delay with a fractional second is rounded up, since Retry-After is the
least time to wait. Large delays are written as exact decimal digits.
Signature
declare function formatRetryAfter(self: RetryAfter): stringparseHttpDate
unstableParses an HTTP date header value into a UTC DateTime.
Details
Accepts the three formats of RFC 9110 §5.6.7: the preferred IMF-fixdate
(Sun, 06 Nov 1994 08:49:37 GMT), the obsolete RFC 850 format
(Sunday, 06-Nov-94 08:49:37 GMT) and the asctime format
(Sun Nov 6 08:49:37 1994). All three are read as UTC regardless of the
process time zone. Day and month names are case-insensitive, and the day
name is not checked against the date. A leap second (23:59:60) is read
as the following second, since epoch time cannot represent it.
The two-digit year of the RFC 850 format is read with a fixed pivot:
70-99 as 1970-1999 and 00-69 as 2000-2069. This deviates from
RFC 9110, which asks for the year to be chosen relative to the current
time so that it is never more than 50 years in the future. The fixed pivot
keeps parsing independent of the clock and matches most other HTTP
implementations.
Signature
declare function parseHttpDate(input: string): Result<Utc, HeaderParseError>parseRetryAfter
unstableParses a Retry-After header value.
Details
Accepts whole non-negative seconds (120) of any size, read exactly, or an
HTTP date in any of the formats parseHttpDate accepts. Fractional,
negative, exponent and non-finite numbers are rejected, as are dates in
other formats.
Signature
declare function parseRetryAfter(input: string): Result<RetryAfter, HeaderParseError>retryAfterDelay
unstableComputes how long to wait for a Retry-After value, measured from now
in epoch milliseconds.
Details
A date that is already in the past yields a zero duration, never a negative one. Compute the delay when the retry is scheduled rather than when the header is parsed, so the wait reflects the time already spent.
Signature
declare function retryAfterDelay(self: RetryAfter, now: number): DurationInstances
Equivalence
unstableProvides an Equivalence instance that compares Headers by header names
and string values.
Signature
declare const Equivalence: Equ.Equivalence<Headers>RetryAfterEquivalence
unstableProvides an Equivalence instance for Retry-After values.
Signature
declare const RetryAfterEquivalence: Equ.Equivalence<RetryAfter>Models
Represents an immutable HTTP header collection keyed by lowercase header name.
Details
Headers values also support redaction through the Redactable protocol.
Signature
interface Headers extends Redactable { [key: string]: string; readonly [TypeId]: typeof TypeId;}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]>Represents a parsed Retry-After header value.
Details
The header carries either a delay in whole seconds or an absolute HTTP
date. Use retryAfterDelay to turn either form into a Duration
measured from a given instant.
Signature
type RetryAfter = RetryAfterDuration | RetryAfterDateTimeA Retry-After value given as an HTTP date.
Signature
interface RetryAfterDateTime { readonly _tag: "DateTime"; readonly dateTime: Utc;}A Retry-After value given as a delay.
Details
The duration is always finite and non-negative. On the wire it is written as whole seconds, rounded up.
Signature
interface RetryAfterDuration { readonly _tag: "Duration"; readonly duration: Duration;}Services
CurrentRedactedNames
unstableContext 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.
A custom list replaces the defaults. Matching uses isRedactedName.
Use UrlParams.CurrentRedactedNames for query parameters.
Signature
declare const CurrentRedactedNames: Reference<readonly Array<string | RegExp>>