HTTP Header Case Normalizer

1.0.3 · maintenance · verified Wed Apr 22

This library provides a utility function to convert HTTP header names into their most commonly used casing (e.g., "user-agent" becomes "User-Agent"). It is particularly useful when interfacing with systems or APIs that expect specific header casing, despite the HTTP specification stating that headers are case-insensitive. Currently at version 1.0.3, `header-case-normalizer` appears to be a stable, focused utility with infrequent updates, indicating it is likely operating in a maintenance mode rather than undergoing active feature development. Its primary differentiator is its specific focus on normalizing a known set of common HTTP header names, based on a list tested with MDN data. This ensures consistent output for widely recognized headers, making it reliable for standard HTTP operations where specific casing might be a requirement for certain environments or legacy systems. It does not attempt to "smart-case" arbitrary strings, only those identified as common HTTP headers.

Common errors

```
TypeError: normalizeHeaderCase is not a function
```
cause Attempting to use named import syntax for a default export in ESM, or incorrect CommonJS destructuring.

fix For ESM: `import normalizeHeaderCase from 'header-case-normalizer';`. For CommonJS: `const normalizeHeaderCase = require('header-case-normalizer');`.
```
console.log(normalizeHeaderCase('X-MY-CUSTOM-HEADER')) outputs 'X-MY-CUSTOM-HEADER' instead of 'X-My-Custom-Header'
```
cause The library primarily normalizes a curated list of common HTTP headers. Custom or less common headers might not be in its internal mapping, causing it to return the input string.

fix This is expected behavior for headers not in the library's internal list derived from MDN. For custom headers, apply your own casing logic or verify if the header is indeed part of the standardized list the library covers.

Warnings

gotcha This library normalizes a predefined list of common HTTP headers. It may not correctly 'smart-case' arbitrary or uncommon custom headers, often returning the input string or a partial normalization if not explicitly known.
Fix: Do not rely on this library for general string casing. Verify its behavior with specific custom headers if normalization is required for them. Consider manual casing or a more generic string utility for unknown header names.
gotcha HTTP headers are case-insensitive by RFC specification. Relying on specific casing might lead to brittle code if downstream systems strictly enforce it without good reason. Use this utility only when strict casing is an unavoidable external dependency (e.g., legacy systems, specific proxies).
Fix: Ensure that explicit header casing is genuinely required by your integration partners. Avoid enforcing specific casing if not necessary, as it can hide issues with non-compliant clients or servers.
gotcha The library assumes standard hyphen-separated header names. Input that deviates significantly from this pattern (e.g., camelCase, underscores) might not be normalized as expected, potentially leading to incorrect output.
Fix: Always provide HTTP header names in their typical kebab-case format (e.g., 'content-type', 'user-agent') to ensure correct normalization.

Install

npm install header-case-normalizer npm
yarn add header-case-normalizer yarn
pnpm add header-case-normalizer pnpm

Imports

normalizeHeaderCase

wrong:

import { normalizeHeaderCase } from 'header-case-normalizer';

correct:

import normalizeHeaderCase from 'header-case-normalizer';

The library exports a default function for ESM usage.

normalizeHeaderCase

wrong:

const { normalizeHeaderCase } = require('header-case-normalizer');

correct:

const normalizeHeaderCase = require('header-case-normalizer');

In CommonJS, the module exports the function directly, not an object with a named export.

Quickstart

Demonstrates how to import and use the `normalizeHeaderCase` function for various HTTP header names, showing both successful normalizations and a note about custom headers.

import normalizeHeaderCase from 'header-case-normalizer';

// Normalize common HTTP headers
console.log(normalizeHeaderCase('user-agent'));       // Expected: User-Agent
console.log(normalizeHeaderCase('content-type'));      // Expected: Content-Type
console.log(normalizeHeaderCase('x-requested-with'));  // Expected: X-Requested-With
console.log(normalizeHeaderCase('etag'));              // Expected: ETag

// Demonstrate case insensitivity handling
console.log(normalizeHeaderCase('uSeR-aGeNt'));      // Expected: User-Agent
console.log(normalizeHeaderCase('CONTENT-type'));    // Expected: Content-Type

// Headers not in its internal list might not be normalized as expected
console.log(normalizeHeaderCase('my-custom-header')); // Expected: My-Custom-Header (might return input or a partial normalization)

view raw JSON →