HTTP Headers Parser

3.0.2 · abandoned · verified Tue Apr 21

The `http-headers` package provides a utility to parse HTTP request and response start-lines and headers into a structured JavaScript object. It can process raw string or Buffer data containing complete HTTP messages, or directly extract and parse headers from Node.js `http.ServerResponse` objects. Key features include automatic body detection and ignored parsing, RFC 2068 compliance, and support for multi-line and repeating headers. The current stable version is 3.0.2. This package appears to be unmaintained; its last update was several years ago, meaning it does not receive active development, bug fixes, or compatibility updates for newer Node.js versions or HTTP standards (e.g., HTTP/2, HTTP/3). Its primary differentiator was simplifying the extraction of response headers from Node's internal `_header` property, which was not easily accessible otherwise.

Common errors

```
SyntaxError: Named export 'default' not found (module 'http-headers')
```
cause Attempting to use ES module `import` syntax for a CommonJS-only module.

fix Use CommonJS `require` syntax instead: `const httpHeaders = require('http-headers');`
```
TypeError: httpHeaders is not a function
```
cause Incorrectly destructuring or calling `require('http-headers')` as a property rather than the function it directly exports.

fix Ensure you are assigning the result of `require('http-headers')` directly to a variable and then calling it: `const parser = require('http-headers'); parser(data);`
```
TypeError: data must be a string, Buffer, or http.ServerResponse instance
```
cause Passing an unsupported data type (e.g., a plain object, array, or null) to the `httpHeaders` function.

fix Verify that the `data` argument is either a string, a Buffer containing HTTP message data, or an instance of Node.js `http.ServerResponse`.

Warnings

breaking The package is unmaintained since 2017. It has not received updates for over 7 years and may contain unpatched security vulnerabilities, especially when parsing arbitrary network input. Relying on it in production for security-sensitive applications is risky.
Fix: Consider migrating to an actively maintained HTTP parsing library or implement robust custom parsing for critical headers. Evaluate the security implications carefully if continued use is unavoidable.
gotcha This module is exclusively CommonJS (`require`). It does not provide an ES module build and cannot be directly imported using `import` statements in modern Node.js or browser environments without a CommonJS wrapper or bundler configuration.
Fix: Ensure your project is configured to use CommonJS for this dependency, or wrap it in a custom ES module if necessary. For ESM-only projects, evaluate modern alternatives.
gotcha The package relies on accessing the private `_header` property of `http.ServerResponse` to extract headers. While functional at the time of its development, relying on private API properties can lead to breakage in future Node.js versions if the internal implementation changes.
Fix: Monitor for compatibility issues with new Node.js releases. If breakage occurs, manual header construction or a different approach for accessing response headers might be necessary.

Install

npm install http-headers npm
yarn add http-headers yarn
pnpm add http-headers pnpm

Imports

httpHeaders
wrong:
```
import httpHeaders from 'http-headers'
```
correct:
```
const httpHeaders = require('http-headers')
```
This package is a CommonJS module and does not natively support ES module `import` syntax. Attempting to import it directly in an ESM context will likely result in an error or require special bundler configuration.
httpHeaders (with onlyHeaders option)
```
const parse = require('http-headers');
const headersOnly = parse(data, true);
```
The module exports a single function. The optional second argument, `true`, instructs the parser to return only the headers object, discarding the start-line details (method, URL, status code, etc.).

Quickstart

This example demonstrates how to use `http-headers` to parse and access the response headers directly from an `http.ServerResponse` object in a Node.js server, a key use case for this library.

const http = require('http');
const httpHeaders = require('http-headers');

const server = http.createServer((req, res) => {
  res.statusCode = 200;
  res.setHeader('Content-Type', 'text/plain');
  res.setHeader('X-Request-ID', '12345');
  res.end('Hello World');

  // Log the parsed response headers as they were sent to the client
  // This uses http-headers to access the internal _header property of res
  console.log('Parsed ServerResponse headers:', httpHeaders(res));
}).listen(8080, () => {
  console.log('Server listening on http://localhost:8080');
});

// To test, run the server and access http://localhost:8080 in your browser or with curl.
// The server's console will output the parsed response headers.

view raw JSON →