effect 4.0.0-beta.65 → 4.0.0-beta.67

package/src/unstable/http/Cookies.ts

@@ -1,4 +1,18 @@
 /**
+ * Utilities for representing, validating, parsing, and serializing HTTP cookies.
+ *
+ * This module provides an immutable `Cookies` collection keyed by cookie name,
+ * constructors for validated `Cookie` values, and helpers for common server and
+ * client flows such as reading `Cookie` request headers, emitting `Set-Cookie`
+ * response headers, merging cookie sets, and expiring cookies.
+ *
+ * Cookie parsing is intentionally tolerant of malformed input: unsupported or
+ * invalid `Set-Cookie` attributes are ignored, values are percent-decoded on a
+ * best-effort basis, and collections keep one cookie per name. Security
+ * attributes such as `HttpOnly`, `Secure`, `SameSite`, and `Partitioned` are
+ * serialized when present, but browsers enforce their final behavior, so set
+ * them explicitly for session, cross-site, and HTTPS-sensitive cookies.
+ *
  * @since 4.0.0
  */
 import * as Data from "../../Data.ts"
@@ -17,14 +31,18 @@ import type * as Types from "../../Types.ts"
 const TypeId = "~effect/http/Cookies"
 
 /**
- * @since 4.0.0
+ * Returns `true` when a value is a `Cookies` collection.
+ *
  * @category refinements
+ * @since 4.0.0
  */
 export const isCookies = (u: unknown): u is Cookies => Predicate.hasProperty(u, TypeId)
 
 /**
- * @since 4.0.0
+ * Immutable collection of HTTP cookies keyed by cookie name.
+ *
  * @category models
+ * @since 4.0.0
  */
 export interface Cookies extends Pipeable, Inspectable.Inspectable {
   readonly [TypeId]: typeof TypeId
@@ -32,14 +50,21 @@ export interface Cookies extends Pipeable, Inspectable.Inspectable {
 }
 
 /**
- * @since 4.0.0
+ * Schema interface for validating and encoding `Cookies` collections.
+ *
  * @category Schemas
+ * @since 4.0.0
  */
 export interface CookiesSchema extends Schema.declare<Cookies, Record.ReadonlyRecord<string, Cookie>> {}
 
 /**
- * @since 4.0.0
+ * Schema for `Cookies` collections.
+ *
+ * JSON encoding uses `Set-Cookie` header strings, while isomorphic encoding uses
+ * a readonly record of cookie values.
+ *
  * @category Schemas
+ * @since 4.0.0
  */
 export const CookiesSchema: CookiesSchema = Schema.declare(
   isCookies,
@@ -76,8 +101,11 @@ export const CookiesSchema: CookiesSchema = Schema.declare(
 const CookieTypeId = "~effect/http/Cookies/Cookie"
 
 /**
- * @since 4.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.
+ *
  * @category cookie
+ * @since 4.0.0
  */
 export interface Cookie extends Inspectable.Inspectable {
   readonly [CookieTypeId]: typeof CookieTypeId
@@ -98,20 +126,26 @@ export interface Cookie extends Inspectable.Inspectable {
 }
 
 /**
- * @since 4.0.0
+ * Returns `true` when a value is a `Cookie`.
+ *
  * @category Guards
+ * @since 4.0.0
  */
 export const isCookie = (u: unknown): u is Cookie => Predicate.hasProperty(u, CookieTypeId)
 
 /**
- * @since 4.0.0
+ * Schema interface for validating `Cookie` values.
+ *
  * @category Schemas
+ * @since 4.0.0
  */
 export interface CookieSchema extends Schema.declare<Cookie> {}
 
 /**
- * @since 4.0.0
+ * Schema for `Cookie` values.
+ *
  * @category Schemas
+ * @since 4.0.0
  */
 export const CookieSchema: CookieSchema = Schema.declare(
   isCookie,
@@ -131,8 +165,11 @@ export const CookieSchema: CookieSchema = Schema.declare(
 const CookieErrorTypeId = "~effect/http/Cookies/CookieError"
 
 /**
- * @since 4.0.0
+ * Structured reason describing why cookie construction failed, such as invalid
+ * name, value, domain, path, or infinite max-age.
+ *
  * @category errors
+ * @since 4.0.0
  */
 export class CookiesErrorReason extends Data.Error<{
   readonly _tag:
@@ -145,13 +182,19 @@ export class CookiesErrorReason extends Data.Error<{
 }> {}
 
 /**
- * @since 4.0.0
+ * Error returned when a cookie name, value, domain, path, or max-age option is invalid.
+ *
+ * Inspect `reason` to determine the specific validation failure.
+ *
  * @category errors
+ * @since 4.0.0
  */
 export class CookiesError extends Data.TaggedError("CookieError")<{
   readonly reason: CookiesErrorReason
 }> {
   /**
+   * Creates a cookie error from a reason tag and optional cause.
+   *
    * @since 4.0.0
    */
   static fromReason(reason: CookiesError["reason"]["_tag"], cause?: unknown): CookiesError {
@@ -159,11 +202,15 @@ export class CookiesError extends Data.TaggedError("CookieError")<{
   }
 
   /**
+   * Marks this value as a cookie validation error for runtime guards.
+   *
    * @since 4.0.0
    */
   readonly [CookieErrorTypeId] = CookieErrorTypeId
 
   /**
+   * Uses the concrete cookie error reason as the public message.
+   *
    * @since 4.0.0
    */
   override get message() {
@@ -186,10 +233,10 @@ const Proto: Omit<Cookies, "cookies"> = {
 }
 
 /**
- * Create a Cookies object from an Iterable
+ * Creates a `Cookies` collection from an existing readonly record of cookies keyed by cookie name.
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const fromReadonlyRecord = (cookies: Record.ReadonlyRecord<string, Cookie>): Cookies => {
   const self = Object.create(Proto)
@@ -200,8 +247,8 @@ export const fromReadonlyRecord = (cookies: Record.ReadonlyRecord<string, Cookie
 /**
  * Create a Cookies object from an Iterable
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const fromIterable = (cookies: Iterable<Cookie>): Cookies => {
   const record: Record<string, Cookie> = {}
@@ -214,8 +261,8 @@ export const fromIterable = (cookies: Iterable<Cookie>): Cookies => {
 /**
  * Create a Cookies object from a set of Set-Cookie headers
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const fromSetCookie = (headers: Iterable<string> | string): Cookies => {
   const arrayHeaders = typeof headers === "string" ? [headers] : headers
@@ -364,14 +411,16 @@ function parseSetCookie(header: string): Cookie | undefined {
 /**
  * An empty Cookies object
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const empty: Cookies = fromIterable([])
 
 /**
- * @since 4.0.0
+ * Returns `true` when the `Cookies` collection contains no cookies.
+ *
  * @category refinements
+ * @since 4.0.0
  */
 export const isEmpty = (self: Cookies): boolean => Record.isEmptyRecord(self.cookies)
 
@@ -392,10 +441,12 @@ const CookieProto = {
 }
 
 /**
- * Create a new cookie
+ * Creates a cookie, validating the name, encoded value, domain, path, and finite `maxAge`.
+ *
+ * Returns a `CookiesError` in the `Result` failure channel when validation fails.
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export function makeCookie(
   name: string,
@@ -435,8 +486,8 @@ export function makeCookie(
 /**
  * Create a new cookie, throwing an error if invalid
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const makeCookieUnsafe = (
   name: string,
@@ -447,22 +498,22 @@ export const makeCookieUnsafe = (
 /**
  * Add a cookie to a Cookies object
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const setCookie: {
   /**
    * Add a cookie to a Cookies object
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   (cookie: Cookie): (self: Cookies) => Cookies
   /**
    * Add a cookie to a Cookies object
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   (self: Cookies, cookie: Cookie): Cookies
 } = dual(
@@ -478,22 +529,22 @@ export const setCookie: {
 /**
  * Add multiple cookies to a Cookies object
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const setAllCookie: {
   /**
    * Add multiple cookies to a Cookies object
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   (cookies: Iterable<Cookie>): (self: Cookies) => Cookies
   /**
    * Add multiple cookies to a Cookies object
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   (self: Cookies, cookies: Iterable<Cookie>): Cookies
 } = dual(2, (self: Cookies, cookies: Iterable<Cookie>) => {
@@ -507,22 +558,22 @@ export const setAllCookie: {
 /**
  * Combine two Cookies objects, removing duplicates from the first
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const merge: {
   /**
    * Combine two Cookies objects, removing duplicates from the first
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   (that: Cookies): (self: Cookies) => Cookies
   /**
    * Combine two Cookies objects, removing duplicates from the first
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   (self: Cookies, that: Cookies): Cookies
 } = dual(2, (self: Cookies, that: Cookies) =>
@@ -534,22 +585,22 @@ export const merge: {
 /**
  * Remove a cookie by name
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const remove: {
   /**
    * Remove a cookie by name
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   (name: string): (self: Cookies) => Cookies
   /**
    * Remove a cookie by name
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   (self: Cookies, name: string): Cookies
 } = dual(2, (self: Cookies, name: string) => fromReadonlyRecord(Record.remove(self.cookies, name)))
@@ -557,22 +608,22 @@ export const remove: {
 /**
  * Get a cookie from a Cookies object
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const get: {
   /**
    * Get a cookie from a Cookies object
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   (name: string): (self: Cookies) => Option.Option<Cookie>
   /**
    * Get a cookie from a Cookies object
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   (self: Cookies, name: string): Option.Option<Cookie>
 } = dual(
@@ -581,24 +632,30 @@ export const get: {
 )
 
 /**
- * Get a cookie from a Cookies object
+ * Gets the decoded value of a cookie by name.
+ *
+ * Returns `Option.none()` when the cookie is not present.
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const getValue: {
   /**
-   * Get a cookie from a Cookies object
+   * Gets the decoded value of a cookie by name.
+   *
+   * Returns `Option.none()` when the cookie is not present.
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   (name: string): (self: Cookies) => Option.Option<string>
   /**
-   * Get a cookie from a Cookies object
+   * Gets the decoded value of a cookie by name.
+   *
+   * Returns `Option.none()` when the cookie is not present.
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   (self: Cookies, name: string): Option.Option<string>
 } = dual(
@@ -607,24 +664,30 @@ export const getValue: {
 )
 
 /**
- * Add a cookie to a Cookies object
+ * Creates and adds a cookie by name and value.
+ *
+ * The cookie fields are validated first; invalid input returns a `CookiesError` in the `Result` failure channel.
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const set: {
   /**
-   * Add a cookie to a Cookies object
+   * Creates and adds a cookie by name and value.
+   *
+   * The cookie fields are validated first; invalid input returns a `CookiesError` in the `Result` failure channel.
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   (name: string, value: string, options?: Cookie["options"]): (self: Cookies) => Result.Result<Cookies, CookiesError>
   /**
-   * Add a cookie to a Cookies object
+   * Creates and adds a cookie by name and value.
+   *
+   * The cookie fields are validated first; invalid input returns a `CookiesError` in the `Result` failure channel.
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   (self: Cookies, name: string, value: string, options?: Cookie["options"]): Result.Result<Cookies, CookiesError>
 } = dual(
@@ -637,24 +700,24 @@ export const set: {
 )
 
 /**
- * Add a cookie to a Cookies object
+ * Creates and adds a cookie by name and value, throwing if the cookie fields are invalid.
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const setUnsafe: {
   /**
-   * Add a cookie to a Cookies object
+   * Creates and adds a cookie by name and value, throwing if the cookie fields are invalid.
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   (name: string, value: string, options?: Cookie["options"]): (self: Cookies) => Cookies
   /**
-   * Add a cookie to a Cookies object
+   * Creates and adds a cookie by name and value, throwing if the cookie fields are invalid.
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   (self: Cookies, name: string, value: string, options?: Cookie["options"]): Cookies
 } = dual(
@@ -668,27 +731,33 @@ export const setUnsafe: {
 )
 
 /**
- * Add an expired cookie to a Cookies object
+ * Adds an expired cookie with an empty value, `Max-Age=0`, and an epoch `Expires` value.
+ *
+ * Returns a `CookiesError` in the `Result` failure channel when the name or options are invalid.
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const expireCookie: {
   /**
-   * Add an expired cookie to a Cookies object
+   * Adds an expired cookie with an empty value, `Max-Age=0`, and an epoch `Expires` value.
+   *
+   * Returns a `CookiesError` in the `Result` failure channel when the name or options are invalid.
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   (
     name: string,
     options?: Omit<NonNullable<Cookie["options"]>, "expires" | "maxAge">
   ): (self: Cookies) => Result.Result<Cookies, CookiesError>
   /**
-   * Add an expired cookie to a Cookies object
+   * Adds an expired cookie with an empty value, `Max-Age=0`, and an epoch `Expires` value.
+   *
+   * Returns a `CookiesError` in the `Result` failure channel when the name or options are invalid.
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   (
     self: Cookies,
@@ -712,15 +781,15 @@ export const expireCookie: {
 /**
  * Add an expired cookie to a Cookies object, throwing an error if invalid
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const expireCookieUnsafe: {
   /**
    * Add an expired cookie to a Cookies object, throwing an error if invalid
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   (
     name: string,
@@ -729,8 +798,8 @@ export const expireCookieUnsafe: {
   /**
    * Add an expired cookie to a Cookies object, throwing an error if invalid
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   (
     self: Cookies,
@@ -752,26 +821,32 @@ export const expireCookieUnsafe: {
 )
 
 /**
- * Add multiple cookies to a Cookies object
+ * Creates and adds multiple cookies from name/value/options tuples.
+ *
+ * If any tuple is invalid, returns the first `CookiesError` and leaves the original collection unchanged.
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const setAll: {
   /**
-   * Add multiple cookies to a Cookies object
+   * Creates and adds multiple cookies from name/value/options tuples.
+   *
+   * If any tuple is invalid, returns the first `CookiesError` and leaves the original collection unchanged.
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   (
     cookies: Iterable<readonly [name: string, value: string, options?: Cookie["options"]]>
   ): (self: Cookies) => Result.Result<Cookies, CookiesError>
   /**
-   * Add multiple cookies to a Cookies object
+   * Creates and adds multiple cookies from name/value/options tuples.
+   *
+   * If any tuple is invalid, returns the first `CookiesError` and leaves the original collection unchanged.
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   (
     self: Cookies,
@@ -798,15 +873,15 @@ export const setAll: {
 /**
  * Add multiple cookies to a Cookies object, throwing an error if invalid
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const setAllUnsafe: {
   /**
    * Add multiple cookies to a Cookies object, throwing an error if invalid
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   (
     cookies: Iterable<readonly [name: string, value: string, options?: Cookie["options"]]>
@@ -814,8 +889,8 @@ export const setAllUnsafe: {
   /**
    * Add multiple cookies to a Cookies object, throwing an error if invalid
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   (
     self: Cookies,
@@ -834,8 +909,8 @@ export const setAllUnsafe: {
  *
  * Adapted from https://github.com/fastify/fastify-cookie under MIT License
  *
- * @since 4.0.0
  * @category encoding
+ * @since 4.0.0
  */
 export function serializeCookie(self: Cookie): string {
   let str = self.name + "=" + self.valueEncoded
@@ -910,15 +985,17 @@ export function serializeCookie(self: Cookie): string {
 /**
  * Serialize a Cookies object into a Cookie header
  *
- * @since 4.0.0
  * @category encoding
+ * @since 4.0.0
  */
 export const toCookieHeader = (self: Cookies): string =>
   Object.values(self.cookies).map((cookie) => `${cookie.name}=${cookie.valueEncoded}`).join("; ")
 
 /**
- * @since 4.0.0
+ * Converts a `Cookies` collection to a record of decoded cookie values keyed by cookie name.
+ *
  * @category encoding
+ * @since 4.0.0
  */
 export const toRecord = (self: Cookies): Record<string, string> => {
   const record: Record<string, string> = {}
@@ -931,8 +1008,10 @@ export const toRecord = (self: Cookies): Record<string, string> => {
 }
 
 /**
- * @since 4.0.0
+ * Schema transformation between `Cookies` and a record of decoded string values keyed by cookie name.
+ *
  * @category Schemas
+ * @since 4.0.0
  */
 export const schemaRecord = CookiesSchema.pipe(
   Schema.decodeTo(
@@ -945,10 +1024,10 @@ export const schemaRecord = CookiesSchema.pipe(
 )
 
 /**
- * Serialize a Cookies object into Headers object containing one or more Set-Cookie headers
+ * Serializes a `Cookies` collection into an array of `Set-Cookie` header values.
  *
- * @since 4.0.0
  * @category encoding
+ * @since 4.0.0
  */
 export const toSetCookieHeaders = (self: Cookies): Array<string> => Object.values(self.cookies).map(serializeCookie)
 
@@ -957,8 +1036,8 @@ export const toSetCookieHeaders = (self: Cookies): Array<string> => Object.value
  *
  * Adapted from https://github.com/fastify/fastify-cookie under MIT License
  *
- * @since 4.0.0
  * @category decoding
+ * @since 4.0.0
  */
 export function parseHeader(header: string): Record<string, string> {
   const result: Record<string, string> = {}