cookie

cookie is a small, focused Node.js library for parsing and serializing HTTP cookies. It reads incoming Cookie headers into plain name-value objects and turns cookie objects back into header strings, and it does the same for Set-Cookie headers including all standard attributes (Domain, Path, Max-Age, Expires, HttpOnly, Secure, SameSite, Priority, and Partitioned).

Built with zero runtime dependencies and shipped as a sub-1.4KB module, it follows RFC 6265 closely while giving you full control over value encoding and decoding. It is the parsing layer beneath much of the Node ecosystem, used by frameworks like Express and countless session and authentication middlewares.

What You Get

• parseCookie and stringifyCookie for converting between Cookie header strings and plain name-value objects
• parseSetCookie and stringifySetCookie for reading and writing Set-Cookie headers with all standard attributes
• Pluggable encode/decode options so you control exactly how cookie values are transformed
• A zero-dependency, sub-1.4KB, tree-shakeable ESM module with TypeScript types included

Common Use Cases

• Reading cookies from an incoming request in a raw Node.js HTTP server or a framework
• Setting session, authentication, or preference cookies with attributes like HttpOnly, Secure, and SameSite
• Building session or auth middleware that needs precise, spec-compliant cookie handling
• Serializing and deserializing cookie state without pulling in a heavier framework dependency

Under The Hood

Architecture

The entire library lives in a single module (src/index.ts, ~17KB) exporting four functions: parseCookie, stringifyCookie, parseSetCookie, and stringifySetCookie. Parsing is done with a tight character-index scanning loop over the header string rather than expensive String.split/regex-splitting, locating = and ; delimiters manually for speed. Validation of names, values, domains, and paths uses a set of precompiled RFC 6265 regular expressions defined at module top. Parsed results are collected into a null-prototype NullObject container so attacker-controlled cookie names can never pollute Object.prototype.

Tech Stack

Written in TypeScript with zero runtime dependencies and distributed as a native ESM module ("type": "module", exports: "./dist/index.js", sideEffects: false). It targets Node.js >= 22, is built and tested via @borderless/ts-scripts on top of Vitest, and enforces a strict bundle budget of 1.4KB with size-limit. Bundled .d.ts types ship for TypeScript consumers.

Code Quality

Code quality is high: each of the four functions has a dedicated spec file (parse-cookie.spec.ts, parse-set-cookie.spec.ts, stringify-cookie.spec.ts, stringify-set-cookie.spec.ts) plus snapshot fixtures and benchmark suites that parse real top-site cookie headers. The source is densely commented with inline RFC 6265 grammar references explaining each regular expression, and the public surface is fully and strictly typed.

API Design

The public API is deliberately minimal and symmetric — a parse and a stringify function for each of the Cookie and Set-Cookie header types — which makes it easy to learn and hard to misuse. Both parse functions accept a decode option and both stringify functions accept an encode option, with safe URL-encoding defaults wrapped in try..catch, so custom value transforms are a one-line override. Getting started requires no configuration or setup beyond a single import.