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

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
  */
@@ -1205,7 +1226,7 @@ const parseContentLength = (contentLength: string | null): number | undefined =>
 }
 
 /**
- * Converts an `HttpClientRequest` to a Web `Request` as a `Result`, failing when the request URL is invalid.
+ * Converts an `HttpClientRequest` safely to a Web `Request` as a `Result`, failing when the request URL is invalid.
  *
  * @category converting
  * @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
  */
@@ -134,7 +151,7 @@ const handledSymbol = Symbol.for("effect/http/HttpEffect/handled")
  * Use only when another owner will close the scope; otherwise resources attached
  * to the request scope can leak.
  *
- * @category Scope
+ * @category resource management
  * @since 4.0.0
  */
 export const scopeDisableClose = (scope: Scope.Scope): void => {
@@ -142,9 +159,9 @@ export const scopeDisableClose = (scope: Scope.Scope): void => {
 }
 
 /**
- * For streaming server responses, transfers request scope ownership to the body stream so the scope closes when the stream exits.
+ * Returns a streaming server response that closes the request scope when the body stream exits.
  *
- * @category Scope
+ * @category resource management
  * @since 4.0.0
  */
 export const scopeTransferToStream = (

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
  */
@@ -67,9 +82,14 @@ export const hasBody = (method: HttpMethod): method is HttpMethod.WithBody =>
   method !== "GET" && method !== "HEAD" && method !== "OPTIONS" && method !== "TRACE"
 
 /**
- * Set containing every supported `HttpMethod` literal.
+ * Provides a readonly set containing every supported `HttpMethod` literal.
  *
- * @category models
+ * **When to use**
+ *
+ * Use when you need to iterate over or test membership against every supported
+ * HTTP method literal.
+ *
+ * @category constants
  * @since 4.0.0
  */
 export const all: ReadonlySet<HttpMethod> = new Set([
@@ -84,9 +104,15 @@ export const all: ReadonlySet<HttpMethod> = new Set([
 ])
 
 /**
- * Tuples mapping each supported HTTP method to its short request-constructor name.
+ * Provides tuples mapping each supported HTTP method to its short
+ * request-constructor name.
  *
- * @category models
+ * **When to use**
+ *
+ * Use when you need the mapping from supported HTTP method literals to their
+ * short request-constructor names.
+ *
+ * @category constants
  * @since 4.0.0
  */
 export const allShort = [
@@ -101,7 +127,7 @@ export const allShort = [
 ] as const
 
 /**
- * Tests if a value is a `HttpMethod`.
+ * Checks whether a value is a `HttpMethod`.
  *
  * **Example** (Checking HTTP method values)
  *

package/src/unstable/http/HttpRouter.ts

@@ -1,20 +1,43 @@
 /**
- * Layer-based server-side HTTP routing for Effect applications.
- *
- * This module provides the `HttpRouter` service and helpers for registering
- * method/path handlers, grouping routes under prefixes, decoding request
- * schemas from route and search parameters, and turning an application layer
- * into an `HttpServer` or Fetch-compatible handler. It is intended for HTTP
- * APIs, webhooks, and other server endpoints that want request-scoped services
- * and typed middleware to be composed through `Layer`.
- *
- * Route paths must be absolute paths beginning with `/`, or the wildcard `*`.
- * Prefixed routes remove the matched prefix from the request URL seen by the
- * handler, `HEAD` requests fall back to matching `GET` routes, and wildcard
- * paths ending in `/*` also match the prefix path itself. Use router middleware
- * when you need to provide request dependencies, handle configured route errors,
- * or modify route responses; server middleware wraps the wider server chain and
- * is not the right hook for changing the final response body or headers.
+ * Layer-based server-side routing for Effect HTTP applications.
+ *
+ * `HttpRouter` collects routes and router middleware while an application layer
+ * is being built, then exposes the registered route table as an
+ * `HttpServerResponse` effect for each incoming `HttpServerRequest`. Use it for
+ * APIs, webhooks, and Fetch handlers that want request-scoped services, schema
+ * decoding, and typed middleware to participate in the same `Layer` graph as
+ * the rest of the application.
+ *
+ * **Mental model**
+ *
+ * Route layers do not handle requests immediately. They register `Route` values
+ * into the current `HttpRouter`; `serve`, `toHttpEffect`, and `toWebHandler`
+ * build the layer, read the completed router, and run the matching handler for
+ * each request. During a request, the router provides `HttpServerRequest`,
+ * `Scope`, parsed search parameters, and `RouteContext`, so handlers can decode
+ * path, search, and body data or access services supplied by router middleware.
+ *
+ * **Common tasks**
+ *
+ * - Register individual routes with `add` or batches with `addAll`.
+ * - Group routes under a prefix with `addAll(..., { prefix })` or
+ *   `router.prefixed`.
+ * - Decode route, search, and JSON body data with `schemaPathParams`,
+ *   `schemaParams`, `schemaNoBody`, and `schemaJson`.
+ * - Apply route-scoped middleware with `middleware(...).layer`, or install
+ *   global router middleware for all routes.
+ * - Serve the layer with `serve` or create a Fetch-compatible handler with
+ *   `toWebHandler`.
+ *
+ * **Gotchas**
+ *
+ * Paths must be absolute `/` paths or the wildcard `*`. `HEAD` falls back to
+ * `GET`, and wildcard paths ending in `/*` also match the prefix path itself.
+ * For prefixed routes the matched prefix is removed from
+ * `HttpServerRequest.url` before the handler sees it. Middleware passed to
+ * `serve` wraps the wider server chain; use router middleware when you need to
+ * provide request dependencies, handle configured route errors, or change the
+ * response that will be sent.
  *
  * @since 4.0.0
  */
@@ -42,7 +65,7 @@ import * as HttpServerResponse from "./HttpServerResponse.ts"
 const TypeId = "~effect/http/HttpRouter"
 
 /**
- * Service interface for registering HTTP routes and middleware.
+ * Defines the service interface for registering HTTP routes and middleware.
  *
  * **Details**
  *
@@ -267,14 +290,19 @@ export const RouterConfig = Context.Reference<Partial<FindMyWay.RouterConfig>>(
 )
 
 /**
- * Request-scoped service containing information about the matched route.
+ * Service for the matched HTTP route in the current request.
+ *
+ * **When to use**
+ *
+ * Use to read captured path parameters and route metadata while handling a
+ * request matched by the router.
  *
  * **Details**
  *
  * It provides the route definition and the path parameters captured by the route
  * matcher.
  *
- * @category RouteContext
+ * @category route context
  * @since 4.0.0
  */
 export class RouteContext extends Context.Service<RouteContext, {
@@ -447,7 +475,7 @@ export const schemaPathParams = <A, I extends Readonly<Record<string, string | u
  *
  * **When to use**
  *
- * Use it to register routes or middleware with the router during layer
+ * Use when you use it to register routes or middleware with the router during layer
  * construction.
  *
  * **Example** (Registering routes during layer construction)
@@ -864,7 +892,7 @@ const MiddlewareTypeId = "~effect/http/HttpRouter/Middleware"
  * while tracking provided services, handled errors, and remaining requirements at
  * the type level.
  *
- * @category Middleware
+ * @category middleware
  * @since 4.0.0
  */
 export interface Middleware<
@@ -965,7 +993,7 @@ export interface Middleware<
  * )
  * ```
  *
- * @category Middleware
+ * @category middleware
  * @since 4.0.0
  */
 export const middleware:
@@ -1103,7 +1131,7 @@ export declare namespace middleware {
    * layer that installs middleware for all routes. The type tracks provided
    * services, handled errors, middleware failures, and remaining requirements.
    *
-   * @category Middleware
+   * @category middleware
    * @since 4.0.0
    */
   export type Make<Provides = never, Handles = never> = {
@@ -1188,7 +1216,7 @@ export declare namespace middleware {
    * Function that transforms an HTTP response effect into another HTTP response
    * effect.
    *
-   * @category Middleware
+   * @category middleware
    * @since 4.0.0
    */
   export type Fn = (
@@ -1197,9 +1225,9 @@ export declare namespace middleware {
 }
 
 /**
- * A middleware that applies CORS headers to the HTTP response.
+ * Middleware that applies CORS headers to the HTTP response.
  *
- * @category Middleware
+ * @category middleware
  * @since 4.0.0
  */
 export const cors = (
@@ -1214,7 +1242,7 @@ export const cors = (
 ): Layer.Layer<never, never, HttpRouter> => middleware(HttpMiddleware.cors(options), { global: true })
 
 /**
- * A middleware that disables the logger for some routes.
+ * Middleware that disables the logger for some routes.
  *
  * **Example** (Disabling route logging)
  *
@@ -1232,7 +1260,7 @@ export const cors = (
  * )
  * ```
  *
- * @category Middleware
+ * @category middleware
  * @since 4.0.0
  */
 export const disableLogger: Layer.Layer<never> = middleware(HttpMiddleware.withLoggerDisabled).layer
@@ -1240,7 +1268,7 @@ export const disableLogger: Layer.Layer<never> = middleware(HttpMiddleware.withL
 /**
  * Provides request-level dependencies to some routes.
  *
- * @category Middleware
+ * @category middleware
  * @since 4.0.0
  */
 export const provideRequest =
@@ -1263,7 +1291,7 @@ export const provideRequest =
     )
 
 /**
- * Serves the provided application layer as an HTTP server.
+ * Runs the provided application layer as an HTTP server.
  *
  * @category Server
  * @since 4.0.0

package/src/unstable/http/HttpServer.ts

@@ -1,21 +1,34 @@
 /**
- * Service and helpers for running Effect HTTP applications on a concrete server
- * runtime.
- *
- * This module defines the `HttpServer` service tag used by platform integrations
- * to expose a listening server, plus accessors for serving an
- * `HttpServerResponse` effect, formatting and logging server addresses, and
- * building test clients against a running server. It is intended for low-level
- * server runtimes, router integrations, HTTP API tests, and applications that
- * need to start serving from a provided `Layer`.
- *
- * The server supplies `HttpServerRequest` for each request, so application
- * effects should rely on the server for request-scoped data while still
- * providing their other services through the surrounding environment. `serve`
- * returns a `Layer` whose listener lifetime is managed by the layer scope; use
- * `serveEffect` when composing directly in an effect with an explicit `Scope`.
- * Test clients only support TCP addresses, and rewrite `0.0.0.0` to
- * `127.0.0.1` for local requests.
+ * Runtime boundary for serving Effect HTTP responses on a concrete HTTP server.
+ *
+ * `HttpServer` is the service implemented by platform adapters and consumed by
+ * routers, API layers, tests, and applications that start serving from a
+ * `Layer`. It exposes the listening address and a `serve` operation that runs
+ * an `HttpServerResponse` effect for each incoming request.
+ *
+ * **Mental model**
+ *
+ * The server owns the listener and supplies `HttpServerRequest` for every
+ * request. The application effect only describes how to produce a response, so
+ * request-scoped data comes from the server while the rest of the environment is
+ * still provided by the surrounding layer graph. `serve` ties listener lifetime
+ * to a layer scope, and `serveEffect` performs the same work inside an explicit
+ * `Scope`.
+ *
+ * **Common tasks**
+ *
+ * - Build a server service from a platform adapter with `make`.
+ * - Serve an HTTP app with `serve` or `serveEffect`.
+ * - Format or log the listening address with `formatAddress`,
+ *   `addressFormattedWith`, `logAddress`, or `withLogAddress`.
+ * - Create a test client that targets the running server with `makeTestClient`
+ *   or `layerTestClient`.
+ *
+ * **Gotchas**
+ *
+ * Middleware is applied at the server boundary, after the server has supplied
+ * the request service. Test clients only support TCP addresses, and rewrite
+ * `0.0.0.0` to `127.0.0.1` for local requests.
  *
  * @since 4.0.0
  */
@@ -378,7 +391,7 @@ export const withLogAddress = <A, E, R>(
  *
  * Unix socket addresses are not supported.
  *
- * @category Testing
+ * @category testing
  * @since 4.0.0
  */
 export const makeTestClient: Effect.Effect<
@@ -400,7 +413,7 @@ export const makeTestClient: Effect.Effect<
 /**
  * Layer that provides the test `HttpClient` created by `makeTestClient`.
  *
- * @category Testing
+ * @category testing
  * @since 4.0.0
  */
 export const layerTestClient: Layer.Layer<
@@ -410,7 +423,7 @@ export const layerTestClient: Layer.Layer<
 > = Layer.effect(HttpClient.HttpClient)(makeTestClient)
 
 /**
- * Testing layer that provides the platform services commonly needed by HTTP
+ * Layer that provides the platform services commonly needed by HTTP
  * server tests.
  *
  * **Details**
@@ -418,7 +431,7 @@ export const layerTestClient: Layer.Layer<
  * It includes `HttpPlatform`, `Path`, a weak ETag generator, and a no-op
  * `FileSystem`.
  *
- * @category Testing
+ * @category testing
  * @since 4.0.0
  */
 export const layerServices: Layer.Layer<