fetch-headers

library3.0.1jsnpmunverified

A WHATWG-compliant Headers implementation for Node.js, version 3.0.1. It provides the standard Headers class as defined in the Fetch spec, with full support for immutable headers via the 'bag' symbol. Unlike other polyfills, this library is tested against the Web Platform Tests (WPT) and correctly handles Set-Cookie headers (iterates individually but joins all other duplicate headers with commas). It is actively maintained, ESM-only, and ships TypeScript declarations. Release cadence is irregular; latest stable is 3.0.1 as of late 2023.

devops

npm install fetch-headers

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · FETCH-HEADERS

fetch-headers

devopsjavascriptv3.0.1

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

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

Headers

✓ import { Headers } from 'fetch-headers'

✗ const Headers = require('fetch-headers').Headers

ESM-only since v3; CommonJS require() will not work. Use dynamic import from CJS: const { Headers } = await import('fetch-headers')

bag

✓ import { bag } from 'fetch-headers'

bag is a symbol used to access internal state (e.g., guard). It is not exported for direct use in most applications; only for advanced manipulation.

Headers type

✓ import type { Headers } from 'fetch-headers'

✗ import { Headers } from 'fetch-headers' // for type-only import in TS, use import type to avoid runtime overhead

Since the package ships TypeScript types, you can use import type for type annotations.

Demonstrates creating Headers, appending values, iterating, and making headers immutable using the bag symbol.

import { Headers, bag } from 'fetch-headers'; const headers = new Headers({ 'Content-Type': 'text/plain', 'X-Custom': 'foo' }); console.log(headers.get('Content-Type')); // 'text/plain' // Append values headers.append('X-Custom', 'bar'); console.log(headers.get('X-Custom')); // 'foo, bar' // Iterate over headers for (const [name, value] of headers) { console.log(name, value); } // Make headers immutable bag.get(headers).guard = 'immutable'; try { headers.set('Content-Type', 'application/json'); } catch (e) { console.error('Cannot modify immutable headers'); }

Debug

Known issues

breakingESM-only; CommonJS require() will throw an error.

fix

Use dynamic import: const { Headers } = await import('fetch-headers')

affects: >=3.0.0

gotchaSet-Cookie headers are iterated individually but joined with comma in get(). get('set-cookie') returns all cookies joined by comma, which may be hard to parse.

fix

Use iteration to get individual Set-Cookie headers: for (const [name, value] of headers) { if (name === 'set-cookie') { /* handle each */ } }

affects: >=1.0.0

gotchabag symbol is used to access internal state; direct manipulation may cause unexpected behavior.

fix

Only use bag.get(headers) for standard guard setting; avoid modifying other internal properties.

affects: >=1.0.0

deprecatedNo deprecated features in this version.

affects: none

Errors

Common errors & fixes

Error [ERR_REQUIRE_ESM]: require() of ES Module /path/to/node_modules/fetch-headers/index.js not supported.

Using CommonJS require() to import an ESM-only package.

fix

Use import statement or dynamic import: const { Headers } = await import('fetch-headers')

TypeError: headers.get is not a function

Importing Headers incorrectly or using a non-standard polyfill.

fix

Ensure you are using import { Headers } from 'fetch-headers' correctly.

Cannot set property 'guard' of undefined

Attempting to access bag.get(headers) before importing bag, or using a non-symbol bag.

fix

Import bag correctly: import { Headers, bag } from 'fetch-headers'; then bag.get(headers).guard = 'immutable'

Upgrade

Version history

3.0.1latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/jimmywarting/fetch-headers ↗

packagefetch-headers ↗

homepagehttps://github.com/jimmywarting/fetch-headers#readme ↗