{"id":47596,"library":"fetch-headers","title":"fetch-headers","description":"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.","status":"active","version":"3.0.1","language":"javascript","source_language":"en","source_url":"https://github.com/jimmywarting/fetch-headers","tags":["javascript","Headers","fetch","spec","whatwg","typescript"],"install":[{"cmd":"npm install fetch-headers","lang":"bash","label":"npm"},{"cmd":"yarn add fetch-headers","lang":"bash","label":"yarn"},{"cmd":"pnpm add fetch-headers","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"ESM-only since v3; CommonJS require() will not work. Use dynamic import from CJS: const { Headers } = await import('fetch-headers')","wrong":"const Headers = require('fetch-headers').Headers","symbol":"Headers","correct":"import { Headers } from 'fetch-headers'"},{"note":"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.","symbol":"bag","correct":"import { bag } from 'fetch-headers'"},{"note":"Since the package ships TypeScript types, you can use import type for type annotations.","wrong":"import { Headers } from 'fetch-headers' // for type-only import in TS, use import type to avoid runtime overhead","symbol":"Headers type","correct":"import type { Headers } from 'fetch-headers'"}],"quickstart":{"code":"import { Headers, bag } from 'fetch-headers';\n\nconst headers = new Headers({\n  'Content-Type': 'text/plain',\n  'X-Custom': 'foo'\n});\n\nconsole.log(headers.get('Content-Type')); // 'text/plain'\n\n// Append values\nheaders.append('X-Custom', 'bar');\nconsole.log(headers.get('X-Custom')); // 'foo, bar'\n\n// Iterate over headers\nfor (const [name, value] of headers) {\n  console.log(name, value);\n}\n\n// Make headers immutable\nbag.get(headers).guard = 'immutable';\ntry {\n  headers.set('Content-Type', 'application/json');\n} catch (e) {\n  console.error('Cannot modify immutable headers');\n}","lang":"typescript","description":"Demonstrates creating Headers, appending values, iterating, and making headers immutable using the bag symbol."},"warnings":[{"fix":"Use dynamic import: const { Headers } = await import('fetch-headers')","message":"ESM-only; CommonJS require() will throw an error.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Use iteration to get individual Set-Cookie headers: for (const [name, value] of headers) { if (name === 'set-cookie') { /* handle each */ } }","message":"Set-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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Only use bag.get(headers) for standard guard setting; avoid modifying other internal properties.","message":"bag symbol is used to access internal state; direct manipulation may cause unexpected behavior.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"","message":"No deprecated features in this version.","severity":"deprecated","affected_versions":"none"}],"env_vars":null,"search_vec":"'2023':88 '3.0.1':13,84 'activ':68 'bag':34 'cadenc':78 'class':19 'comma':65 'compliant':7 'cooki':54 'correct':50 'declar':76 'defin':21 'duplic':62 'esm':71 'esm-on':70 'fetch':2,24,91 'fetch-head':1 'full':27 'handl':51 'header':3,8,18,31,55,63,90 'immut':30 'implement':9 'individu':57 'irregular':80 'iter':56 'javascript':89 'join':59 'late':87 'latest':81 'librari':40 'maintain':69 'node.js':11 'platform':46 'polyfil':38 'provid':15 'releas':77 'set':53 'set-cooki':52 'ship':74 'spec':25,92 'stabl':82 'standard':17 'support':28 'symbol':35 'test':42,47 'typescript':75,94 'unlik':36 'version':12 'via':32 'web':45 'whatwg':6,93 'whatwg-compli':5 'wpt':48","created_at":"2026-06-07T16:52:19.868480+00:00","updated_at":"2026-06-07T16:52:19.868480+00:00","problems":[{"fix":"Use import statement or dynamic import: const { Headers } = await import('fetch-headers')","cause":"Using CommonJS require() to import an ESM-only package.","error":"Error [ERR_REQUIRE_ESM]: require() of ES Module /path/to/node_modules/fetch-headers/index.js not supported."},{"fix":"Ensure you are using import { Headers } from 'fetch-headers' correctly.","cause":"Importing Headers incorrectly or using a non-standard polyfill.","error":"TypeError: headers.get is not a function"},{"fix":"Import bag correctly: import { Headers, bag } from 'fetch-headers'; then bag.get(headers).guard = 'immutable'","cause":"Attempting to access bag.get(headers) before importing bag, or using a non-symbol bag.","error":"Cannot set property 'guard' of undefined"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null,"cli_version":null,"type":"library","homepage":"https://github.com/jimmywarting/fetch-headers#readme","github":"https://github.com/jimmywarting/fetch-headers","docs":null,"changelog":null,"pypi":null,"npm":"fetch-headers","openapi_spec":null,"status_page":null,"smithery":null,"categories":["devops"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-07","next_check":"2026-09-05","install_tag":null}}