Skip to content
// EFFECT DAYS 2026

Cookies unstable

Models HTTP cookies and cookie collections for requests and responses.

A Cookie stores a name, value, encoded value, and standard cookie attributes. A Cookies value is an immutable collection keyed by cookie name. This module parses request Cookie headers, builds response Set-Cookie headers, and provides helpers for adding, removing, merging, and expiring cookies.

For client-side storage, mergeIntoArray and toRequestCookieHeader work on a plain array of cookies scoped by domain, path and scheme, following RFC 6265.

33 exports Since v4.0.0 Source

Client Storage

mergeIntoArray

unstable
Since v4.0.0

Merges cookies set by url into an array of client cookies, returning a new array.

When to use

Use to record the cookies of a response, or to seed an array of client cookies from Set-Cookie values for a base URL.

Details

A cookie without a Domain attribute is scoped as hostOnly to the exact host of url. A Domain attribute is accepted only when the host of url domain-matches it. Without a Path attribute the cookie uses the default path of url. Max-Age takes precedence over Expires, and both are converted to an absolute expires computed from now (epoch milliseconds).

A cookie replaces the existing cookie with the same name, domain and path, keeping its position. A cookie that is already expired removes that existing cookie instead. The array is returned unchanged when url is not a valid absolute URL.

Gotchas

  • There is no public suffix list. A Domain attribute is accepted whenever the request host domain-matches it, unless the host is an IP address or the domain is a single label such as com, so foo.co.uk can set Domain=co.uk.

Signature

declare const mergeIntoArray: {
  (url: string, cookies: Cookies, now: number): (self: readonly Array<Cookie>) => readonly Array<Cookie>;
  (self: readonly Array<Cookie>, url: string, cookies: Cookies, now: number): readonly Array<Cookie>;
}

toRequestCookieHeader

unstable
Since v4.0.0

Serializes the client cookies to send with a request to url into a Cookie header value.

Details

Selects cookies that have not expired at now (epoch milliseconds) and whose domain and path match url, skipping Secure cookies unless url uses https. Every matching cookie is kept, including cookies with the same name, ordered by longest path first. Returns undefined when no cookie matches.

A leading dot and letter case in domain are ignored. A cookie without a domain is never sent, and a cookie without a path matches every path.

Signature

declare const toRequestCookieHeader: {
  (url: string, now: number): (self: readonly Array<Cookie>) => string | undefined;
  (self: readonly Array<Cookie>, url: string, now: number): string | undefined;
}

Combinators

expireCookie

unstable
Since v4.0.0

Adds an expired cookie safely with an empty value, Max-Age=0, and an epoch Expires value.

Details

Returns a CookiesError in the Result failure channel when the name or options are invalid.

Signature

declare const expireCookie: {
  (name: string, options?: Omit<{
    readonly domain?: string;
    readonly expires?: Date;
    readonly hostOnly?: boolean;
    readonly httpOnly?: boolean;
    readonly maxAge?: Duration.Input;
    readonly partitioned?: boolean;
    readonly path?: string;
    readonly priority?: "low" | "medium" | "high";
    readonly sameSite?: "lax" | "strict" | "none";
    readonly secure?: boolean;
  }, "expires" | "maxAge">): (self: Cookies) => Result<Cookies, CookiesError>;
  (self: Cookies, name: string, options?: Omit<{
    readonly domain?: string;
    readonly expires?: Date;
    readonly hostOnly?: boolean;
    readonly httpOnly?: boolean;
    readonly maxAge?: Duration.Input;
    readonly partitioned?: boolean;
    readonly path?: string;
    readonly priority?: "low" | "medium" | "high";
    readonly sameSite?: "lax" | "strict" | "none";
    readonly secure?: boolean;
  }, "expires" | "maxAge">): Result<Cookies, CookiesError>;
}

expireCookieUnsafe

unstable
Since v4.0.0

Adds an expired cookie to a Cookies object, throwing an error if invalid

Signature

declare const expireCookieUnsafe: {
  (name: string, options?: Omit<{
    readonly domain?: string;
    readonly expires?: Date;
    readonly hostOnly?: boolean;
    readonly httpOnly?: boolean;
    readonly maxAge?: Duration.Input;
    readonly partitioned?: boolean;
    readonly path?: string;
    readonly priority?: "low" | "medium" | "high";
    readonly sameSite?: "lax" | "strict" | "none";
    readonly secure?: boolean;
  }, "expires" | "maxAge">): (self: Cookies) => Cookies;
  (self: Cookies, name: string, options?: Omit<{
    readonly domain?: string;
    readonly expires?: Date;
    readonly hostOnly?: boolean;
    readonly httpOnly?: boolean;
    readonly maxAge?: Duration.Input;
    readonly partitioned?: boolean;
    readonly path?: string;
    readonly priority?: "low" | "medium" | "high";
    readonly sameSite?: "lax" | "strict" | "none";
    readonly secure?: boolean;
  }, "expires" | "maxAge">): Cookies;
}

get

unstable
Since v4.0.0

Gets a cookie from a Cookies object safely.

Signature

declare const get: {
  (name: string): (self: Cookies) => Option<Cookie>;
  (self: Cookies, name: string): Option<Cookie>;
}

getValue

unstable
Since v4.0.0

Gets the decoded value of a cookie by name safely.

Details

Returns Option.none() when the cookie is not present.

Signature

declare const getValue: {
  (name: string): (self: Cookies) => Option<string>;
  (self: Cookies, name: string): Option<string>;
}

merge

unstable
Since v4.0.0

Combines two Cookies objects, removing duplicates from the first

Signature

declare const merge: {
  (that: Cookies): (self: Cookies) => Cookies;
  (self: Cookies, that: Cookies): Cookies;
}

remove

unstable
Since v4.0.0

Removes a cookie by name

Signature

declare const remove: {
  (name: string): (self: Cookies) => Cookies;
  (self: Cookies, name: string): Cookies;
}

set

unstable
Since v4.0.0

Creates and adds a cookie safely by name and value.

Details

The cookie fields are validated first; invalid input returns a CookiesError in the Result failure channel.

Signature

declare const set: {
  (name: string, value: string, options?: {
    readonly domain?: string;
    readonly expires?: Date;
    readonly hostOnly?: boolean;
    readonly httpOnly?: boolean;
    readonly maxAge?: Duration.Input;
    readonly partitioned?: boolean;
    readonly path?: string;
    readonly priority?: "low" | "medium" | "high";
    readonly sameSite?: "lax" | "strict" | "none";
    readonly secure?: boolean;
  }): (self: Cookies) => Result<Cookies, CookiesError>;
  (self: Cookies, name: string, value: string, options?: {
    readonly domain?: string;
    readonly expires?: Date;
    readonly hostOnly?: boolean;
    readonly httpOnly?: boolean;
    readonly maxAge?: Duration.Input;
    readonly partitioned?: boolean;
    readonly path?: string;
    readonly priority?: "low" | "medium" | "high";
    readonly sameSite?: "lax" | "strict" | "none";
    readonly secure?: boolean;
  }): Result<Cookies, CookiesError>;
}

setAll

unstable
Since v4.0.0

Creates and adds multiple cookies safely from name/value/options tuples.

Details

If any tuple is invalid, returns the first CookiesError and leaves the original collection unchanged.

Signature

declare const setAll: {
  (cookies: Iterable<readonly [string, string, {
    readonly domain?: string;
    readonly expires?: Date;
    readonly hostOnly?: boolean;
    readonly httpOnly?: boolean;
    readonly maxAge?: Duration.Input;
    readonly partitioned?: boolean;
    readonly path?: string;
    readonly priority?: "low" | "medium" | "high";
    readonly sameSite?: "lax" | "strict" | "none";
    readonly secure?: boolean;
  } | undefined]>): (self: Cookies) => Result<Cookies, CookiesError>;
  (self: Cookies, cookies: Iterable<readonly [string, string, {
    readonly domain?: string;
    readonly expires?: Date;
    readonly hostOnly?: boolean;
    readonly httpOnly?: boolean;
    readonly maxAge?: Duration.Input;
    readonly partitioned?: boolean;
    readonly path?: string;
    readonly priority?: "low" | "medium" | "high";
    readonly sameSite?: "lax" | "strict" | "none";
    readonly secure?: boolean;
  } | undefined]>): Result<Cookies, CookiesError>;
}

setAllCookie

unstable
Since v4.0.0

Adds multiple cookies to a Cookies object

Signature

declare const setAllCookie: {
  (cookies: Iterable<Cookie>): (self: Cookies) => Cookies;
  (self: Cookies, cookies: Iterable<Cookie>): Cookies;
}

setAllUnsafe

unstable
Since v4.0.0

Adds multiple cookies to a Cookies object, throwing an error if invalid

Signature

declare const setAllUnsafe: {
  (cookies: Iterable<readonly [string, string, {
    readonly domain?: string;
    readonly expires?: Date;
    readonly hostOnly?: boolean;
    readonly httpOnly?: boolean;
    readonly maxAge?: Duration.Input;
    readonly partitioned?: boolean;
    readonly path?: string;
    readonly priority?: "low" | "medium" | "high";
    readonly sameSite?: "lax" | "strict" | "none";
    readonly secure?: boolean;
  } | undefined]>): (self: Cookies) => Cookies;
  (self: Cookies, cookies: Iterable<readonly [string, string, {
    readonly domain?: string;
    readonly expires?: Date;
    readonly hostOnly?: boolean;
    readonly httpOnly?: boolean;
    readonly maxAge?: Duration.Input;
    readonly partitioned?: boolean;
    readonly path?: string;
    readonly priority?: "low" | "medium" | "high";
    readonly sameSite?: "lax" | "strict" | "none";
    readonly secure?: boolean;
  } | undefined]>): Cookies;
}

setCookie

unstable
Since v4.0.0

Adds a cookie to a Cookies object

Signature

declare const setCookie: {
  (cookie: Cookie): (self: Cookies) => Cookies;
  (self: Cookies, cookie: Cookie): Cookies;
}

setUnsafe

unstable
Since v4.0.0

Creates and adds a cookie by name and value, throwing if the cookie fields are invalid.

Signature

declare const setUnsafe: {
  (name: string, value: string, options?: {
    readonly domain?: string;
    readonly expires?: Date;
    readonly hostOnly?: boolean;
    readonly httpOnly?: boolean;
    readonly maxAge?: Duration.Input;
    readonly partitioned?: boolean;
    readonly path?: string;
    readonly priority?: "low" | "medium" | "high";
    readonly sameSite?: "lax" | "strict" | "none";
    readonly secure?: boolean;
  }): (self: Cookies) => Cookies;
  (self: Cookies, name: string, value: string, options?: {
    readonly domain?: string;
    readonly expires?: Date;
    readonly hostOnly?: boolean;
    readonly httpOnly?: boolean;
    readonly maxAge?: Duration.Input;
    readonly partitioned?: boolean;
    readonly path?: string;
    readonly priority?: "low" | "medium" | "high";
    readonly sameSite?: "lax" | "strict" | "none";
    readonly secure?: boolean;
  }): Cookies;
}

Constructors

empty

unstable
Since v4.0.0

An empty Cookies object

Signature

declare const empty: Cookies

fromIterable

unstable
Since v4.0.0

Create a Cookies object from an Iterable

Signature

declare function fromIterable(cookies: Iterable<Cookie>): Cookies

fromReadonlyRecord

unstable
Since v4.0.0

Creates a Cookies collection from an existing readonly record of cookies keyed by cookie name.

Signature

declare function fromReadonlyRecord(cookies: Record.ReadonlyRecord<string, Cookie>): Cookies

fromSetCookie

unstable
Since v4.0.0

Create a Cookies object from a set of Set-Cookie headers

Signature

declare function fromSetCookie(headers: string | Iterable<string, any, any>): Cookies

makeCookie

unstable
Since v4.0.0

Creates a cookie, validating the name, encoded value, domain, path, and finite maxAge.

Details

Returns a CookiesError in the Result failure channel when validation fails.

Signature

declare function makeCookie(name: string, value: string, options?: {
  readonly domain?: string;
  readonly expires?: Date;
  readonly hostOnly?: boolean;
  readonly httpOnly?: boolean;
  readonly maxAge?: Input;
  readonly partitioned?: boolean;
  readonly path?: string;
  readonly priority?: "low" | "medium" | "high";
  readonly sameSite?: "none" | "strict" | "lax";
  readonly secure?: boolean;
}): Result<Cookie, CookiesError>

makeCookieUnsafe

unstable
Since v4.0.0

Create a new cookie, throwing an error if invalid

Signature

declare function makeCookieUnsafe(name: string, value: string, options?: {
  readonly domain?: string;
  readonly expires?: Date;
  readonly hostOnly?: boolean;
  readonly httpOnly?: boolean;
  readonly maxAge?: Input;
  readonly partitioned?: boolean;
  readonly path?: string;
  readonly priority?: "low" | "medium" | "high";
  readonly sameSite?: "none" | "strict" | "lax";
  readonly secure?: boolean;
}): Cookie

Cookies

Decoding

parseHeader

unstable
Since v4.0.0

Parses a cookie header into a record of key-value pairs

Details

Adapted from https://github.com/fastify/fastify-cookie under MIT License

Signature

declare function parseHeader(header: string): Record<string, string>

Encoding

serializeCookie

unstable
Since v4.0.0

Serializes a cookie into a string.

Details

Adapted from https://github.com/fastify/fastify-cookie under MIT License

Signature

declare function serializeCookie(self: Cookie): string

toCookieHeader

unstable
Since v4.0.0

Serializes a Cookies object into a Cookie header.

Signature

declare function toCookieHeader(self: Cookies): string

toRecord

unstable
Since v4.0.0

Converts a Cookies collection to a record of decoded cookie values keyed by cookie name.

Signature

declare function toRecord(self: Cookies): Record<string, string>

toSetCookieHeaders

unstable
Since v4.0.0

Serializes a Cookies collection into an array of Set-Cookie header values.

Signature

declare function toSetCookieHeaders(self: Cookies): Array<string>

Errors

CookiesError

unstable
Since v4.0.0

Error returned when a cookie name, value, domain, path, or max-age option is invalid.

Details

Inspect reason to determine the specific validation failure.

Signature

declare class CookiesError extends YieldableError<this> & {
  readonly _tag: "CookiesError";
} & Readonly<{
  readonly reason: CookiesErrorReason;
}> {
  constructor(args: {
    readonly reason: CookiesErrorReason;
  });
  readonly "~effect/http/Cookies/CookieError": "~effect/http/Cookies/CookieError";
  message: "InvalidCookieName" | "InvalidCookieValue" | "InvalidCookieDomain" | "InvalidCookiePath" | "CookieInfinityMaxAge";
  static fromReason(reason: "InvalidCookieName" | "InvalidCookieValue" | "InvalidCookieDomain" | "InvalidCookiePath" | "CookieInfinityMaxAge", cause?: unknown): CookiesError;
}

CookiesErrorReason

unstable
Since v4.0.0

Error reason describing why cookie construction failed, such as invalid name, value, domain, path, or infinite max-age.

Signature

declare class CookiesErrorReason extends Error<{
  readonly _tag: "InvalidCookieName" | "InvalidCookieValue" | "InvalidCookieDomain" | "InvalidCookiePath" | "CookieInfinityMaxAge";
  readonly cause?: unknown;
}> {
  constructor(args: {
    readonly _tag: "InvalidCookieName" | "InvalidCookieValue" | "InvalidCookieDomain" | "InvalidCookiePath" | "CookieInfinityMaxAge";
    readonly cause?: unknown;
  });
}

Guards

isCookie

unstable
Since v4.0.0

Returns true when a value is a Cookie.

Signature

declare function isCookie(u: unknown): u is Cookie

isCookies

unstable
Since v4.0.0

Returns true when a value is a Cookies collection.

Signature

declare function isCookies(u: unknown): u is Cookies

isCookiesError

unstable
Since v4.0.0

Checks whether a value is a CookiesError.

Signature

declare function isCookiesError(u: unknown): u is CookiesError

Models

Cookies

interface unstable
Since v4.0.0

Immutable collection of HTTP cookies keyed by cookie name.

Signature

interface Cookies extends Pipeable, Inspectable {
  readonly "~effect/http/Cookies": "~effect/http/Cookies";
  readonly cookies: Record.ReadonlyRecord<string, Cookie>;
}

Predicates

isEmpty

unstable
Since v4.0.0

Returns true when the Cookies collection contains no cookies.

Signature

declare function isEmpty(self: Cookies): boolean