effect 4.0.0-beta.70 → 4.0.0-beta.71

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
  */

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
  */

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.
+ * Dependency-injected HTTP client for executing outgoing requests from 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.
+ * 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.
  *
- * 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`.
+ * **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
  */
@@ -416,7 +432,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 +1110,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 +1126,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 +1161,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 +1198,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 +1216,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**
    *

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
  */

package/src/unstable/http/HttpClientRequest.ts

@@ -1,21 +1,42 @@
 /**
- * Utilities for constructing immutable outgoing HTTP client requests.
+ * Immutable outgoing HTTP client requests.
  *
- * This module models the request data passed to HTTP clients and adapters:
- * method, URL, query parameters, hash, headers, and body. It provides
- * method-specific constructors, pipeable combinators for adding authentication
- * headers and accepted media types, helpers for JSON, form, stream, and file
- * bodies, and conversions to and from the Web `Request` type.
+ * `HttpClientRequest` is the request model shared by Effect HTTP clients and
+ * platform adapters. A request stores its method, URL, query parameters, hash,
+ * headers, and body as structured data, and this module provides constructors,
+ * pipeable update helpers, body encoders, and Web `Request` conversions.
  *
- * Request construction keeps the base URL, query parameters, and hash as
- * separate fields until conversion. Passing a `URL` extracts its search
- * parameters and fragment into those structured fields, while string URLs are
- * kept as provided. Use the `setUrlParam` helpers when replacing query values
- * and the `appendUrlParam` helpers when multiple values for the same key should
- * be preserved. Setting a body also updates `Content-Type` and
- * `Content-Length` from the body metadata when available; `FormData` leaves
- * those headers to the runtime so multipart boundaries can be generated
- * correctly.
+ * **Mental model**
+ *
+ * Request builders start from {@link empty} and return a new request for every
+ * change. The base URL, query parameters, and hash stay separate until
+ * conversion, so code can update them independently before calling
+ * {@link toUrl}, {@link toWebResult}, or {@link toWeb}. Body helpers delegate to
+ * `HttpBody` and update `Content-Type` and `Content-Length` when the selected
+ * body carries that metadata.
+ *
+ * **Common tasks**
+ *
+ * - Start a request with {@link get}, {@link post}, {@link put},
+ *   {@link patch}, or another method constructor.
+ * - Add authentication or accepted media types with {@link basicAuth},
+ *   {@link bearerToken}, {@link accept}, or {@link acceptJson}.
+ * - Change URL parts with {@link setUrl}, {@link prependUrl},
+ *   {@link appendUrl}, {@link setUrlParam}, {@link appendUrlParam}, and
+ *   {@link setHash}.
+ * - Attach payloads with {@link bodyJson}, {@link bodyUrlParams},
+ *   {@link bodyFormData}, {@link bodyStream}, or {@link bodyFile}.
+ * - Bridge Web platform values with {@link fromWeb}, {@link toWebResult}, and
+ *   {@link toWeb}.
+ *
+ * **Gotchas**
+ *
+ * Passing a `URL` extracts its search parameters and fragment into structured
+ * fields, while a string URL is kept as provided. Use the `setUrlParam` helpers
+ * to replace query values, and the `appendUrlParam` helpers when repeated keys
+ * should be preserved. `FormData` bodies intentionally leave multipart boundary
+ * headers to the runtime, so `setBody` removes explicit content headers for
+ * them.
  *
  * @since 4.0.0
  */

package/src/unstable/http/HttpClientResponse.ts

@@ -1,20 +1,39 @@
 /**
- * Utilities for inspecting, decoding, and filtering HTTP client responses.
+ * HTTP client response values, status helpers, and body decoders.
  *
- * An `HttpClientResponse` pairs the platform `Response` with the request that
- * produced it, exposing status, headers, cookies, and effectful views of the
- * response body. Use this module after an `HttpClient` call to branch on status
- * with `matchStatus` or `filterStatus`, decode JSON or URL-encoded bodies with
- * schemas, stream bytes, or adapt a Web `Response` with `fromWeb`.
+ * This module represents responses produced by the Effect HTTP client. An
+ * {@link HttpClientResponse} keeps the original request together with the
+ * response status, headers, cookies, and effectful body accessors inherited from
+ * the shared incoming-message model.
  *
- * Response bodies come from the underlying Web response and should be decoded
- * deliberately: `json` parses an empty text body as `null`, body readers fail
- * with `HttpClientError` when decoding fails, and the raw stream fails when no
- * body is present. Headers are represented by the HTTP `Headers` module's
- * single-value, lowercase map, while response cookies are parsed separately from
- * `Set-Cookie` headers. Status values are not considered errors by themselves;
- * use the provided filters or matchers when only specific status codes are
- * acceptable.
+ * **Mental model**
+ *
+ * A response is a successful client result unless a status filter turns it into
+ * a failure. {@link fromWeb} adapts a platform `Response`, body readers decode
+ * the underlying Web response, and schema helpers combine status, headers, and
+ * decoded body data when validating API-specific responses.
+ *
+ * **Common tasks**
+ *
+ * - Branch on exact or status-class handlers with {@link matchStatus}.
+ * - Fail non-accepted statuses with {@link filterStatus} or
+ *   {@link filterStatusOk}.
+ * - Decode JSON response envelopes with {@link schemaJson}.
+ * - Decode status and headers without reading a body with {@link schemaNoBody}.
+ * - Stream response bytes from an effect with {@link stream}.
+ *
+ * **Gotchas**
+ *
+ * HTTP status codes are data, not errors, until a filter is applied. `json`
+ * parses an empty text body as `null`. Body readers fail with `HttpClientError`
+ * when decoding fails, and the raw stream fails when no body is present.
+ * Headers use the HTTP `Headers` module's lowercase, single-value map, while
+ * response cookies are parsed separately from `Set-Cookie` headers.
+ *
+ * **See also**
+ *
+ * {@link HttpClientResponse}, {@link fromWeb}, {@link matchStatus},
+ * {@link schemaJson}, {@link filterStatus}.
  *
  * @since 4.0.0
  */

package/src/unstable/http/HttpEffect.ts

@@ -1,21 +1,38 @@
 /**
- * Utilities for running HTTP server effects at the boundary between Effect and
- * platform request handlers.
+ * Bridges Effect HTTP server programs with platform request handlers.
  *
- * This module is used to turn an effect that produces an `HttpServerResponse`
- * into a concrete handler, such as a Web `Request` handler, while applying
- * middleware, converting failures into HTTP responses, and preserving the
- * current `HttpServerRequest` in the Effect context. It also provides hooks for
- * adjusting a response immediately before it is sent and helpers for managing
- * the request `Scope`, especially when a streaming response must own that scope
- * until the stream completes.
+ * This module runs effects that produce `HttpServerResponse` values at the edge
+ * of a server runtime. It can turn an Effect handler into a Web `Request`
+ * handler, build that handler from a `Layer`, adapt an existing Web handler back
+ * into an Effect server effect, apply HTTP middleware, translate failures into
+ * responses, and run pre-response hooks immediately before a response is sent.
  *
- * Handlers built here expect the per-request context to contain
- * `HttpServerRequest` and, for scoped resources, `Scope.Scope`. Failures are
- * reported and translated through `HttpServerError` / respondable conversions,
- * so unhandled defects generally become server error responses while request
- * aborts and already-sent responses need to be handled with the provided
- * middleware and scope utilities.
+ * **Mental model**
+ *
+ * Each incoming platform request becomes an `HttpServerRequest` in the Effect
+ * context plus a request `Scope`. The server effect produces a response, or
+ * fails with a cause that is converted into an HTTP response. Web handler
+ * adapters fork the Effect program, resolve the platform `Response` promise when
+ * the response is handled, and interrupt the fiber when the request aborts.
+ * Streaming responses transfer scope ownership to the body stream so resources
+ * remain open until the stream exits.
+ *
+ * **Common tasks**
+ *
+ * Use `toWebHandler` for a handler with no extra services, `toWebHandlerWith`
+ * when each request may provide additional context, `toWebHandlerLayer` or
+ * `toWebHandlerLayerWith` when services come from a layer that must later be
+ * disposed, and `fromWebHandler` when embedding a Web-standard handler inside an
+ * Effect HTTP server. Use pre-response handlers to adjust headers, cookies, or
+ * status before the response is converted to the platform response type.
+ *
+ * **Gotchas**
+ *
+ * Layer-backed handlers return a `dispose` function for the layer scope; call it
+ * when the hosting runtime shuts down. Pre-response handlers run before bytes
+ * are sent, not after a streaming body has started. Web adapters handle
+ * streaming scope transfer automatically, but lower-level integrations that call
+ * `toHandled` directly must preserve request scope ownership themselves.
  *
  * @since 4.0.0
  */

package/src/unstable/http/HttpMethod.ts

@@ -1,19 +1,34 @@
 /**
- * Defines the supported HTTP method literals shared by the unstable HTTP client,
- * server, and routing APIs.
- *
- * Use this module when constructing method-specific requests, matching incoming
- * requests, validating unknown method values, or deriving method helper names.
- * Methods are represented as uppercase string literals, so values such as `"get"`
- * are not accepted as `HttpMethod` values.
- *
- * The body classification is intentionally conservative and file-specific:
- * `GET`, `HEAD`, `OPTIONS`, and `TRACE` are modeled as bodyless methods, while
- * `POST`, `PUT`, `DELETE`, and `PATCH` are modeled as methods that can carry a
- * request body. This means `DELETE` is allowed to carry a body even though some
- * servers and intermediaries may ignore it, and `GET` request bodies are not
- * represented by these helpers even though the wire protocol does not strictly
- * forbid them.
+ * HTTP method literals and helpers shared by the unstable HTTP client, server,
+ * and routing APIs.
+ *
+ * This module keeps the supported method vocabulary in one place: the
+ * {@link HttpMethod} union, {@link all} set, {@link allShort} mapping,
+ * {@link hasBody} body classification helper, and {@link isHttpMethod} runtime
+ * refinement. Values are uppercase string literals such as `"GET"` and
+ * `"POST"`, matching the method tokens used by the HTTP APIs in this package.
+ *
+ * **Mental model**
+ *
+ * {@link HttpMethod} is the complete set this module recognizes.
+ * {@link HttpMethod.NoBody} is the subset treated as bodyless (`GET`, `HEAD`,
+ * `OPTIONS`, and `TRACE`), and {@link HttpMethod.WithBody} is the remaining
+ * subset accepted by request builders that can carry a body.
+ *
+ * **Common tasks**
+ *
+ * Use {@link isHttpMethod} before accepting an unknown value as an HTTP method,
+ * {@link hasBody} to narrow a method before attaching a body, {@link all} for
+ * membership checks or iteration, and {@link allShort} when deriving the short
+ * constructor names used by request helpers.
+ *
+ * **Gotchas**
+ *
+ * Lowercase method names are not valid {@link HttpMethod} values. The body
+ * split is a typed helper convention, not a full statement of every
+ * wire-protocol edge case: `DELETE` is treated as able to carry a body, while
+ * `GET` helpers are treated as bodyless even though some systems may send a
+ * body on the wire.
  *
  * @since 4.0.0
  */