effect 4.0.0-beta.66 → 4.0.0-beta.67

package/src/unstable/http/Headers.ts

@@ -1,4 +1,20 @@
 /**
+ * Utilities for representing and transforming HTTP headers.
+ *
+ * This module provides an immutable `Headers` collection for request and
+ * response metadata, along with constructors and combinators for common header
+ * workflows such as reading values, checking for presence, setting or merging
+ * header sets, removing names, and redacting sensitive headers before
+ * inspection.
+ *
+ * Header names are normalized to lowercase by the safe constructors and
+ * lookups, matching HTTP's case-insensitive header-name semantics. Each stored
+ * header name maps to a single string value: array values in record input are
+ * joined with `", "`, iterable input keeps the last value for duplicate names,
+ * and later values override earlier ones when setting or merging. Be careful
+ * with headers that require distinct field lines, such as `set-cookie`, because
+ * this representation does not preserve multiple values separately.
+ *
  * @since 4.0.0
  */
 import * as Context from "../../Context.ts"
@@ -19,26 +35,34 @@ import type { Mutable } from "../../Types.ts"
 /**
  * This is a symbol to allow direct access of keys without conflicts.
  *
- * @since 4.0.0
  * @category type ids
+ * @since 4.0.0
  */
 export const TypeId: unique symbol = Symbol.for("~effect/http/Headers")
 
 /**
- * @since 4.0.0
+ * Type of the unique symbol used to brand `Headers` values.
+ *
  * @category type ids
+ * @since 4.0.0
  */
 export type TypeId = typeof TypeId
 
 /**
- * @since 4.0.0
+ * Returns `true` if the provided value is a `Headers` value.
+ *
  * @category refinements
+ * @since 4.0.0
  */
 export const isHeaders = (u: unknown): u is Headers => Predicate.hasProperty(u, TypeId)
 
 /**
- * @since 4.0.0
+ * Represents an immutable HTTP header collection keyed by lowercase header name.
+ *
+ * `Headers` values also support redaction through the `Redactable` protocol.
+ *
  * @category models
+ * @since 4.0.0
  */
 export interface Headers extends Redactable.Redactable {
   readonly [TypeId]: TypeId
@@ -83,20 +107,28 @@ const make = (input: Record.ReadonlyRecord<string, string>): Mutable<Headers> =>
   Object.assign(Object.create(Proto), input) as Headers
 
 /**
- * @since 4.0.0
+ * Equivalence instance that compares `Headers` by their header names and string values.
+ *
  * @category Equivalence
+ * @since 4.0.0
  */
 export const Equivalence: Equ.Equivalence<Headers> = Record.makeEquivalence(Equ.strictEqual<string>())
 
 /**
- * @since 4.0.0
+ * Schema interface for `Headers` values encoded as records of string header values.
+ *
  * @category schemas
+ * @since 4.0.0
  */
 export interface HeadersSchema extends Schema.declare<Headers, { readonly [x: string]: string }> {}
 
 /**
- * @since 4.0.0
+ * Schema for `Headers` values encoded as records of string header values.
+ *
+ * Decoding normalizes header names through `fromInput`; encoding returns a plain record.
+ *
  * @category schemas
+ * @since 4.0.0
  */
 export const HeadersSchema: HeadersSchema = Schema.declare(
   isHeaders,
@@ -124,22 +156,32 @@ export const HeadersSchema: HeadersSchema = Schema.declare(
 )
 
 /**
- * @since 4.0.0
+ * Input accepted when constructing headers.
+ *
+ * Records may contain string values, string arrays, or `undefined`; arrays are joined with `", "`, and `undefined` values are omitted.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type Input =
   | Record.ReadonlyRecord<string, string | ReadonlyArray<string> | undefined>
   | Iterable<readonly [string, string]>
 
 /**
- * @since 4.0.0
+ * An empty `Headers` collection.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const empty: Headers = Object.create(Proto)
 
 /**
- * @since 4.0.0
+ * Creates `Headers` from a record or iterable of header entries.
+ *
+ * Header names are normalized to lowercase. Array values in record input are joined with `", "`, and `undefined` values are omitted.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const fromInput: (input?: Input) => Headers = (input) => {
   if (input === undefined) {
@@ -163,92 +205,156 @@ export const fromInput: (input?: Input) => Headers = (input) => {
 }
 
 /**
- * @since 4.0.0
+ * Unsafely treats an existing record as `Headers`.
+ *
+ * This mutates the record's prototype and does not normalize header names; callers must provide the expected lowercase keys.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const fromRecordUnsafe = (input: Record.ReadonlyRecord<string, string>): Headers =>
   Object.setPrototypeOf(input, Proto) as Headers
 
 /**
- * @since 4.0.0
+ * Returns `true` when a header with the given name is present.
+ *
+ * The lookup lowercases the provided header name.
+ *
  * @category combinators
+ * @since 4.0.0
  */
 export const has: {
   /**
-   * @since 4.0.0
+   * Returns `true` when a header with the given name is present.
+   *
+   * The lookup lowercases the provided header name.
+   *
    * @category combinators
+   * @since 4.0.0
    */
   (key: string): (self: Headers) => boolean
   /**
-   * @since 4.0.0
+   * Returns `true` when a header with the given name is present.
+   *
+   * The lookup lowercases the provided header name.
+   *
    * @category combinators
+   * @since 4.0.0
    */
   (self: Headers, key: string): boolean
 } = dual<
   /**
-   * @since 4.0.0
+   * Returns `true` when a header with the given name is present.
+   *
+   * The lookup lowercases the provided header name.
+   *
    * @category combinators
+   * @since 4.0.0
    */
   (key: string) => (self: Headers) => boolean,
   /**
-   * @since 4.0.0
+   * Returns `true` when a header with the given name is present.
+   *
+   * The lookup lowercases the provided header name.
+   *
    * @category combinators
+   * @since 4.0.0
    */
   (self: Headers, key: string) => boolean
 >(2, (self, key) => key.toLowerCase() in self)
 
 /**
- * @since 4.0.0
+ * Gets a header value by name.
+ *
+ * The lookup lowercases the provided header name and returns `Option.none()` when absent.
+ *
  * @category combinators
+ * @since 4.0.0
  */
 export const get: {
   /**
-   * @since 4.0.0
+   * Gets a header value by name.
+   *
+   * The lookup lowercases the provided header name and returns `Option.none()` when absent.
+   *
    * @category combinators
+   * @since 4.0.0
    */
   (key: string): (self: Headers) => Option.Option<string>
   /**
-   * @since 4.0.0
+   * Gets a header value by name.
+   *
+   * The lookup lowercases the provided header name and returns `Option.none()` when absent.
+   *
    * @category combinators
+   * @since 4.0.0
    */
   (self: Headers, key: string): Option.Option<string>
 } = dual<
   /**
-   * @since 4.0.0
+   * Gets a header value by name.
+   *
+   * The lookup lowercases the provided header name and returns `Option.none()` when absent.
+   *
    * @category combinators
+   * @since 4.0.0
    */
   (key: string) => (self: Headers) => Option.Option<string>,
   /**
-   * @since 4.0.0
+   * Gets a header value by name.
+   *
+   * The lookup lowercases the provided header name and returns `Option.none()` when absent.
+   *
    * @category combinators
+   * @since 4.0.0
    */
   (self: Headers, key: string) => Option.Option<string>
 >(2, (self, key) => Option.fromUndefinedOr(self[key.toLowerCase()]))
 
 /**
- * @since 4.0.0
+ * Returns a new `Headers` collection with the given header set.
+ *
+ * The header name is normalized to lowercase.
+ *
  * @category combinators
+ * @since 4.0.0
  */
 export const set: {
   /**
-   * @since 4.0.0
+   * Returns a new `Headers` collection with the given header set.
+   *
+   * The header name is normalized to lowercase.
+   *
    * @category combinators
+   * @since 4.0.0
    */
   (key: string, value: string): (self: Headers) => Headers
   /**
-   * @since 4.0.0
+   * Returns a new `Headers` collection with the given header set.
+   *
+   * The header name is normalized to lowercase.
+   *
    * @category combinators
+   * @since 4.0.0
    */
   (self: Headers, key: string, value: string): Headers
 } = dual<
   /**
-   * @since 4.0.0
+   * Returns a new `Headers` collection with the given header set.
+   *
+   * The header name is normalized to lowercase.
+   *
    * @category combinators
+   * @since 4.0.0
    */
   (key: string, value: string) => (self: Headers) => Headers,
   /**
-   * @since 4.0.0
+   * Returns a new `Headers` collection with the given header set.
+   *
+   * The header name is normalized to lowercase.
+   *
    * @category combinators
+   * @since 4.0.0
    */
   (self: Headers, key: string, value: string) => Headers
 >(3, (self, key, value) => {
@@ -258,29 +364,49 @@ export const set: {
 })
 
 /**
- * @since 4.0.0
+ * Returns a new `Headers` collection with all provided headers set.
+ *
+ * Input headers are normalized with `fromInput` and override existing headers with the same lowercase name.
+ *
  * @category combinators
+ * @since 4.0.0
  */
 export const setAll: {
   /**
-   * @since 4.0.0
+   * Returns a new `Headers` collection with all provided headers set.
+   *
+   * Input headers are normalized with `fromInput` and override existing headers with the same lowercase name.
+   *
    * @category combinators
+   * @since 4.0.0
    */
   (headers: Input): (self: Headers) => Headers
   /**
-   * @since 4.0.0
+   * Returns a new `Headers` collection with all provided headers set.
+   *
+   * Input headers are normalized with `fromInput` and override existing headers with the same lowercase name.
+   *
    * @category combinators
+   * @since 4.0.0
    */
   (self: Headers, headers: Input): Headers
 } = dual<
   /**
-   * @since 4.0.0
+   * Returns a new `Headers` collection with all provided headers set.
+   *
+   * Input headers are normalized with `fromInput` and override existing headers with the same lowercase name.
+   *
    * @category combinators
+   * @since 4.0.0
    */
   (headers: Input) => (self: Headers) => Headers,
   /**
-   * @since 4.0.0
+   * Returns a new `Headers` collection with all provided headers set.
+   *
+   * Input headers are normalized with `fromInput` and override existing headers with the same lowercase name.
+   *
    * @category combinators
+   * @since 4.0.0
    */
   (self: Headers, headers: Input) => Headers
 >(2, (self, headers) =>
@@ -290,29 +416,49 @@ export const setAll: {
   }))
 
 /**
- * @since 4.0.0
+ * Returns a new `Headers` collection containing headers from both collections.
+ *
+ * Headers from the second collection override headers from the first collection with the same name.
+ *
  * @category combinators
+ * @since 4.0.0
  */
 export const merge: {
   /**
-   * @since 4.0.0
+   * Returns a new `Headers` collection containing headers from both collections.
+   *
+   * Headers from the second collection override headers from the first collection with the same name.
+   *
    * @category combinators
+   * @since 4.0.0
    */
   (headers: Headers): (self: Headers) => Headers
   /**
-   * @since 4.0.0
+   * Returns a new `Headers` collection containing headers from both collections.
+   *
+   * Headers from the second collection override headers from the first collection with the same name.
+   *
    * @category combinators
+   * @since 4.0.0
    */
   (self: Headers, headers: Headers): Headers
 } = dual<
   /**
-   * @since 4.0.0
+   * Returns a new `Headers` collection containing headers from both collections.
+   *
+   * Headers from the second collection override headers from the first collection with the same name.
+   *
    * @category combinators
+   * @since 4.0.0
    */
   (headers: Headers) => (self: Headers) => Headers,
   /**
-   * @since 4.0.0
+   * Returns a new `Headers` collection containing headers from both collections.
+   *
+   * Headers from the second collection override headers from the first collection with the same name.
+   *
    * @category combinators
+   * @since 4.0.0
    */
   (self: Headers, headers: Headers) => Headers
 >(2, (self, headers) => {
@@ -322,29 +468,49 @@ export const merge: {
 })
 
 /**
- * @since 4.0.0
+ * Returns a new `Headers` collection with the named header removed.
+ *
+ * The provided header name is normalized to lowercase before removal.
+ *
  * @category combinators
+ * @since 4.0.0
  */
 export const remove: {
   /**
-   * @since 4.0.0
+   * Returns a new `Headers` collection with the named header removed.
+   *
+   * The provided header name is normalized to lowercase before removal.
+   *
    * @category combinators
+   * @since 4.0.0
    */
   (key: string): (self: Headers) => Headers
   /**
-   * @since 4.0.0
+   * Returns a new `Headers` collection with the named header removed.
+   *
+   * The provided header name is normalized to lowercase before removal.
+   *
    * @category combinators
+   * @since 4.0.0
    */
   (self: Headers, key: string): Headers
 } = dual<
   /**
-   * @since 4.0.0
+   * Returns a new `Headers` collection with the named header removed.
+   *
+   * The provided header name is normalized to lowercase before removal.
+   *
    * @category combinators
+   * @since 4.0.0
    */
   (key: string) => (self: Headers) => Headers,
   /**
-   * @since 4.0.0
+   * Returns a new `Headers` collection with the named header removed.
+   *
+   * The provided header name is normalized to lowercase before removal.
+   *
    * @category combinators
+   * @since 4.0.0
    */
   (self: Headers, key: string) => Headers
 >(2, (self, key) => {
@@ -354,29 +520,49 @@ export const remove: {
 })
 
 /**
- * @since 4.0.0
+ * Returns a new `Headers` collection with each named header removed.
+ *
+ * Each provided header name is normalized to lowercase before removal.
+ *
  * @category combinators
+ * @since 4.0.0
  */
 export const removeMany: {
   /**
-   * @since 4.0.0
+   * Returns a new `Headers` collection with each named header removed.
+   *
+   * Each provided header name is normalized to lowercase before removal.
+   *
    * @category combinators
+   * @since 4.0.0
    */
   (keys: Iterable<string>): (self: Headers) => Headers
   /**
-   * @since 4.0.0
+   * Returns a new `Headers` collection with each named header removed.
+   *
+   * Each provided header name is normalized to lowercase before removal.
+   *
    * @category combinators
+   * @since 4.0.0
    */
   (self: Headers, keys: Iterable<string>): Headers
 } = dual<
   /**
-   * @since 4.0.0
+   * Returns a new `Headers` collection with each named header removed.
+   *
+   * Each provided header name is normalized to lowercase before removal.
+   *
    * @category combinators
+   * @since 4.0.0
    */
   (keys: Iterable<string>) => (self: Headers) => Headers,
   /**
-   * @since 4.0.0
+   * Returns a new `Headers` collection with each named header removed.
+   *
+   * Each provided header name is normalized to lowercase before removal.
+   *
    * @category combinators
+   * @since 4.0.0
    */
   (self: Headers, keys: Iterable<string>) => Headers
 >(2, (self, keys) => {
@@ -388,18 +574,30 @@ export const removeMany: {
 })
 
 /**
- * @since 4.0.0
+ * Returns a plain record with selected header values wrapped in `Redacted`.
+ *
+ * String keys are normalized to lowercase before matching; regular expressions are tested against the stored header names.
+ *
  * @category combinators
+ * @since 4.0.0
  */
 export const redact: {
   /**
-   * @since 4.0.0
+   * Returns a plain record with selected header values wrapped in `Redacted`.
+   *
+   * String keys are normalized to lowercase before matching; regular expressions are tested against the stored header names.
+   *
    * @category combinators
+   * @since 4.0.0
    */
   (key: string | RegExp | ReadonlyArray<string | RegExp>): (self: Headers) => Record<string, string | Redacted.Redacted>
   /**
-   * @since 4.0.0
+   * Returns a plain record with selected header values wrapped in `Redacted`.
+   *
+   * String keys are normalized to lowercase before matching; regular expressions are tested against the stored header names.
+   *
    * @category combinators
+   * @since 4.0.0
    */
   (self: Headers, key: string | RegExp | ReadonlyArray<string | RegExp>): Record<string, string | Redacted.Redacted>
 } = dual(
@@ -435,8 +633,12 @@ export const redact: {
 )
 
 /**
- * @since 4.0.0
+ * Context reference listing header names or patterns that should be redacted when `Headers` are inspected or rendered.
+ *
+ * Defaults include `authorization`, `cookie`, `set-cookie`, and `x-api-key`.
+ *
  * @category fiber refs
+ * @since 4.0.0
  */
 export const CurrentRedactedNames = Context.Reference<
   ReadonlyArray<string | RegExp>