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

package/src/unstable/http/Headers.ts

@@ -1,19 +1,56 @@
 /**
- * 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.
+ * Immutable HTTP header collections for the unstable HTTP modules.
+ *
+ * This module defines the `Headers` data type used by HTTP client and server
+ * request / response models. It converts records or iterables into a
+ * predictable lowercase map, provides pipeable operations for reading and
+ * updating header values, and integrates with inspection redaction so sensitive
+ * header names can be masked before logging or serialization.
+ *
+ * ## Mental model
+ *
+ * A `Headers` value is a plain immutable record whose keys are normalized
+ * header names and whose values are strings. Safe constructors and lookups
+ * lowercase names because HTTP header names are case-insensitive, and
+ * combinators return new `Headers` values instead of mutating the original
+ * collection.
+ *
+ * ## Common tasks
+ *
+ * - Build headers from records or entry iterables with {@link fromInput}.
+ * - Read values with {@link get} or check presence with {@link has}.
+ * - Add, replace, merge, or remove headers with {@link set}, {@link setAll},
+ *   {@link merge}, {@link remove}, and {@link removeMany}.
+ * - Mask sensitive names before inspection with {@link redact} and
+ *   {@link CurrentRedactedNames}.
+ *
+ * ## Gotchas
+ *
+ * Each lowercase header name stores one string. Record array values are joined
+ * with `", "`, iterable input keeps the last value for duplicate names, and
+ * later set / merge operations replace earlier values. This is convenient for
+ * most headers but does not preserve repeated field lines such as `Set-Cookie`;
+ * use cookie-specific HTTP modules when cookie multiplicity matters.
+ *
+ * **Example** (Normalize and update headers)
+ *
+ * ```ts
+ * import { Option } from "effect"
+ * import { Headers } from "effect/unstable/http"
+ *
+ * const headers = Headers.fromInput({
+ *   "Content-Type": "application/json",
+ *   accept: ["application/json", "text/plain"]
+ * })
+ *
+ * const contentType = Headers.get(headers, "content-type")
+ * if (Option.isSome(contentType)) {
+ *   console.log(contentType.value)
+ * }
+ *
+ * const next = Headers.set(headers, "authorization", "Bearer token")
+ * console.log(Headers.has(next, "Authorization")) // true
+ * ```
  *
  * @since 4.0.0
  */
@@ -33,7 +70,7 @@ import * as Transformation from "../../SchemaTransformation.ts"
 import type { Mutable } from "../../Types.ts"
 
 /**
- * This is a symbol to allow direct access of keys without conflicts.
+ * Runtime type identifier for `Headers` values.
  *
  * @category type IDs
  * @since 4.0.0
@@ -109,9 +146,10 @@ const make = (input: Record.ReadonlyRecord<string, string>): Mutable<Headers> =>
   Object.assign(Object.create(Proto), input) as Headers
 
 /**
- * Equivalence instance that compares `Headers` by their header names and string values.
+ * Provides an `Equivalence` instance that compares `Headers` by header names
+ * and string values.
  *
- * @category Equivalence
+ * @category instances
  * @since 4.0.0
  */
 export const Equivalence: Equ.Equivalence<Headers> = Record.makeEquivalence(Equ.strictEqual<string>())
@@ -213,7 +251,7 @@ export const fromInput: (input?: Input) => Headers = (input) => {
 }
 
 /**
- * Unsafely treats an existing record as `Headers`.
+ * Treats an existing record as `Headers` unsafely.
  *
  * **Gotchas**
  *
@@ -284,7 +322,7 @@ export const has: {
 >(2, (self, key) => key.toLowerCase() in self)
 
 /**
- * Gets a header value by name.
+ * Gets a header value by name safely.
  *
  * **Details**
  *
@@ -295,7 +333,7 @@ export const has: {
  */
 export const get: {
   /**
-   * Gets a header value by name.
+   * Gets a header value by name safely.
    *
    * **Details**
    *
@@ -306,7 +344,7 @@ export const get: {
    */
   (key: string): (self: Headers) => Option.Option<string>
   /**
-   * Gets a header value by name.
+   * Gets a header value by name safely.
    *
    * **Details**
    *
@@ -318,7 +356,7 @@ export const get: {
   (self: Headers, key: string): Option.Option<string>
 } = dual<
   /**
-   * Gets a header value by name.
+   * Gets a header value by name safely.
    *
    * **Details**
    *
@@ -329,7 +367,7 @@ export const get: {
    */
   (key: string) => (self: Headers) => Option.Option<string>,
   /**
-   * Gets a header value by name.
+   * Gets a header value by name safely.
    *
    * **Details**
    *

package/src/unstable/http/HttpBody.ts

@@ -1,17 +1,57 @@
 /**
- * Utilities and data types for describing outgoing HTTP body content.
- *
- * This module provides a small set of `HttpBody` variants used by HTTP client
- * requests and server responses: empty bodies, raw runtime values, in-memory
- * bytes, `FormData`, and byte streams. Constructors cover the common cases of
- * text, JSON, URL-encoded forms, multipart forms, and files while carrying the
- * content type and, when known, the content length used by platform adapters.
- *
- * Streaming bodies are represented as streams of `Uint8Array` chunks and may
- * omit `contentLength` when the size is not known ahead of time. Multipart
- * `FormData` intentionally leaves `contentType` unset so the runtime can add
- * the required boundary; setting that header manually can produce invalid
- * requests.
+ * Describes the body attached to outgoing HTTP requests and server responses.
+ *
+ * `HttpBody` is the transport-facing representation used by the HTTP modules
+ * before a platform adapter turns a request or response into a concrete Web,
+ * Node, or other runtime value. Each body variant carries the payload plus the
+ * metadata an adapter can safely know ahead of time, such as `contentType` and
+ * `contentLength`.
+ *
+ * **Mental model**
+ *
+ * - {@link empty} represents an absent body.
+ * - {@link uint8Array}, {@link text}, {@link jsonUnsafe}, {@link json}, and
+ *   {@link urlParams} build in-memory byte bodies with content metadata.
+ * - {@link formData} and {@link formDataRecord} keep multipart data as
+ *   `FormData` so the runtime can generate the boundary.
+ * - {@link stream} represents a stream of `Uint8Array` chunks and may omit the
+ *   content length when the final size is not known.
+ * - {@link raw} is the escape hatch for platform-specific body values that an
+ *   adapter already knows how to send.
+ *
+ * **Common tasks**
+ *
+ * - Send text, bytes, JSON, URL-encoded data, multipart forms, or files.
+ * - Use {@link json} or {@link jsonSchema} when JSON encoding failures should
+ *   be represented as `HttpBodyError` values.
+ * - Use {@link file} or {@link fileFromInfo} when file metadata should become
+ *   `contentType` / `contentLength` metadata for the adapter.
+ * - Use {@link isHttpBody} when accepting unknown values at an integration
+ *   boundary.
+ *
+ * **Gotchas**
+ *
+ * - {@link jsonUnsafe} calls `JSON.stringify` directly and can throw; prefer
+ *   {@link json} in effectful code.
+ * - `FormData` bodies intentionally leave `contentType` unset because setting a
+ *   multipart header without the generated boundary produces invalid requests.
+ * - Stream bodies may not have a `contentLength`; code that requires one must
+ *   provide it explicitly when constructing the stream body.
+ *
+ * **Example** (Creating common body variants)
+ *
+ * ```ts
+ * import { HttpBody, UrlParams } from "effect/unstable/http"
+ * import * as assert from "node:assert"
+ *
+ * const textBody = HttpBody.text("hello")
+ * const jsonBody = HttpBody.jsonUnsafe({ name: "Ada" })
+ * const formBody = HttpBody.urlParams(UrlParams.fromInput({ q: "effect" }))
+ *
+ * assert.equal(textBody.contentType, "text/plain")
+ * assert.equal(jsonBody.contentType, "application/json")
+ * assert.equal(formBody.contentType, "application/x-www-form-urlencoded")
+ * ```
  *
  * @since 4.0.0
  */
@@ -158,9 +198,13 @@ export class Empty extends Proto {
 }
 
 /**
- * Singleton empty HTTP body.
+ * Provides the singleton empty HTTP body.
  *
- * @category constructors
+ * **When to use**
+ *
+ * Use when you need an HTTP body value that represents no body content.
+ *
+ * @category constants
  * @since 4.0.0
  */
 export const empty: Empty = new Empty()

package/src/unstable/http/HttpClient.ts

@@ -1,22 +1,38 @@
 /**
- * Composable HTTP client service for executing `HttpClientRequest` values and
- * receiving `HttpClientResponse` values inside Effect programs.
- *
- * This module provides the `HttpClient` service tag, method-specific accessors,
- * constructors for low-level runtimes, and middleware-style combinators for
- * common client concerns such as request rewriting, response filtering, retries,
- * redirects, cookies, rate limiting, and tracing. It is intended for code that
- * needs dependency-injected outbound HTTP calls, reusable clients customized for
- * an API, or cross-cutting behavior layered around a concrete platform client.
- *
- * Responses are successful Effects even for non-2xx status codes unless a
- * filter such as `filterStatus` or `filterStatusOk` is applied. Request
- * middleware is ordered by whether it prepends to or appends after the existing
- * preprocessing pipeline, so use `mapRequestInput` for transformations that
- * should run before previously installed request middleware and `mapRequest`
- * for transformations that should run after it. Non-scoped responses are tied to
- * an abort controller for interruption cleanup; use `withScope` when the request
- * lifetime should instead be controlled by a surrounding `Scope`.
+ * Dependency-injected HTTP client for executing outgoing requests from Effect
+ * programs.
+ *
+ * This module defines the `HttpClient` service used by platform clients,
+ * tests, and API-specific clients. It executes immutable `HttpClientRequest`
+ * values, returns `HttpClientResponse` values, and keeps outbound HTTP behind a
+ * service boundary so call sites do not depend on a concrete runtime transport.
+ *
+ * **Mental model**
+ *
+ * A client is an `execute` function plus method helpers such as `get`, `post`,
+ * and `del`. Before a request reaches the runtime, it passes through a
+ * preprocessing pipeline. After the runtime returns a response, it passes
+ * through a postprocessing pipeline. Combinators such as `mapRequest`,
+ * `filterStatusOk`, `retry`, `followRedirects`, `withCookiesRef`, and
+ * `withRateLimiter` return a new client with behavior layered around the
+ * previous one.
+ *
+ * **Common tasks**
+ *
+ * Use method helpers for straightforward calls, construct `HttpClientRequest`
+ * values directly when a request is assembled across several steps, and use
+ * `make` or `makeWith` when adapting a lower-level transport. Use
+ * `filterStatus` or `filterStatusOk` when non-success HTTP statuses should fail
+ * the Effect. Use `withScope` when response resources should live for a
+ * surrounding scope instead of only the individual request.
+ *
+ * **Gotchas**
+ *
+ * Receiving a response is a successful Effect even for non-2xx statuses unless
+ * a status filter has been applied. `mapRequestInput` prepends work before
+ * existing request middleware, while `mapRequest` appends after it. Without
+ * `withScope`, non-scoped responses are attached to an abort controller so
+ * interruption can clean up the request.
  *
  * @since 4.0.0
  */
@@ -145,7 +161,12 @@ export declare namespace HttpClient {
 }
 
 /**
- * Service tag for the default `HttpClient` used by HTTP client accessors.
+ * Service tag for the default outgoing HTTP client service.
+ *
+ * **When to use**
+ *
+ * Use to provide the HTTP client implementation consumed by the module's
+ * request accessor functions.
  *
  * @category tags
  * @since 4.0.0
@@ -416,7 +437,57 @@ export const catchTag: {
       e: ExtractTag<E, K extends NonEmptyReadonlyArray<string> ? K[number] : K>
     ) => Effect.Effect<HttpClientResponse.HttpClientResponse, E1, R1>
   ): HttpClient.With<E1 | ExcludeTag<E, K extends NonEmptyReadonlyArray<string> ? K[number] : K>, R1 | R> =>
-    transformResponse(self, Effect.catchTag(tag, f))
+    transformResponse(
+      self,
+      (effect) =>
+        Effect.catchTag</**
+         * Handles client failures with one or more matching `_tag` values and returns a transformed client.
+         *
+         * @category error handling
+         * @since 4.0.0
+         */
+        HttpClientResponse.HttpClientResponse, /**
+         * Handles client failures with one or more matching `_tag` values and returns a transformed client.
+         *
+         * @category error handling
+         * @since 4.0.0
+         */
+        E, /**
+         * Handles client failures with one or more matching `_tag` values and returns a transformed client.
+         *
+         * @category error handling
+         * @since 4.0.0
+         */
+        R, /**
+         * Handles client failures with one or more matching `_tag` values and returns a transformed client.
+         *
+         * @category error handling
+         * @since 4.0.0
+         */
+        K, /**
+         * Handles client failures with one or more matching `_tag` values and returns a transformed client.
+         *
+         * @category error handling
+         * @since 4.0.0
+         */
+        R1, /**
+         * Handles client failures with one or more matching `_tag` values and returns a transformed client.
+         *
+         * @category error handling
+         * @since 4.0.0
+         */
+        E1, /**
+         * Handles client failures with one or more matching `_tag` values and returns a transformed client.
+         *
+         * @category error handling
+         * @since 4.0.0
+         */
+        HttpClientResponse.HttpClientResponse>(
+          effect,
+          tag,
+          f
+        )
+    )
 )
 
 /**
@@ -1044,7 +1115,7 @@ export const retry: {
  *
  * **When to use**
  *
- * Use `retryOn` to focus on retrying errors, transient responses, or both.
+ * Use to focus on retrying errors, transient responses, or both.
  *
  * **Details**
  *
@@ -1060,7 +1131,7 @@ export const retryTransient: {
    *
    * **When to use**
    *
-   * Use `retryOn` to focus on retrying errors, transient responses, or both.
+   * Use to focus on retrying errors, transient responses, or both.
    *
    * **Details**
    *
@@ -1095,7 +1166,7 @@ export const retryTransient: {
    *
    * **When to use**
    *
-   * Use `retryOn` to focus on retrying errors, transient responses, or both.
+   * Use to focus on retrying errors, transient responses, or both.
    *
    * **Details**
    *
@@ -1132,7 +1203,7 @@ export const retryTransient: {
    *
    * **When to use**
    *
-   * Use `retryOn` to focus on retrying errors, transient responses, or both.
+   * Use to focus on retrying errors, transient responses, or both.
    *
    * **Details**
    *
@@ -1150,7 +1221,7 @@ export const retryTransient: {
    *
    * **When to use**
    *
-   * Use `retryOn` to focus on retrying errors, transient responses, or both.
+   * Use to focus on retrying errors, transient responses, or both.
    *
    * **Details**
    *
@@ -1614,21 +1685,36 @@ export const tapRequest: {
 )
 
 /**
- * Associates a `Ref` of cookies with the client for handling cookies across requests.
+ * Adds a `Ref` of cookies to the client for handling cookies across requests.
+ *
+ * **When to use**
+ *
+ * Use to add shared cookie storage to a client so response cookies are retained
+ * and sent by later requests.
  *
  * @category cookies
  * @since 4.0.0
  */
 export const withCookiesRef: {
   /**
-   * Associates a `Ref` of cookies with the client for handling cookies across requests.
+   * Adds a `Ref` of cookies to the client for handling cookies across requests.
+   *
+   * **When to use**
+   *
+   * Use to add shared cookie storage to a client so response cookies are retained
+   * and sent by later requests.
    *
    * @category cookies
    * @since 4.0.0
    */
   (ref: Ref.Ref<Cookies.Cookies>): <E, R>(self: HttpClient.With<E, R>) => HttpClient.With<E, R>
   /**
-   * Associates a `Ref` of cookies with the client for handling cookies across requests.
+   * Adds a `Ref` of cookies to the client for handling cookies across requests.
+   *
+   * **When to use**
+   *
+   * Use to add shared cookie storage to a client so response cookies are retained
+   * and sent by later requests.
    *
    * @category cookies
    * @since 4.0.0
@@ -1659,9 +1745,9 @@ export const withCookiesRef: {
 )
 
 /**
- * Ties the lifetime of the `HttpClientRequest` to a `Scope`.
+ * Attaches the lifetime of the `HttpClientRequest` to a `Scope`.
  *
- * @category Scope
+ * @category resource management
  * @since 4.0.0
  */
 export const withScope = <E, R>(
@@ -1680,21 +1766,21 @@ export const withScope = <E, R>(
   )
 
 /**
- * Follows HTTP redirects up to a specified number of times.
+ * Enables following HTTP redirects up to a specified number of times.
  *
  * @category redirects
  * @since 4.0.0
  */
 export const followRedirects: {
   /**
-   * Follows HTTP redirects up to a specified number of times.
+   * Enables following HTTP redirects up to a specified number of times.
    *
    * @category redirects
    * @since 4.0.0
    */
   (maxRedirects?: number | undefined): <E, R>(self: HttpClient.With<E, R>) => HttpClient.With<E, R>
   /**
-   * Follows HTTP redirects up to a specified number of times.
+   * Enables following HTTP redirects up to a specified number of times.
    *
    * @category redirects
    * @since 4.0.0

package/src/unstable/http/HttpClientError.ts

@@ -1,15 +1,31 @@
 /**
- * Error types used by the HTTP client to describe failures that occur while
- * preparing requests, sending them, validating response status codes, and
- * decoding response bodies.
+ * Typed failure model for Effect HTTP client operations.
  *
- * The module exposes the `HttpClientError` wrapper together with the specific
- * reason classes it can carry, so applications can either handle all HTTP
- * client failures uniformly or branch on the exact `_tag` for retries, logging,
- * metrics, and user-facing messages. A common gotcha is that only response
- * errors carry an `HttpClientResponse`: transport, encoding, and invalid URL
- * failures happen before a response is available, while status-code, decode, and
- * empty-body failures preserve the response that triggered them.
+ * HTTP clients wrap request construction, transport, status-code validation, and
+ * response decoding failures in `HttpClientError`. The wrapper keeps the failed
+ * request and the specific failure reason together, so callers can handle client
+ * failures uniformly while still matching on the reason `_tag` for retry
+ * policy, logging, metrics, and user-facing messages.
+ *
+ * **Mental model**
+ *
+ * A client error reason belongs to one of two families. Request errors happen
+ * before a response exists: `TransportError`, `EncodeError`, and
+ * `InvalidUrlError`. Response errors include the response that triggered them:
+ * `StatusCodeError`, `DecodeError`, and `EmptyBodyError`.
+ *
+ * **Common tasks**
+ *
+ * - Use `isHttpClientError` at untyped boundaries.
+ * - Read `request` for the method and URL associated with any client failure.
+ * - Match on `reason._tag` when different failures need different recovery.
+ * - Read `response` only for response errors or after checking that it exists.
+ *
+ * **Gotchas**
+ *
+ * `response` is `undefined` for transport, encoding, and invalid URL failures.
+ * Preserve the original `cause` when constructing reason classes so lower-level
+ * platform or decoding details are not lost.
  *
  * @since 4.0.0
  */
@@ -32,7 +48,7 @@ export const isHttpClientError = (u: unknown): u is HttpClientError => hasProper
 /**
  * Error wrapper for HTTP client failures, exposing the failed request and the optional response through its `reason`.
  *
- * @category error
+ * @category errors
  * @since 4.0.0
  */
 export class HttpClientError extends Data.TaggedError("HttpClientError")<{
@@ -87,9 +103,9 @@ const formatMessage = (reason: string, description: string | undefined, info: st
   description ? `${reason}: ${description} (${info})` : `${reason} error (${info})`
 
 /**
- * Request error for transport-level failures that occur while sending an HTTP request.
+ * Error describing transport-level failures that occur while sending an HTTP request.
  *
- * @category error
+ * @category errors
  * @since 4.0.0
  */
 export class TransportError extends Data.TaggedError("TransportError")<{
@@ -117,9 +133,9 @@ export class TransportError extends Data.TaggedError("TransportError")<{
 }
 
 /**
- * Request error for failures while encoding an HTTP request body.
+ * Error describing failures while encoding an HTTP request body.
  *
- * @category error
+ * @category errors
  * @since 4.0.0
  */
 export class EncodeError extends Data.TaggedError("EncodeError")<{
@@ -147,9 +163,9 @@ export class EncodeError extends Data.TaggedError("EncodeError")<{
 }
 
 /**
- * Request error for failures while constructing a URL from an HTTP client request.
+ * Error describing failures while constructing a URL from an HTTP client request.
  *
- * @category error
+ * @category errors
  * @since 4.0.0
  */
 export class InvalidUrlError extends Data.TaggedError("InvalidUrlError")<{
@@ -179,7 +195,7 @@ export class InvalidUrlError extends Data.TaggedError("InvalidUrlError")<{
 /**
  * Response error for HTTP responses rejected because of their status code.
  *
- * @category error
+ * @category errors
  * @since 4.0.0
  */
 export class StatusCodeError extends Data.TaggedError("StatusCodeError")<{
@@ -211,7 +227,7 @@ export class StatusCodeError extends Data.TaggedError("StatusCodeError")<{
 /**
  * Response error for failures while decoding an HTTP response body.
  *
- * @category error
+ * @category errors
  * @since 4.0.0
  */
 export class DecodeError extends Data.TaggedError("DecodeError")<{
@@ -243,7 +259,7 @@ export class DecodeError extends Data.TaggedError("DecodeError")<{
 /**
  * Response error for operations that expected a response body but received an empty body.
  *
- * @category error
+ * @category errors
  * @since 4.0.0
  */
 export class EmptyBodyError extends Data.TaggedError("EmptyBodyError")<{
@@ -275,7 +291,7 @@ export class EmptyBodyError extends Data.TaggedError("EmptyBodyError")<{
 /**
  * Union of HTTP client errors that occur before a response is available.
  *
- * @category error
+ * @category errors
  * @since 4.0.0
  */
 export type RequestError = TransportError | EncodeError | InvalidUrlError
@@ -283,7 +299,7 @@ export type RequestError = TransportError | EncodeError | InvalidUrlError
 /**
  * Union of HTTP client errors that include an HTTP response.
  *
- * @category error
+ * @category errors
  * @since 4.0.0
  */
 export type ResponseError = StatusCodeError | DecodeError | EmptyBodyError
@@ -291,13 +307,14 @@ export type ResponseError = StatusCodeError | DecodeError | EmptyBodyError
 /**
  * Union of all specific failure reasons carried by `HttpClientError`.
  *
- * @category error
+ * @category errors
  * @since 4.0.0
  */
 export type HttpClientErrorReason = RequestError | ResponseError
 
 /**
- * Serializable schema representation of an `HttpClientError`, preserving the specific error kind and cause.
+ * Schema for serializable HTTP client errors, preserving the specific error kind
+ * and cause.
  *
  * @category schemas
  * @since 4.0.0