{"id":16167,"library":"parse-headers","title":"HTTP Header Parser","description":"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.","status":"maintenance","version":"2.0.6","language":"javascript","source_language":"en","source_url":"https://github.com/kesla/parse-headers","tags":["javascript","http","headers","typescript"],"install":[{"cmd":"npm install parse-headers","lang":"bash","label":"npm"},{"cmd":"yarn add parse-headers","lang":"bash","label":"yarn"},{"cmd":"pnpm add parse-headers","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The package provides a default export. Use `import parse from 'parse-headers'` for ESM or TypeScript, or `const parse = require('parse-headers')` for CommonJS.","wrong":"import { parse } from 'parse-headers'","symbol":"parse","correct":"import parse from 'parse-headers'"},{"note":"This is the classic CommonJS `require` syntax. For modern Node.js or browser environments using ES Modules, prefer the `import` statement.","wrong":"import parse from 'parse-headers'","symbol":"parse","correct":"const parse = require('parse-headers')"},{"note":"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.","symbol":"ParsedHeaders","correct":"import type { ParsedHeaders } from 'parse-headers'"}],"quickstart":{"code":"import parse from 'parse-headers';\n\nconst headersString = [\n  'Date: Sun, 17 Aug 2014 16:24:52 GMT',\n  'Content-Type: text/html; charset=utf-8',\n  'Transfer-Encoding: chunked',\n  'X-Custom-Header: beep',\n  'X-Custom-Header: boop',\n  'Accept-Language: en-US,en;q=0.9,fr;q=0.8'\n].join('\\n');\n\nconst parsed = parse(headersString);\n\nconsole.log(parsed);\n/*\nOutput:\n{\n  date: 'Sun, 17 Aug 2014 16:24:52 GMT',\n  'content-type': 'text/html; charset=utf-8',\n  'transfer-encoding': 'chunked',\n  'x-custom-header': [ 'beep', 'boop' ],\n  'accept-language': 'en-US,en;q=0.9,fr;q=0.8'\n}\n*/\n\n// Accessing a single header\nconsole.log('Content Type:', parsed['content-type']);\n// Accessing a repeated header\nconsole.log('Custom Headers:', parsed['x-custom-header']);","lang":"typescript","description":"Demonstrates parsing a multi-line HTTP header string into a JavaScript object, showing how duplicate headers are handled as arrays."},"warnings":[{"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`.","message":"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.","severity":"gotcha","affected_versions":">=2.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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'];`","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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`).","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).","error":"ReferenceError: require is not defined"},{"fix":"Correct the import statement to use a default import: `import parse from 'parse-headers';`","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'`).","error":"TypeError: (0 , parse_headers__WEBPACK_IMPORTED_MODULE_0__.parse) is not a function"},{"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']];`","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.","error":"Unexpected single string instead of an array for a repeated header"}],"ecosystem":"npm"}