effect 4.0.0-beta.66 → 4.0.0-beta.67

package/src/unstable/http/HttpClientRequest.ts

@@ -1,4 +1,22 @@
 /**
+ * Utilities for constructing 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.
+ *
+ * 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.
+ *
  * @since 4.0.0
  */
 import * as Context from "../../Context.ts"
@@ -25,14 +43,18 @@ import * as UrlParams from "./UrlParams.ts"
 const TypeId = "~effect/http/HttpClientRequest"
 
 /**
- * @since 4.0.0
+ * Returns `true` when a value is an `HttpClientRequest`.
+ *
  * @category Guards
+ * @since 4.0.0
  */
 export const isHttpClientRequest = (u: unknown): u is HttpClientRequest => hasProperty(u, TypeId)
 
 /**
- * @since 4.0.0
+ * Immutable model of an outgoing HTTP client request, including its method, URL components, headers, and body.
+ *
  * @category models
+ * @since 4.0.0
  */
 export interface HttpClientRequest extends Inspectable.Inspectable, Pipeable {
   readonly [TypeId]: typeof TypeId
@@ -45,8 +67,10 @@ export interface HttpClientRequest extends Inspectable.Inspectable, Pipeable {
 }
 
 /**
- * @since 4.0.0
+ * Options for constructing or modifying an `HttpClientRequest`.
+ *
  * @category models
+ * @since 4.0.0
  */
 export interface Options {
   readonly method?: HttpMethod | undefined
@@ -60,12 +84,16 @@ export interface Options {
 }
 
 /**
+ * Namespace containing option types associated with `HttpClientRequest` construction.
+ *
  * @since 4.0.0
  */
 export declare namespace Options {
   /**
-   * @since 4.0.0
+   * Request options that omit the method and URL for helpers that already receive those values separately.
+   *
    * @category models
+   * @since 4.0.0
    */
   export interface NoUrl extends Omit<Options, "method" | "url"> {}
 }
@@ -90,8 +118,10 @@ const Proto = {
 }
 
 /**
- * @since 4.0.0
+ * Constructs an `HttpClientRequest` from fully normalized request components.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export function makeWith(
   method: HttpMethod,
@@ -112,8 +142,10 @@ export function makeWith(
 }
 
 /**
- * @since 4.0.0
+ * An empty `GET` request with no URL, query parameters, hash, headers, or body.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const empty: HttpClientRequest = makeWith(
   "GET",
@@ -125,8 +157,10 @@ export const empty: HttpClientRequest = makeWith(
 )
 
 /**
- * @since 4.0.0
+ * Creates a request constructor for the specified HTTP method.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const make = <M extends HttpMethod>(
   method: M
@@ -142,26 +176,34 @@ export const make = <M extends HttpMethod>(
   })
 
 /**
- * @since 4.0.0
+ * Creates a `GET` request for the specified URL.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const get: (url: string | URL, options?: Options.NoUrl) => HttpClientRequest = make("GET")
 
 /**
- * @since 4.0.0
+ * Creates a `POST` request for the specified URL.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const post: (url: string | URL, options?: Options.NoUrl) => HttpClientRequest = make("POST")
 
 /**
- * @since 4.0.0
+ * Creates a `PATCH` request for the specified URL.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const patch: (url: string | URL, options?: Options.NoUrl) => HttpClientRequest = make("PATCH")
 
 /**
- * @since 4.0.0
+ * Creates a `PUT` request for the specified URL.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const put: (url: string | URL, options?: Options.NoUrl) => HttpClientRequest = make("PUT")
 
@@ -169,43 +211,55 @@ const del: (url: string | URL, options?: Options.NoUrl) => HttpClientRequest = m
 
 export {
   /**
-   * @since 4.0.0
    * @category constructors
+   * @since 4.0.0
    */
   del as delete
 }
 
 /**
- * @since 4.0.0
+ * Creates a `HEAD` request for the specified URL.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const head: (url: string | URL, options?: Options.NoUrl) => HttpClientRequest = make("HEAD")
 
 /**
- * @since 4.0.0
+ * Creates an `OPTIONS` request for the specified URL.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const options: (url: string | URL, options?: Options.NoUrl) => HttpClientRequest = make("OPTIONS")
 
 /**
- * @since 4.0.0
+ * Creates a `TRACE` request for the specified URL.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const trace: (url: string | URL, options?: Options.NoUrl) => HttpClientRequest = make("TRACE")
 
 /**
- * @since 4.0.0
+ * Applies request options to an `HttpClientRequest`, returning a new request.
+ *
  * @category combinators
+ * @since 4.0.0
  */
 export const modify: {
   /**
-   * @since 4.0.0
+   * Applies request options to an `HttpClientRequest`, returning a new request.
+   *
    * @category combinators
+   * @since 4.0.0
    */
   (options: Options): (self: HttpClientRequest) => HttpClientRequest
   /**
-   * @since 4.0.0
+   * Applies request options to an `HttpClientRequest`, returning a new request.
+   *
    * @category combinators
+   * @since 4.0.0
    */
   (self: HttpClientRequest, options: Options): HttpClientRequest
 } = dual(2, (self: HttpClientRequest, options: Options): HttpClientRequest => {
@@ -240,18 +294,24 @@ export const modify: {
 })
 
 /**
- * @since 4.0.0
+ * Sets the HTTP method on a request, returning a new request.
+ *
  * @category combinators
+ * @since 4.0.0
  */
 export const setMethod: {
   /**
-   * @since 4.0.0
+   * Sets the HTTP method on a request, returning a new request.
+   *
    * @category combinators
+   * @since 4.0.0
    */
   (method: HttpMethod): (self: HttpClientRequest) => HttpClientRequest
   /**
-   * @since 4.0.0
+   * Sets the HTTP method on a request, returning a new request.
+   *
    * @category combinators
+   * @since 4.0.0
    */
   (self: HttpClientRequest, method: HttpMethod): HttpClientRequest
 } = dual(
@@ -261,18 +321,24 @@ export const setMethod: {
 )
 
 /**
- * @since 4.0.0
+ * Sets a single request header, replacing any existing value for that header.
+ *
  * @category combinators
+ * @since 4.0.0
  */
 export const setHeader: {
   /**
-   * @since 4.0.0
+   * Sets a single request header, replacing any existing value for that header.
+   *
    * @category combinators
+   * @since 4.0.0
    */
   (key: string, value: string): (self: HttpClientRequest) => HttpClientRequest
   /**
-   * @since 4.0.0
+   * Sets a single request header, replacing any existing value for that header.
+   *
    * @category combinators
+   * @since 4.0.0
    */
   (self: HttpClientRequest, key: string, value: string): HttpClientRequest
 } = dual(3, (self: HttpClientRequest, key: string, value: string): HttpClientRequest =>
@@ -286,18 +352,24 @@ export const setHeader: {
   ))
 
 /**
- * @since 4.0.0
+ * Sets multiple request headers from an input collection, replacing existing values with matching names.
+ *
  * @category combinators
+ * @since 4.0.0
  */
 export const setHeaders: {
   /**
-   * @since 4.0.0
+   * Sets multiple request headers from an input collection, replacing existing values with matching names.
+   *
    * @category combinators
+   * @since 4.0.0
    */
   (input: Headers.Input): (self: HttpClientRequest) => HttpClientRequest
   /**
-   * @since 4.0.0
+   * Sets multiple request headers from an input collection, replacing existing values with matching names.
+   *
    * @category combinators
+   * @since 4.0.0
    */
   (self: HttpClientRequest, input: Headers.Input): HttpClientRequest
 } = dual(2, (self: HttpClientRequest, input: Headers.Input): HttpClientRequest =>
@@ -311,18 +383,24 @@ export const setHeaders: {
   ))
 
 /**
- * @since 4.0.0
+ * Sets the `Authorization` header using HTTP Basic authentication credentials.
+ *
  * @category combinators
+ * @since 4.0.0
  */
 export const basicAuth: {
   /**
-   * @since 4.0.0
+   * Sets the `Authorization` header using HTTP Basic authentication credentials.
+   *
    * @category combinators
+   * @since 4.0.0
    */
   (username: string | Redacted.Redacted, password: string | Redacted.Redacted): (self: HttpClientRequest) => HttpClientRequest
   /**
-   * @since 4.0.0
+   * Sets the `Authorization` header using HTTP Basic authentication credentials.
+   *
    * @category combinators
+   * @since 4.0.0
    */
   (
     self: HttpClientRequest,
@@ -340,18 +418,24 @@ export const basicAuth: {
 )
 
 /**
- * @since 4.0.0
+ * Sets the `Authorization` header using a bearer token.
+ *
  * @category combinators
+ * @since 4.0.0
  */
 export const bearerToken: {
   /**
-   * @since 4.0.0
+   * Sets the `Authorization` header using a bearer token.
+   *
    * @category combinators
+   * @since 4.0.0
    */
   (token: string | Redacted.Redacted): (self: HttpClientRequest) => HttpClientRequest
   /**
-   * @since 4.0.0
+   * Sets the `Authorization` header using a bearer token.
+   *
    * @category combinators
+   * @since 4.0.0
    */
   (self: HttpClientRequest, token: string | Redacted.Redacted): HttpClientRequest
 } = dual(
@@ -361,41 +445,55 @@ export const bearerToken: {
 )
 
 /**
- * @since 4.0.0
+ * Sets the `Accept` header to the specified media type.
+ *
  * @category combinators
+ * @since 4.0.0
  */
 export const accept: {
   /**
-   * @since 4.0.0
+   * Sets the `Accept` header to the specified media type.
+   *
    * @category combinators
+   * @since 4.0.0
    */
   (mediaType: string): (self: HttpClientRequest) => HttpClientRequest
   /**
-   * @since 4.0.0
+   * Sets the `Accept` header to the specified media type.
+   *
    * @category combinators
+   * @since 4.0.0
    */
   (self: HttpClientRequest, mediaType: string): HttpClientRequest
 } = dual(2, (self: HttpClientRequest, mediaType: string): HttpClientRequest => setHeader(self, "Accept", mediaType))
 
 /**
- * @since 4.0.0
+ * Sets the `Accept` header to `application/json`.
+ *
  * @category combinators
+ * @since 4.0.0
  */
 export const acceptJson: (self: HttpClientRequest) => HttpClientRequest = accept("application/json")
 
 /**
- * @since 4.0.0
+ * Sets the request URL. When given a `URL`, its search parameters and hash are extracted into the request's structured fields.
+ *
  * @category combinators
+ * @since 4.0.0
  */
 export const setUrl: {
   /**
-   * @since 4.0.0
+   * Sets the request URL. When given a `URL`, its search parameters and hash are extracted into the request's structured fields.
+   *
    * @category combinators
+   * @since 4.0.0
    */
   (url: string | URL): (self: HttpClientRequest) => HttpClientRequest
   /**
-   * @since 4.0.0
+   * Sets the request URL. When given a `URL`, its search parameters and hash are extracted into the request's structured fields.
+   *
    * @category combinators
+   * @since 4.0.0
    */
   (self: HttpClientRequest, url: string | URL): HttpClientRequest
 } = dual(2, (self: HttpClientRequest, url: string | URL): HttpClientRequest => {
@@ -425,18 +523,24 @@ export const setUrl: {
 })
 
 /**
- * @since 4.0.0
+ * Prepends a URL segment to the request URL, inserting or trimming one slash as needed.
+ *
  * @category combinators
+ * @since 4.0.0
  */
 export const prependUrl: {
   /**
-   * @since 4.0.0
+   * Prepends a URL segment to the request URL, inserting or trimming one slash as needed.
+   *
    * @category combinators
+   * @since 4.0.0
    */
   (path: string): (self: HttpClientRequest) => HttpClientRequest
   /**
-   * @since 4.0.0
+   * Prepends a URL segment to the request URL, inserting or trimming one slash as needed.
+   *
    * @category combinators
+   * @since 4.0.0
    */
   (self: HttpClientRequest, path: string): HttpClientRequest
 } = dual(2, (self: HttpClientRequest, path: string): HttpClientRequest => {
@@ -452,18 +556,24 @@ export const prependUrl: {
 })
 
 /**
- * @since 4.0.0
+ * Appends a URL segment to the request URL, inserting or trimming one slash as needed.
+ *
  * @category combinators
+ * @since 4.0.0
  */
 export const appendUrl: {
   /**
-   * @since 4.0.0
+   * Appends a URL segment to the request URL, inserting or trimming one slash as needed.
+   *
    * @category combinators
+   * @since 4.0.0
    */
   (path: string): (self: HttpClientRequest) => HttpClientRequest
   /**
-   * @since 4.0.0
+   * Appends a URL segment to the request URL, inserting or trimming one slash as needed.
+   *
    * @category combinators
+   * @since 4.0.0
    */
   (self: HttpClientRequest, path: string): HttpClientRequest
 } = dual(2, (self: HttpClientRequest, path: string): HttpClientRequest => {
@@ -491,18 +601,24 @@ const joinSegments = (first: string, second: string): string => {
 }
 
 /**
- * @since 4.0.0
+ * Updates the request URL by applying a function to the current URL string.
+ *
  * @category combinators
+ * @since 4.0.0
  */
 export const updateUrl: {
   /**
-   * @since 4.0.0
+   * Updates the request URL by applying a function to the current URL string.
+   *
    * @category combinators
+   * @since 4.0.0
    */
   (f: (url: string) => string): (self: HttpClientRequest) => HttpClientRequest
   /**
-   * @since 4.0.0
+   * Updates the request URL by applying a function to the current URL string.
+   *
    * @category combinators
+   * @since 4.0.0
    */
   (self: HttpClientRequest, f: (url: string) => string): HttpClientRequest
 } = dual(2, (self: HttpClientRequest, f: (url: string) => string): HttpClientRequest =>
@@ -516,18 +632,24 @@ export const updateUrl: {
   ))
 
 /**
- * @since 4.0.0
+ * Sets one query parameter, replacing existing values for that parameter name.
+ *
  * @category combinators
+ * @since 4.0.0
  */
 export const setUrlParam: {
   /**
-   * @since 4.0.0
+   * Sets one query parameter, replacing existing values for that parameter name.
+   *
    * @category combinators
+   * @since 4.0.0
    */
   (key: string, value: string): (self: HttpClientRequest) => HttpClientRequest
   /**
-   * @since 4.0.0
+   * Sets one query parameter, replacing existing values for that parameter name.
+   *
    * @category combinators
+   * @since 4.0.0
    */
   (self: HttpClientRequest, key: string, value: string): HttpClientRequest
 } = dual(3, (self: HttpClientRequest, key: string, value: string): HttpClientRequest =>
@@ -541,18 +663,24 @@ export const setUrlParam: {
   ))
 
 /**
- * @since 4.0.0
+ * Sets query parameters from an input collection, replacing existing values for matching names.
+ *
  * @category combinators
+ * @since 4.0.0
  */
 export const setUrlParams: {
   /**
-   * @since 4.0.0
+   * Sets query parameters from an input collection, replacing existing values for matching names.
+   *
    * @category combinators
+   * @since 4.0.0
    */
   (input: UrlParams.Input): (self: HttpClientRequest) => HttpClientRequest
   /**
-   * @since 4.0.0
+   * Sets query parameters from an input collection, replacing existing values for matching names.
+   *
    * @category combinators
+   * @since 4.0.0
    */
   (self: HttpClientRequest, input: UrlParams.Input): HttpClientRequest
 } = dual(2, (self: HttpClientRequest, input: UrlParams.Input): HttpClientRequest =>
@@ -566,18 +694,24 @@ export const setUrlParams: {
   ))
 
 /**
- * @since 4.0.0
+ * Appends one query parameter value without removing existing values for the same name.
+ *
  * @category combinators
+ * @since 4.0.0
  */
 export const appendUrlParam: {
   /**
-   * @since 4.0.0
+   * Appends one query parameter value without removing existing values for the same name.
+   *
    * @category combinators
+   * @since 4.0.0
    */
   (key: string, value: string): (self: HttpClientRequest) => HttpClientRequest
   /**
-   * @since 4.0.0
+   * Appends one query parameter value without removing existing values for the same name.
+   *
    * @category combinators
+   * @since 4.0.0
    */
   (self: HttpClientRequest, key: string, value: string): HttpClientRequest
 } = dual(3, (self: HttpClientRequest, key: string, value: string): HttpClientRequest =>
@@ -591,18 +725,24 @@ export const appendUrlParam: {
   ))
 
 /**
- * @since 4.0.0
+ * Appends query parameters from an input collection without removing existing values for matching names.
+ *
  * @category combinators
+ * @since 4.0.0
  */
 export const appendUrlParams: {
   /**
-   * @since 4.0.0
+   * Appends query parameters from an input collection without removing existing values for matching names.
+   *
    * @category combinators
+   * @since 4.0.0
    */
   (input: UrlParams.Input): (self: HttpClientRequest) => HttpClientRequest
   /**
-   * @since 4.0.0
+   * Appends query parameters from an input collection without removing existing values for matching names.
+   *
    * @category combinators
+   * @since 4.0.0
    */
   (self: HttpClientRequest, input: UrlParams.Input): HttpClientRequest
 } = dual(2, (self: HttpClientRequest, input: UrlParams.Input): HttpClientRequest =>
@@ -616,18 +756,24 @@ export const appendUrlParams: {
   ))
 
 /**
- * @since 4.0.0
+ * Sets the URL fragment on a request without the leading `#`.
+ *
  * @category combinators
+ * @since 4.0.0
  */
 export const setHash: {
   /**
-   * @since 4.0.0
+   * Sets the URL fragment on a request without the leading `#`.
+   *
    * @category combinators
+   * @since 4.0.0
    */
   (hash: string): (self: HttpClientRequest) => HttpClientRequest
   /**
-   * @since 4.0.0
+   * Sets the URL fragment on a request without the leading `#`.
+   *
    * @category combinators
+   * @since 4.0.0
    */
   (self: HttpClientRequest, hash: string): HttpClientRequest
 } = dual(2, (self: HttpClientRequest, hash: string): HttpClientRequest =>
@@ -641,8 +787,10 @@ export const setHash: {
   ))
 
 /**
- * @since 4.0.0
+ * Removes the URL fragment from a request.
+ *
  * @category combinators
+ * @since 4.0.0
  */
 export const removeHash = (self: HttpClientRequest): HttpClientRequest =>
   makeWith(
@@ -655,18 +803,24 @@ export const removeHash = (self: HttpClientRequest): HttpClientRequest =>
   )
 
 /**
- * @since 4.0.0
+ * Sets the request body and updates `Content-Type` and `Content-Length` headers from the body metadata when available.
+ *
  * @category combinators
+ * @since 4.0.0
  */
 export const setBody: {
   /**
-   * @since 4.0.0
+   * Sets the request body and updates `Content-Type` and `Content-Length` headers from the body metadata when available.
+   *
    * @category combinators
+   * @since 4.0.0
    */
   (body: HttpBody.HttpBody): (self: HttpClientRequest) => HttpClientRequest
   /**
-   * @since 4.0.0
+   * Sets the request body and updates `Content-Type` and `Content-Length` headers from the body metadata when available.
+   *
    * @category combinators
+   * @since 4.0.0
    */
   (self: HttpClientRequest, body: HttpBody.HttpBody): HttpClientRequest
 } = dual(2, (self: HttpClientRequest, body: HttpBody.HttpBody): HttpClientRequest => {
@@ -692,18 +846,24 @@ export const setBody: {
 })
 
 /**
- * @since 4.0.0
+ * Sets a `Uint8Array` request body with an optional content type.
+ *
  * @category combinators
+ * @since 4.0.0
  */
 export const bodyUint8Array: {
   /**
-   * @since 4.0.0
+   * Sets a `Uint8Array` request body with an optional content type.
+   *
    * @category combinators
+   * @since 4.0.0
    */
   (body: Uint8Array, contentType?: string): (self: HttpClientRequest) => HttpClientRequest
   /**
-   * @since 4.0.0
+   * Sets a `Uint8Array` request body with an optional content type.
+   *
    * @category combinators
+   * @since 4.0.0
    */
   (self: HttpClientRequest, body: Uint8Array, contentType?: string): HttpClientRequest
 } = dual(
@@ -713,18 +873,24 @@ export const bodyUint8Array: {
 )
 
 /**
- * @since 4.0.0
+ * Sets a text request body with an optional content type.
+ *
  * @category combinators
+ * @since 4.0.0
  */
 export const bodyText: {
   /**
-   * @since 4.0.0
+   * Sets a text request body with an optional content type.
+   *
    * @category combinators
+   * @since 4.0.0
    */
   (body: string, contentType?: string): (self: HttpClientRequest) => HttpClientRequest
   /**
-   * @since 4.0.0
+   * Sets a text request body with an optional content type.
+   *
    * @category combinators
+   * @since 4.0.0
    */
   (self: HttpClientRequest, body: string, contentType?: string): HttpClientRequest
 } = dual(
@@ -734,18 +900,24 @@ export const bodyText: {
 )
 
 /**
- * @since 4.0.0
+ * Encodes a value as a JSON request body and sets it on the request, failing with `HttpBodyError` if encoding fails.
+ *
  * @category combinators
+ * @since 4.0.0
  */
 export const bodyJson: {
   /**
-   * @since 4.0.0
+   * Encodes a value as a JSON request body and sets it on the request, failing with `HttpBodyError` if encoding fails.
+   *
    * @category combinators
+   * @since 4.0.0
    */
   (body: unknown): (self: HttpClientRequest) => Effect.Effect<HttpClientRequest, HttpBody.HttpBodyError>
   /**
-   * @since 4.0.0
+   * Encodes a value as a JSON request body and sets it on the request, failing with `HttpBodyError` if encoding fails.
+   *
    * @category combinators
+   * @since 4.0.0
    */
   (self: HttpClientRequest, body: unknown): Effect.Effect<HttpClientRequest, HttpBody.HttpBodyError>
 } = dual(
@@ -755,25 +927,33 @@ export const bodyJson: {
 )
 
 /**
- * @since 4.0.0
+ * Sets a JSON request body using unsafe JSON encoding, which may throw instead of failing in the Effect error channel.
+ *
  * @category combinators
+ * @since 4.0.0
  */
 export const bodyJsonUnsafe: {
   /**
-   * @since 4.0.0
+   * Sets a JSON request body using unsafe JSON encoding, which may throw instead of failing in the Effect error channel.
+   *
    * @category combinators
+   * @since 4.0.0
    */
   (body: unknown): (self: HttpClientRequest) => HttpClientRequest
   /**
-   * @since 4.0.0
+   * Sets a JSON request body using unsafe JSON encoding, which may throw instead of failing in the Effect error channel.
+   *
    * @category combinators
+   * @since 4.0.0
    */
   (self: HttpClientRequest, body: unknown): HttpClientRequest
 } = dual(2, (self: HttpClientRequest, body: unknown): HttpClientRequest => setBody(self, HttpBody.jsonUnsafe(body)))
 
 /**
- * @since 4.0.0
+ * Creates a schema-based JSON body encoder that sets the encoded value on a request.
+ *
  * @category combinators
+ * @since 4.0.0
  */
 export const schemaBodyJson = <S extends Schema.Top>(
   schema: S,
@@ -801,18 +981,24 @@ export const schemaBodyJson = <S extends Schema.Top>(
 }
 
 /**
- * @since 4.0.0
+ * Sets an `application/x-www-form-urlencoded` request body from URL parameter input.
+ *
  * @category combinators
+ * @since 4.0.0
  */
 export const bodyUrlParams: {
   /**
-   * @since 4.0.0
+   * Sets an `application/x-www-form-urlencoded` request body from URL parameter input.
+   *
    * @category combinators
+   * @since 4.0.0
    */
   (input: UrlParams.Input): (self: HttpClientRequest) => HttpClientRequest
   /**
-   * @since 4.0.0
+   * Sets an `application/x-www-form-urlencoded` request body from URL parameter input.
+   *
    * @category combinators
+   * @since 4.0.0
    */
   (self: HttpClientRequest, input: UrlParams.Input): HttpClientRequest
 } = dual(
@@ -822,35 +1008,47 @@ export const bodyUrlParams: {
 )
 
 /**
- * @since 4.0.0
+ * Sets a `FormData` request body.
+ *
  * @category combinators
+ * @since 4.0.0
  */
 export const bodyFormData: {
   /**
-   * @since 4.0.0
+   * Sets a `FormData` request body.
+   *
    * @category combinators
+   * @since 4.0.0
    */
   (body: FormData): (self: HttpClientRequest) => HttpClientRequest
   /**
-   * @since 4.0.0
+   * Sets a `FormData` request body.
+   *
    * @category combinators
+   * @since 4.0.0
    */
   (self: HttpClientRequest, body: FormData): HttpClientRequest
 } = dual(2, (self: HttpClientRequest, body: FormData): HttpClientRequest => setBody(self, HttpBody.formData(body)))
 
 /**
- * @since 4.0.0
+ * Creates a `FormData` request body from record-style entries and sets it on the request.
+ *
  * @category combinators
+ * @since 4.0.0
  */
 export const bodyFormDataRecord: {
   /**
-   * @since 4.0.0
+   * Creates a `FormData` request body from record-style entries and sets it on the request.
+   *
    * @category combinators
+   * @since 4.0.0
    */
   (entries: HttpBody.FormDataInput): (self: HttpClientRequest) => HttpClientRequest
   /**
-   * @since 4.0.0
+   * Creates a `FormData` request body from record-style entries and sets it on the request.
+   *
    * @category combinators
+   * @since 4.0.0
    */
   (self: HttpClientRequest, entries: HttpBody.FormDataInput): HttpClientRequest
 } = dual(
@@ -860,21 +1058,27 @@ export const bodyFormDataRecord: {
 )
 
 /**
- * @since 4.0.0
+ * Sets a streaming `Uint8Array` request body with optional content type and content length metadata.
+ *
  * @category combinators
+ * @since 4.0.0
  */
 export const bodyStream: {
   /**
-   * @since 4.0.0
+   * Sets a streaming `Uint8Array` request body with optional content type and content length metadata.
+   *
    * @category combinators
+   * @since 4.0.0
    */
   (
     body: Stream.Stream<Uint8Array, unknown>,
     options?: { readonly contentType?: string | undefined; readonly contentLength?: number | undefined } | undefined
   ): (self: HttpClientRequest) => HttpClientRequest
   /**
-   * @since 4.0.0
+   * Sets a streaming `Uint8Array` request body with optional content type and content length metadata.
+   *
    * @category combinators
+   * @since 4.0.0
    */
   (
     self: HttpClientRequest,
@@ -895,13 +1099,17 @@ export const bodyStream: {
 )
 
 /**
- * @since 4.0.0
+ * Creates a file-backed request body from a filesystem path and sets it on the request.
+ *
  * @category combinators
+ * @since 4.0.0
  */
 export const bodyFile: {
   /**
-   * @since 4.0.0
+   * Creates a file-backed request body from a filesystem path and sets it on the request.
+   *
    * @category combinators
+   * @since 4.0.0
    */
   (
     path: string,
@@ -913,8 +1121,10 @@ export const bodyFile: {
     }
   ): (self: HttpClientRequest) => Effect.Effect<HttpClientRequest, PlatformError.PlatformError, FileSystem.FileSystem>
   /**
-   * @since 4.0.0
+   * Creates a file-backed request body from a filesystem path and sets it on the request.
+   *
    * @category combinators
+   * @since 4.0.0
    */
   (
     self: HttpClientRequest,
@@ -945,8 +1155,10 @@ export const bodyFile: {
 )
 
 /**
- * @since 4.0.0
+ * Builds a `URL` from the request URL, query parameters, and hash, returning `Option.none()` if the URL is invalid.
+ *
  * @category combinators
+ * @since 4.0.0
  */
 export function toUrl(self: HttpClientRequest): Option.Option<URL> {
   const r = UrlParams.makeUrl(self.url, self.urlParams, Option.getOrUndefined(self.hash))
@@ -957,8 +1169,10 @@ export function toUrl(self: HttpClientRequest): Option.Option<URL> {
 }
 
 /**
- * @since 4.0.0
+ * Converts a Web `Request` into an `HttpClientRequest`, preserving method, URL, headers, and supported request bodies.
+ *
  * @category conversions
+ * @since 4.0.0
  */
 export const fromWeb = (request: globalThis.Request): HttpClientRequest => {
   const method = request.method.toUpperCase() as HttpMethod
@@ -989,8 +1203,10 @@ const parseContentLength = (contentLength: string | null): number | undefined =>
 }
 
 /**
- * @since 4.0.0
+ * Converts an `HttpClientRequest` to a Web `Request` as a `Result`, failing when the request URL is invalid.
+ *
  * @category conversions
+ * @since 4.0.0
  */
 export const toWebResult = (self: HttpClientRequest, options?: {
   readonly signal?: AbortSignal | undefined
@@ -1044,8 +1260,10 @@ const isReadableStream = (u: unknown): u is ReadableStream<Uint8Array> =>
   typeof ReadableStream !== "undefined" && u instanceof ReadableStream
 
 /**
- * @since 4.0.0
+ * Converts an `HttpClientRequest` to a Web `Request`, failing with `UrlParamsError` when the request URL is invalid.
+ *
  * @category conversions
+ * @since 4.0.0
  */
 export const toWeb = (self: HttpClientRequest, options?: {
   readonly signal?: AbortSignal | undefined