🍪 cookie-es

ESM-ready Cookie and Set-Cookie parser and serializer based on cookie and set-cookie-parser with built-in TypeScript types. Compliant with RFC 6265bis.

Install

# ✨ Auto-detect (npm, yarn, pnpm, bun, deno)
npx nypm install cookie-es

Import

ESM (Node.js, Bun, Deno)

import {
  parseCookie,
  parseSetCookie,
  serializeCookie,
  stringifyCookie,
  splitSetCookieString,
} from "cookie-es";

CDN (Deno, Bun and Browsers)

import {
  parseCookie,
  parseSetCookie,
  serializeCookie,
  stringifyCookie,
  splitSetCookieString,
} from "https://esm.sh/cookie-es";

API

parseCookie(str, options?)

Parse a Cookie header string into an object. First occurrence wins for duplicate names.

parseCookie("foo=bar; equation=E%3Dmc%5E2");
// { foo: "bar", equation: "E=mc^2" }

// Custom decoder
parseCookie("foo=bar", { decode: (v) => v });

// Only parse specific keys
parseCookie("a=1; b=2; c=3", { filter: (key) => key !== "b" });
// { a: "1", c: "3" }

parseSetCookie(str, options?)

Parse a Set-Cookie header string into an object with all cookie attributes.

parseSetCookie(
  "id=abc; Domain=example.com; Path=/; HttpOnly; Secure; SameSite=Lax; Max-Age=3600; Partitioned; Priority=High",
);
// {
//   name: "id",
//   value: "abc",
//   domain: "example.com",
//   path: "/",
//   httpOnly: true,
//   secure: true,
//   sameSite: "lax",
//   maxAge: 3600,
//   partitioned: true,
//   priority: "high",
// }

Supports decode option (custom function or false to skip decoding). Returns undefined for cookies with forbidden names (prototype pollution protection) or when both name and value are empty (RFC 6265bis sec 5.7).

serializeCookie(name, value, options?)

Serialize a cookie name-value pair into a Set-Cookie header string.

serializeCookie("foo", "bar", { httpOnly: true, secure: true, maxAge: 3600 });
// "foo=bar; Max-Age=3600; HttpOnly; Secure"

// Also accepts a cookie object
serializeCookie({
  name: "foo",
  value: "bar",
  domain: "example.com",
  path: "/",
  sameSite: "lax",
});
// "foo=bar; Domain=example.com; Path=/; SameSite=Lax"

Supported attributes: maxAge, expires, domain, path, httpOnly, secure, sameSite, priority, partitioned. Use encode option for custom value encoding (default: encodeURIComponent).

Note

parse and serialize are available as shorter aliases for parseCookie and serializeCookie.

stringifyCookie(cookies, options?)

Stringify a cookies object into an HTTP Cookie header string.

stringifyCookie({ foo: "bar", baz: "qux" });
// "foo=bar; baz=qux"

splitSetCookieString(input)

Split comma-joined Set-Cookie headers into individual strings. Correctly handles commas within cookie attributes like Expires dates.

splitSetCookieString(
  "foo=bar; Expires=Thu, 01 Jan 2026 00:00:00 GMT, baz=qux",
);
// ["foo=bar; Expires=Thu, 01 Jan 2026 00:00:00 GMT", "baz=qux"]

// Also accepts an array
splitSetCookieString(["a=1, b=2", "c=3"]);
// ["a=1", "b=2", "c=3"]

Parsing Options

allowMultiple

By default, when a cookie name appears more than once, only the first value is kept. Set allowMultiple: true to collect all values into an array:

import { parseCookie } from "cookie-es";

// Default: first value wins
parseCookie("foo=a;bar=b;foo=c");
// => { foo: "a", bar: "b" }

// With allowMultiple: duplicates return arrays
parseCookie("foo=a;bar=b;foo=c", { allowMultiple: true });
// => { foo: ["a", "c"], bar: "b" }

License

MIT

Based on jshttp/cookie (Roman Shtylman and Douglas Christopher Wilson) and nfriedly/set-cookie-parser (Nathan Friedly).