🍪 @chaisser/cookie-parser

Parse and serialize HTTP cookies with full TypeScript support.

✨ Features

• 🔍 Parse Cookie request headers into key-value records
• 📝 Parse Set-Cookie response headers into structured objects
• 🛠 Serialize cookies with all standard attributes (Max-Age, Expires, SameSite, Priority, etc.)
• ✅ Validate cookie names and values per RFC 6265
• 🪶 Zero dependencies – lightweight and fast
• 💪 Full TypeScript – strict types, no any
• 🔄 Round-trip safe – parse(serialize(...)) just works

📦 Installation

npm install @chaisser/cookie-parser

🚀 Quick Start

import { parse, serialize, parseSetCookie } from "@chaisser/cookie-parser";

// Parse an incoming Cookie header
const cookies = parse("session=abc123; theme=dark");
// => { session: "abc123", theme: "dark" }

// Serialize a Set-Cookie header value
const setCookie = serialize("session", "abc123", {
  maxAge: 3600,
  httpOnly: true,
  secure: true,
  sameSite: "lax",
  path: "/",
});
// => "session=abc123; Max-Age=3600; HttpOnly; Secure; SameSite=Lax; Path=/"

// Parse a Set-Cookie header value
const parsed = parseSetCookie(setCookie);
// => { name: "session", value: "abc123", maxAge: 3600, httpOnly: true, ... }

📖 What It Does

@chaisser/cookie-parser handles the tedious parts of working with HTTP cookies:

• Parsing Cookie headers with proper handling of quoted values, URL-encoding, and whitespace
• Parsing Set-Cookie headers into structured objects with typed attributes
• Serializing cookies with all standard attributes including SameSite and Priority
• Validating cookie names and values according to RFC 6265
• Convenience helpers for common operations like getting, checking, and deleting cookies

📚 Usage Examples

Parse a Cookie Header

import { parse } from "@chaisser/cookie-parser";

const cookies = parse("name=John; theme=dark; lang=%C3%A9");
// { name: "John", theme: "dark", lang: "é" }

Parse a Set-Cookie Header

import { parseSetCookie } from "@chaisser/cookie-parser";

const cookie = parseSetCookie(
  "sid=abc; Expires=Thu, 01 Jan 2026 00:00:00 GMT; Max-Age=3600; Domain=example.com; Path=/; Secure; HttpOnly; SameSite=Strict"
);
// {
//   name: "sid",
//   value: "abc",
//   expires: Date,
//   maxAge: 3600,
//   domain: "example.com",
//   path: "/",
//   secure: true,
//   httpOnly: true,
//   sameSite: "strict"
// }

Serialize a Cookie

import { serialize } from "@chaisser/cookie-parser";

const header = serialize("token", "xyz789", {
  maxAge: 86400,
  secure: true,
  httpOnly: true,
  sameSite: "none",
  path: "/api",
  domain: ".example.com",
});

Convenience Helpers

import { get, has, getAll, deleteCookie } from "@chaisser/cookie-parser";

const header = "session=abc; theme=dark";

get(header, "session"); // "abc"
get(header, "missing"); // undefined
has(header, "theme");   // true
has(header, "lang");    // false
getAll(header);         // [{ name: "session", value: "abc" }, { name: "theme", value: "dark" }]

// Build a Set-Cookie that deletes a cookie
deleteCookie("session", { path: "/" });
// "session=; Max-Age=0; Path=/"

Validation

import { isValidCookieName, isValidCookieValue } from "@chaisser/cookie-parser";

isValidCookieName("session_id"); // true
isValidCookieName("bad name");   // false (spaces not allowed)
isValidCookieValue("hello");     // true
isValidCookieValue("bad;value"); // false (semicolons not allowed)

📋 API Reference

| Function | Description | |---|---| | parse(cookieHeader) | Parse a Cookie header into Record<string, string> | | parseSetCookie(setCookieHeader) | Parse a Set-Cookie header into CookieOptions \| null | | serialize(name, value, options?) | Serialize into a Set-Cookie header string | | getAll(cookieHeader) | Get all cookies as Array<{ name, value }> | | get(cookieHeader, name) | Get a single cookie value by name | | has(cookieHeader, name) | Check if a cookie exists | | deleteCookie(name, options?) | Serialize a cookie deletion (Max-Age=0) | | isValidCookieName(name) | Validate a cookie name per RFC 6265 | | isValidCookieValue(value) | Validate a cookie value per RFC 6265 |

Interfaces

| Interface | Description | |---|---| | CookieSerializeOptions | Options for serialize(): maxAge, expires, httpOnly, secure, path, domain, sameSite, priority | | CookieOptions | Parsed Set-Cookie result: name, value, expires, maxAge, domain, path, secure, httpOnly, sameSite, priority |

🏗 Related Packages

| Package | Description | |---|---| | @chaisser/chunk-array | Split arrays into chunks | | @chaisser/string-wizard | String manipulation utilities | | @chaisser/type-guard | Runtime type guards | | @chaisser/uuid-v7 | UUID v7 generation | | @chaisser/wait-for | Async wait utilities | | @chaisser/regex-humanizer | Human-readable regex descriptions | | @chaisser/password-strength | Password strength checking | | @chaisser/human-time | Human-readable time formatting | | @chaisser/obj-path | Deep object path access | | @chaisser/debounce-throttle | Debounce and throttle functions | | @chaisser/color-utils | Color manipulation utilities | | @chaisser/deep-clone | Deep cloning of objects | | @chaisser/array-group-by | Group array elements by key | | @chaisser/merge-objects | Deep merge objects | | @chaisser/event-emitter | Type-safe event emitter | | @chaisser/unique-by | Unique array elements by property | | @chaisser/memoize | Function memoization | | @chaisser/base64-url | Base64 URL-safe encoding/decoding | | @chaisser/ip-regex | IP address regex patterns | | @chaisser/retry-async | Retry async operations | | @chaisser/rate-limiter | Rate limiting for async functions | | @chaisser/circuit-breaker | Circuit breaker pattern | | @chaisser/query-string | Query string parsing and stringification |

📄 License

MIT

Developed by Doruk Karaboncuk ([email protected])

Repository: github.com/Chaisser/cookie-parser