🍪 @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 (doruk.karaboncuk@interaktifis.com)

Repository: github.com/Chaisser/cookie-parser