HTTP Header Value Parameter Parser

1.0.1 · abandoned · verified Wed Apr 22

The `parse-http-header` package (version 1.0.1) is a lightweight JavaScript utility specifically designed to extract structured information from parameterized HTTP header *value strings*. For instance, a common header value like `text/html; charset=UTF-8` is parsed into an object where `text/html` is accessible as the first element of an array, and parameters like `charset` are exposed as direct properties of that object. This allows developers to easily access both the primary media type and its associated attributes in a unified structure. Originally published around 2014, the library appears to be stable but has not seen active development or new releases in many years. Its key differentiators include its focused scope on parsing *just* the value string portion of a header, rather than handling full HTTP messages or multiple header lines, and its minimal footprint with no external runtime dependencies. It exclusively uses CommonJS module syntax.

Common errors

```
TypeError: parseHttpHeader is not a function
```
cause Attempting to import the CommonJS module using ESM `import` syntax without proper transpilation or Node.js module resolution configuration.

fix Change the import statement to `const parseHttpHeader = require('parse-http-header');`.
```
TypeError: Cannot read properties of undefined (reading '0')
```
cause Attempting to access `[0]` on the result of `parseHttpHeader()` when the input was `null` or `undefined`, or the parsing failed to produce a valid array-like object.

fix Ensure the input to `parseHttpHeader` is a valid string. Add a null/undefined check before accessing properties: `const parsed = parseHttpHeader(headerString); if (parsed) { console.log(parsed[0]); }`.
```
My header parameter 'foo' is missing or incorrect, even though it's in the string.
```
cause The input string might contain characters that the parser doesn't correctly handle as delimiters or escapes, especially within quoted strings. For instance, a semicolon inside a quoted filename might be misinterpreted as a new parameter.

fix Verify the exact format of the header value. This library might have limitations with complex or non-standard parameter escaping. For advanced parsing, consider more robust HTTP header parsing libraries.

Warnings

breaking This package is CommonJS-only and does not provide an ESM export. Attempting to use `import` syntax will result in a runtime error or require complex transpilation/configuration in modern Node.js environments.
Fix: Use `const parseHttpHeader = require('parse-http-header');` for module import.
gotcha The output format is an array-like object. The main header value is at index `0`, while parameters are properties. Misunderstanding this can lead to incorrect data access or `undefined` values.
Fix: Always access the main value via `[0]` (e.g., `parsedHeader[0]`) and parameters via named properties (e.g., `parsedHeader.paramName`).
gotcha This library appears to be unmaintained, with its latest copyright from 2014. It may not conform to newer HTTP header specifications (e.g., RFC 8941 Structured Headers) or handle all edge cases in modern HTTP parsing, potentially leading to incorrect or incomplete parsing results.
Fix: For new projects or applications requiring robust and up-to-date HTTP header parsing, consider alternatives like `http-link-header` (for Link headers specifically), or more general-purpose HTTP parsing libraries that are actively maintained.
gotcha The parser is designed for single header *value strings* (e.g., `text/html; charset=UTF-8`). It will not correctly parse entire HTTP header lines (which include the field name and colon) or multiple headers concatenated together, which can lead to unexpected output.
Fix: Ensure that only the header's value string (the part after the colon) is passed to the `parseHttpHeader` function. If processing full header lines, pre-process them to extract only the value.

Install

npm install parse-http-header npm
yarn add parse-http-header yarn
pnpm add parse-http-header pnpm

Imports

parseHttpHeader
wrong:
```
import parseHttpHeader from 'parse-http-header';
```
correct:
```
const parseHttpHeader = require('parse-http-header');
```
This library is CommonJS-only and does not provide an ESM export. Direct `import` statements will fail without a transpilation step or specific Node.js `--experimental-modules` configuration.

Parsing a value

wrong:

const headerValue = parseHttpHeader('text/html; charset=UTF-8');
const mainType = headerValue.value; // Incorrect: main value is at index 0
const charset = headerValue['charset']; // Correct but less idiomatic for direct property access

correct:

const headerValue = parseHttpHeader('text/html; charset=UTF-8');
const mainType = headerValue[0]; // 'text/html'
const charset = headerValue.charset; // 'UTF-8'

The parser returns an array-like object where the primary header value is at index `0`, and parameters are accessible as named properties.

Quickstart

Demonstrates how to parse common parameterized HTTP header value strings like Content-Type and Content-Disposition, showing access to both the primary value and its parameters.

const parseHttpHeader = require('parse-http-header');

// Simulate a response headers object
const responseHeaders = {
  'content-type': 'text/html; charset=UTF-8',
  'content-disposition': 'attachment; filename="report.pdf"; size=12345'
};

// Parse Content-Type
const contentType = parseHttpHeader(responseHeaders['content-type']);
console.log('Content-Type main value:', contentType[0]); // Output: text/html
console.log('Content-Type charset:', contentType.charset); // Output: UTF-8

// Parse Content-Disposition
const contentDisposition = parseHttpHeader(responseHeaders['content-disposition']);
console.log('Content-Disposition main value:', contentDisposition[0]); // Output: attachment
console.log('Content-Disposition filename:', contentDisposition.filename); // Output: report.pdf
console.log('Content-Disposition size:', contentDisposition.size); // Output: 12345

view raw JSON →