effect 4.0.0-beta.66 → 4.0.0-beta.68

package/dist/unstable/http/HttpClient.d.ts

@@ -1,4 +1,23 @@
 /**
+ * Composable HTTP client service for executing `HttpClientRequest` values and
+ * receiving `HttpClientResponse` values inside Effect programs.
+ *
+ * This module provides the `HttpClient` service tag, method-specific accessors,
+ * constructors for low-level runtimes, and middleware-style combinators for
+ * common client concerns such as request rewriting, response filtering, retries,
+ * redirects, cookies, rate limiting, and tracing. It is intended for code that
+ * needs dependency-injected outbound HTTP calls, reusable clients customized for
+ * an API, or cross-cutting behavior layered around a concrete platform client.
+ *
+ * Responses are successful Effects even for non-2xx status codes unless a
+ * filter such as `filterStatus` or `filterStatusOk` is applied. Request
+ * middleware is ordered by whether it prepends to or appends after the existing
+ * preprocessing pipeline, so use `mapRequestInput` for transformations that
+ * should run before previously installed request middleware and `mapRequest`
+ * for transformations that should run after it. Non-scoped responses are tied to
+ * an abort controller for interruption cleanup; use `withScope` when the request
+ * lifetime should instead be controlled by a surrounding `Scope`.
+ *
  * @since 4.0.0
  */
 import type { NonEmptyReadonlyArray } from "../../Array.ts";
@@ -21,23 +40,33 @@ import * as HttpClientRequest from "./HttpClientRequest.ts";
 import * as HttpClientResponse from "./HttpClientResponse.ts";
 declare const TypeId = "~effect/http/HttpClient";
 /**
+ * Returns `true` if the provided value is an `HttpClient`.
+ *
+ * @category guards
  * @since 4.0.0
- * @category Guards
  */
 export declare const isHttpClient: (u: unknown) => u is HttpClient;
 /**
- * @since 4.0.0
+ * HTTP client whose requests produce `HttpClientResponse` values and can fail with `HttpClientError`.
+ *
  * @category models
+ * @since 4.0.0
  */
 export interface HttpClient extends HttpClient.With<Error.HttpClientError> {
 }
 /**
+ * Namespace containing type-level members associated with `HttpClient`.
+ *
  * @since 4.0.0
  */
 export declare namespace HttpClient {
     /**
-     * @since 4.0.0
+     * Parameterized HTTP client that may fail with `E` and require environment `R`.
+     *
+     * It exposes preprocessing, postprocessing, direct request execution, and method-specific helpers.
+     *
      * @category models
+     * @since 4.0.0
      */
     interface With<E, R = never> extends Pipeable, Inspectable.Inspectable {
         readonly [TypeId]: typeof TypeId;
@@ -53,90 +82,130 @@ export declare namespace HttpClient {
         readonly options: (url: string | URL, options?: HttpClientRequest.Options.NoUrl) => Effect.Effect<HttpClientResponse.HttpClientResponse, E, R>;
     }
     /**
-     * @since 4.0.0
+     * Effectful transformation applied to a request before the client executes it.
+     *
      * @category models
+     * @since 4.0.0
      */
     type Preprocess<E, R> = (request: HttpClientRequest.HttpClientRequest) => Effect.Effect<HttpClientRequest.HttpClientRequest, E, R>;
     /**
-     * @since 4.0.0
+     * Function that turns a preprocessed request effect into the response effect executed by the client.
+     *
      * @category models
+     * @since 4.0.0
      */
     type Postprocess<E = never, R = never> = (request: Effect.Effect<HttpClientRequest.HttpClientRequest, E, R>) => Effect.Effect<HttpClientResponse.HttpClientResponse, E, R>;
 }
 /**
- * @since 4.0.0
+ * Service tag for the default `HttpClient` used by HTTP client accessors.
+ *
  * @category tags
+ * @since 4.0.0
  */
 export declare const HttpClient: Context.Service<HttpClient, HttpClient>;
 /**
- * @since 4.0.0
+ * Executes a prebuilt `HttpClientRequest` using the `HttpClient` service from the environment.
+ *
  * @category accessors
+ * @since 4.0.0
  */
 export declare const execute: (request: HttpClientRequest.HttpClientRequest) => Effect.Effect<HttpClientResponse.HttpClientResponse, Error.HttpClientError, HttpClient>;
 /**
- * @since 4.0.0
+ * Executes a `GET` request using the `HttpClient` service from the environment.
+ *
  * @category accessors
+ * @since 4.0.0
  */
 export declare const get: (url: string | URL, options?: HttpClientRequest.Options.NoUrl | undefined) => Effect.Effect<HttpClientResponse.HttpClientResponse, Error.HttpClientError, HttpClient>;
 /**
- * @since 4.0.0
+ * Executes a `HEAD` request using the `HttpClient` service from the environment.
+ *
  * @category accessors
+ * @since 4.0.0
  */
 export declare const head: (url: string | URL, options?: HttpClientRequest.Options.NoUrl | undefined) => Effect.Effect<HttpClientResponse.HttpClientResponse, Error.HttpClientError, HttpClient>;
 /**
- * @since 4.0.0
+ * Executes a `POST` request using the `HttpClient` service from the environment.
+ *
  * @category accessors
+ * @since 4.0.0
  */
 export declare const post: (url: string | URL, options?: HttpClientRequest.Options.NoUrl | undefined) => Effect.Effect<HttpClientResponse.HttpClientResponse, Error.HttpClientError, HttpClient>;
 /**
- * @since 4.0.0
+ * Executes a `PATCH` request using the `HttpClient` service from the environment.
+ *
  * @category accessors
+ * @since 4.0.0
  */
 export declare const patch: (url: string | URL, options?: HttpClientRequest.Options.NoUrl | undefined) => Effect.Effect<HttpClientResponse.HttpClientResponse, Error.HttpClientError, HttpClient>;
 /**
- * @since 4.0.0
+ * Executes a `PUT` request using the `HttpClient` service from the environment.
+ *
  * @category accessors
+ * @since 4.0.0
  */
 export declare const put: (url: string | URL, options?: HttpClientRequest.Options.NoUrl | undefined) => Effect.Effect<HttpClientResponse.HttpClientResponse, Error.HttpClientError, HttpClient>;
 /**
- * @since 4.0.0
+ * Executes a `DELETE` request using the `HttpClient` service from the environment.
+ *
  * @category accessors
+ * @since 4.0.0
  */
 export declare const del: (url: string | URL, options?: HttpClientRequest.Options.NoUrl | undefined) => Effect.Effect<HttpClientResponse.HttpClientResponse, Error.HttpClientError, HttpClient>;
 /**
- * @since 4.0.0
+ * Executes an `OPTIONS` request using the `HttpClient` service from the environment.
+ *
  * @category accessors
+ * @since 4.0.0
  */
 export declare const options: (url: string | URL, options?: HttpClientRequest.Options.NoUrl | undefined) => Effect.Effect<HttpClientResponse.HttpClientResponse, Error.HttpClientError, HttpClient>;
 /**
- * @since 4.0.0
+ * Transforms a client by wrapping the response effect for each request.
+ *
+ * The transformation receives both the response effect and the original request, allowing it to change success, error, and environment behavior.
+ *
  * @category mapping & sequencing
+ * @since 4.0.0
  */
 export declare const transform: {
     /**
-     * @since 4.0.0
+     * Transforms a client by wrapping the response effect for each request.
+     *
+     * The transformation receives both the response effect and the original request, allowing it to change success, error, and environment behavior.
+     *
      * @category mapping & sequencing
+     * @since 4.0.0
      */
     <E, R, E1, R1>(f: (effect: Effect.Effect<HttpClientResponse.HttpClientResponse, E, R>, request: HttpClientRequest.HttpClientRequest) => Effect.Effect<HttpClientResponse.HttpClientResponse, E1, R1>): (self: HttpClient.With<E, R>) => HttpClient.With<E | E1, R | R1>;
     /**
-     * @since 4.0.0
+     * Transforms a client by wrapping the response effect for each request.
+     *
+     * The transformation receives both the response effect and the original request, allowing it to change success, error, and environment behavior.
+     *
      * @category mapping & sequencing
+     * @since 4.0.0
      */
     <E, R, E1, R1>(self: HttpClient.With<E, R>, f: (effect: Effect.Effect<HttpClientResponse.HttpClientResponse, E, R>, request: HttpClientRequest.HttpClientRequest) => Effect.Effect<HttpClientResponse.HttpClientResponse, E1, R1>): HttpClient.With<E | E1, R | R1>;
 };
 /**
- * @since 4.0.0
+ * Transforms a client by applying an effectful transformation to each response effect.
+ *
  * @category mapping & sequencing
+ * @since 4.0.0
  */
 export declare const transformResponse: {
     /**
-     * @since 4.0.0
+     * Transforms a client by applying an effectful transformation to each response effect.
+     *
      * @category mapping & sequencing
+     * @since 4.0.0
      */
     <E, R, E1, R1>(f: (effect: Effect.Effect<HttpClientResponse.HttpClientResponse, E, R>) => Effect.Effect<HttpClientResponse.HttpClientResponse, E1, R1>): (self: HttpClient.With<E, R>) => HttpClient.With<E1, R1>;
     /**
-     * @since 4.0.0
+     * Transforms a client by applying an effectful transformation to each response effect.
+     *
      * @category mapping & sequencing
+     * @since 4.0.0
      */
     <E, R, E1, R1>(self: HttpClient.With<E, R>, f: (effect: Effect.Effect<HttpClientResponse.HttpClientResponse, E, R>) => Effect.Effect<HttpClientResponse.HttpClientResponse, E1, R1>): HttpClient.With<E1, R1>;
 };
@@ -146,34 +215,44 @@ declare const catch_: {
 };
 export { 
 /**
- * @since 4.0.0
  * @category error handling
+ * @since 4.0.0
  */
 catch_ as catch };
 /**
- * @since 4.0.0
+ * Handles client failures with one or more matching `_tag` values and returns a transformed client.
+ *
  * @category error handling
+ * @since 4.0.0
  */
 export declare const catchTag: {
     /**
-     * @since 4.0.0
+     * Handles client failures with one or more matching `_tag` values and returns a transformed client.
+     *
      * @category error handling
+     * @since 4.0.0
      */
     <K extends Tags<E> | NonEmptyReadonlyArray<Tags<E>>, E, E1, R1>(tag: K, f: (e: ExtractTag<NoInfer<E>, K extends NonEmptyReadonlyArray<string> ? K[number] : K>) => Effect.Effect<HttpClientResponse.HttpClientResponse, E1, R1>): <R>(self: HttpClient.With<E, R>) => HttpClient.With<E1 | ExcludeTag<E, K extends NonEmptyReadonlyArray<string> ? K[number] : K>, R1 | R>;
     /**
-     * @since 4.0.0
+     * Handles client failures with one or more matching `_tag` values and returns a transformed client.
+     *
      * @category error handling
+     * @since 4.0.0
      */
     <R, E, K extends Tags<E> | NonEmptyReadonlyArray<Tags<E>>, R1, E1>(self: HttpClient.With<E, R>, tag: K, f: (e: ExtractTag<E, K extends NonEmptyReadonlyArray<string> ? K[number] : K>) => Effect.Effect<HttpClientResponse.HttpClientResponse, E1, R1>): HttpClient.With<E1 | ExcludeTag<E, K extends NonEmptyReadonlyArray<string> ? K[number] : K>, R1 | R>;
 };
 /**
- * @since 4.0.0
+ * Handles client failures by matching their `_tag` values against a case map.
+ *
  * @category error handling
+ * @since 4.0.0
  */
 export declare const catchTags: {
     /**
-     * @since 4.0.0
+     * Handles client failures by matching their `_tag` values against a case map.
+     *
      * @category error handling
+     * @since 4.0.0
      */
     <E, Cases extends {
         [K in Extract<E, {
@@ -193,8 +272,10 @@ export declare const catchTags: {
         [K in keyof Cases]: Cases[K] extends (...args: Array<any>) => Effect.Effect<any, any, infer R> ? R : never;
     }[keyof Cases]>;
     /**
-     * @since 4.0.0
+     * Handles client failures by matching their `_tag` values against a case map.
+     *
      * @category error handling
+     * @since 4.0.0
      */
     <E extends {
         _tag: string;
@@ -219,210 +300,223 @@ export declare const catchTags: {
 /**
  * Filters the result of a response, or runs an alternative effect if the predicate fails.
  *
- * @since 4.0.0
  * @category filters
+ * @since 4.0.0
  */
 export declare const filterOrElse: {
     /**
      * Filters the result of a response, or runs an alternative effect if the predicate fails.
      *
-     * @since 4.0.0
      * @category filters
+     * @since 4.0.0
      */
     <B extends HttpClientResponse.HttpClientResponse, E2, R2>(refinement: Predicate.Refinement<NoInfer<HttpClientResponse.HttpClientResponse>, B>, orElse: (response: EqualsWith<HttpClientResponse.HttpClientResponse, B, NoInfer<HttpClientResponse.HttpClientResponse>, Exclude<NoInfer<HttpClientResponse.HttpClientResponse>, B>>) => Effect.Effect<HttpClientResponse.HttpClientResponse, E2, R2>): <E, R>(self: HttpClient.With<E, R>) => HttpClient.With<E2 | E, R2 | R>;
     /**
      * Filters the result of a response, or runs an alternative effect if the predicate fails.
      *
-     * @since 4.0.0
      * @category filters
+     * @since 4.0.0
      */
     <E2, R2>(predicate: Predicate.Predicate<NoInfer<HttpClientResponse.HttpClientResponse>>, orElse: (response: NoInfer<HttpClientResponse.HttpClientResponse>) => Effect.Effect<HttpClientResponse.HttpClientResponse, E2, R2>): <E, R>(self: HttpClient.With<E, R>) => HttpClient.With<E2 | E, R2 | R>;
     /**
      * Filters the result of a response, or runs an alternative effect if the predicate fails.
      *
-     * @since 4.0.0
      * @category filters
+     * @since 4.0.0
      */
     <E, R, B extends HttpClientResponse.HttpClientResponse, E2, R2>(self: HttpClient.With<E, R>, refinement: Predicate.Refinement<HttpClientResponse.HttpClientResponse, B>, orElse: (response: EqualsWith<HttpClientResponse.HttpClientResponse, B, HttpClientResponse.HttpClientResponse, Exclude<HttpClientResponse.HttpClientResponse, B>>) => Effect.Effect<HttpClientResponse.HttpClientResponse, E2, R2>): HttpClient.With<E2 | E, R2 | R>;
     /**
      * Filters the result of a response, or runs an alternative effect if the predicate fails.
      *
-     * @since 4.0.0
      * @category filters
+     * @since 4.0.0
      */
     <E, R, E2, R2>(self: HttpClient.With<E, R>, predicate: Predicate.Predicate<HttpClientResponse.HttpClientResponse>, orElse: (response: HttpClientResponse.HttpClientResponse) => Effect.Effect<HttpClientResponse.HttpClientResponse, E2, R2>): HttpClient.With<E2 | E, R2 | R>;
 };
 /**
- * Filters the result of a response, or throws an error if the predicate fails.
+ * Filters successful responses, or fails with the error produced by `orFailWith` when the predicate does not match.
  *
- * @since 4.0.0
  * @category filters
+ * @since 4.0.0
  */
 export declare const filterOrFail: {
     /**
-     * Filters the result of a response, or throws an error if the predicate fails.
+     * Filters successful responses, or fails with the error produced by `orFailWith` when the predicate does not match.
      *
-     * @since 4.0.0
      * @category filters
+     * @since 4.0.0
      */
     <B extends HttpClientResponse.HttpClientResponse, E2>(refinement: Predicate.Refinement<NoInfer<HttpClientResponse.HttpClientResponse>, B>, orFailWith: (response: NoInfer<HttpClientResponse.HttpClientResponse>) => E2): <E, R>(self: HttpClient.With<E, R>) => HttpClient.With<E2 | E, R>;
     /**
-     * Filters the result of a response, or throws an error if the predicate fails.
+     * Filters successful responses, or fails with the error produced by `orFailWith` when the predicate does not match.
      *
-     * @since 4.0.0
      * @category filters
+     * @since 4.0.0
      */
     <E2>(predicate: Predicate.Predicate<NoInfer<HttpClientResponse.HttpClientResponse>>, orFailWith: (response: NoInfer<HttpClientResponse.HttpClientResponse>) => E2): <E, R>(self: HttpClient.With<E, R>) => HttpClient.With<E2 | E, R>;
     /**
-     * Filters the result of a response, or throws an error if the predicate fails.
+     * Filters successful responses, or fails with the error produced by `orFailWith` when the predicate does not match.
      *
-     * @since 4.0.0
      * @category filters
+     * @since 4.0.0
      */
     <E, R, B extends HttpClientResponse.HttpClientResponse, E2>(self: HttpClient.With<E, R>, refinement: Predicate.Refinement<NoInfer<HttpClientResponse.HttpClientResponse>, B>, orFailWith: (response: NoInfer<HttpClientResponse.HttpClientResponse>) => E2): HttpClient.With<E2 | E, R>;
     /**
-     * Filters the result of a response, or throws an error if the predicate fails.
+     * Filters successful responses, or fails with the error produced by `orFailWith` when the predicate does not match.
      *
-     * @since 4.0.0
      * @category filters
+     * @since 4.0.0
      */
     <E, R, E2>(self: HttpClient.With<E, R>, predicate: Predicate.Predicate<NoInfer<HttpClientResponse.HttpClientResponse>>, orFailWith: (response: NoInfer<HttpClientResponse.HttpClientResponse>) => E2): HttpClient.With<E2 | E, R>;
 };
 /**
  * Filters responses by HTTP status code.
  *
- * @since 4.0.0
  * @category filters
+ * @since 4.0.0
  */
 export declare const filterStatus: {
     /**
      * Filters responses by HTTP status code.
      *
-     * @since 4.0.0
      * @category filters
+     * @since 4.0.0
      */
     (f: (status: number) => boolean): <E, R>(self: HttpClient.With<E, R>) => HttpClient.With<E | Error.HttpClientError, R>;
     /**
      * Filters responses by HTTP status code.
      *
-     * @since 4.0.0
      * @category filters
+     * @since 4.0.0
      */
     <E, R>(self: HttpClient.With<E, R>, f: (status: number) => boolean): HttpClient.With<E | Error.HttpClientError, R>;
 };
 /**
  * Filters responses that return a 2xx status code.
  *
- * @since 4.0.0
  * @category filters
+ * @since 4.0.0
  */
 export declare const filterStatusOk: <E, R>(self: HttpClient.With<E, R>) => HttpClient.With<E | Error.HttpClientError, R>;
 /**
- * @since 4.0.0
+ * Constructs an `HttpClient.With` from a preprocessing function and a postprocessing function.
+ *
+ * `execute` applies preprocessing to the request and then passes the resulting request effect to postprocessing.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export declare const makeWith: <E2, R2, E, R>(postprocess: (request: Effect.Effect<HttpClientRequest.HttpClientRequest, E2, R2>) => Effect.Effect<HttpClientResponse.HttpClientResponse, E, R>, preprocess: HttpClient.Preprocess<E2, R2>) => HttpClient.With<E, R>;
 /**
- * @since 4.0.0
+ * Constructs an `HttpClient` from a low-level request runner.
+ *
+ * The runner receives the request, resolved URL, abort signal, and current fiber. The client wrapper handles URL construction failures, tracing and propagation, header redaction, and aborting non-scoped requests on interruption.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export declare const make: (f: (request: HttpClientRequest.HttpClientRequest, url: URL, signal: AbortSignal, fiber: Fiber.Fiber<HttpClientResponse.HttpClientResponse, Error.HttpClientError>) => Effect.Effect<HttpClientResponse.HttpClientResponse, Error.HttpClientError>) => HttpClient;
 /**
  * Appends a transformation of the request object before sending it.
  *
- * @since 4.0.0
  * @category mapping & sequencing
+ * @since 4.0.0
  */
 export declare const mapRequest: {
     /**
      * Appends a transformation of the request object before sending it.
      *
-     * @since 4.0.0
      * @category mapping & sequencing
+     * @since 4.0.0
      */
     (f: (a: HttpClientRequest.HttpClientRequest) => HttpClientRequest.HttpClientRequest): <E, R>(self: HttpClient.With<E, R>) => HttpClient.With<E, R>;
     /**
      * Appends a transformation of the request object before sending it.
      *
-     * @since 4.0.0
      * @category mapping & sequencing
+     * @since 4.0.0
      */
     <E, R>(self: HttpClient.With<E, R>, f: (a: HttpClientRequest.HttpClientRequest) => HttpClientRequest.HttpClientRequest): HttpClient.With<E, R>;
 };
 /**
  * Appends an effectful transformation of the request object before sending it.
  *
- * @since 4.0.0
  * @category mapping & sequencing
+ * @since 4.0.0
  */
 export declare const mapRequestEffect: {
     /**
      * Appends an effectful transformation of the request object before sending it.
      *
-     * @since 4.0.0
      * @category mapping & sequencing
+     * @since 4.0.0
      */
     <E2, R2>(f: (a: HttpClientRequest.HttpClientRequest) => Effect.Effect<HttpClientRequest.HttpClientRequest, E2, R2>): <E, R>(self: HttpClient.With<E, R>) => HttpClient.With<E | E2, R | R2>;
     /**
      * Appends an effectful transformation of the request object before sending it.
      *
-     * @since 4.0.0
      * @category mapping & sequencing
+     * @since 4.0.0
      */
     <E, R, E2, R2>(self: HttpClient.With<E, R>, f: (a: HttpClientRequest.HttpClientRequest) => Effect.Effect<HttpClientRequest.HttpClientRequest, E2, R2>): HttpClient.With<E | E2, R | R2>;
 };
 /**
  * Prepends a transformation of the request object before sending it.
  *
- * @since 4.0.0
  * @category mapping & sequencing
+ * @since 4.0.0
  */
 export declare const mapRequestInput: {
     /**
      * Prepends a transformation of the request object before sending it.
      *
-     * @since 4.0.0
      * @category mapping & sequencing
+     * @since 4.0.0
      */
     (f: (a: HttpClientRequest.HttpClientRequest) => HttpClientRequest.HttpClientRequest): <E, R>(self: HttpClient.With<E, R>) => HttpClient.With<E, R>;
     /**
      * Prepends a transformation of the request object before sending it.
      *
-     * @since 4.0.0
      * @category mapping & sequencing
+     * @since 4.0.0
      */
     <E, R>(self: HttpClient.With<E, R>, f: (a: HttpClientRequest.HttpClientRequest) => HttpClientRequest.HttpClientRequest): HttpClient.With<E, R>;
 };
 /**
  * Prepends an effectful transformation of the request object before sending it.
  *
- * @since 4.0.0
  * @category mapping & sequencing
+ * @since 4.0.0
  */
 export declare const mapRequestInputEffect: {
     /**
      * Prepends an effectful transformation of the request object before sending it.
      *
-     * @since 4.0.0
      * @category mapping & sequencing
+     * @since 4.0.0
      */
     <E2, R2>(f: (a: HttpClientRequest.HttpClientRequest) => Effect.Effect<HttpClientRequest.HttpClientRequest, E2, R2>): <E, R>(self: HttpClient.With<E, R>) => HttpClient.With<E | E2, R | R2>;
     /**
      * Prepends an effectful transformation of the request object before sending it.
      *
-     * @since 4.0.0
      * @category mapping & sequencing
+     * @since 4.0.0
      */
     <E, R, E2, R2>(self: HttpClient.With<E, R>, f: (a: HttpClientRequest.HttpClientRequest) => Effect.Effect<HttpClientRequest.HttpClientRequest, E2, R2>): HttpClient.With<E | E2, R | R2>;
 };
 /**
+ * Namespace containing type-level helpers for retrying HTTP clients.
+ *
  * @since 4.0.0
- * @category error handling
  */
 export declare namespace Retry {
     /**
-     * @since 4.0.0
+     * Computes the client type returned by `retry` for a given set of retry options.
+     *
+     * The result includes errors and requirements introduced by schedules and effectful retry predicates.
+     *
      * @category error handling
+     * @since 4.0.0
      */
     type Return<R, E, O extends NoExcessProperties<Effect.Retry.Options<E>, O>> = HttpClient.With<(O extends {
         schedule: Schedule.Schedule<infer _O, infer _I, infer _E, infer _R>;
@@ -445,36 +539,36 @@ export declare namespace Retry {
 /**
  * Retries the request based on a provided schedule or policy.
  *
- * @since 4.0.0
  * @category error handling
+ * @since 4.0.0
  */
 export declare const retry: {
     /**
      * Retries the request based on a provided schedule or policy.
      *
-     * @since 4.0.0
      * @category error handling
+     * @since 4.0.0
      */
     <E, O extends NoExcessProperties<Effect.Retry.Options<E>, O>>(options: O): <R>(self: HttpClient.With<E, R>) => Retry.Return<R, E, O>;
     /**
      * Retries the request based on a provided schedule or policy.
      *
-     * @since 4.0.0
      * @category error handling
+     * @since 4.0.0
      */
     <B, E, ES, R1>(policy: Schedule.Schedule<B, NoInfer<E>, ES, R1>): <R>(self: HttpClient.With<E, R>) => HttpClient.With<E | ES, R1 | R>;
     /**
      * Retries the request based on a provided schedule or policy.
      *
-     * @since 4.0.0
      * @category error handling
+     * @since 4.0.0
      */
     <E, R, O extends NoExcessProperties<Effect.Retry.Options<E>, O>>(self: HttpClient.With<E, R>, options: O): Retry.Return<R, E, O>;
     /**
      * Retries the request based on a provided schedule or policy.
      *
-     * @since 4.0.0
      * @category error handling
+     * @since 4.0.0
      */
     <E, R, B, ES, R1>(self: HttpClient.With<E, R>, policy: Schedule.Schedule<B, E, ES, R1>): HttpClient.With<E | ES, R1 | R>;
 };
@@ -486,8 +580,8 @@ export declare const retry: {
  * Specifying a `while` predicate allows you to consider other errors as
  * transient, and is ignored in "response-only" mode.
  *
- * @since 4.0.0
  * @category error handling
+ * @since 4.0.0
  */
 export declare const retryTransient: {
     /**
@@ -498,8 +592,8 @@ export declare const retryTransient: {
      * Specifying a `while` predicate allows you to consider other errors as
      * transient, and is ignored in "response-only" mode.
      *
-     * @since 4.0.0
      * @category error handling
+     * @since 4.0.0
      */
     <E, B = never, ES = never, R1 = never, const RetryOn extends "errors-only" | "response-only" | "errors-and-responses" = "errors-only" | "response-only" | "errors-and-responses", Input = RetryOn extends "errors-only" ? E : RetryOn extends "response-only" ? HttpClientResponse.HttpClientResponse : HttpClientResponse.HttpClientResponse | E>(options: {
         readonly retryOn?: RetryOn | undefined;
@@ -515,8 +609,8 @@ export declare const retryTransient: {
      * Specifying a `while` predicate allows you to consider other errors as
      * transient, and is ignored in "response-only" mode.
      *
-     * @since 4.0.0
      * @category error handling
+     * @since 4.0.0
      */
     <E, R, B = never, ES = never, R1 = never, const RetryOn extends "errors-only" | "response-only" | "errors-and-responses" = "errors-only" | "response-only" | "errors-and-responses", Input = RetryOn extends "errors-only" ? E : RetryOn extends "response-only" ? HttpClientResponse.HttpClientResponse : HttpClientResponse.HttpClientResponse | E>(self: HttpClient.With<E, R>, options: {
         readonly retryOn?: RetryOn | undefined;
@@ -532,8 +626,8 @@ export declare const retryTransient: {
      * Specifying a `while` predicate allows you to consider other errors as
      * transient, and is ignored in "response-only" mode.
      *
-     * @since 4.0.0
      * @category error handling
+     * @since 4.0.0
      */
     <B, E, ES = never, R1 = never>(options: Schedule.Schedule<B, NoInfer<HttpClientResponse.HttpClientResponse | E>, ES, R1>): <R>(self: HttpClient.With<E, R>) => HttpClient.With<E | ES, R1 | R>;
     /**
@@ -544,19 +638,24 @@ export declare const retryTransient: {
      * Specifying a `while` predicate allows you to consider other errors as
      * transient, and is ignored in "response-only" mode.
      *
-     * @since 4.0.0
      * @category error handling
+     * @since 4.0.0
      */
     <E, R, B, ES = never, R1 = never>(self: HttpClient.With<E, R>, options: Schedule.Schedule<B, NoInfer<HttpClientResponse.HttpClientResponse | E>, ES, R1>): HttpClient.With<E | ES, R1 | R>;
 };
 /**
+ * Namespace containing configuration types for `withRateLimiter`.
+ *
  * @since 4.0.0
- * @category rate limiting
  */
 export declare namespace WithRateLimiter {
     /**
-     * @since 4.0.0
+     * Options used to configure `withRateLimiter`.
+     *
+     * They define the backing limiter, initial limit window, keying strategy, algorithm, token cost, and whether response headers update future limits.
+     *
      * @category rate limiting
+     * @since 4.0.0
      */
     interface Options {
         /**
@@ -598,8 +697,8 @@ export declare namespace WithRateLimiter {
  * automatically retries HTTP `429` responses (or `HttpClientError` values
  * wrapping a `429` response) by forcing the retry back through the limiter.
  *
- * @since 4.0.0
  * @category rate limiting
+ * @since 4.0.0
  */
 export declare const withRateLimiter: {
     /**
@@ -609,8 +708,8 @@ export declare const withRateLimiter: {
      * automatically retries HTTP `429` responses (or `HttpClientError` values
      * wrapping a `429` response) by forcing the retry back through the limiter.
      *
-     * @since 4.0.0
      * @category rate limiting
+     * @since 4.0.0
      */
     (options: WithRateLimiter.Options): <E, R>(self: HttpClient.With<E, R>) => HttpClient.With<E | RateLimiter.RateLimiterError, R>;
     /**
@@ -620,144 +719,153 @@ export declare const withRateLimiter: {
      * automatically retries HTTP `429` responses (or `HttpClientError` values
      * wrapping a `429` response) by forcing the retry back through the limiter.
      *
-     * @since 4.0.0
      * @category rate limiting
+     * @since 4.0.0
      */
     <E, R>(self: HttpClient.With<E, R>, options: WithRateLimiter.Options): HttpClient.With<E | RateLimiter.RateLimiterError, R>;
 };
 /**
  * Performs an additional effect after a successful request.
  *
- * @since 4.0.0
  * @category mapping & sequencing
+ * @since 4.0.0
  */
 export declare const tap: {
     /**
      * Performs an additional effect after a successful request.
      *
-     * @since 4.0.0
      * @category mapping & sequencing
+     * @since 4.0.0
      */
     <_, E2, R2>(f: (response: HttpClientResponse.HttpClientResponse) => Effect.Effect<_, E2, R2>): <E, R>(self: HttpClient.With<E, R>) => HttpClient.With<E | E2, R | R2>;
     /**
      * Performs an additional effect after a successful request.
      *
-     * @since 4.0.0
      * @category mapping & sequencing
+     * @since 4.0.0
      */
     <E, R, _, E2, R2>(self: HttpClient.With<E, R>, f: (response: HttpClientResponse.HttpClientResponse) => Effect.Effect<_, E2, R2>): HttpClient.With<E | E2, R | R2>;
 };
 /**
  * Performs an additional effect after an unsuccessful request.
  *
- * @since 4.0.0
  * @category mapping & sequencing
+ * @since 4.0.0
  */
 export declare const tapError: {
     /**
      * Performs an additional effect after an unsuccessful request.
      *
-     * @since 4.0.0
      * @category mapping & sequencing
+     * @since 4.0.0
      */
     <_, E, E2, R2>(f: (e: NoInfer<E>) => Effect.Effect<_, E2, R2>): <R>(self: HttpClient.With<E, R>) => HttpClient.With<E | E2, R | R2>;
     /**
      * Performs an additional effect after an unsuccessful request.
      *
-     * @since 4.0.0
      * @category mapping & sequencing
+     * @since 4.0.0
      */
     <E, R, _, E2, R2>(self: HttpClient.With<E, R>, f: (e: NoInfer<E>) => Effect.Effect<_, E2, R2>): HttpClient.With<E | E2, R | R2>;
 };
 /**
  * Performs an additional effect on the request before sending it.
  *
- * @since 4.0.0
  * @category mapping & sequencing
+ * @since 4.0.0
  */
 export declare const tapRequest: {
     /**
      * Performs an additional effect on the request before sending it.
      *
-     * @since 4.0.0
      * @category mapping & sequencing
+     * @since 4.0.0
      */
     <_, E2, R2>(f: (a: HttpClientRequest.HttpClientRequest) => Effect.Effect<_, E2, R2>): <E, R>(self: HttpClient.With<E, R>) => HttpClient.With<E | E2, R | R2>;
     /**
      * Performs an additional effect on the request before sending it.
      *
-     * @since 4.0.0
      * @category mapping & sequencing
+     * @since 4.0.0
      */
     <E, R, _, E2, R2>(self: HttpClient.With<E, R>, f: (a: HttpClientRequest.HttpClientRequest) => Effect.Effect<_, E2, R2>): HttpClient.With<E | E2, R | R2>;
 };
 /**
  * Associates a `Ref` of cookies with the client for handling cookies across requests.
  *
- * @since 4.0.0
  * @category cookies
+ * @since 4.0.0
  */
 export declare const withCookiesRef: {
     /**
      * Associates a `Ref` of cookies with the client for handling cookies across requests.
      *
-     * @since 4.0.0
      * @category cookies
+     * @since 4.0.0
      */
     (ref: Ref.Ref<Cookies.Cookies>): <E, R>(self: HttpClient.With<E, R>) => HttpClient.With<E, R>;
     /**
      * Associates a `Ref` of cookies with the client for handling cookies across requests.
      *
-     * @since 4.0.0
      * @category cookies
+     * @since 4.0.0
      */
     <E, R>(self: HttpClient.With<E, R>, ref: Ref.Ref<Cookies.Cookies>): HttpClient.With<E, R>;
 };
 /**
  * Ties the lifetime of the `HttpClientRequest` to a `Scope`.
  *
- * @since 4.0.0
  * @category Scope
+ * @since 4.0.0
  */
 export declare const withScope: <E, R>(self: HttpClient.With<E, R>) => HttpClient.With<E, R | Scope.Scope>;
 /**
  * Follows HTTP redirects up to a specified number of times.
  *
- * @since 4.0.0
  * @category redirects
+ * @since 4.0.0
  */
 export declare const followRedirects: {
     /**
      * Follows HTTP redirects up to a specified number of times.
      *
-     * @since 4.0.0
      * @category redirects
+     * @since 4.0.0
      */
     (maxRedirects?: number | undefined): <E, R>(self: HttpClient.With<E, R>) => HttpClient.With<E, R>;
     /**
      * Follows HTTP redirects up to a specified number of times.
      *
-     * @since 4.0.0
      * @category redirects
+     * @since 4.0.0
      */
     <E, R>(self: HttpClient.With<E, R>, maxRedirects?: number | undefined): HttpClient.With<E, R>;
 };
 /**
+ * Context reference for a predicate that disables client-side tracing for matching outgoing requests.
+ *
+ * @category references
  * @since 4.0.0
- * @category References
  */
 export declare const TracerDisabledWhen: Context.Reference<Predicate.Predicate<HttpClientRequest.HttpClientRequest>>;
 /**
+ * Context reference that controls whether outgoing client spans are propagated to request headers.
+ *
+ * @category references
  * @since 4.0.0
- * @category References
  */
 export declare const TracerPropagationEnabled: Context.Reference<boolean>;
 /**
+ * Context reference for generating the span name used for outgoing client request spans.
+ *
+ * @category references
  * @since 4.0.0
- * @category References
  */
 export declare const SpanNameGenerator: Context.Reference<(request: HttpClientRequest.HttpClientRequest) => string>;
 /**
+ * Creates an `HttpClient` layer and merges the layer construction context into client response effects.
+ *
+ * @category layers
  * @since 4.0.0
  */
 export declare const layerMergedContext: <E, R>(effect: Effect.Effect<HttpClient, E, R>) => Layer.Layer<HttpClient, E, R>;