HTTP Header Parser

Common errors

• ReferenceError: require is not defined

  cause 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

  cause 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

  cause 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']];`

Warnings

• gotcha The `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`.
• gotcha This 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.
• gotcha For 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'];`

Install

• npm install parse-headers npm
• yarn add parse-headers yarn
• pnpm add parse-headers pnpm

Imports

• parse
  wrong:

  import { parse } from 'parse-headers'

  correct:

  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
  wrong:

  import parse from 'parse-headers'

  correct:

  const parse = require('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.

Quickstart

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']);