Registry / http-networking / parse-headers

parse-headers

JSON →
library2.0.6jsnpmunverified

The `parse-headers` package is a lightweight utility designed to transform raw HTTP header strings into a JavaScript object. It is currently at version 2.0.6, with its last update occurring approximately one year ago (as of early 2024), indicating a slow release cadence and minimal active development. The library's core functionality involves parsing a multi-line header string, lowercasing all header names, and consolidating multiple instances of the same header into an array of values. It distinguishes itself by being a zero-dependency solution, making it ideal for environments where a minimal footprint is critical, such as older browser environments via Browserify or for basic XHR header processing. Unlike more comprehensive, RFC-strict parsers that handle structured field values, `parse-headers` offers a straightforward, object-based representation suitable for common, less complex HTTP header scenarios.

http-networkingserialization
npm install parse-headers
github ↗package ↗
INSTALL
IMPORT
SIG · PARSE-HEADERS
P
parse-headers
http-networkingjavascriptv2.0.6
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

parse
✓ import parse from 'parse-headers'
✗ import { parse } from 'parse-headers'
The package provides a default export. Use `import parse from 'parse-headers'` for ESM or TypeScript, or `const parse = require('parse-headers')` for CommonJS.
parse
✓ const parse = require('parse-headers')
✗ import parse from 'parse-headers'
This is the classic CommonJS `require` syntax. For modern Node.js or browser environments using ES Modules, prefer the `import` statement.
ParsedHeaders
✓ import type { ParsedHeaders } from 'parse-headers'
The package ships with TypeScript type definitions, allowing for type-safe usage and enabling the import of its internal types, such as `ParsedHeaders` for the output object structure.

Demonstrates parsing a multi-line HTTP header string into a JavaScript object, showing how duplicate headers are handled as arrays.

import parse from 'parse-headers'; const headersString = [ 'Date: Sun, 17 Aug 2014 16:24:52 GMT', 'Content-Type: text/html; charset=utf-8', 'Transfer-Encoding: chunked', 'X-Custom-Header: beep', 'X-Custom-Header: boop', 'Accept-Language: en-US,en;q=0.9,fr;q=0.8' ].join('\n'); const parsed = parse(headersString); console.log(parsed); /* Output: { date: 'Sun, 17 Aug 2014 16:24:52 GMT', 'content-type': 'text/html; charset=utf-8', 'transfer-encoding': 'chunked', 'x-custom-header': [ 'beep', 'boop' ], 'accept-language': 'en-US,en;q=0.9,fr;q=0.8' } */ // Accessing a single header console.log('Content Type:', parsed['content-type']); // Accessing a repeated header console.log('Custom Headers:', parsed['x-custom-header']);
Debug
Known issues
gotchaThe `parse-headers` package has seen minimal updates since its initial release in 2014, with its last publish being over a year ago. While functional for basic use cases, users should be aware that active feature development, support for new HTTP RFCs, or prompt bug/security fixes are unlikely.
fix
For applications requiring active maintenance, adherence to the latest HTTP specifications (e.g., Structured Field Values for HTTP RFC 8941/9651), or advanced header parsing capabilities, consider more actively developed alternatives like `structured-headers` or `http-headers`.
affects: >=2.0.0
gotchaThis parser always converts HTTP header names to lowercase in the resulting JavaScript object. If your application relies on the original casing of header names, or if the order of duplicate headers is semantically important beyond their collection into an array, this behavior must be explicitly accounted for.
fix
Access header values using their lowercase keys (e.g., `parsed['content-type']`). If original casing is critical, post-processing or a different parsing library is required.
affects: >=1.0.0
gotchaFor headers that appear multiple times in the input string (e.g., `Set-Cookie` or custom headers), `parse-headers` consolidates all values into an array. If only the first or last instance is expected, explicit handling of the array is necessary.
fix
When accessing a potentially repeated header, check if the value is an array (`Array.isArray(parsedHeader)`) and process accordingly. For example, `const firstCustomHeader = Array.isArray(parsed['x-custom-header']) ? parsed['x-custom-header'][0] : parsed['x-custom-header'];`
affects: >=1.0.0
Errors
Common errors & fixes
ReferenceError: require is not defined
Attempting to use `require('parse-headers')` in a JavaScript file that is being interpreted as an ES Module (e.g., due to `"type": "module"` in `package.json` or `.mjs` file extension).
fix
Change the import statement to `import parse from 'parse-headers';` for ES Module compatibility. If strictly needing CommonJS, ensure the file is treated as CommonJS (e.g., `.cjs` extension or no `"type": "module"` in `package.json`).
TypeError: (0 , parse_headers__WEBPACK_IMPORTED_MODULE_0__.parse) is not a function
This error typically occurs in a bundled environment when `parse-headers` (which exports a default function) is imported as a named export (`import { parse } from 'parse-headers'`).
fix
Correct the import statement to use a default import: `import parse from 'parse-headers';`
Unexpected single string instead of an array for a repeated header
Developers might mistakenly expect a single string value for a header like 'X-Custom-Header' if it appeared multiple times in the input, not realizing the library combines them into an array.
fix
Always anticipate that repeated HTTP headers will be represented as an array of strings in the parsed object. Implement logic to handle both single string (for non-repeated headers) and array (for repeated headers) outcomes, or explicitly check `Array.isArray()` before processing. Example: `const values = Array.isArray(parsed['header-name']) ? parsed['header-name'] : [parsed['header-name']];`
Upgrade
Version history
2.0.6latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
2 hits · last 30 days
node
2
Resources
githubhttps://github.com/kesla/parse-headers ↗
packagehttps://www.npmjs.com/package/parse-headers ↗
parse-headers — npm install parse-headers · libregistry