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.

31 exports Since v4.0.0 Source

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 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 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 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 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 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 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 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 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 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 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 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 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;
}

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 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 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

Cookie

interface unstable

Since v4.0.0

HTTP cookie value with its decoded value, encoded value, and optional cookie attributes such as domain, path, expiration, security, and same-site settings.

Signature

interface Cookie extends Inspectable {
  readonly "~effect/http/Cookies/Cookie": "~effect/http/Cookies/Cookie";
  readonly name: string;
  readonly options?: {
    readonly domain?: string;
    readonly expires?: Date;
    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;
  };
  readonly value: string;
  readonly valueEncoded: string;
}

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;
  });
}

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