# headers-polyfill

> A native "Headers" class polyfill.

Latest version **5.0.1** (published 2026-03-05) · MIT license · 0 weekly downloads

## Install

```sh
npm install headers-polyfill
pnpm add headers-polyfill
yarn add headers-polyfill
bun add headers-polyfill
```

## Health

**Score 55/100 (C)** — status: stable.

Positive: esm support; no vulnerabilities; has provenance.

Warnings: low downloads; no types.

## Facts

| | |
|---|---|
| Version | 5.0.1 |
| Published | 2026-03-05 |
| First published | 2022-02-13 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | ESM + CommonJS |
| Dependencies | 2 |
| Unpacked size | 110 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 33 |
| Author | Artem Zakharchenko |
| Maintainers | kettanaito |

## Links

- npm: https://www.npmjs.com/package/headers-polyfill
- Repository: https://github.com/mswjs/headers-polyfill
- Homepage: https://github.com/mswjs/headers-polyfill#readme
- Issues: https://github.com/mswjs/headers-polyfill/issues
- npm.io page: https://npm.io/package/headers-polyfill

## Dependencies (2)

- [set-cookie-parser](https://npm.io/package/set-cookie-parser.md) ^3.0.1
- [@types/set-cookie-parser](https://npm.io/package/@types/set-cookie-parser.md) ^2.4.10

## Recent versions

- 5.0.1 (latest) — 2026-03-05
- 5.0.0 — 2026-03-05
- 4.0.3 — 2024-03-18
- 4.0.2 — 2023-10-18
- 4.0.1 — 2023-09-13
- 4.0.0 — 2023-09-13
- 3.3.0 — 2023-09-13
- 3.2.5 — 2023-09-13
- 3.2.4 — 2023-09-13
- 3.2.3 — 2023-09-07
- 3.2.2 — 2023-09-05
- 3.2.1 — 2023-08-29
- 3.2.0 — 2023-08-26
- 3.1.2 — 2022-10-09
- 3.1.1 — 2022-10-06
- … 9 more at https://npm.io/package/headers-polyfill/versions

## README

[![Published version](https://img.shields.io/npm/v/headers-polyfill.svg)](https://www.npmjs.com/package/headers-polyfill)

# `headers-polyfill`

A `Headers` class polyfill and transformation library.

## Motivation

Various request issuing libraries utilize a different format of headers. This library chooses the [`Headers`](https://developer.mozilla.org/en-US/docs/Web/API/Headers) instance as the middle-ground between server and client, and provides functions to convert that instance to primitives and vice-versa.

## Install

```bash
npm install headers-polyfill
```

## Polyfill

This package exports the `Headers` class that polyfills the native [`window.Headers`](https://developer.mozilla.org/en-US/docs/Web/API/Headers) implementation. This allows you to construct and manage headers using the same API in non-browser environments.

```js
import { Headers } from 'headers-polyfill'

const headers = new Headers({
  Accept: '*/*',
  'Content-Type': 'application/json',
})

headers.get('accept') // "*/*"
```

## Methods

The `Headers` polyfill instance supports the same methods as the standard `Headers` instance:

- [`.has()`](https://developer.mozilla.org/en-US/docs/Web/API/Headers/has)
- [`.get()`](https://developer.mozilla.org/en-US/docs/Web/API/Headers/get)
- [`.set()`](https://developer.mozilla.org/en-US/docs/Web/API/Headers/set)
- [`.append()`](https://developer.mozilla.org/en-US/docs/Web/API/Headers/append)
- [`.delete()`](https://developer.mozilla.org/en-US/docs/Web/API/Headers/delete)
- [`.forEach()`](https://developer.mozilla.org/en-US/docs/Web/API/Headers/forEach)
- [`.getSetCookie()`](https://developer.mozilla.org/en-US/docs/Web/API/Headers/getSetCookie)

As well as the iterator methods:

- [`.keys()`](https://developer.mozilla.org/en-US/docs/Web/API/Headers/keys)
- [`.values()`](https://developer.mozilla.org/en-US/docs/Web/API/Headers/values)
- [`.entries()`](https://developer.mozilla.org/en-US/docs/Web/API/Headers/entries)

## Transformations

### `getRawHeaders()`

Returns an object consisting of the header name/value pairs but preserving raw header names.

```js
const headers = new Headers({
  Accept: '*/*',
  'Content-Type': 'application/json',
})

headers.raw()
// { "Accept": "*/*", "Content-Type": "application/json" }
```

### Headers ⭢ N

- `headersToString: (h: Headers): string`

```js
import { headersToString } from 'headers-polyfill'

headersToString(
  new Headers({
    connection: 'keep-alive',
    'content-type': ['text/plain', 'image/png'],
  })
)
// connetion: keep-alive
// content-type: text/plain, image/png
```

- `headersToList: (h: Headers): Array<[string, string | string[]]>`

```js
import { headersToList } from 'headers-polyfill'

headersToList(
  new Headers({
    connection: 'keep-alive',
    'content-type': ['text/plain', 'image/png'],
  })
)
// [['connection', 'keep-alive'], ['content-type', ['text/plain', 'image/png']]]
```

- `headersToObject: (h: Headers): Record<string, string | string[]>`

```js
import { headersToObject } from 'headers-polyfill'

headersToObject(
  new Headers({
    connection: 'keep-alive',
    'content-type': ['text/plain', 'image/png'],
  })
)
// { connection: 'keep-alive', 'content-type': ['text/plain', 'image/png'] }
```

### N ⭢ Headers

- `stringToHeaders: (s: string): Headers`

```js
import { stringToHeaders } from 'headers-polyfill'


const stringToHeaders(`
connection: keep-alive
content-type: text/plain, image/png
`)
// Headers { connection: 'keep-alive', 'content-type': ['text/plain', 'image/png'] }
```

- `listToHeaders: (l: Array<[string, string | string[]]>): Headers`

```js
import { listToHeaders } from 'headers-polyfill'

listToHeaders([
  ['connection', 'keep-alive'],
  ['content-type', ['text/plain', 'image/png']],
])
// Headers { connection: 'keep-alive', 'content-type': ['text/plain', 'image/png'] }
```

- `objectToHeaders: (o: Record<string, string | string[] | undefined>): Headers`

```js
import { objectToHeaders } from 'headers-polyfill'

objectToHeaders({
  connection: 'keep-alive',
  'content-type': ['text/plain', 'image/png'],
})
// Headers { connection: 'keep-alive', 'content-type': ['text/plain', 'image/png'] }
```

---

## Utilities

- `reduceHeadersObject: <R>(o: Record<string, string | string[]>, reducer: (acc: R, name: string, value: string | string[]) => R) => R`

```js
import { reduceHeadersObject } from 'headers-polyfill'

reduceHeadersObject <
  HeadersObject >
  ({
    Accept: '*/*',
    'Content-Type': ['application/json', 'text/plain'],
  },
  (headers, name, value) => {
    headers[name.toLowerCase()] = value
    return headers
  },
  {})
// { 'accept': '*/*', 'content-type': ['application/json', 'text/plain'] }
```

- `appendHeader: (o: Record<string, string | string[]>, n: string, v: string | string[]): Record<string, string | string[]>`

```js
import { appendHeader } from 'headers-polyfill'

appendHeader(
  { 'content-type': 'application/json' },
  'content-type',
  'text/plain'
)
// { 'content-type': ['application/json', 'text/plain']}
```

- `flattenHeadersList: (l: Array<[string, string | string[]]>): Array<string, string>`

```js
import { flattenHeadersList } from 'headers-polyfill'

flattenHeadersList([['content-type', ['text/plain', 'image/png']]])
// ['content-type', 'text/plain, image/png']
```

- `flattenHeadersObject: (o: Record<string, string | string[]>): Record<string, string>`

```js
import { flattenHeadersObject } from 'headers-polyfill'

flattenHeadersObject({
  'content-type': ['text/plain', 'image/png'],
})
// { 'content-type': 'text/plain, image/png' }
```

---
_Source: https://npm.io/package/headers-polyfill · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._