effect 4.0.0-beta.70 → 4.0.0-beta.72

package/src/unstable/http/Cookies.ts

@@ -1,17 +1,63 @@
 /**
- * Utilities for representing, validating, parsing, and serializing HTTP cookies.
+ * Immutable HTTP cookie values and collections for request and response
+ * workflows.
  *
- * 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.
+ * The module models a validated {@link Cookie}, an immutable {@link Cookies}
+ * collection keyed by cookie name, and the conversions needed around HTTP
+ * headers. Use it to read request `Cookie` headers, build cookies with standard
+ * attributes, merge or remove cookies immutably, expire cookies, and emit
+ * response `Set-Cookie` headers.
  *
- * 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.
+ * **Mental model**
+ *
+ * - A `Cookie` stores both the decoded `value` and the encoded `valueEncoded`
+ *   used in headers
+ * - A `Cookies` collection contains at most one cookie per name; later writes,
+ *   merges, and iterable inputs replace earlier cookies with the same name
+ * - `Cookie` request headers carry name/value pairs, while `Set-Cookie`
+ *   response headers carry one cookie plus optional attributes
+ * - Safe constructors return `Result` failures for invalid names, values,
+ *   domains, paths, or infinite `Max-Age` values
+ *
+ * **Common tasks**
+ *
+ * - Create cookies: {@link makeCookie}, {@link makeCookieUnsafe}
+ * - Build collections: {@link empty}, {@link fromIterable},
+ *   {@link fromSetCookie}, {@link fromReadonlyRecord}
+ * - Read values: {@link get}, {@link getValue}, {@link toRecord},
+ *   {@link isEmpty}
+ * - Update collections: {@link set}, {@link setUnsafe}, {@link setAll},
+ *   {@link setCookie}, {@link setAllCookie}, {@link remove}, {@link merge}
+ * - Expire cookies: {@link expireCookie}, {@link expireCookieUnsafe}
+ * - Encode and decode headers: {@link toCookieHeader},
+ *   {@link toSetCookieHeaders}, {@link serializeCookie}, {@link parseHeader}
+ *
+ * **Gotchas**
+ *
+ * - Use {@link toCookieHeader} for an outbound request `Cookie` header and
+ *   {@link toSetCookieHeaders} for response `Set-Cookie` headers.
+ * - Parsing is intentionally tolerant: malformed `Set-Cookie` input can be
+ *   ignored, unsupported attributes are skipped, and percent-decoding falls
+ *   back to the original text.
+ * - Security attributes such as `HttpOnly`, `Secure`, `SameSite`, and
+ *   `Partitioned` are serialized when present, but browser policy enforces
+ *   their final behavior.
+ *
+ * **Example** (Serializing a session cookie)
+ *
+ * ```ts
+ * import { Cookies } from "effect/unstable/http"
+ *
+ * const cookies = Cookies.setUnsafe(Cookies.empty, "session", "abc123", {
+ *   httpOnly: true,
+ *   path: "/",
+ *   sameSite: "lax",
+ *   secure: true
+ * })
+ *
+ * console.log(Cookies.toSetCookieHeaders(cookies))
+ * // ["session=abc123; Path=/; HttpOnly; Secure; SameSite=Lax"]
+ * ```
  *
  * @since 4.0.0
  */
@@ -167,8 +213,8 @@ export const CookieSchema: CookieSchema = Schema.declare(
 const CookieErrorTypeId = "~effect/http/Cookies/CookieError"
 
 /**
- * Structured reason describing why cookie construction failed, such as invalid
- * name, value, domain, path, or infinite max-age.
+ * Error reason describing why cookie construction failed, such as invalid name,
+ * value, domain, path, or infinite max-age.
  *
  * @category errors
  * @since 4.0.0
@@ -502,21 +548,21 @@ export const makeCookieUnsafe = (
 ): Cookie => Result.getOrThrow(makeCookie(name, value, options))
 
 /**
- * Add a cookie to a Cookies object
+ * Adds a cookie to a Cookies object
  *
  * @category combinators
  * @since 4.0.0
  */
 export const setCookie: {
   /**
-   * Add a cookie to a Cookies object
+   * Adds a cookie to a Cookies object
    *
    * @category combinators
    * @since 4.0.0
    */
   (cookie: Cookie): (self: Cookies) => Cookies
   /**
-   * Add a cookie to a Cookies object
+   * Adds a cookie to a Cookies object
    *
    * @category combinators
    * @since 4.0.0
@@ -533,21 +579,21 @@ export const setCookie: {
 )
 
 /**
- * Add multiple cookies to a Cookies object
+ * Adds multiple cookies to a Cookies object
  *
  * @category combinators
  * @since 4.0.0
  */
 export const setAllCookie: {
   /**
-   * Add multiple cookies to a Cookies object
+   * Adds multiple cookies to a Cookies object
    *
    * @category combinators
    * @since 4.0.0
    */
   (cookies: Iterable<Cookie>): (self: Cookies) => Cookies
   /**
-   * Add multiple cookies to a Cookies object
+   * Adds multiple cookies to a Cookies object
    *
    * @category combinators
    * @since 4.0.0
@@ -562,21 +608,21 @@ export const setAllCookie: {
 })
 
 /**
- * Combine two Cookies objects, removing duplicates from the first
+ * Combines two Cookies objects, removing duplicates from the first
  *
  * @category combinators
  * @since 4.0.0
  */
 export const merge: {
   /**
-   * Combine two Cookies objects, removing duplicates from the first
+   * Combines two Cookies objects, removing duplicates from the first
    *
    * @category combinators
    * @since 4.0.0
    */
   (that: Cookies): (self: Cookies) => Cookies
   /**
-   * Combine two Cookies objects, removing duplicates from the first
+   * Combines two Cookies objects, removing duplicates from the first
    *
    * @category combinators
    * @since 4.0.0
@@ -589,21 +635,21 @@ export const merge: {
   }))
 
 /**
- * Remove a cookie by name
+ * Removes a cookie by name
  *
  * @category combinators
  * @since 4.0.0
  */
 export const remove: {
   /**
-   * Remove a cookie by name
+   * Removes a cookie by name
    *
    * @category combinators
    * @since 4.0.0
    */
   (name: string): (self: Cookies) => Cookies
   /**
-   * Remove a cookie by name
+   * Removes a cookie by name
    *
    * @category combinators
    * @since 4.0.0
@@ -612,21 +658,21 @@ export const remove: {
 } = dual(2, (self: Cookies, name: string) => fromReadonlyRecord(Record.remove(self.cookies, name)))
 
 /**
- * Get a cookie from a Cookies object
+ * Gets a cookie from a Cookies object safely.
  *
  * @category combinators
  * @since 4.0.0
  */
 export const get: {
   /**
-   * Get a cookie from a Cookies object
+   * Gets a cookie from a Cookies object safely.
    *
    * @category combinators
    * @since 4.0.0
    */
   (name: string): (self: Cookies) => Option.Option<Cookie>
   /**
-   * Get a cookie from a Cookies object
+   * Gets a cookie from a Cookies object safely.
    *
    * @category combinators
    * @since 4.0.0
@@ -638,7 +684,7 @@ export const get: {
 )
 
 /**
- * Gets the decoded value of a cookie by name.
+ * Gets the decoded value of a cookie by name safely.
  *
  * **Details**
  *
@@ -649,7 +695,7 @@ export const get: {
  */
 export const getValue: {
   /**
-   * Gets the decoded value of a cookie by name.
+   * Gets the decoded value of a cookie by name safely.
    *
    * **Details**
    *
@@ -660,7 +706,7 @@ export const getValue: {
    */
   (name: string): (self: Cookies) => Option.Option<string>
   /**
-   * Gets the decoded value of a cookie by name.
+   * Gets the decoded value of a cookie by name safely.
    *
    * **Details**
    *
@@ -676,7 +722,7 @@ export const getValue: {
 )
 
 /**
- * Creates and adds a cookie by name and value.
+ * Creates and adds a cookie safely by name and value.
  *
  * **Details**
  *
@@ -687,7 +733,7 @@ export const getValue: {
  */
 export const set: {
   /**
-   * Creates and adds a cookie by name and value.
+   * Creates and adds a cookie safely by name and value.
    *
    * **Details**
    *
@@ -698,7 +744,7 @@ export const set: {
    */
   (name: string, value: string, options?: Cookie["options"]): (self: Cookies) => Result.Result<Cookies, CookiesError>
   /**
-   * Creates and adds a cookie by name and value.
+   * Creates and adds a cookie safely by name and value.
    *
    * **Details**
    *
@@ -749,7 +795,7 @@ export const setUnsafe: {
 )
 
 /**
- * Adds an expired cookie with an empty value, `Max-Age=0`, and an epoch `Expires` value.
+ * Adds an expired cookie safely with an empty value, `Max-Age=0`, and an epoch `Expires` value.
  *
  * **Details**
  *
@@ -760,7 +806,7 @@ export const setUnsafe: {
  */
 export const expireCookie: {
   /**
-   * Adds an expired cookie with an empty value, `Max-Age=0`, and an epoch `Expires` value.
+   * Adds an expired cookie safely with an empty value, `Max-Age=0`, and an epoch `Expires` value.
    *
    * **Details**
    *
@@ -774,7 +820,7 @@ export const expireCookie: {
     options?: Omit<NonNullable<Cookie["options"]>, "expires" | "maxAge">
   ): (self: Cookies) => Result.Result<Cookies, CookiesError>
   /**
-   * Adds an expired cookie with an empty value, `Max-Age=0`, and an epoch `Expires` value.
+   * Adds an expired cookie safely with an empty value, `Max-Age=0`, and an epoch `Expires` value.
    *
    * **Details**
    *
@@ -803,14 +849,14 @@ export const expireCookie: {
 )
 
 /**
- * Add an expired cookie to a Cookies object, throwing an error if invalid
+ * Adds an expired cookie to a Cookies object, throwing an error if invalid
  *
  * @category combinators
  * @since 4.0.0
  */
 export const expireCookieUnsafe: {
   /**
-   * Add an expired cookie to a Cookies object, throwing an error if invalid
+   * Adds an expired cookie to a Cookies object, throwing an error if invalid
    *
    * @category combinators
    * @since 4.0.0
@@ -820,7 +866,7 @@ export const expireCookieUnsafe: {
     options?: Omit<NonNullable<Cookie["options"]>, "expires" | "maxAge">
   ): (self: Cookies) => Cookies
   /**
-   * Add an expired cookie to a Cookies object, throwing an error if invalid
+   * Adds an expired cookie to a Cookies object, throwing an error if invalid
    *
    * @category combinators
    * @since 4.0.0
@@ -845,7 +891,7 @@ export const expireCookieUnsafe: {
 )
 
 /**
- * Creates and adds multiple cookies from name/value/options tuples.
+ * Creates and adds multiple cookies safely from name/value/options tuples.
  *
  * **Details**
  *
@@ -856,7 +902,7 @@ export const expireCookieUnsafe: {
  */
 export const setAll: {
   /**
-   * Creates and adds multiple cookies from name/value/options tuples.
+   * Creates and adds multiple cookies safely from name/value/options tuples.
    *
    * **Details**
    *
@@ -869,7 +915,7 @@ export const setAll: {
     cookies: Iterable<readonly [name: string, value: string, options?: Cookie["options"]]>
   ): (self: Cookies) => Result.Result<Cookies, CookiesError>
   /**
-   * Creates and adds multiple cookies from name/value/options tuples.
+   * Creates and adds multiple cookies safely from name/value/options tuples.
    *
    * **Details**
    *
@@ -901,14 +947,14 @@ export const setAll: {
 )
 
 /**
- * Add multiple cookies to a Cookies object, throwing an error if invalid
+ * Adds multiple cookies to a Cookies object, throwing an error if invalid
  *
  * @category combinators
  * @since 4.0.0
  */
 export const setAllUnsafe: {
   /**
-   * Add multiple cookies to a Cookies object, throwing an error if invalid
+   * Adds multiple cookies to a Cookies object, throwing an error if invalid
    *
    * @category combinators
    * @since 4.0.0
@@ -917,7 +963,7 @@ export const setAllUnsafe: {
     cookies: Iterable<readonly [name: string, value: string, options?: Cookie["options"]]>
   ): (self: Cookies) => Cookies
   /**
-   * Add multiple cookies to a Cookies object, throwing an error if invalid
+   * Adds multiple cookies to a Cookies object, throwing an error if invalid
    *
    * @category combinators
    * @since 4.0.0
@@ -935,7 +981,7 @@ export const setAllUnsafe: {
 )
 
 /**
- * Serialize a cookie into a string
+ * Serializes a cookie into a string.
  *
  * **Details**
  *
@@ -1015,7 +1061,7 @@ export function serializeCookie(self: Cookie): string {
 }
 
 /**
- * Serialize a Cookies object into a Cookie header
+ * Serializes a `Cookies` object into a Cookie header.
  *
  * @category encoding
  * @since 4.0.0
@@ -1040,7 +1086,8 @@ export const toRecord = (self: Cookies): Record<string, string> => {
 }
 
 /**
- * Schema transformation between `Cookies` and a record of decoded string values keyed by cookie name.
+ * Schema for transforming `Cookies` into records of decoded string values keyed
+ * by cookie name.
  *
  * @category schemas
  * @since 4.0.0
@@ -1064,7 +1111,7 @@ export const schemaRecord = CookiesSchema.pipe(
 export const toSetCookieHeaders = (self: Cookies): Array<string> => Object.values(self.cookies).map(serializeCookie)
 
 /**
- * Parse a cookie header into a record of key-value pairs
+ * Parses a cookie header into a record of key-value pairs
  *
  * **Details**
  *

package/src/unstable/http/Etag.ts

@@ -1,18 +1,32 @@
 /**
- * Utilities for representing and generating HTTP entity tags.
+ * HTTP entity tag values and metadata-based generator layers.
  *
- * ETags are validators that identify a particular representation of a
- * resource. Servers commonly attach them to responses so clients and
- * intermediaries can revalidate cached content with conditional requests such
- * as `If-None-Match`, or protect updates with preconditions such as `If-Match`.
+ * ETags are validators for a specific representation of a resource. Servers put
+ * them in `ETag` response headers so clients and intermediaries can revalidate
+ * cached content with `If-None-Match`, or protect writes with preconditions such
+ * as `If-Match`.
  *
- * This module models weak and strong ETags, formats them for the `ETag` header,
- * and provides generator layers that derive tags from file size and
- * modification-time metadata. Metadata-derived tags are convenient for static
- * files, but they are only as precise as the underlying metadata: choose strong
- * tags only when that metadata reliably changes for every byte-level change,
- * and use weak tags when the validator is suitable for cache revalidation but
- * not for operations that require byte-for-byte identity.
+ * **Mental model**
+ *
+ * A strong ETag represents byte-for-byte identity for the selected
+ * representation. A weak ETag represents a validator that is useful for cache
+ * revalidation but not for operations that require exact byte identity. The
+ * `Weak` and `Strong` models store the raw tag value; `toString` adds the
+ * required quotes and the `W/` prefix for weak tags.
+ *
+ * **Common tasks**
+ *
+ * - Format an `Etag` value for an HTTP header with `toString`.
+ * - Provide a `Generator` service with `layer` for strong metadata-derived tags.
+ * - Use `layerWeak` when size and modification time are good cache validators
+ *   but not a byte-for-byte guarantee.
+ *
+ * **Gotchas**
+ *
+ * The built-in generator derives tags only from file size and modification time.
+ * Choose the strong layer only when that metadata changes for every byte-level
+ * content change. This module formats ETags but does not parse incoming ETag
+ * headers or implement conditional request logic.
  *
  * @since 4.0.0
  */
@@ -100,7 +114,23 @@ const fromFileWeb = (file: Body.HttpBody.FileLike) => {
 }
 
 /**
- * Layer that provides a `Generator` which produces strong ETags from file size and modification time metadata.
+ * Layer that provides a `Generator` which produces strong ETags from file size
+ * and modification time metadata.
+ *
+ * **When to use**
+ *
+ * Use when file size and modification time reliably change for every byte-level
+ * change and the consuming HTTP code needs strong ETags from the `Generator`
+ * service.
+ *
+ * **Gotchas**
+ *
+ * This layer marks metadata-derived tags as strong. If the underlying storage
+ * can update file contents without changing the recorded size or modification
+ * time, those tags can stop representing byte-for-byte identity.
+ *
+ * @see {@link layerWeak} for weak metadata-derived ETags when byte-for-byte identity is not required
+ * @see {@link Generator} for the service provided by this layer
  *
  * @category layers
  * @since 4.0.0

package/src/unstable/http/FetchHttpClient.ts

@@ -1,19 +1,33 @@
 /**
- * Provides an `HttpClient` implementation backed by the Web Fetch API.
- *
- * Use this module when an application should run HTTP requests through the
- * platform's `fetch` implementation, such as browser code, edge runtimes, or
- * Node.js environments that provide `globalThis.fetch`. The `Fetch` reference
- * allows tests and custom runtimes to supply a different fetch function, while
- * `RequestInit` can provide defaults such as credentials, redirect behavior,
- * cache mode, or other platform-specific fetch options.
- *
- * The client translates Effect HTTP requests into fetch calls and wraps Web
- * `Response` values as `HttpClientResponse`s. Fetch implementations control
- * details such as CORS, cookies, redirect handling, and abort semantics, so
- * behavior can vary by platform. Stream request bodies are sent as Web streams
- * with `duplex: "half"` for runtimes that require it, and `content-length` is
- * omitted so fetch can manage body framing itself.
+ * Fetch-based implementation of the Effect HTTP client service.
+ *
+ * This module provides an `HttpClient` layer that executes requests through a
+ * Web Fetch API implementation. It is the transport to use in browsers, edge
+ * runtimes, and Node.js environments where `globalThis.fetch` is available, or
+ * anywhere a compatible fetch function can be supplied.
+ *
+ * **Mental model**
+ *
+ * `layer` installs an `HttpClient` whose runtime boundary is a call to `fetch`.
+ * The `Fetch` reference chooses the fetch function and defaults to
+ * `globalThis.fetch`. The `RequestInit` service supplies default fetch options
+ * such as credentials, redirects, cache behavior, or other platform-specific
+ * settings. Request-specific method, headers, body, and abort signal are written
+ * by the client for each call.
+ *
+ * **Common tasks**
+ *
+ * Provide `layer` when an Effect program should run outbound HTTP through the
+ * current platform. Override `Fetch` in tests or custom runtimes to capture
+ * requests or route them to a different implementation. Provide `RequestInit`
+ * when all requests made by this client should share fetch defaults.
+ *
+ * **Gotchas**
+ *
+ * Fetch behavior is platform behavior: CORS, cookies, redirect handling, aborts,
+ * and streaming support can differ across runtimes. Stream request bodies are
+ * sent as Web streams with `duplex: "half"` for runtimes that require it, and
+ * `content-length` is removed so fetch can manage body framing.
  *
  * @since 4.0.0
  */
@@ -41,7 +55,12 @@ export const Fetch = Context.Reference<typeof globalThis.fetch>("effect/http/Fet
 })
 
 /**
- * Service containing default `RequestInit` options for the fetch-based HTTP client.
+ * Service that contains default fetch options for the fetch-based HTTP client.
+ *
+ * **When to use**
+ *
+ * Use to provide default credentials, cache, redirect, integrity, or other
+ * fetch options for outgoing HTTP requests.
  *
  * **Details**
  *
@@ -96,7 +115,30 @@ const fetch: HttpClient.HttpClient = HttpClient.make((request, url, signal, fibe
 })
 
 /**
- * Layer that provides an `HttpClient` implementation backed by the configured `Fetch` function.
+ * Layer that provides an `HttpClient` implementation backed by the configured
+ * `Fetch` function.
+ *
+ * **When to use**
+ *
+ * Use when an Effect program should execute `HttpClient` requests through the
+ * platform `fetch` implementation, especially in browser, edge, or Node.js
+ * runtimes with `globalThis.fetch`.
+ *
+ * **Details**
+ *
+ * The layer uses the current `Fetch` reference and optional `RequestInit`
+ * service for each request. Request-specific method, headers, body, and abort
+ * signal are supplied by the client and override matching `RequestInit` fields.
+ *
+ * **Gotchas**
+ *
+ * Fetch behavior comes from the runtime's implementation, so CORS, cookies,
+ * redirects, abort handling, and streaming support can vary by platform. Stream
+ * request bodies are sent as Web streams with `duplex: "half"`, and any
+ * `content-length` header is removed before calling `fetch`.
+ *
+ * @see {@link Fetch} for supplying the fetch implementation used by this layer
+ * @see {@link RequestInit} for default `RequestInit` options applied before request-specific fields
  *
  * @category layers
  * @since 4.0.0