HTTP Header Validation Utility

Common errors

• TypeError: headerUtils.validateHeaderName is not a function

  cause Attempting to use `headerUtils` global or CJS `require` object with ESM named imports, or incorrect destructuring.
  fix If using ESM, ensure you are using named imports: `import { validateHeaderName } from 'http-headers-validation';`. If in a browser with a script tag, ensure the `index.js` file is loaded and the `headerUtils` global is available before calling its methods.

• Error: Cannot find module 'http-headers-validation'

  cause The package has not been installed or is not correctly resolved in the module path.
  fix Run `npm install http-headers-validation` or `yarn add http-headers-validation` in your project directory. Check your `package.json` dependencies.

• Argument of type 'null' is not assignable to parameter of type 'string'.

  cause Passing `null`, `undefined`, or a non-string type to a validation function in a TypeScript project.
  fix Ensure all arguments passed to `validateHeaderName`, `validateHeaderValue`, or `validateHeader` are non-empty strings, as required by the function signatures and documented API.

Warnings

• gotcha The package is currently at an early version (0.0.2). While functional, API stability may not be guaranteed, and future updates could introduce breaking changes without explicit major version bumps typical of more mature libraries.
  Fix: Pin exact versions (e.g., `"http-headers-validation": "0.0.2"`) in your `package.json` to prevent unexpected updates. Regularly review the GitHub repository for new releases and changes.
• gotcha The README explicitly shows CommonJS `require` examples and mentions a global `headerUtils` for client-side script tags, but doesn't detail official ESM module entry points beyond what's implied by shipping TypeScript types. While modern bundlers handle CJS in ESM, direct ESM imports are preferred.
  Fix: For Node.js ESM or TypeScript projects, use named imports like `import { validateHeaderName } from 'http-headers-validation';`. If using in a browser via a script tag, ensure the `index.js` file is included and access functions via the global `headerUtils` object.
• gotcha The utility validates header names and values based on 'the standart' as stated in the README, implying RFCs. However, the specific RFC (e.g., RFC 7230, RFC 9110) or any edge cases regarding internationalization (e.g., non-ASCII characters in values for specific headers) are not explicitly detailed.
  Fix: Consult the source code on GitHub for exact validation logic if specific RFC compliance or edge-case behavior is critical for your application. Consider adding internal integration tests for scenarios not explicitly covered by the library's tests.

Install

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

Imports

• validateHeaderName
  wrong:

  import validateHeaderName from 'http-headers-validation';

  correct:

  import { validateHeaderName } from 'http-headers-validation';

  This is a named export. Ensure you destructure it correctly.
• validateHeaderValue
  wrong:

  const { validateHeaderValue } = require('http-headers-validation');

  correct:

  import { validateHeaderValue } from 'http-headers-validation';

  While CJS `require` works, ESM `import` is preferred in modern Node.js and TypeScript projects. For browser usage via script tag, the global `headerUtils` object exposes this function.
• validateHeader
  wrong:

  const headerUtils = require('http-headers-validation');
  headerUtils.validateHeaderName('...');

  correct:

  import { validateHeader } from 'http-headers-validation';

  The package exports individual validation functions. While `headerUtils` works in CJS, direct named imports are idiomatic for ESM. In browsers, `headerUtils.validateHeader` is available globally.

Quickstart

This quickstart demonstrates how to import and use the `validateHeaderName`, `validateHeaderValue`, and `validateHeader` functions to check the conformance of HTTP header strings against the standard, including a practical usage example.

import { validateHeaderName, validateHeaderValue, validateHeader } from 'http-headers-validation';

// Validate a header name
const isValidName1 = validateHeaderName('If-Unmodified-Since'); // true
const isValidName2 = validateHeaderName('Front-End-[]');      // false
console.log(`'If-Unmodified-Since' is valid: ${isValidName1}`);
console.log(`'Front-End-[]' is valid: ${isValidName2}`);

// Validate a header value
const isValidValue1 = validateHeaderValue('VQcFUFFRCBABUFhaAwQOVw=='); // true
const isValidValue2 = validateHeaderValue('\n\b');                 // false
console.log(`'VQcFUFFRC...' is valid: ${isValidValue1}`);
console.log(`'\n\b' is valid: ${isValidValue2}`);

// Validate both name and value combined
const isValidHeader1 = validateHeader('Cache-Control', 'public, max-age=2000'); // true
const isValidHeader2 = validateHeader('Front-End-[]', 'backspace\bValue');     // false
console.log(`'Cache-Control: public, max-age=2000' is valid: ${isValidHeader1}`);
console.log(`'Front-End-[]: backspace\bValue' is valid: ${isValidHeader2}`);

// Example of how it might be used in a server middleware
function processHeaders(headers: Record<string, string>) {
  for (const name in headers) {
    const value = headers[name];
    if (!validateHeader(name, value)) {
      console.warn(`Invalid header detected: ${name}: ${value}`);
      // Potentially throw an error or sanitize
    }
  }
}

processHeaders({
  'Accept': 'application/json',
  'Custom-Bad-Header[]': 'oops\tbad value'
});