Class CookieJar

RFC 6265 §5.3 + §5.4 cookie jar implementation.

Stores cookies in a three-level map (domain → path → name) with:

LRU eviction (per-domain cap of 50, global cap of 3000)
__Secure- / __Host- prefix enforcement (RFC 6265bis §4.1.3)
SameSite Strict / Lax / None enforcement
JSON serialization / deserialization

Example

const jar = new CookieJar();
jar.setCookie("session=abc; Path=/; Secure", { url: "https://example.com/" });
const cookies = jar.getCookies({ url: "https://example.com/page" });

Index

Constructors

constructor

new CookieJar(options?: CookieJarOptions): CookieJar
Parameters
- options: CookieJarOptions = {}
  Cookie jar limits and optional custom domain matcher
Returns CookieJar
- Defined in src/cookie-store.ts:282

Accessors

count

get count(): number
Total number of cookies currently stored in the jar.

Returns number
- Defined in src/cookie-store.ts:799

Methods

destroy

destroy(): void
Destroy the jar — clears the periodic cleanup timer. Call this when the jar is no longer needed to prevent memory leaks.

Returns void
- Defined in src/cookie-store.ts:309

setCookie

setCookie(header: string, options: SetCookieOptions): boolean
Set a cookie per RFC 6265 §5.3.

Rejects cookies that exceed size limits, fail domain/path validation, violate prefix rules, or would be immediately expired (treats those as deletes).
Parameters
- header: string
  Raw Set-Cookie header value (e.g. "session=abc; Path=/; Secure")
- options: SetCookieOptions
  URL the cookie was received from + SameSite context
Returns boolean
true if the cookie was stored, false if rejected
- Defined in src/cookie-store.ts:330

getCookies

getCookies(options: GetCookiesOptions): Cookie[]
Retrieve matching cookies per RFC 6265 §5.4.

Filters by domain, path, secure/httpOnly flags, and SameSite context. Results are sorted by longest path first, then oldest creation time. Updates lastAccessed on returned cookies.
Parameters
- options: GetCookiesOptions
  URL, protocol context, and SameSite context
Returns Cookie[]
Array of matching Cookie objects (direct references into storage)
- Defined in src/cookie-store.ts:449

getCookieHeader

getCookieHeader(options: GetCookiesOptions): string
Get a Cookie header string for a request.
Parameters
- options: GetCookiesOptions
  URL and request context
Returns string
"name=value; name=value" string suitable for a Cookie header
- Defined in src/cookie-store.ts:529

getCookiesForDomain

getCookiesForDomain(domain: string): Cookie[]
Get all cookies for a specific domain.
Parameters
- domain: string
  The domain to get cookies for (will be canonicalized)
Returns Cookie[]
Array of cookies that would be sent to this domain
Example
```
jar.setCookie("session=abc", { url: "https://example.com/" });
jar.getCookiesForDomain("example.com"); // Returns cookies for example.com
```
- Defined in src/cookie-store.ts:549

processResponseHeaders

processResponseHeaders(
headers: Headers | Record<string, string | string[]>,
options: SetCookieOptions,
): void
Process Set-Cookie headers from an HTTP response. Extracts all Set-Cookie values and calls setCookie() for each.
Parameters
- headers: Headers | Record<string, string | string[]>
  Response headers (Headers object or plain record)
- options: SetCookieOptions
  URL and SameSite context for all cookies
Returns void
- Defined in src/cookie-store.ts:580

removeCookie

removeCookie(domain: string, path: string, name: string): boolean
Remove a specific cookie by domain, path, and name.
Parameters
- domain: string
  Domain the cookie was stored under
- path: string
  Cookie path
- name: string
  Cookie name
Returns boolean
true if a cookie was removed
- Defined in src/cookie-store.ts:601

clear

clear(): void
Remove every cookie from the jar.

Returns void
- Defined in src/cookie-store.ts:623

clearExpired

clearExpired(): number
Remove all expired cookies from the jar.

Returns number
Number of cookies removed
- Defined in src/cookie-store.ts:633

clearSession

clearSession(): number
Remove all session cookies (cookies with no expiry / Infinity).

Returns number
Number of cookies removed
- Defined in src/cookie-store.ts:657

clearForDomain

clearForDomain(domain: string): number
Remove all cookies for a domain and its subdomains.
Parameters
- domain: string
  Domain to clear (e.g., "example.com" clears sub.example.com too)
Returns number
Number of cookies removed
- Defined in src/cookie-store.ts:681

clearForUrl

clearForUrl(url: string): number
Remove all cookies that would be sent to a given URL.
Parameters
- url: string
  Full URL whose hostname cookies should be cleared
Returns number
Number of cookies removed
- Defined in src/cookie-store.ts:702

toJSON

toJSON(): CookieJSON[]
Serialize all non-expired cookies to a JSON-compatible array. Session cookies (Infinity) are stored with expires: null.

Returns CookieJSON[]
Array of serialized cookies
- Defined in src/cookie-store.ts:718

toString

toString(): string
Get a pretty-printed JSON string of all cookies.

Returns string
Formatted JSON string
- Defined in src/cookie-store.ts:752

`Static`fromJSON

fromJSON(data: string | CookieJSON[]): CookieJar
Deserialize cookies from JSON and create a new CookieJar. Expired cookies in the input are silently skipped.
Parameters
- data: string | CookieJSON[]
  Array of serialized cookies or a JSON string
Returns CookieJar
A new CookieJar populated with the deserialized cookies
- Defined in src/cookie-store.ts:763

getAll

getAll(): Cookie[]
Return a snapshot of all cookies (copies, not references to internal storage).

Returns Cookie[]
Array of cloned Cookie objects
- Defined in src/cookie-store.ts:808

getForDomain

getForDomain(domain: string): Cookie[]
Return all cookies for a given domain (exact match + subdomains).
Parameters
- domain: string
  Domain to query (e.g., "example.com")
Returns Cookie[]
Array of cloned Cookie objects for matching domains
- Defined in src/cookie-store.ts:824

Class CookieJar

Example

Index

Constructors

Accessors

Methods

Constructors

constructor

Parameters

Returns CookieJar

Accessors

count

Returns number

Methods

destroy

Returns void

setCookie

Parameters

Returns boolean

getCookies

Parameters

Returns Cookie[]

getCookieHeader

Parameters

Returns string

getCookiesForDomain

Parameters

Returns Cookie[]

Example

processResponseHeaders

Parameters

Returns void

removeCookie

Parameters

Returns boolean

clear

Returns void

clearExpired

Returns number

clearSession

Returns number

clearForDomain

Parameters

Returns number

clearForUrl

Parameters

Returns number

toJSON

Returns CookieJSON[]

toString

Returns string

StaticfromJSON

Parameters

Returns CookieJar

getAll

Returns Cookie[]

getForDomain

Parameters

Returns Cookie[]

Settings

On This Page

`Static`fromJSON