Headers

Header names, header-value builders, and the Headers extensions the framework relies on.

Two things happen here. HeaderKey gives the common header names as documented constants, so header access is autocompleted and typo-free rather than stringly typed. patchGlobalHeaders then extends the global Headers class with conveniences the native API lacks: non-string values, bulk assignment through Headers.setMany, and structured builders for Cache-Control and Content-Disposition.

The patch is what lets Res, FileRoute and BundleRoute write headers without stringifying every value by hand. It applies to the process's own Headers, so it must be installed once at startup, before any request is served.

Headers

interface — augments global

interface Headers

The Headers surface after patchGlobalHeaders has run.

The existing methods are re-declared to accept a HeaderKey and a HeadersInitValue; the rest are additions.

Headers.append()

append(name: HeaderKey, value: MaybeArray<HeadersInitValue>): void

Adds a value without replacing existing ones. An array appends each item as its own header line.

Headers.set()

set(name: HeaderKey, value: HeadersInitValue): void

Sets a header, replacing any existing value. Numbers and booleans are stringified.

Headers.get()

get(name: HeaderKey): Nullable<string>

Reads a header, falling back to the lowercased name.

Headers.has()

has(name: HeaderKey): boolean

Reports whether a header is present, falling back to the lowercased name.

Headers.setMany()

setMany(init: CustomHeadersInit): void

Sets many headers at once. See CustomHeadersInit.

Headers.setCacheControl()

setCacheControl(def: CacheControlDefinition): void

Sets Cache-Control from a CacheControlDefinition.

Headers.setContentDisposition()

setContentDisposition(def: ContentDispositionDefinition): void

Sets Content-Disposition from a ContentDispositionDefinition.

patchGlobalHeaders

function

function patchGlobalHeaders();

Installs the extended Headers behaviour declared above onto the global class. Call it once at startup, before any request is served.

The patch is applied twice over, deliberately. The prototype methods are replaced so headers the runtime created — those on an incoming Request, or on a Response built elsewhere — gain the same behaviour. The global class is then also replaced with a subclass, so instances constructed after the patch carry the methods as own class members rather than only as prototype assignments.

The subclass overrides Symbol.hasInstance to defer to the native class, so instanceof Headers stays true for objects the runtime created before or outside the patch. Without it, the swap would silently break every instanceof check against headers the framework did not construct.

createCacheControlHeader

function

function createCacheControlHeader(def: CacheControlDefinition): string;

Renders a CacheControlDefinition into a Cache-Control header value.

The two prohibitive directives take precedence and are emitted alone, since combining them with freshness directives is contradictory: noStore wins over everything, then noCache. Otherwise the remaining directives are joined in order.

Parameters

• def — The caching policy to render.

Returns — The header value, or an empty string when the definition sets nothing.

createContentDispositionHeader

function

function createContentDispositionHeader(def: ContentDispositionDefinition);

Renders a ContentDispositionDefinition into a Content-Disposition header value.

Parameters

• def — The disposition to render.

Returns — The header value, with a quoted filename parameter when one is given.

readHeader

function

function readHeader(headers: Optional<HeadersInit>, name: HeaderKey): Nullable<string>;

Reads a header from any HeadersInit shape, without constructing a Headers.

Header names are case-insensitive, so every shape is matched case-insensitively: a Headers instance is probed with both casings, and the array and object forms are scanned with lowercased comparison.

Parameters

• headers — The headers to read, in any accepted form. undefined and null are allowed and yield null.
• name — The header to look for.

Returns — The value, or null when absent.

HeaderKey

const

const HeaderKey;
type HeaderKey = OrString<ValueOf<typeof HeaderKey>>;

Just some common headers. See MDN Reference for the full spec.

A header name. The HeaderKey constants are suggested, but OrString keeps any custom header name assignable — the enum is a convenience, not a restriction.

ContentDispositionDefinition

interface

interface ContentDispositionDefinition

How a response body should be presented, rendered by createContentDispositionHeader.

CacheControlDefinition

interface

interface CacheControlDefinition

A caching policy, rendered into a Cache-Control value by createCacheControlHeader. Used by FileRoute.cache and by each entry of a BundleRouteDefinition.