Skip to content

Cookies

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.

35 exports Added in v4.0.0 Source

Combinators

expireCookie

Added in v4.0.0 Source

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

Added in v4.0.0 Source

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

Added in v4.0.0 Source

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

Added in v4.0.0 Source

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

Added in v4.0.0 Source

Combines two Cookies objects, removing duplicates from the first

Signature

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

remove

Added in v4.0.0 Source

Removes a cookie by name

Signature

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

set

Added in v4.0.0 Source

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

Added in v4.0.0 Source

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

Added in v4.0.0 Source

Adds multiple cookies to a Cookies object

Signature

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

setAllUnsafe

Added in v4.0.0 Source

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

Added in v4.0.0 Source

Adds a cookie to a Cookies object

Signature

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

setUnsafe

Added in v4.0.0 Source

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

Constructors

empty

Added in v4.0.0 Source

An empty Cookies object

Signature

declare const empty: Cookies;

fromIterable

Added in v4.0.0 Source

Create a Cookies object from an Iterable

Signature

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

fromReadonlyRecord

Added in v4.0.0 Source

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

Added in v4.0.0 Source

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

Signature

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

makeCookie

Added in v4.0.0 Source

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 httpOnly?: boolean;
    readonly maxAge?: Input;
    readonly partitioned?: boolean;
    readonly path?: string;
    readonly priority?: "low" | "medium" | "high";
    readonly sameSite?: "none" | "lax" | "strict";
    readonly secure?: boolean;
  },
): Result<Cookie, CookiesError>;

makeCookieUnsafe

Added in v4.0.0 Source

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" | "lax" | "strict";
    readonly secure?: boolean;
  },
): Cookie;

Cookies

Decoding

parseHeader

Added in v4.0.0 Source

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

Added in v4.0.0 Source

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

Added in v4.0.0 Source

Serializes a Cookies object into a Cookie header.

Signature

declare function toCookieHeader(self: Cookies): string;

toRecord

Added in v4.0.0 Source

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

Added in v4.0.0 Source

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

Signature

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

Errors

CookiesError

Added in v4.0.0 Source

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: "CookieError";
} & 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

Added in v4.0.0 Source

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

Added in v4.0.0 Source

Returns true when a value is a Cookie.

Signature

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

isCookies

Added in v4.0.0 Source

Returns true when a value is a Cookies collection.

Signature

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

Models

Cookies interface

Added in v4.0.0 Source

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

Added in v4.0.0 Source

Returns true when the Cookies collection contains no cookies.

Signature

declare function isEmpty(self: Cookies): boolean;

Schemas

CookieSchema

Added in v4.0.0 Source

Schema for Cookie values.

Signature

declare const CookieSchema: CookieSchema;

CookieSchema interface

Added in v4.0.0 Source

Schema interface for validating Cookie values.

Signature

interface CookieSchema extends declare<Cookie> {
  constructor(_: never);
}

CookiesSchema

Added in v4.0.0 Source

Schema for Cookies collections.

Details

JSON encoding uses Set-Cookie header strings, while isomorphic encoding uses a readonly record of cookie values.

Signature

declare const CookiesSchema: CookiesSchema;

CookiesSchema interface

Added in v4.0.0 Source

Schema interface for validating and encoding Cookies collections.

Signature

interface CookiesSchema extends declare<Cookies, Record.ReadonlyRecord<string, Cookie>> {
  constructor(_: never);
}

schemaRecord

Added in v4.0.0 Source

Schema for transforming Cookies into records of decoded string values keyed by cookie name.

Signature

declare const schemaRecord: decodeTo<$Record<String, String>, CookiesSchema, never, never>;