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

package/src/unstable/http/HttpClient.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"
@@ -35,24 +54,34 @@ import * as UrlParams from "./UrlParams.ts"
 const TypeId = "~effect/http/HttpClient"
 
 /**
+ * Returns `true` if the provided value is an `HttpClient`.
+ *
+ * @category guards
  * @since 4.0.0
- * @category Guards
  */
 export const isHttpClient = (u: unknown): u is HttpClient => Predicate.hasProperty(u, TypeId)
 
 /**
- * @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
    */
   export interface With<E, R = never> extends Pipeable, Inspectable.Inspectable {
     readonly [TypeId]: typeof TypeId
@@ -93,16 +122,20 @@ export declare namespace HttpClient {
   }
 
   /**
-   * @since 4.0.0
+   * Effectful transformation applied to a request before the client executes it.
+   *
    * @category models
+   * @since 4.0.0
    */
   export 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
    */
   export type Postprocess<E = never, R = never> = (
     request: Effect.Effect<HttpClientRequest.HttpClientRequest, E, R>
@@ -110,8 +143,10 @@ export declare namespace HttpClient {
 }
 
 /**
- * @since 4.0.0
+ * Service tag for the default `HttpClient` used by HTTP client accessors.
+ *
  * @category tags
+ * @since 4.0.0
  */
 export const HttpClient: Context.Service<HttpClient, HttpClient> = Context.Service<HttpClient, HttpClient>(
   "effect/HttpClient"
@@ -124,16 +159,20 @@ const accessor = (method: keyof HttpClient) => (...args: Array<any>): Effect.Eff
   )
 
 /**
- * @since 4.0.0
+ * Executes a prebuilt `HttpClientRequest` using the `HttpClient` service from the environment.
+ *
  * @category accessors
+ * @since 4.0.0
  */
 export const execute: (
   request: HttpClientRequest.HttpClientRequest
 ) => Effect.Effect<HttpClientResponse.HttpClientResponse, Error.HttpClientError, HttpClient> = accessor("execute")
 
 /**
- * @since 4.0.0
+ * Executes a `GET` request using the `HttpClient` service from the environment.
+ *
  * @category accessors
+ * @since 4.0.0
  */
 export const get: (url: string | URL, options?: HttpClientRequest.Options.NoUrl | undefined) => Effect.Effect<
   HttpClientResponse.HttpClientResponse,
@@ -142,8 +181,10 @@ export const get: (url: string | URL, options?: HttpClientRequest.Options.NoUrl
 > = accessor("get")
 
 /**
- * @since 4.0.0
+ * Executes a `HEAD` request using the `HttpClient` service from the environment.
+ *
  * @category accessors
+ * @since 4.0.0
  */
 export const head: (url: string | URL, options?: HttpClientRequest.Options.NoUrl | undefined) => Effect.Effect<
   HttpClientResponse.HttpClientResponse,
@@ -152,8 +193,10 @@ export const head: (url: string | URL, options?: HttpClientRequest.Options.NoUrl
 > = accessor("head")
 
 /**
- * @since 4.0.0
+ * Executes a `POST` request using the `HttpClient` service from the environment.
+ *
  * @category accessors
+ * @since 4.0.0
  */
 export const post: (url: string | URL, options?: HttpClientRequest.Options.NoUrl | undefined) => Effect.Effect<
   HttpClientResponse.HttpClientResponse,
@@ -162,8 +205,10 @@ export const post: (url: string | URL, options?: HttpClientRequest.Options.NoUrl
 > = accessor("post")
 
 /**
- * @since 4.0.0
+ * Executes a `PATCH` request using the `HttpClient` service from the environment.
+ *
  * @category accessors
+ * @since 4.0.0
  */
 export const patch: (url: string | URL, options?: HttpClientRequest.Options.NoUrl | undefined) => Effect.Effect<
   HttpClientResponse.HttpClientResponse,
@@ -172,8 +217,10 @@ export const patch: (url: string | URL, options?: HttpClientRequest.Options.NoUr
 > = accessor("patch")
 
 /**
- * @since 4.0.0
+ * Executes a `PUT` request using the `HttpClient` service from the environment.
+ *
  * @category accessors
+ * @since 4.0.0
  */
 export const put: (url: string | URL, options?: HttpClientRequest.Options.NoUrl | undefined) => Effect.Effect<
   HttpClientResponse.HttpClientResponse,
@@ -182,8 +229,10 @@ export const put: (url: string | URL, options?: HttpClientRequest.Options.NoUrl
 > = accessor("put")
 
 /**
- * @since 4.0.0
+ * Executes a `DELETE` request using the `HttpClient` service from the environment.
+ *
  * @category accessors
+ * @since 4.0.0
  */
 export const del: (url: string | URL, options?: HttpClientRequest.Options.NoUrl | undefined) => Effect.Effect<
   HttpClientResponse.HttpClientResponse,
@@ -192,8 +241,10 @@ export const del: (url: string | URL, options?: HttpClientRequest.Options.NoUrl
 > = accessor("del")
 
 /**
- * @since 4.0.0
+ * Executes an `OPTIONS` request using the `HttpClient` service from the environment.
+ *
  * @category accessors
+ * @since 4.0.0
  */
 export const options: (url: string | URL, options?: HttpClientRequest.Options.NoUrl | undefined) => Effect.Effect<
   HttpClientResponse.HttpClientResponse,
@@ -202,13 +253,21 @@ export const options: (url: string | URL, options?: HttpClientRequest.Options.No
 > = accessor("options")
 
 /**
- * @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 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: (
@@ -217,8 +276,12 @@ export const transform: {
     ) => 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>,
@@ -240,13 +303,17 @@ export const transform: {
   ))
 
 /**
- * @since 4.0.0
+ * Transforms a client by applying an effectful transformation to each response effect.
+ *
  * @category mapping & sequencing
+ * @since 4.0.0
  */
 export 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: (
@@ -254,8 +321,10 @@ export const transformResponse: {
     ) => 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>,
@@ -288,20 +357,24 @@ 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 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,
@@ -312,8 +385,10 @@ export const catchTag: {
     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>,
@@ -335,13 +410,17 @@ export const catchTag: {
 )
 
 /**
- * @since 4.0.0
+ * Handles client failures by matching their `_tag` values against a case map.
+ *
  * @category error handling
+ * @since 4.0.0
  */
 export 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,
@@ -365,8 +444,10 @@ export const catchTags: {
     }[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 },
@@ -432,15 +513,15 @@ export 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 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>,
@@ -456,8 +537,8 @@ export 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
    */
   <E2, R2>(
     predicate: Predicate.Predicate<NoInfer<HttpClientResponse.HttpClientResponse>>,
@@ -468,8 +549,8 @@ export 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
    */
   <E, R, B extends HttpClientResponse.HttpClientResponse, E2, R2>(
     self: HttpClient.With<E, R>,
@@ -486,8 +567,8 @@ export 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
    */
   <E, R, E2, R2>(
     self: HttpClient.With<E, R>,
@@ -499,37 +580,37 @@ export const filterOrElse: {
 } = dual(3, (self, f, orElse) => transformResponse(self, Effect.filterOrElse(f, orElse)))
 
 /**
- * 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 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>,
@@ -537,10 +618,10 @@ export const filterOrFail: {
     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>,
@@ -552,22 +633,22 @@ export const filterOrFail: {
 /**
  * Filters responses by HTTP status code.
  *
- * @since 4.0.0
  * @category filters
+ * @since 4.0.0
  */
 export 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>
 } = dual(
@@ -579,15 +660,19 @@ export const filterStatus: {
 /**
  * Filters responses that return a 2xx status code.
  *
- * @since 4.0.0
  * @category filters
+ * @since 4.0.0
  */
 export const filterStatusOk: <E, R>(self: HttpClient.With<E, R>) => HttpClient.With<E | Error.HttpClientError, R> =
   transformResponse(Effect.flatMap(HttpClientResponse.filterStatusOk))
 
 /**
- * @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 const makeWith = <E2, R2, E, R>(
   postprocess: (
@@ -625,8 +710,12 @@ const Proto = {
 }
 
 /**
- * @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 const make = (
   f: (
@@ -728,15 +817,15 @@ export const make = (
 /**
  * Appends a transformation of the request object before sending it.
  *
- * @since 4.0.0
  * @category mapping & sequencing
+ * @since 4.0.0
  */
 export 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
@@ -744,8 +833,8 @@ export const mapRequest: {
   /**
    * 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>,
@@ -762,15 +851,15 @@ export const mapRequest: {
 /**
  * Appends an effectful transformation of the request object before sending it.
  *
- * @since 4.0.0
  * @category mapping & sequencing
+ * @since 4.0.0
  */
 export 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>
@@ -778,8 +867,8 @@ export const mapRequestEffect: {
   /**
    * 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>,
@@ -797,15 +886,15 @@ export const mapRequestEffect: {
 /**
  * Prepends a transformation of the request object before sending it.
  *
- * @since 4.0.0
  * @category mapping & sequencing
+ * @since 4.0.0
  */
 export 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
@@ -813,8 +902,8 @@ export const mapRequestInput: {
   /**
    * 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>,
@@ -831,15 +920,15 @@ export const mapRequestInput: {
 /**
  * Prepends an effectful transformation of the request object before sending it.
  *
- * @since 4.0.0
  * @category mapping & sequencing
+ * @since 4.0.0
  */
 export 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>
@@ -847,8 +936,8 @@ export const mapRequestInputEffect: {
   /**
    * 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>,
@@ -864,13 +953,18 @@ export const mapRequestInputEffect: {
 )
 
 /**
+ * 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
    */
   export 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> } ? E | _E
@@ -889,36 +983,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 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>
 } = dual(
@@ -937,8 +1031,8 @@ export 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 const retryTransient: {
   /**
@@ -949,8 +1043,8 @@ export 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,
@@ -980,8 +1074,8 @@ export 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,
@@ -1013,8 +1107,8 @@ export 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>
@@ -1027,8 +1121,8 @@ export 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>,
@@ -1077,13 +1171,18 @@ export const retryTransient: {
 )
 
 /**
+ * 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
    */
   export interface Options {
     /**
@@ -1126,8 +1225,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 const withRateLimiter: {
   /**
@@ -1137,8 +1236,8 @@ export 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>
@@ -1150,8 +1249,8 @@ export 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>
 } = dual(2, <E, R>(
@@ -1374,15 +1473,15 @@ const getHeader = (headers: Headers.Headers, ...keys: Array<string>): string | u
 /**
  * Performs an additional effect after a successful request.
  *
- * @since 4.0.0
  * @category mapping & sequencing
+ * @since 4.0.0
  */
 export 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>
@@ -1390,8 +1489,8 @@ export const tap: {
   /**
    * 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>,
@@ -1408,22 +1507,22 @@ export const tap: {
 /**
  * Performs an additional effect after an unsuccessful request.
  *
- * @since 4.0.0
  * @category mapping & sequencing
+ * @since 4.0.0
  */
 export 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>,
@@ -1440,22 +1539,22 @@ export const tapError: {
 /**
  * Performs an additional effect on the request before sending it.
  *
- * @since 4.0.0
  * @category mapping & sequencing
+ * @since 4.0.0
  */
 export 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>,
@@ -1473,22 +1572,22 @@ export const tapRequest: {
 /**
  * Associates a `Ref` of cookies with the client for handling cookies across requests.
  *
- * @since 4.0.0
  * @category cookies
+ * @since 4.0.0
  */
 export 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>
 } = dual(
@@ -1518,8 +1617,8 @@ export const withCookiesRef: {
 /**
  * Ties the lifetime of the `HttpClientRequest` to a `Scope`.
  *
- * @since 4.0.0
  * @category Scope
+ * @since 4.0.0
  */
 export const withScope = <E, R>(
   self: HttpClient.With<E, R>
@@ -1539,22 +1638,22 @@ export const withScope = <E, R>(
 /**
  * Follows HTTP redirects up to a specified number of times.
  *
- * @since 4.0.0
  * @category redirects
+ * @since 4.0.0
  */
 export 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>
 } = dual((args) => isHttpClient(args[0]), <E, R>(
@@ -1587,8 +1686,10 @@ export const followRedirects: {
   ))
 
 /**
+ * Context reference for a predicate that disables client-side tracing for matching outgoing requests.
+ *
+ * @category references
  * @since 4.0.0
- * @category References
  */
 export const TracerDisabledWhen = Context.Reference<
   Predicate.Predicate<HttpClientRequest.HttpClientRequest>
@@ -1597,16 +1698,20 @@ export const TracerDisabledWhen = Context.Reference<
 })
 
 /**
+ * Context reference that controls whether outgoing client spans are propagated to request headers.
+ *
+ * @category references
  * @since 4.0.0
- * @category References
  */
 export const TracerPropagationEnabled = Context.Reference<boolean>("effect/HttpClient/TracerPropagationEnabled", {
   defaultValue: constTrue
 })
 
 /**
+ * Context reference for generating the span name used for outgoing client request spans.
+ *
+ * @category references
  * @since 4.0.0
- * @category References
  */
 export const SpanNameGenerator = Context.Reference<
   (request: HttpClientRequest.HttpClientRequest) => string
@@ -1615,6 +1720,9 @@ export const SpanNameGenerator = Context.Reference<
 })
 
 /**
+ * Creates an `HttpClient` layer and merges the layer construction context into client response effects.
+ *
+ * @category layers
  * @since 4.0.0
  */
 export const layerMergedContext = <E, R>(