@philiprehberger/cookie-ts

Parse, serialize, and manage HTTP cookies with full typing

Installation

npm install @philiprehberger/cookie-ts

Usage

Parse Cookies

import { parseCookies, parseCookie } from '@philiprehberger/cookie-ts';

// Parse a Cookie header into key-value pairs
const cookies = parseCookies('session=abc123; theme=dark');
// { session: 'abc123', theme: 'dark' }

// Parse a Set-Cookie header into a structured object
const cookie = parseCookie(
  'id=xyz; Max-Age=3600; Domain=.example.com; Path=/; Secure; HttpOnly; SameSite=Strict'
);
// { name: 'id', value: 'xyz', maxAge: 3600, domain: '.example.com', ... }

Serialize Cookies

import { serializeCookie } from '@philiprehberger/cookie-ts';

const header = serializeCookie('session', 'abc123', {
  maxAge: 3600,
  path: '/',
  secure: true,
  httpOnly: true,
  sameSite: 'lax',
});
// "session=abc123; Max-Age=3600; Path=/; Secure; HttpOnly; SameSite=Lax"

Cookie Builder

import { cookieBuilder } from '@philiprehberger/cookie-ts';

const header = cookieBuilder('session', 'abc123')
  .maxAge(3600)
  .path('/')
  .secure()
  .httpOnly()
  .sameSite('lax')
  .build();
// "session=abc123; Max-Age=3600; Path=/; Secure; HttpOnly; SameSite=Lax"

Sign and Verify

import { signCookie, verifyCookie } from '@philiprehberger/cookie-ts';

const signed = await signCookie('user123', 'my-secret');
// "user123.HmacSignatureBase64Url"

const value = await verifyCookie(signed, 'my-secret');
// "user123" (or undefined if tampered)

Client-Side (Browser)

import { getCookie, setCookie, deleteCookie } from '@philiprehberger/cookie-ts';

// Read a cookie
const theme = getCookie('theme'); // "dark" or undefined

// Set a cookie
setCookie('theme', 'dark', { maxAge: 86400, path: '/' });

// Delete a cookie
deleteCookie('theme', { path: '/' });

API

Function	Description
parseCookies(header)	Parse a Cookie header string into a Record<string, string>
parseCookie(setCookieHeader)	Parse a Set-Cookie header into a ParsedCookie object
serializeCookie(name, value, options?)	Serialize a cookie into a Set-Cookie header string
cookieBuilder(name, value)	Create a chainable builder that produces a Set-Cookie string
signCookie(value, secret)	Sign a cookie value with HMAC-SHA256
verifyCookie(signed, secret)	Verify a signed cookie, returns value or undefined
getCookie(name)	Get a cookie by name from document.cookie
setCookie(name, value, options?)	Set a cookie via document.cookie
deleteCookie(name, options?)	Delete a cookie by setting Max-Age to 0

Development

npm install
npm run build
npm test

Support

If you find this project useful:

⭐ Star the repo

🐛 Report issues

💡 Suggest features

❤️ Sponsor development

🌐 All Open Source Projects

💻 GitHub Profile

🔗 LinkedIn Profile

License

MIT