Skip to content
Effect V4 Docs

HttpClient.ts

HttpClient.ts overview

Section titled “HttpClient.ts overview”

Provides the service used to run outgoing HTTP requests.

HttpClient executes immutable HttpClientRequest values and returns HttpClientResponse values. Keeping HTTP behind this service lets programs, tests, and generated API clients use the same request model without depending on one concrete platform transport. This module includes request accessors, constructors and layers, request and response transformations, status filtering, retries, rate limiting, cookies, redirect handling, scoped request abortion, and tracing support.

Since v4.0.0

Exports Grouped by Category

Section titled “Exports Grouped by Category”

accessors

Section titled “accessors”

del

Section titled “del”

Executes a DELETE request using the HttpClient service from the environment.

Signature

declare const del: (
  url: string | URL,
  options?: HttpClientRequest.Options.NoUrl | undefined
) => Effect.Effect<HttpClientResponse.HttpClientResponse, Error.HttpClientError, HttpClient>

Source

Since v4.0.0

execute

Section titled “execute”

Executes a prebuilt HttpClientRequest using the HttpClient service from the environment.

Signature

declare const execute: (
  request: HttpClientRequest.HttpClientRequest
) => Effect.Effect<HttpClientResponse.HttpClientResponse, Error.HttpClientError, HttpClient>

Source

Since v4.0.0

get

Section titled “get”

Executes a GET request using the HttpClient service from the environment.

Signature

declare const get: (
  url: string | URL,
  options?: HttpClientRequest.Options.NoUrl | undefined
) => Effect.Effect<HttpClientResponse.HttpClientResponse, Error.HttpClientError, HttpClient>

Source

Since v4.0.0

Section titled “head”

Executes a HEAD request using the HttpClient service from the environment.

Signature

declare const head: (
  url: string | URL,
  options?: HttpClientRequest.Options.NoUrl | undefined
) => Effect.Effect<HttpClientResponse.HttpClientResponse, Error.HttpClientError, HttpClient>

Source

Since v4.0.0

options

Section titled “options”

Executes an OPTIONS request using the HttpClient service from the environment.

Signature

declare const options: (
  url: string | URL,
  options?: HttpClientRequest.Options.NoUrl | undefined
) => Effect.Effect<HttpClientResponse.HttpClientResponse, Error.HttpClientError, HttpClient>

Source

Since v4.0.0

patch

Section titled “patch”

Executes a PATCH request using the HttpClient service from the environment.

Signature

declare const patch: (
  url: string | URL,
  options?: HttpClientRequest.Options.NoUrl | undefined
) => Effect.Effect<HttpClientResponse.HttpClientResponse, Error.HttpClientError, HttpClient>

Source

Since v4.0.0

post

Section titled “post”

Executes a POST request using the HttpClient service from the environment.

Signature

declare const post: (
  url: string | URL,
  options?: HttpClientRequest.Options.NoUrl | undefined
) => Effect.Effect<HttpClientResponse.HttpClientResponse, Error.HttpClientError, HttpClient>

Source

Since v4.0.0

put

Section titled “put”

Executes a PUT request using the HttpClient service from the environment.

Signature

declare const put: (
  url: string | URL,
  options?: HttpClientRequest.Options.NoUrl | undefined
) => Effect.Effect<HttpClientResponse.HttpClientResponse, Error.HttpClientError, HttpClient>

Source

Since v4.0.0

constructors

Section titled “constructors”

make

Section titled “make”

Constructs an HttpClient from a low-level request runner.

Details

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.

Signature

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

Source

Since v4.0.0

makeWith

Section titled “makeWith”

Constructs an HttpClient.With from a preprocessing function and a postprocessing function.

Details

execute applies preprocessing to the request and then passes the resulting request effect to postprocessing.

Signature

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>

Source

Since v4.0.0

cookies

Section titled “cookies”

withCookiesRef

Section titled “withCookiesRef”

Adds a Ref of cookies to the client for handling cookies across requests.

When to use

Use to add shared cookie storage to a client so response cookies are retained and sent by later requests.

Signature

declare const withCookiesRef: {
  (ref: Ref.Ref<Cookies.Cookies>): <E, R>(self: HttpClient.With<E, R>) => HttpClient.With<E, R>
  <E, R>(self: HttpClient.With<E, R>, ref: Ref.Ref<Cookies.Cookies>): HttpClient.With<E, R>
}

Source

Since v4.0.0

error handling

Section titled “error handling”

catch

Section titled “catch”

Handles all client failures with an effectful recovery function and returns a transformed client.

Signature

declare const catch: { <E, E2, R2>(f: (e: E) => Effect.Effect<HttpClientResponse.HttpClientResponse, E2, R2>): <R>(self: HttpClient.With<E, R>) => HttpClient.With<E2, R2 | R>; <E, R, A2, E2, R2>(self: HttpClient.With<E, R>, f: (e: E) => Effect.Effect<A2, E2, R2>): HttpClient.With<E2, R | R2>; }

Source

Since v4.0.0

catchTag

Section titled “catchTag”

Handles client failures with one or more matching _tag values and returns a transformed client.

Signature

declare const catchTag: {
  <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>
  <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>
}

Source

Since v4.0.0

catchTags

Section titled “catchTags”

Handles client failures by matching their _tag values against a case map.

Signature

declare const catchTags: {
  <
    E,
    Cases extends {
      [K in Extract<E, { _tag: string }>["_tag"]]+?: (
        error: Extract<E, { _tag: K }>
      ) => Effect.Effect<HttpClientResponse.HttpClientResponse, any, any>
    } & (unknown extends E ? {} : { [K in Exclude<keyof Cases, Extract<E, { _tag: string }>["_tag"]>]: never })
  >(
    cases: Cases
  ): <R>(
    self: HttpClient.With<E, R>
  ) => HttpClient.With<
    | Exclude<E, { _tag: keyof Cases }>
    | {
        [K in keyof Cases]: Cases[K] extends (...args: Array<any>) => Effect.Effect<any, infer E, any> ? E : never
      }[keyof Cases],
    | R
    | {
        [K in keyof Cases]: Cases[K] extends (...args: Array<any>) => Effect.Effect<any, any, infer R> ? R : never
      }[keyof Cases]
  >
  <
    E extends { _tag: string },
    R,
    Cases extends {
      [K in Extract<E, { _tag: string }>["_tag"]]+?: (
        error: Extract<E, { _tag: K }>
      ) => Effect.Effect<HttpClientResponse.HttpClientResponse, any, any>
    } & (unknown extends E ? {} : { [K in Exclude<keyof Cases, Extract<E, { _tag: string }>["_tag"]>]: never })
  >(
    self: HttpClient.With<E, R>,
    cases: Cases
  ): HttpClient.With<
    | Exclude<E, { _tag: keyof Cases }>
    | {
        [K in keyof Cases]: Cases[K] extends (...args: Array<any>) => Effect.Effect<any, infer E, any> ? E : never
      }[keyof Cases],
    | R
    | {
        [K in keyof Cases]: Cases[K] extends (...args: Array<any>) => Effect.Effect<any, any, infer R> ? R : never
      }[keyof Cases]
  >
}

Source

Since v4.0.0

retry

Section titled “retry”

Retries the request based on a provided schedule or policy.

Signature

declare const retry: {
  <E, O extends NoExcessProperties<Effect.Retry.Options<E>, O>>(
    options: O
  ): <R>(self: HttpClient.With<E, R>) => Retry.Return<R, E, O>
  <B, E, ES, R1>(
    policy: Schedule.Schedule<B, NoInfer<E>, ES, R1>
  ): <R>(self: HttpClient.With<E, R>) => HttpClient.With<E | ES, R1 | R>
  <E, R, O extends NoExcessProperties<Effect.Retry.Options<E>, O>>(
    self: HttpClient.With<E, R>,
    options: O
  ): Retry.Return<R, E, O>
  <E, R, B, ES, R1>(
    self: HttpClient.With<E, R>,
    policy: Schedule.Schedule<B, E, ES, R1>
  ): HttpClient.With<E | ES, R1 | R>
}

Source

Since v4.0.0

retryTransient

Section titled “retryTransient”

Retries common transient errors, such as rate limiting, timeouts or network issues.

When to use

Use to focus on retrying errors, transient responses, or both.

Details

Specifying a while predicate allows you to consider other errors as transient, and is ignored in “response-only” mode.

Signature

declare const retryTransient: {
  <
    E,
    B = never,
    ES = never,
    R1 = never,
    const RetryOn extends "errors-only" | "response-only" | "errors-and-responses" =
      | "response-only"
      | "errors-only"
      | "errors-and-responses",
    Input = RetryOn extends "errors-only"
      ? E
      : RetryOn extends "response-only"
        ? HttpClientResponse.HttpClientResponse
        : HttpClientResponse.HttpClientResponse | E
  >(options: {
    readonly retryOn?: RetryOn | undefined
    readonly while?: Predicate.Predicate<NoInfer<E | ES>>
    readonly schedule?: Schedule.Schedule<B, NoInfer<Input>, ES, R1>
    readonly times?: number
  }): <R>(self: HttpClient.With<E, R>) => HttpClient.With<E | ES, R1 | R>
  <
    E,
    R,
    B = never,
    ES = never,
    R1 = never,
    const RetryOn extends "errors-only" | "response-only" | "errors-and-responses" =
      | "response-only"
      | "errors-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
      readonly while?: Predicate.Predicate<NoInfer<E | ES>>
      readonly schedule?: Schedule.Schedule<B, NoInfer<Input>, ES, R1>
      readonly times?: number
    }
  ): HttpClient.With<E | ES, R1 | R>
  <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>
  <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>
}

Source

Since v4.0.0

filters

Section titled “filters”

filterOrElse

Section titled “filterOrElse”

Filters the result of a response, or runs an alternative effect if the predicate fails.

Signature

declare const filterOrElse: {
  <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>
  <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>
  <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>
  <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>
}

Source

Since v4.0.0

filterOrFail

Section titled “filterOrFail”

Filters successful responses, or fails with the error produced by orFailWith when the predicate does not match.

Signature

declare const filterOrFail: {
  <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>
  <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>
  <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>
  <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>
}

Source

Since v4.0.0

filterStatus

Section titled “filterStatus”

Filters responses by HTTP status code.

Signature

declare const filterStatus: {
  (f: (status: number) => boolean): <E, R>(self: HttpClient.With<E, R>) => HttpClient.With<E | Error.HttpClientError, R>
  <E, R>(self: HttpClient.With<E, R>, f: (status: number) => boolean): HttpClient.With<E | Error.HttpClientError, R>
}

Source

Since v4.0.0

filterStatusOk

Section titled “filterStatusOk”

Filters responses that return a 2xx status code.

Signature

declare const filterStatusOk: <E, R>(self: HttpClient.With<E, R>) => HttpClient.With<E | Error.HttpClientError, R>

Source

Since v4.0.0

guards

Section titled “guards”

isHttpClient

Section titled “isHttpClient”

Returns true if the provided value is an HttpClient.

Signature

declare const isHttpClient: (u: unknown) => u is HttpClient

Source

Since v4.0.0

layers

Section titled “layers”

layerMergedContext

Section titled “layerMergedContext”

Creates an HttpClient layer and merges the layer construction context into client response effects.

Signature

declare const layerMergedContext: <E, R>(effect: Effect.Effect<HttpClient, E, R>) => Layer.Layer<HttpClient, E, R>

Source

Since v4.0.0

mapping & sequencing

Section titled “mapping & sequencing”

mapRequest

Section titled “mapRequest”

Appends a transformation of the request object before sending it.

Signature

declare const mapRequest: {
  (
    f: (a: HttpClientRequest.HttpClientRequest) => HttpClientRequest.HttpClientRequest
  ): <E, R>(self: HttpClient.With<E, R>) => HttpClient.With<E, R>
  <E, R>(
    self: HttpClient.With<E, R>,
    f: (a: HttpClientRequest.HttpClientRequest) => HttpClientRequest.HttpClientRequest
  ): HttpClient.With<E, R>
}

Source

Since v4.0.0

mapRequestEffect

Section titled “mapRequestEffect”

Appends an effectful transformation of the request object before sending it.

Signature

declare const mapRequestEffect: {
  <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>
  <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>
}

Source

Since v4.0.0

mapRequestInput

Section titled “mapRequestInput”

Prepends a transformation of the request object before sending it.

Signature

declare const mapRequestInput: {
  (
    f: (a: HttpClientRequest.HttpClientRequest) => HttpClientRequest.HttpClientRequest
  ): <E, R>(self: HttpClient.With<E, R>) => HttpClient.With<E, R>
  <E, R>(
    self: HttpClient.With<E, R>,
    f: (a: HttpClientRequest.HttpClientRequest) => HttpClientRequest.HttpClientRequest
  ): HttpClient.With<E, R>
}

Source

Since v4.0.0

mapRequestInputEffect

Section titled “mapRequestInputEffect”

Prepends an effectful transformation of the request object before sending it.

Signature

declare const mapRequestInputEffect: {
  <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>
  <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>
}

Source

Since v4.0.0

tap

Section titled “tap”

Performs an additional effect after a successful request.

Signature

declare const tap: {
  <_, E2, R2>(
    f: (response: HttpClientResponse.HttpClientResponse) => Effect.Effect<_, E2, R2>
  ): <E, R>(self: HttpClient.With<E, R>) => HttpClient.With<E | E2, R | R2>
  <E, R, _, E2, R2>(
    self: HttpClient.With<E, R>,
    f: (response: HttpClientResponse.HttpClientResponse) => Effect.Effect<_, E2, R2>
  ): HttpClient.With<E | E2, R | R2>
}

Source

Since v4.0.0

tapError

Section titled “tapError”

Performs an additional effect after an unsuccessful request.

Signature

declare const tapError: {
  <_, E, E2, R2>(
    f: (e: NoInfer<E>) => Effect.Effect<_, E2, R2>
  ): <R>(self: HttpClient.With<E, R>) => HttpClient.With<E | E2, R | R2>
  <E, R, _, E2, R2>(
    self: HttpClient.With<E, R>,
    f: (e: NoInfer<E>) => Effect.Effect<_, E2, R2>
  ): HttpClient.With<E | E2, R | R2>
}

Source

Since v4.0.0

tapRequest

Section titled “tapRequest”

Performs an additional effect on the request before sending it.

Signature

declare const tapRequest: {
  <_, E2, R2>(
    f: (a: HttpClientRequest.HttpClientRequest) => Effect.Effect<_, E2, R2>
  ): <E, R>(self: HttpClient.With<E, R>) => HttpClient.With<E | E2, R | R2>
  <E, R, _, E2, R2>(
    self: HttpClient.With<E, R>,
    f: (a: HttpClientRequest.HttpClientRequest) => Effect.Effect<_, E2, R2>
  ): HttpClient.With<E | E2, R | R2>
}

Source

Since v4.0.0

transform

Section titled “transform”

Transforms a client by wrapping the response effect for each request.

Details

The transformation receives both the response effect and the original request, allowing it to change success, error, and environment behavior.

Signature

declare const transform: {
  <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>
  <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>
}

Source

Since v4.0.0

transformResponse

Section titled “transformResponse”

Transforms a client by applying an effectful transformation to each response effect.

Signature

declare const transformResponse: {
  <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>
  <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>
}

Source

Since v4.0.0

models

Section titled “models”

HttpClient (interface)

Section titled “HttpClient (interface)”

HTTP client whose requests produce HttpClientResponse values and can fail with HttpClientError.

Signature

export interface HttpClient extends HttpClient.With<Error.HttpClientError> {}

Source

Since v4.0.0

rate limiting

Section titled “rate limiting”

withRateLimiter

Section titled “withRateLimiter”

Applies request rate limiting using the RateLimiter service.

Details

It can update limits by inspecting common rate limit response headers and automatically retries HTTP 429 responses (or HttpClientError values wrapping a 429 response) by forcing the retry back through the limiter.

Signature

declare const withRateLimiter: {
  (
    options: WithRateLimiter.Options
  ): <E, R>(self: HttpClient.With<E, R>) => HttpClient.With<E | RateLimiter.RateLimiterError, R>
  <E, R>(
    self: HttpClient.With<E, R>,
    options: WithRateLimiter.Options
  ): HttpClient.With<E | RateLimiter.RateLimiterError, R>
}

Source

Since v4.0.0

redirects

Section titled “redirects”

followRedirects

Section titled “followRedirects”

Enables following HTTP redirects up to a specified number of times.

Signature

declare const followRedirects: {
  (maxRedirects?: number | undefined): <E, R>(self: HttpClient.With<E, R>) => HttpClient.With<E, R>
  <E, R>(self: HttpClient.With<E, R>, maxRedirects?: number | undefined): HttpClient.With<E, R>
}

Source

Since v4.0.0

references

Section titled “references”

SpanNameGenerator

Section titled “SpanNameGenerator”

Context reference for generating the span name used for outgoing client request spans.

Signature

declare const SpanNameGenerator: Context.Reference<(request: HttpClientRequest.HttpClientRequest) => string>

Source

Since v4.0.0

TracerDisabledWhen

Section titled “TracerDisabledWhen”

Context reference for a predicate that disables client-side tracing for matching outgoing requests.

Signature

declare const TracerDisabledWhen: Context.Reference<Predicate.Predicate<HttpClientRequest.HttpClientRequest>>

Source

Since v4.0.0

TracerPropagationEnabled

Section titled “TracerPropagationEnabled”

Context reference that controls whether outgoing client spans are propagated to request headers.

Signature

declare const TracerPropagationEnabled: Context.Reference<boolean>

Source

Since v4.0.0

resource management

Section titled “resource management”

withScope

Section titled “withScope”

Attaches the lifetime of the HttpClientRequest to a Scope.

Signature

declare const withScope: <E, R>(self: HttpClient.With<E, R>) => HttpClient.With<E, R | Scope.Scope>

Source

Since v4.0.0

services

Section titled “services”

HttpClient

Section titled “HttpClient”

Service tag for the default outgoing HTTP client service.

When to use

Use to provide the default outgoing HTTP client service used by request accessors such as execute, get, and post.

Signature

declare const HttpClient: Context.Service<HttpClient, HttpClient>

Source

Since v4.0.0

utils

Section titled “utils”

HttpClient (namespace)

Section titled “HttpClient (namespace)”

Namespace containing type-level members associated with HttpClient.

Source

Since v4.0.0

With (interface)

Section titled “With (interface)”

Parameterized HTTP client that may fail with E and require environment R.

Details

It exposes preprocessing, postprocessing, direct request execution, and method-specific helpers.

Signature

export interface With<E, R = never> extends Pipeable, Inspectable.Inspectable {
  readonly [TypeId]: typeof TypeId
  readonly preprocess: Preprocess<E, R>
  readonly postprocess: Postprocess<E, R>
  readonly execute: (
    request: HttpClientRequest.HttpClientRequest
  ) => Effect.Effect<HttpClientResponse.HttpClientResponse, E, R>


  readonly get: (
    url: string | URL,
    options?: HttpClientRequest.Options.NoUrl
  ) => Effect.Effect<HttpClientResponse.HttpClientResponse, E, R>
  readonly head: (
    url: string | URL,
    options?: HttpClientRequest.Options.NoUrl
  ) => Effect.Effect<HttpClientResponse.HttpClientResponse, E, R>
  readonly post: (
    url: string | URL,
    options?: HttpClientRequest.Options.NoUrl
  ) => Effect.Effect<HttpClientResponse.HttpClientResponse, E, R>
  readonly patch: (
    url: string | URL,
    options?: HttpClientRequest.Options.NoUrl
  ) => Effect.Effect<HttpClientResponse.HttpClientResponse, E, R>
  readonly put: (
    url: string | URL,
    options?: HttpClientRequest.Options.NoUrl
  ) => Effect.Effect<HttpClientResponse.HttpClientResponse, E, R>
  readonly del: (
    url: string | URL,
    options?: HttpClientRequest.Options.NoUrl
  ) => Effect.Effect<HttpClientResponse.HttpClientResponse, E, R>
  readonly options: (
    url: string | URL,
    options?: HttpClientRequest.Options.NoUrl
  ) => Effect.Effect<HttpClientResponse.HttpClientResponse, E, R>
}

Source

Since v4.0.0

Preprocess (type alias)

Section titled “Preprocess (type alias)”

Effectful transformation applied to a request before the client executes it.

Signature

type Preprocess<E, R> = (
  request: HttpClientRequest.HttpClientRequest
) => Effect.Effect<HttpClientRequest.HttpClientRequest, E, R>

Source

Since v4.0.0

Postprocess (type alias)

Section titled “Postprocess (type alias)”

Function that turns a preprocessed request effect into the response effect executed by the client.

Signature

type Postprocess<E, R> = (
  request: Effect.Effect<HttpClientRequest.HttpClientRequest, E, R>
) => Effect.Effect<HttpClientResponse.HttpClientResponse, E, R>

Source

Since v4.0.0

Retry (namespace)

Section titled “Retry (namespace)”

Namespace containing type-level helpers for retrying HTTP clients.

Source

Since v4.0.0

Return (type alias)

Section titled “Return (type alias)”

Computes the client type returned by retry for a given set of retry options.

Details

The result includes errors and requirements introduced by schedules and effectful retry predicates.

Signature

type HttpClient.With<(O extends { schedule: Schedule.Schedule<infer _O, infer _I, infer _E, infer _R>; } ? E | _E : O extends { times: number; } ? E : O extends { until: Predicate.Refinement<E, infer E2>; } ? E2 : E) | (O extends { while: (...args: Array<any>) => Effect.Effect<infer _A, infer E, infer _R>; } ? E : never) | (O extends { until: (...args: Array<any>) => Effect.Effect<infer _A, infer E, infer _R>; } ? E : never), R | (O extends { schedule: Schedule.Schedule<infer _O, infer _I, infer _E, infer R>; } ? R : never) | (O extends { while: (...args: Array<any>) => Effect.Effect<infer _A, infer _E, infer R>; } ? R : never) | (O extends { until: (...args: Array<any>) => Effect.Effect<infer _A, infer _E, infer R>; } ? R : never)> = HttpClient.With<
    | (O extends { schedule: Schedule.Schedule<infer _O, infer _I, infer _E, infer _R> } ? E | _E
      : O extends { times: number } ? E
      : O extends { until: Predicate.Refinement<E, infer E2> } ? E2
      : E)
    | (O extends { while: (...args: Array<any>) => Effect.Effect<infer _A, infer E, infer _R> } ? E : never)
    | (O extends { until: (...args: Array<any>) => Effect.Effect<infer _A, infer E, infer _R> } ? E : never),
    | R
    | (O extends { schedule: Schedule.Schedule<infer _O, infer _I, infer _E, infer R> } ? R : never)
    | (O extends { while: (...args: Array<any>) => Effect.Effect<infer _A, infer _E, infer R> } ? R : never)
    | (O extends { until: (...args: Array<any>) => Effect.Effect<infer _A, infer _E, infer R> } ? R : never)
  > extends infer Z ? Z : never

Source

Since v4.0.0

WithRateLimiter (namespace)

Section titled “WithRateLimiter (namespace)”

Namespace containing configuration types for withRateLimiter.

Source

Since v4.0.0

Options (interface)

Section titled “Options (interface)”

Options used to configure withRateLimiter.

Details

They define the backing limiter, initial limit window, keying strategy, algorithm, token cost, and whether response headers update future limits.

Signature

export interface Options {
  /**
   * The `RateLimiter` service to use for rate limiting.
   */
  readonly limiter: RateLimiter.RateLimiter
  /**
   * The initial rate limit window duration.
   */
  readonly window: Duration.Input
  /**
   * The initial maximum number of allowed requests in the window.
   */
  readonly limit: number
  /**
   * The key to identify the rate limit. Requests with the same key will share
   * the same rate limit. This can be used to implement per-user or
   * per-endpoint rate limits.
   */
  readonly key: string | ((request: HttpClientRequest.HttpClientRequest) => string)
  /**
   * Defaults to `"fixed-window"`.
   */
  readonly algorithm?: "fixed-window" | "token-bucket" | undefined
  /**
   * Defaults to `1`.
   */
  readonly tokens?: number | ((request: HttpClientRequest.HttpClientRequest) => number) | undefined
  /**
   * Disable automatic limits updates from response headers.
   */
  readonly disableResponseInspection?: boolean | undefined
  /**
   * Disable adaptive learning from `Retry-After` responses.
   */
  readonly disableAdaptiveLearning?: boolean | undefined
}

Source

Since v4.0.0