Parse Raw HTTP Headers into a Key-Value Object

Header names are normalized to lowercase, surrounding whitespace is removed from values, and repeated names such as Set-Cookie are preserved in order as arrays instead of being overwritten. Every nonempty line must use the standard Name: Value structure, so malformed input produces a clear error rather than a partially trusted result. The parser is deterministic and runs without network access.

Turn copied header blocks into usable structured data

Browser developer tools, command-line clients, reverse proxies, and server logs often present HTTP headers as plain lines. That representation is easy for a person to scan but awkward for code to query, compare, or store. This parser converts each valid Name: Value line into a property under a single headers object. Names are normalized to lowercase because HTTP field names are case-insensitive, which means Content-Type and content-type resolve to the same property. Whitespace surrounding the value is removed, while colons inside the value remain untouched. That distinction matters for timestamps, URLs, authorization schemes, and other values that legitimately contain punctuation. The result can be copied directly into a fixture, passed to another script, or compared with an expected response. A trailing blank line is accepted because copied HTTP header sections commonly end with the empty separator that precedes a message body. Blank or malformed lines inside the block are rejected so an incomplete parse cannot quietly look successful.

Preserve duplicate headers instead of losing information

A plain JavaScript object normally stores one value per key, so a simplistic parser overwrites earlier values whenever a name appears twice. That behavior can silently discard meaningful protocol data. This capability returns a string when a header occurs once and changes that property to an array when the same case-insensitive name occurs again. Additional occurrences are appended in their original order. The rule works for Set-Cookie, Warning, Link, and any other repeated field without attempting to combine values using commas. Avoiding automatic comma joining is intentional: different header fields have different combination rules, and Set-Cookie in particular must not be treated like a generic comma-separated list. An empty value is still valid when the colon is present, so X-Optional: becomes an empty string rather than an error. The parser does not interpret dates, cookies, media types, quality weights, or authentication credentials. It preserves field values as text, leaving protocol-specific interpretation to the component that understands that header.

Detect malformed lines early and use the result safely

Reliable parsing is as much about rejection as conversion. Each input line must begin with a valid HTTP field name, immediately followed by a colon and then its value. Field names may contain the token characters allowed by HTTP, but they cannot contain spaces, tabs, parentheses, separators, or leading whitespace. Obsolete folded continuation lines are rejected rather than attached to the previous value, which prevents ambiguous results and encourages callers to provide a modern normalized header block. When validation fails, the error identifies the relevant line and explains whether the pair or the name is invalid. No partial object is returned. This makes the capability useful in import pipelines and automated tests where accepting half of a block would be worse than stopping. Processing is local and deterministic: there are no network requests, time-dependent fields, random values, or external lookups. The same text therefore produces the same JSON structure in browser use and through the API, whose base request price is $0.002.