http-z

library8.1.1jsnpmunverified

http-z is a focused JavaScript and TypeScript library for parsing and building HTTP messages (requests and responses) in strict accordance with RFC 7230. It provides distinct functions to convert raw HTTP strings into a structured model and to serialize a model back into a raw message string. The current stable version is 8.1.1, indicating ongoing maintenance and development. A key differentiator for http-z is its zero-dependency design, which contributes to a minimal footprint, making it suitable for environments where bundle size is critical. It operates seamlessly across both Node.js (requiring Node.js >=18) and modern web browser environments. This library is ideal for developers needing low-level interaction with HTTP message serialization and deserialization, offering a robust, RFC-compliant alternative to higher-level HTTP client or server frameworks by concentrating solely on the message structure.

http-networking serialization web-framework

npm install http-z

github ↗package ↗

INSTALL

IMPORT

SIG · HTTP-Z

http-z

http-networkingjavascriptv8.1.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

parse

✓ import { parse } from 'http-z'

✗ const { parse } = require('http-z')

http-z is primarily designed for ESM environments. While CommonJS might work with transpilation, direct `require` for named exports is generally not supported in Node.js >=18 when the package is ESM-first.

build

✓ import { build } from 'http-z'

✗ import build from 'http-z'

Both `parse` and `build` are named exports, not default exports.

HttpZParserModel

✓ import type { HttpZParserModel } from 'http-z'

This is a TypeScript type import for the parsed HTTP message structure.

consts

✓ import { consts } from 'http-z'

✗ import * as consts from 'http-z'

The library exports a `consts` object containing various HTTP constants (methods, headers, etc.). It's a named export, not a wildcard import of everything.

This quickstart demonstrates parsing a raw HTTP GET request, inspecting its structured model, modifying the model to represent a POST request, and then rebuilding the raw HTTP message from the modified model.

import { parse, build } from 'http-z' const plainRequestMessage = [ 'GET /api/data?param1=value1 HTTP/1.1', 'Host: example.com', 'User-Agent: http-z-client/1.0', 'Accept: application/json', 'Content-Length: 0', '', '' ].join('\r\n') console.log('--- Original Request ---') console.log(plainRequestMessage) try { const messageModel = parse(plainRequestMessage) console.log('\n--- Parsed Model ---') console.log(JSON.stringify(messageModel, null, 2)) // Example of modifying the model const modifiedModel = { ...messageModel, method: 'POST', path: '/api/submit', queryParams: [], headers: [ ...messageModel.headers.filter(h => h.name.toLowerCase() !== 'content-length'), { name: 'Content-Type', value: 'application/x-www-form-urlencoded' }, { name: 'Content-Length', value: '11' } ], body: 'key=value' } const rebuiltMessage = build(modifiedModel) console.log('\n--- Rebuilt Message ---') console.log(rebuiltMessage) } catch (error) { console.error('\nError parsing/building message:', error.message) }

Debug

Known issues

breakinghttp-z requires Node.js version 18 or higher. Projects running on older Node.js runtimes will encounter errors.

fix

Upgrade your Node.js environment to version 18 or newer to ensure compatibility.

affects: <8.0.0

gotchaThe parser strictly adheres to RFC 7230. Malformed or non-standard HTTP messages may lead to parsing errors (e.g., 'Error: Invalid HTTP message format') where other, more lenient parsers might succeed.

fix

Ensure input messages are strictly RFC 7230 compliant. Use robust error handling around `parse` calls to catch and log specific parsing failures.

affects: >=1.0.0

gotchaWhen rebuilding messages, ensure the `Content-Length` header accurately reflects the `body` length. Mismatches can lead to unexpected behavior in HTTP clients/servers. `http-z` does not automatically calculate or correct `Content-Length`.

fix

Manually update the `Content-Length` header in the message model to match the byte length of the `body` string, especially after modifying the body content.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: Cannot assign to read only property 'exports' of object '#<Object>'

Attempting to use `require()` to import `http-z` in a CommonJS module while the package is designed for ESM, leading to conflicts in module export mechanisms.

fix

Ensure your project is configured for ESM (e.g., `"type": "module"` in `package.json`) and use `import { parse, build } from 'http-z'` syntax. If staying in CommonJS, you might need a transpiler or a dynamic import `import('http-z').then(({ parse, build }) => ...)`.

SyntaxError: Named export 'parse' not found. The requested module 'http-z' does not provide an export named 'parse'

Incorrectly trying to `require` a named export from an ESM-only package as if it were a CommonJS module, or trying to use `import parse from 'http-z'` (default import).

fix

Use the correct named import syntax: `import { parse, build } from 'http-z'`. Verify your Node.js environment supports ESM or use a bundler/transpiler if targeting older environments.

Error: Invalid HTTP message format

The input string provided to the `parse` function does not conform to the strict HTTP/1.1 message format as defined by RFC 7230.

fix

Review the `rawMessage` string for common HTTP formatting issues: incorrect line endings (must be `\r\n`), missing blank line between headers and body, malformed status lines or headers, or invalid characters. Ensure all parts of the HTTP message are correctly structured.

TypeError: parse is not a function

The `parse` function was not correctly imported or is being accessed incorrectly from the imported module. This often happens with incorrect default vs. named import syntax.

fix

Verify that `parse` is imported as a named export: `import { parse } from 'http-z'`. Avoid `import httpz from 'http-z'` as there is no default export for the main functions.

Upgrade

Version history

8.1.1latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/AlexanderMac/http-z ↗

packagehttps://www.npmjs.com/package/http-z ↗