effect 4.0.0-beta.65 → 4.0.0-beta.67

package/src/unstable/http/HttpClientResponse.ts

@@ -1,4 +1,21 @@
 /**
+ * Utilities for inspecting, decoding, and filtering HTTP client responses.
+ *
+ * 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`.
+ *
+ * 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.
+ *
  * @since 4.0.0
  */
 import * as Effect from "../../Effect.ts"
@@ -19,31 +36,35 @@ import * as UrlParams from "./UrlParams.ts"
 
 export {
   /**
-   * @since 4.0.0
    * @category schema
+   * @since 4.0.0
    */
   schemaBodyJson,
   /**
-   * @since 4.0.0
    * @category schema
+   * @since 4.0.0
    */
   schemaBodyUrlParams,
   /**
-   * @since 4.0.0
    * @category schema
+   * @since 4.0.0
    */
   schemaHeaders
 } from "./HttpIncomingMessage.ts"
 
 /**
- * @since 4.0.0
+ * Type identifier for `HttpClientResponse` values.
+ *
  * @category Type IDs
+ * @since 4.0.0
  */
 export const TypeId = "~effect/http/HttpClientResponse"
 
 /**
- * @since 4.0.0
+ * Model of an HTTP client response, including the original request, status, cookies, headers, and body accessors.
+ *
  * @category models
+ * @since 4.0.0
  */
 export interface HttpClientResponse extends HttpIncomingMessage.HttpIncomingMessage<Error.HttpClientError>, Pipeable {
   readonly [TypeId]: typeof TypeId
@@ -54,15 +75,19 @@ export interface HttpClientResponse extends HttpIncomingMessage.HttpIncomingMess
 }
 
 /**
- * @since 4.0.0
+ * Wraps a Web `Response` and its original `HttpClientRequest` as an `HttpClientResponse`.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const fromWeb = (request: HttpClientRequest.HttpClientRequest, source: Response): HttpClientResponse =>
   new WebHttpClientResponse(request, source)
 
 /**
- * @since 4.0.0
+ * Creates a decoder for a response's status, headers, and JSON body using the supplied schema.
+ *
  * @category schema
+ * @since 4.0.0
  */
 export const schemaJson = <
   A,
@@ -90,8 +115,10 @@ export const schemaJson = <
 }
 
 /**
- * @since 4.0.0
+ * Creates a decoder for a response's status and headers without reading a response body.
+ *
  * @category schema
+ * @since 4.0.0
  */
 export const schemaNoBody = <
   A,
@@ -114,21 +141,27 @@ export const schemaNoBody = <
 }
 
 /**
- * @since 4.0.0
+ * Converts an effect producing an `HttpClientResponse` into a stream of response body bytes.
+ *
  * @category accessors
+ * @since 4.0.0
  */
 export const stream = <E, R>(
   effect: Effect.Effect<HttpClientResponse, E, R>
 ): Stream.Stream<Uint8Array, Error.HttpClientError | E, R> => Stream.unwrap(Effect.map(effect, (self) => self.stream))
 
 /**
- * @since 4.0.0
+ * Pattern matches on a response status, checking exact status handlers before status-class handlers and `orElse`.
+ *
  * @category pattern matching
+ * @since 4.0.0
  */
 export const matchStatus: {
   /**
-   * @since 4.0.0
+   * Pattern matches on a response status, checking exact status handlers before status-class handlers and `orElse`.
+   *
    * @category pattern matching
+   * @since 4.0.0
    */
   <
     const Cases extends {
@@ -141,8 +174,10 @@ export const matchStatus: {
     }
   >(cases: Cases): (self: HttpClientResponse) => Cases[keyof Cases] extends (_: any) => infer R ? Unify<R> : never
   /**
-   * @since 4.0.0
+   * Pattern matches on a response status, checking exact status handlers before status-class handlers and `orElse`.
+   *
    * @category pattern matching
+   * @since 4.0.0
    */
   <
     const Cases extends {
@@ -180,18 +215,24 @@ export const matchStatus: {
 })
 
 /**
- * @since 4.0.0
+ * Succeeds with the response when its status satisfies the predicate, otherwise fails with `HttpClientError`.
+ *
  * @category filters
+ * @since 4.0.0
  */
 export const filterStatus: {
   /**
-   * @since 4.0.0
+   * Succeeds with the response when its status satisfies the predicate, otherwise fails with `HttpClientError`.
+   *
    * @category filters
+   * @since 4.0.0
    */
   (f: (status: number) => boolean): (self: HttpClientResponse) => Effect.Effect<HttpClientResponse, Error.HttpClientError>
   /**
-   * @since 4.0.0
+   * Succeeds with the response when its status satisfies the predicate, otherwise fails with `HttpClientError`.
+   *
    * @category filters
+   * @since 4.0.0
    */
   (self: HttpClientResponse, f: (status: number) => boolean): Effect.Effect<HttpClientResponse, Error.HttpClientError>
 } = dual(
@@ -211,8 +252,10 @@ export const filterStatus: {
 )
 
 /**
- * @since 4.0.0
+ * Succeeds with the response only when its status is in the 2xx range, otherwise fails with `HttpClientError`.
+ *
  * @category filters
+ * @since 4.0.0
  */
 export const filterStatusOk = (self: HttpClientResponse): Effect.Effect<HttpClientResponse, Error.HttpClientError> =>
   self.status >= 200 && self.status < 300 ? Effect.succeed(self) : Effect.fail(

package/src/unstable/http/HttpEffect.ts

@@ -1,4 +1,22 @@
 /**
+ * Utilities for running HTTP server effects at the boundary between Effect and
+ * 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.
+ *
+ * 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.
+ *
  * @since 4.0.0
  */
 import type * as Cause from "../../Cause.ts"
@@ -21,8 +39,10 @@ import * as Response from "./HttpServerResponse.ts"
 import { appendPreResponseHandlerUnsafe, requestPreResponseHandlers } from "./internal/preResponseHandler.ts"
 
 /**
- * @since 4.0.0
+ * Runs an HTTP server effect, sends the produced response with the supplied handler, and converts failures into HTTP responses.
+ *
  * @category combinators
+ * @since 4.0.0
  */
 export const toHandled = <E, R, EH, RH>(
   self: Effect.Effect<HttpServerResponse, E, R>,
@@ -107,19 +127,23 @@ export const toHandled = <E, R, EH, RH>(
 const handledSymbol = Symbol.for("effect/http/HttpEffect/handled")
 
 /**
- * If you want to finalize the http request scope elsewhere, you can use this
- * function to eject from the default scope closure.
+ * Disables automatic closing for an HTTP request scope.
+ *
+ * Use only when another owner will close the scope; otherwise resources attached
+ * to the request scope can leak.
  *
- * @since 4.0.0
  * @category Scope
+ * @since 4.0.0
  */
 export const scopeDisableClose = (scope: Scope.Scope): void => {
   ;(scope as any)[scopeEjected] = true
 }
 
 /**
- * @since 4.0.0
+ * For streaming server responses, transfers request scope ownership to the body stream so the scope closes when the stream exits.
+ *
  * @category Scope
+ * @since 4.0.0
  */
 export const scopeTransferToStream = (
   response: HttpServerResponse
@@ -155,8 +179,10 @@ const scoped = <A, E, R>(effect: Effect.Effect<A, E, R>) =>
   })
 
 /**
- * @since 4.0.0
+ * Function run with the current request and response just before the response is sent, allowing the response to be replaced or failing with `HttpServerError`.
+ *
  * @category Pre-response handlers
+ * @since 4.0.0
  */
 export type PreResponseHandler = (
   request: HttpServerRequest,
@@ -164,8 +190,10 @@ export type PreResponseHandler = (
 ) => Effect.Effect<HttpServerResponse, HttpServerError>
 
 /**
- * @since 4.0.0
+ * Registers an additional pre-response handler for the current HTTP server request.
+ *
  * @category fiber refs
+ * @since 4.0.0
  */
 export const appendPreResponseHandler = (handler: PreResponseHandler): Effect.Effect<void, never, HttpServerRequest> =>
   HttpServerRequest.use((request) => {
@@ -175,36 +203,46 @@ export const appendPreResponseHandler = (handler: PreResponseHandler): Effect.Ef
 
 export {
   /**
-   * @since 4.0.0
    * @category fiber refs
+   * @since 4.0.0
    */
   appendPreResponseHandlerUnsafe
 }
 
 /**
- * @since 4.0.0
+ * Runs an effect after registering a pre-response handler for the current HTTP server request.
+ *
  * @category fiber refs
+ * @since 4.0.0
  */
 export const withPreResponseHandler: {
   /**
-   * @since 4.0.0
+   * Runs an effect after registering a pre-response handler for the current HTTP server request.
+   *
    * @category fiber refs
+   * @since 4.0.0
    */
   (handler: PreResponseHandler): <A, E, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R | HttpServerRequest>
   /**
-   * @since 4.0.0
+   * Runs an effect after registering a pre-response handler for the current HTTP server request.
+   *
    * @category fiber refs
+   * @since 4.0.0
    */
   <A, E, R>(self: Effect.Effect<A, E, R>, handler: PreResponseHandler): Effect.Effect<A, E, R | HttpServerRequest>
 } = dual<
   /**
-   * @since 4.0.0
+   * Runs an effect after registering a pre-response handler for the current HTTP server request.
+   *
    * @category fiber refs
+   * @since 4.0.0
    */
   (handler: PreResponseHandler) => <A, E, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R | HttpServerRequest>,
   /**
-   * @since 4.0.0
+   * Runs an effect after registering a pre-response handler for the current HTTP server request.
+   *
    * @category fiber refs
+   * @since 4.0.0
    */
   <A, E, R>(self: Effect.Effect<A, E, R>, handler: PreResponseHandler) => Effect.Effect<A, E, R | HttpServerRequest>
 >(2, (self, handler) =>
@@ -214,8 +252,10 @@ export const withPreResponseHandler: {
   }))
 
 /**
- * @since 4.0.0
+ * Converts an HTTP server effect into a Web `Request` handler using the supplied base context and optional middleware.
+ *
  * @category conversions
+ * @since 4.0.0
  */
 export const toWebHandlerWith = <Provided, R = never, ReqR = Exclude<R, Provided | Scope.Scope | HttpServerRequest>>(
   context: Context.Context<Provided>
@@ -254,8 +294,10 @@ export const toWebHandlerWith = <Provided, R = never, ReqR = Exclude<R, Provided
 }
 
 /**
- * @since 4.0.0
+ * Converts an HTTP server effect into a Web `Request` handler using an empty base context.
+ *
  * @category conversions
+ * @since 4.0.0
  */
 export const toWebHandler: <E>(
   self: Effect.Effect<HttpServerResponse, E, HttpServerRequest | Scope.Scope>,
@@ -264,8 +306,10 @@ export const toWebHandler: <E>(
   toWebHandlerWith(Context.empty())
 
 /**
- * @since 4.0.0
+ * Builds a Web `Request` handler from a layer and handler factory, returning the handler with a `dispose` function for the layer scope.
+ *
  * @category conversions
+ * @since 4.0.0
  */
 export const toWebHandlerLayerWith = <
   E,
@@ -324,8 +368,10 @@ export const toWebHandlerLayerWith = <
 }
 
 /**
- * @since 4.0.0
+ * Builds a Web `Request` handler for an HTTP server effect using a layer to provide its services, returning the handler with a `dispose` function.
+ *
  * @category conversions
+ * @since 4.0.0
  */
 export const toWebHandlerLayer = <E, R, Provided, LE, ReqR = Exclude<R, Provided | Scope.Scope | HttpServerRequest>>(
   self: Effect.Effect<HttpServerResponse, E, R>,
@@ -349,8 +395,10 @@ export const toWebHandlerLayer = <E, R, Provided, LE, ReqR = Exclude<R, Provided
   })
 
 /**
- * @since 4.0.0
+ * Adapts a Web `Request` handler into an HTTP server effect for the current `HttpServerRequest`.
+ *
  * @category conversions
+ * @since 4.0.0
  */
 export const fromWebHandler = (
   handler: (request: Request) => Promise<Response>

package/src/unstable/http/HttpIncomingMessage.ts

@@ -1,4 +1,28 @@
 /**
+ * Shared utilities for reading and decoding incoming HTTP messages.
+ *
+ * `HttpIncomingMessage` is the common body-and-header surface used by HTTP
+ * server requests and client responses. It keeps transport-specific metadata in
+ * the surrounding request and response modules while this module focuses on
+ * headers, optional remote address information, byte streams, buffered body
+ * views, and schema decoders for JSON bodies, URL-encoded bodies, and headers.
+ *
+ * Use these helpers in middleware, route handlers, client response processing,
+ * and adapters when code should work with any incoming message instead of a
+ * concrete request or response type. Body access is effectful because reading,
+ * parsing, and decoding can fail; use `stream` when bytes should stay
+ * streaming, and use `text`, `json`, `urlParamsBody`, or `arrayBuffer` when a
+ * buffered view is appropriate. Some runtimes expose bodies as one-shot Web
+ * streams, so prefer one body representation per message and let each
+ * implementation's cached accessors handle repeated reads where available.
+ *
+ * Headers use the HTTP `Headers` module's lowercase, single-value map, so
+ * repeated values may already have been combined or normalized by the adapter.
+ * Decode headers with `schemaHeaders` when their shape matters. For form
+ * bodies, `urlParamsBody` handles URL-encoded payloads; multipart support lives
+ * on `HttpServerRequest`, with `MaxBodySize` providing the shared limit
+ * reference used by multipart parsing.
+ *
  * @since 4.0.0
  */
 import * as Context from "../../Context.ts"
@@ -15,20 +39,26 @@ import type * as Headers from "./Headers.ts"
 import * as UrlParams from "./UrlParams.ts"
 
 /**
- * @since 4.0.0
+ * Type identifier for `HttpIncomingMessage` values.
+ *
  * @category Type IDs
+ * @since 4.0.0
  */
 export const TypeId = "~effect/http/HttpIncomingMessage"
 
 /**
- * @since 4.0.0
+ * Returns `true` when a value is an `HttpIncomingMessage`.
+ *
  * @category Guards
+ * @since 4.0.0
  */
 export const isHttpIncomingMessage = (u: unknown): u is HttpIncomingMessage => hasProperty(u, TypeId)
 
 /**
- * @since 4.0.0
+ * Common model for incoming HTTP messages, with headers, remote address, and effectful body accessors.
+ *
  * @category models
+ * @since 4.0.0
  */
 export interface HttpIncomingMessage<E = unknown> extends Inspectable.Inspectable {
   readonly [TypeId]: typeof TypeId
@@ -42,8 +72,10 @@ export interface HttpIncomingMessage<E = unknown> extends Inspectable.Inspectabl
 }
 
 /**
- * @since 4.0.0
+ * Creates a decoder that reads an incoming message's JSON body and decodes it with the supplied schema.
+ *
  * @category schema
+ * @since 4.0.0
  */
 export const schemaBodyJson = <S extends Schema.Top>(schema: S, options?: ParseOptions | undefined) => {
   const decode = Schema.decodeEffect(Schema.toCodecJson(schema))
@@ -54,8 +86,10 @@ export const schemaBodyJson = <S extends Schema.Top>(schema: S, options?: ParseO
 }
 
 /**
- * @since 4.0.0
+ * Creates a decoder that reads an incoming message's URL-encoded body parameters and decodes them with the supplied schema.
+ *
  * @category schema
+ * @since 4.0.0
  */
 export const schemaBodyUrlParams = <
   A,
@@ -75,8 +109,10 @@ export const schemaBodyUrlParams = <
 }
 
 /**
- * @since 4.0.0
+ * Creates a decoder that validates and decodes an incoming message's headers with the supplied schema.
+ *
  * @category schema
+ * @since 4.0.0
  */
 export const schemaHeaders = <A, I extends Readonly<Record<string, string | undefined>>, RD, RE>(
   schema: Schema.Codec<A, I, RD, RE>,
@@ -87,8 +123,10 @@ export const schemaHeaders = <A, I extends Readonly<Record<string, string | unde
 }
 
 /**
- * @since 4.0.0
+ * Context reference for the optional maximum size allowed when reading an incoming message body.
+ *
  * @category References
+ * @since 4.0.0
  */
 export const MaxBodySize = Context.Reference<FileSystem.Size | undefined>(
   "effect/http/HttpIncomingMessage/MaxBodySize",
@@ -96,6 +134,8 @@ export const MaxBodySize = Context.Reference<FileSystem.Size | undefined>(
 )
 
 /**
+ * Builds an inspectable object for an incoming message, redacting headers and including a synchronously readable JSON or text body when available.
+ *
  * @since 4.0.0
  */
 export const inspect = <E>(self: HttpIncomingMessage<E>, that: object): object => {

package/src/unstable/http/HttpMethod.ts

@@ -1,10 +1,28 @@
 /**
+ * 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.
+ *
  * @since 4.0.0
  */
 
 /**
- * @since 4.0.0
+ * Union of supported uppercase HTTP method literals.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type HttpMethod =
   | "GET"
@@ -17,30 +35,40 @@ export type HttpMethod =
   | "TRACE"
 
 /**
- * @since 4.0.0
+ * Namespace containing subtype helpers associated with `HttpMethod`.
+ *
  * @category models
+ * @since 4.0.0
  */
 export declare namespace HttpMethod {
   /**
-   * @since 4.0.0
+   * HTTP methods that this module treats as not carrying a request body.
+   *
    * @category models
+   * @since 4.0.0
    */
   export type NoBody = "GET" | "HEAD" | "OPTIONS" | "TRACE"
 
   /**
-   * @since 4.0.0
+   * HTTP methods that this module treats as capable of carrying a request body.
+   *
    * @category models
+   * @since 4.0.0
    */
   export type WithBody = Exclude<HttpMethod, NoBody>
 }
 
 /**
+ * Returns `true` when a method can carry a request body and narrows it to `HttpMethod.WithBody`.
+ *
  * @since 4.0.0
  */
 export const hasBody = (method: HttpMethod): method is HttpMethod.WithBody =>
   method !== "GET" && method !== "HEAD" && method !== "OPTIONS" && method !== "TRACE"
 
 /**
+ * Set containing every supported `HttpMethod` literal.
+ *
  * @since 4.0.0
  */
 export const all: ReadonlySet<HttpMethod> = new Set([
@@ -55,6 +83,8 @@ export const all: ReadonlySet<HttpMethod> = new Set([
 ])
 
 /**
+ * Tuples mapping each supported HTTP method to its short request-constructor name.
+ *
  * @since 4.0.0
  */
 export const allShort = [
@@ -84,7 +114,7 @@ export const allShort = [
  * // false
  * ```
  *
- * @since 4.0.0
  * @category refinements
+ * @since 4.0.0
  */
 export const isHttpMethod = (u: unknown): u is HttpMethod => all.has(u as HttpMethod)