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

package/dist/unstable/http/HttpClientRequest.d.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";
@@ -19,13 +37,17 @@ import { type HttpMethod } from "./HttpMethod.ts";
 import * as UrlParams from "./UrlParams.ts";
 declare const TypeId = "~effect/http/HttpClientRequest";
 /**
- * @since 4.0.0
+ * Returns `true` when a value is an `HttpClientRequest`.
+ *
  * @category Guards
+ * @since 4.0.0
  */
 export declare const isHttpClientRequest: (u: unknown) => u is HttpClientRequest;
 /**
- * @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;
@@ -37,8 +59,10 @@ export interface HttpClientRequest extends Inspectable.Inspectable, Pipeable {
     readonly body: HttpBody.HttpBody;
 }
 /**
- * @since 4.0.0
+ * Options for constructing or modifying an `HttpClientRequest`.
+ *
  * @category models
+ * @since 4.0.0
  */
 export interface Options {
     readonly method?: HttpMethod | undefined;
@@ -51,491 +75,671 @@ export interface Options {
     readonly acceptJson?: boolean | undefined;
 }
 /**
+ * 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
      */
     interface NoUrl extends Omit<Options, "method" | "url"> {
     }
 }
 /**
- * @since 4.0.0
+ * Constructs an `HttpClientRequest` from fully normalized request components.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export declare function makeWith(method: HttpMethod, url: string, urlParams: UrlParams.UrlParams, hash: Option.Option<string>, headers: Headers.Headers, body: HttpBody.HttpBody): HttpClientRequest;
 /**
- * @since 4.0.0
+ * An empty `GET` request with no URL, query parameters, hash, headers, or body.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export declare const empty: HttpClientRequest;
 /**
- * @since 4.0.0
+ * Creates a request constructor for the specified HTTP method.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export declare const make: <M extends HttpMethod>(method: M) => (url: string | URL, options?: Options.NoUrl | undefined) => HttpClientRequest;
 /**
- * @since 4.0.0
+ * Creates a `GET` request for the specified URL.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export declare const get: (url: string | URL, options?: Options.NoUrl) => HttpClientRequest;
 /**
- * @since 4.0.0
+ * Creates a `POST` request for the specified URL.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export declare const post: (url: string | URL, options?: Options.NoUrl) => HttpClientRequest;
 /**
- * @since 4.0.0
+ * Creates a `PATCH` request for the specified URL.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export declare const patch: (url: string | URL, options?: Options.NoUrl) => HttpClientRequest;
 /**
- * @since 4.0.0
+ * Creates a `PUT` request for the specified URL.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export declare const put: (url: string | URL, options?: Options.NoUrl) => HttpClientRequest;
 declare const del: (url: string | URL, options?: Options.NoUrl) => HttpClientRequest;
 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 declare const head: (url: string | URL, options?: Options.NoUrl) => HttpClientRequest;
 /**
- * @since 4.0.0
+ * Creates an `OPTIONS` request for the specified URL.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export declare const options: (url: string | URL, options?: Options.NoUrl) => HttpClientRequest;
 /**
- * @since 4.0.0
+ * Creates a `TRACE` request for the specified URL.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export declare const trace: (url: string | URL, options?: Options.NoUrl) => HttpClientRequest;
 /**
- * @since 4.0.0
+ * Applies request options to an `HttpClientRequest`, returning a new request.
+ *
  * @category combinators
+ * @since 4.0.0
  */
 export declare 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;
 };
 /**
- * @since 4.0.0
+ * Sets the HTTP method on a request, returning a new request.
+ *
  * @category combinators
+ * @since 4.0.0
  */
 export declare 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;
 };
 /**
- * @since 4.0.0
+ * Sets a single request header, replacing any existing value for that header.
+ *
  * @category combinators
+ * @since 4.0.0
  */
 export declare 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;
 };
 /**
- * @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 declare 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;
 };
 /**
- * @since 4.0.0
+ * Sets the `Authorization` header using HTTP Basic authentication credentials.
+ *
  * @category combinators
+ * @since 4.0.0
  */
 export declare 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, username: string | Redacted.Redacted, password: string | Redacted.Redacted): HttpClientRequest;
 };
 /**
- * @since 4.0.0
+ * Sets the `Authorization` header using a bearer token.
+ *
  * @category combinators
+ * @since 4.0.0
  */
 export declare 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;
 };
 /**
- * @since 4.0.0
+ * Sets the `Accept` header to the specified media type.
+ *
  * @category combinators
+ * @since 4.0.0
  */
 export declare 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;
 };
 /**
- * @since 4.0.0
+ * Sets the `Accept` header to `application/json`.
+ *
  * @category combinators
+ * @since 4.0.0
  */
 export declare const acceptJson: (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
  */
 export declare 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;
 };
 /**
- * @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 declare 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;
 };
 /**
- * @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 declare 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;
 };
 /**
- * @since 4.0.0
+ * Updates the request URL by applying a function to the current URL string.
+ *
  * @category combinators
+ * @since 4.0.0
  */
 export declare 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;
 };
 /**
- * @since 4.0.0
+ * Sets one query parameter, replacing existing values for that parameter name.
+ *
  * @category combinators
+ * @since 4.0.0
  */
 export declare 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;
 };
 /**
- * @since 4.0.0
+ * Sets query parameters from an input collection, replacing existing values for matching names.
+ *
  * @category combinators
+ * @since 4.0.0
  */
 export declare 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;
 };
 /**
- * @since 4.0.0
+ * Appends one query parameter value without removing existing values for the same name.
+ *
  * @category combinators
+ * @since 4.0.0
  */
 export declare 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;
 };
 /**
- * @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 declare 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;
 };
 /**
- * @since 4.0.0
+ * Sets the URL fragment on a request without the leading `#`.
+ *
  * @category combinators
+ * @since 4.0.0
  */
 export declare 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;
 };
 /**
- * @since 4.0.0
+ * Removes the URL fragment from a request.
+ *
  * @category combinators
+ * @since 4.0.0
  */
 export declare 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 declare 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;
 };
 /**
- * @since 4.0.0
+ * Sets a `Uint8Array` request body with an optional content type.
+ *
  * @category combinators
+ * @since 4.0.0
  */
 export declare 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;
 };
 /**
- * @since 4.0.0
+ * Sets a text request body with an optional content type.
+ *
  * @category combinators
+ * @since 4.0.0
  */
 export declare 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;
 };
 /**
- * @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 declare 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>;
 };
 /**
- * @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 declare 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;
 };
 /**
- * @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 declare const schemaBodyJson: <S extends Schema.Top>(schema: S, options?: ParseOptions | undefined) => {
     (body: S["Type"]): (self: HttpClientRequest) => Effect.Effect<HttpClientRequest, HttpBody.HttpBodyError, S["EncodingServices"]>;
     (self: HttpClientRequest, body: S["Type"]): Effect.Effect<HttpClientRequest, HttpBody.HttpBodyError, S["EncodingServices"]>;
 };
 /**
- * @since 4.0.0
+ * Sets an `application/x-www-form-urlencoded` request body from URL parameter input.
+ *
  * @category combinators
+ * @since 4.0.0
  */
 export declare 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;
 };
 /**
- * @since 4.0.0
+ * Sets a `FormData` request body.
+ *
  * @category combinators
+ * @since 4.0.0
  */
 export declare 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;
 };
 /**
- * @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 declare 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;
 };
 /**
- * @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 declare 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, body: Stream.Stream<Uint8Array, unknown>, options?: {
         readonly contentType?: string | undefined;
@@ -543,13 +747,17 @@ export declare const bodyStream: {
     } | undefined): HttpClientRequest;
 };
 /**
- * @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 declare 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, options?: {
         readonly bytesToRead?: FileSystem.SizeInput | undefined;
@@ -558,8 +766,10 @@ export declare const bodyFile: {
         readonly contentType?: string;
     }): (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, path: string, options?: {
         readonly bytesToRead?: FileSystem.SizeInput | undefined;
@@ -569,26 +779,34 @@ export declare const bodyFile: {
     }): Effect.Effect<HttpClientRequest, PlatformError.PlatformError, FileSystem.FileSystem>;
 };
 /**
- * @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 declare 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 declare const fromWeb: (request: globalThis.Request) => HttpClientRequest;
 /**
- * @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 declare const toWebResult: (self: HttpClientRequest, options?: {
     readonly signal?: AbortSignal | undefined;
     readonly context?: Context.Context<never> | undefined;
 }) => Result.Result<Request, UrlParams.UrlParamsError>;
 /**
- * @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 declare const toWeb: (self: HttpClientRequest, options?: {
     readonly signal?: AbortSignal | undefined;