Pure JavaScript HTTP Parser

Common errors

• TypeError: process.binding(...).HTTPParser is not a constructor

  cause Attempting to monkey-patch `http-parser-js` on Node.js v12.x without enabling the legacy HTTP parser.
  fix Execute your Node.js application with the flag: `node --http-parser=legacy your-app.js`

• Error: Cannot find module 'http-parser-js'

  cause The package `http-parser-js` has not been installed as a dependency.
  fix Install the package: `npm install http-parser-js` or `yarn add http-parser-js`

• The Node.js `http` module is still using the default parser, despite patching attempts.

  cause The monkey-patching code was executed *after* the `http` module was first `require`d in the application lifecycle.
  fix Move the `process.binding('http_parser').HTTPParser = require('http-parser-js').HTTPParser;` line to the very top of your application's main entry file, ensuring it runs before any other code that might implicitly or explicitly load the `http` module.

Warnings

• breaking Node.js v12.x renamed its internal HTTP parser and did not expose it for direct monkey-patching by default. Attempting to patch without a specific flag will fail.
  Fix: Run Node.js v12.x with `node --http-parser=legacy file.js` to opt into the older, patchable binding.
• gotcha Monkey-patching must occur *before* the native Node.js `http` module is `require`d for the first time. Loading `http` prematurely will result in it using the default C++ parser.
  Fix: Ensure the `process.binding('http_parser').HTTPParser = require('http-parser-js').HTTPParser;` line is at the absolute top of your application's entry point, before any `require('http')` statements.
• gotcha The API for standalone usage (not monkey-patching) is described as 'somewhat awkward' due to its adherence to Node.js internal compatibility. Directly using `HTTPParser` requires careful handling of raw buffers and state management.
  Fix: Refer to the `standalone-example.js` in the package's GitHub repository for guidance on how to use the raw `HTTPParser` class for manual parsing.
• gotcha This library is designed to replace Node.js's internal C parser for specific use cases (tolerance, pure JS). For most standard applications, Node.js's default parser offers superior performance due to its C++ implementation.
  Fix: Only use this package if you specifically need its tolerant parsing behavior or have strong reasons to avoid C++ bindings; otherwise, rely on Node.js's default `http` module behavior.

Install

• npm install http-parser-js npm
• yarn add http-parser-js yarn
• pnpm add http-parser-js pnpm

Imports

• HTTPParser
  wrong:

  const HTTPParser = require('http-parser-js').HTTPParser;

  correct:

  import { HTTPParser } from 'http-parser-js';

  While Node.js uses CommonJS, this project also ships TypeScript types and can be imported via ESM syntax in environments supporting it, although its primary use case involves CommonJS `require` for monkey-patching.
• monkey-patching entry
  wrong:

  require('http-parser-js'); // This only imports the module, not patches.

  correct:

  process.binding('http_parser').HTTPParser = require('http-parser-js').HTTPParser;

  This specific line must be executed *before* `require('http')` to effectively replace Node.js's internal parser.

Quickstart

This example demonstrates how to monkey-patch Node.js's internal HTTP parser with `http-parser-js` before initializing the native `http` module, then starts a basic HTTP server.

import { HTTPParser } from 'http-parser-js';
import http from 'http';

// Monkey patch before you require http for the first time.
// Note: This specific usage pattern primarily targets CommonJS environments in Node.js.
// For ESM, you might need a different approach or a build step to ensure `require` behavior.
if (typeof process.binding === 'function' && process.binding('http_parser')) {
  process.binding('http_parser').HTTPParser = HTTPParser; // Assuming HTTPParser is already imported
  console.log('http-parser-js successfully monkey-patched into Node.js runtime.');
}

// Now, `http` module will use http-parser-js
const server = http.createServer((req, res) => {
  console.log(`Received request for: ${req.url}`);
  res.writeHead(200, { 'Content-Type': 'text/plain' });
  res.end('Hello from http-parser-js powered server!\n');
});

server.listen(3000, () => {
  console.log('Server running on port 3000');
});

// Example of making a request to demonstrate it's working
// setTimeout(() => {
//   http.get('http://localhost:3000/', (res) => {
//     let data = '';
//     res.on('data', (chunk) => { data += chunk; });
//     res.on('end', () => { console.log('Client received:', data); server.close(); });
//   }).on('error', (err) => {
//     console.error('Client error:', err.message);
//     server.close();
//   });
// }, 1000);