ESM Set-Cookie Header Parser

1.0.5 · active · verified Tue Apr 21

set-cookie-parser-es is an actively maintained, ESM-first JavaScript library, currently at version 1.0.5, designed for parsing `Set-Cookie` HTTP headers. It serves as an ECMAScript Module (ESM) port of the popular `set-cookie-parser` package, offering bundled TypeScript types for an enhanced developer experience. Unlike its predecessor, this library distinguishes itself by being entirely framework and runtime agnostic; it specifically does *not* accept Node.js response objects, focusing purely on string-based header parsing. Its `splitCookiesString` utility also strictly operates on a single `set-cookie` header string, deviating from the original's broader input acceptance. While primarily an ESM package, it also provides CommonJS compatibility for wider ecosystem integration. The project appears to follow a release cadence driven by feature parity with the original library, bug fixes, and minor enhancements.

Common errors

```
TypeError: parse is not a function
```
cause Attempting to import `parse` as a default export in an ESM context, or incorrect CommonJS `require` syntax when the module primarily provides named exports.

fix Use named imports for ESM (`import { parse } from 'set-cookie-parser-es'`) or destructuring for CommonJS (`const { parse } = require('set-cookie-parser-es')`).
```
Argument of type 'IncomingMessage' is not assignable to parameter of type 'string | string[]'.
```
cause Passing a Node.js `http.IncomingMessage` or `http.ServerResponse` object directly to the `parse` or `parseString` functions, which expect string(s).

fix Extract the `set-cookie` header values from the Node.js response object first. For example, `parse(response.headers['set-cookie'])` for an array of headers or `parseString(response.headers['set-cookie'][0])` for a single header.

Warnings

breaking The library explicitly does not accept Node.js response objects, unlike the original `set-cookie-parser` package. Users migrating from the original package in Node.js environments will need to manually extract `Set-Cookie` headers into a string or array of strings.
Fix: Manually extract `Set-Cookie` headers from the response object (e.g., `response.headers['set-cookie']` or `res.getHeader('set-cookie')`) before passing to `parse` or `parseString`.
gotcha The `splitCookiesString` function strictly expects a `Set-Cookie` header string as input, which can contain multiple comma-separated `Set-Cookie` values. It is not designed to parse generic comma-separated cookie strings (e.g., from a `Cookie` request header), and also does not accept Node.js response objects.
Fix: Ensure only valid `Set-Cookie` header strings are passed to `splitCookiesString`. For parsing `Cookie` request headers, use a dedicated parser for that specific format.

Install

npm install set-cookie-parser-es npm
yarn add set-cookie-parser-es yarn
pnpm add set-cookie-parser-es pnpm

Imports

parse
wrong:
```
import parse from 'set-cookie-parser-es'
```
correct:
```
import { parse } from 'set-cookie-parser-es'
```
The `parse` function is a named export, used for parsing an array of `Set-Cookie` header strings. Ensure named imports are used for ESM or destructuring for CommonJS.
parseString
wrong:
```
const parseString = require('set-cookie-parser-es').parseString
```
correct:
```
import { parseString } from 'set-cookie-parser-es'
```
While the library supports CommonJS `require`, directly accessing `require('pkg').symbol` without destructuring is less idiomatic. `parseString` is for parsing a single `Set-Cookie` header string.
splitCookiesString
wrong:
```
import { splitCookiesString as split } from 'set-cookie-parser-es'
```
correct:
```
import { splitCookiesString } from 'set-cookie-parser-es'
```
The `splitCookiesString` function is a named export. While aliasing is not inherently wrong, it can lead to confusion if not consistently applied. This function splits a single string containing multiple concatenated `Set-Cookie` headers.

Quickstart

Demonstrates how to parse single `Set-Cookie` headers, arrays of headers, and split concatenated `Set-Cookie` strings using the library's core functions.

import { parse, parseString, splitCookiesString } from 'set-cookie-parser-es';

// Example 1: Parse a single Set-Cookie header string
const singleSetCookieHeader = 'session_id=abc; Path=/; Expires=Wed, 21 Oct 2026 07:28:00 GMT; HttpOnly; Secure';
const parsedCookie = parseString(singleSetCookieHeader);
console.log('Parsed single cookie:', parsedCookie);

// Example 2: Parse an array of Set-Cookie header strings
const multipleSetCookieHeaders = [
  'user_token=xyz; Max-Age=3600; HttpOnly',
  'preferences=theme=dark; Path=/',
];
const parsedCookiesArray = parse(multipleSetCookieHeaders);
console.log('Parsed array of cookies:', parsedCookiesArray);

// Example 3: Split a single string containing multiple Set-Cookie values
// This is useful if a server concatenates multiple Set-Cookie headers into one string.
const concatenatedSetCookies = 'my_app_session=value1; Path=/; Secure, my_app_prefs=value2; Path=/';
const splitCookies = splitCookiesString(concatenatedSetCookies);
console.log('Split cookies string:', splitCookies);

// You can then parse the split strings:
const parsedSplitCookies = parse(splitCookies);
console.log('Parsed split cookies:', parsedSplitCookies);

view raw JSON →