Skip to content

HttpClient

45 exports Added in v1.0.0 Source

Accessors

del

Added in v1.0.0 Source

Signature

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

execute

Added in v1.0.0 Source

Signature

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

get

Added in v1.0.0 Source

Signature

declare const get: (
  url: string | URL,
  options?: ClientRequest.Options.NoBody,
) => Effect.Effect<ClientResponse.HttpClientResponse, Error.HttpClientError, HttpClient>;

options

Added in v1.0.0 Source

Signature

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

patch

Added in v1.0.0 Source

Signature

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

post

Added in v1.0.0 Source

Signature

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

put

Added in v1.0.0 Source

Signature

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

Constructors

make

Added in v1.0.0 Source

Signature

declare const make: (
  f: (
    request: ClientRequest.HttpClientRequest,
    url: URL,
    signal: AbortSignal,
    fiber: RuntimeFiber<ClientResponse.HttpClientResponse, Error.HttpClientError>,
  ) => Effect.Effect<ClientResponse.HttpClientResponse, Error.HttpClientError>,
) => HttpClient;

makeWith

Added in v1.0.0 Source

Signature

declare const makeWith: <E2, R2, E, R>(
  postprocess: (
    request: Effect.Effect<ClientRequest.HttpClientRequest, E2, R2>,
  ) => Effect.Effect<ClientResponse.HttpClientResponse, E, R>,
  preprocess: HttpClient.Preprocess<E2, R2>,
) => HttpClient.With<E, R>;

Cookies

withCookiesRef

Added in v1.0.0 Source

Associates a Ref of cookies with the client for handling cookies across requests.

Signature

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

Error Handling

catchAll

Added in v1.0.0 Source

Signature

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

catchTag

Added in v1.0.0 Source

Signature

declare const catchTag: {
  <K extends string, E, E1, R1>(
    tag: K,
    f: (
      e: Extract<
        E,
        {
          _tag: K;
        }
      >,
    ) => Effect<HttpClientResponse, E1, R1>,
  ): <R>(self: With<E, R>) => With<
    | E1
    | Exclude<
        E,
        {
          _tag: K;
        }
      >,
    R1 | R
  >;
  <R, E, K extends string, R1, E1>(
    self: With<E, R>,
    tag: K,
    f: (
      e: Extract<
        E,
        {
          _tag: K;
        }
      >,
    ) => Effect<HttpClientResponse, E1, R1>,
  ): With<
    | E1
    | Exclude<
        E,
        {
          _tag: K;
        }
      >,
    R | R1
  >;
};

catchTags

Added in v1.0.0 Source

Signature

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

retry

Added in v1.0.0 Source

Retries the request based on a provided schedule or policy.

Signature

declare const retry: {
  <E, O extends NoExcessProperties<Options<E>, O>>(
    options: O,
  ): <R>(self: With<E, R>) => With<
    O extends {
      schedule: Schedule.Schedule<infer _O, infer _I, infer _R>;
    }
      ? 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 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
  >;
  <B, E, R1>(policy: Schedule<B, NoInfer<E>, R1>): <R>(self: With<E, R>) => With<E, R1 | R>;
  <E, R, O extends NoExcessProperties<Options<E>, O>>(
    self: With<E, R>,
    options: O,
  ): With<
    O extends {
      schedule: Schedule.Schedule<infer _O, infer _I, infer _R>;
    }
      ? 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 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
  >;
  <E, R, B, R1>(self: With<E, R>, policy: Schedule<B, E, R1>): With<E, R | R1>;
};

Retry

Added in v1.0.0 Source

retryTransient

Added in v1.0.0 Source

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

Specifying a while predicate allows you to consider other errors as transient.

Signature

declare const retryTransient: {
  <
    B,
    E,
    R1 = never,
    Mode extends "errors-only" | "response-only" | "both" = never,
    Input = "errors-only" extends Mode
      ? E
      : "response-only" extends Mode
        ? HttpClientResponse
        : HttpClientResponse | E,
  >(
    options:
      | {
          readonly mode?: Mode;
          readonly schedule?: Schedule.Schedule<B, NoInfer<Input>, R1>;
          readonly times?: number;
          readonly while?: Predicate.Predicate<NoInfer<E>>;
        }
      | Schedule<B, NoInfer<Input>, R1, never>,
  ): <R>(self: With<E, R>) => With<E, R1 | R>;
  <
    E,
    R,
    B,
    R1 = never,
    Mode extends "errors-only" | "response-only" | "both" = never,
    Input = "errors-only" extends Mode
      ? E
      : "response-only" extends Mode
        ? HttpClientResponse
        : HttpClientResponse | E,
  >(
    self: With<E, R>,
    options:
      | {
          readonly mode?: Mode;
          readonly schedule?: Schedule.Schedule<B, NoInfer<Input>, R1>;
          readonly times?: number;
          readonly while?: Predicate.Predicate<NoInfer<E>>;
        }
      | Schedule<B, NoInfer<Input>, R1, never>,
  ): With<E, R | R1>;
};

Filters

filterOrElse

Added in v1.0.0 Source

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

Signature

declare const filterOrElse: {
  <E2, R2>(
    predicate: Predicate<HttpClientResponse>,
    orElse: (response: HttpClientResponse) => Effect<HttpClientResponse, E2, R2>,
  ): <E, R>(self: With<E, R>) => With<E2 | E, R2 | R>;
  <E, R, E2, R2>(
    self: With<E, R>,
    predicate: Predicate<HttpClientResponse>,
    orElse: (response: HttpClientResponse) => Effect<HttpClientResponse, E2, R2>,
  ): With<E | E2, R | R2>;
};

filterOrFail

Added in v1.0.0 Source

Filters the result of a response, or throws an error if the predicate fails.

Signature

declare const filterOrFail: {
  <E2>(
    predicate: Predicate<HttpClientResponse>,
    orFailWith: (response: HttpClientResponse) => E2,
  ): <E, R>(self: With<E, R>) => With<E2 | E, R>;
  <E, R, E2>(
    self: With<E, R>,
    predicate: Predicate<HttpClientResponse>,
    orFailWith: (response: HttpClientResponse) => E2,
  ): With<E | E2, R>;
};

filterStatus

Added in v1.0.0 Source

Filters responses by HTTP status code.

Signature

declare const filterStatus: {
  (f: (status: number) => boolean): <E, R>(self: With<E, R>) => With<ResponseError | E, R>;
  <E, R>(self: With<E, R>, f: (status: number) => boolean): With<ResponseError | E, R>;
};

filterStatusOk

Added in v1.0.0 Source

Filters responses that return a 2xx status code.

Signature

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

Mapping & Sequencing

mapRequest

Added in v1.0.0 Source

Appends a transformation of the request object before sending it.

Signature

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

mapRequestEffect

Added in v1.0.0 Source

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

Signature

declare const mapRequestEffect: {
  <E2, R2>(
    f: (a: HttpClientRequest) => Effect<HttpClientRequest, E2, R2>,
  ): <E, R>(self: With<E, R>) => With<E2 | E, R2 | R>;
  <E, R, E2, R2>(
    self: With<E, R>,
    f: (a: HttpClientRequest) => Effect<HttpClientRequest, E2, R2>,
  ): With<E | E2, R | R2>;
};

mapRequestInput

Added in v1.0.0 Source

Prepends a transformation of the request object before sending it.

Signature

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

mapRequestInputEffect

Added in v1.0.0 Source

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

Signature

declare const mapRequestInputEffect: {
  <E2, R2>(
    f: (a: HttpClientRequest) => Effect<HttpClientRequest, E2, R2>,
  ): <E, R>(self: With<E, R>) => With<E2 | E, R2 | R>;
  <E, R, E2, R2>(
    self: With<E, R>,
    f: (a: HttpClientRequest) => Effect<HttpClientRequest, E2, R2>,
  ): With<E | E2, R | R2>;
};

tap

Added in v1.0.0 Source

Performs an additional effect after a successful request.

Signature

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

tapError

Added in v1.0.0 Source

Performs an additional effect after an unsuccessful request.

Signature

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

tapRequest

Added in v1.0.0 Source

Performs an additional effect on the request before sending it.

Signature

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

transform

Added in v1.0.0 Source

Signature

declare const transform: {
  <E, R, E1, R1>(
    f: (
      effect: Effect<HttpClientResponse, E, R>,
      request: HttpClientRequest,
    ) => Effect<HttpClientResponse, E1, R1>,
  ): (self: With<E, R>) => With<E | E1, R | R1>;
  <E, R, E1, R1>(
    self: With<E, R>,
    f: (
      effect: Effect<HttpClientResponse, E, R>,
      request: HttpClientRequest,
    ) => Effect<HttpClientResponse, E1, R1>,
  ): With<E | E1, R | R1>;
};

transformResponse

Added in v1.0.0 Source

Signature

declare const transformResponse: {
  <E, R, E1, R1>(
    f: (effect: Effect<HttpClientResponse, E, R>) => Effect<HttpClientResponse, E1, R1>,
  ): (self: With<E, R>) => With<E1, R1>;
  <E, R, E1, R1>(
    self: With<E, R>,
    f: (effect: Effect<HttpClientResponse, E, R>) => Effect<HttpClientResponse, E1, R1>,
  ): With<E1, R1>;
};

Models

HttpClient interface

Added in v1.0.0 Source

Signature

interface HttpClient extends With<Error.HttpClientError> {}

Other

HttpClient

Added in v1.0.0 Source

layerMergedContext

Added in v1.0.0 Source

Signature

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

Redirects

followRedirects

Added in v1.0.0 Source

Follows HTTP redirects up to a specified number of times.

Signature

declare const followRedirects: {
  (maxRedirects?: number): <E, R>(self: With<E, R>) => With<E, R>;
  <E, R>(self: With<E, R>, maxRedirects?: number): With<E, R>;
};

Scope

withScope

Added in v1.0.0 Source

Ties the lifetime of the HttpClientRequest to a Scope.

Signature

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

Tags

HttpClient

Added in v1.0.0 Source

Signature

declare const HttpClient: Tag<HttpClient, HttpClient>;

Tracing

currentTracerDisabledWhen

Added in v1.0.0 Source

Signature

declare const currentTracerDisabledWhen: FiberRef.FiberRef<
  Predicate.Predicate<ClientRequest.HttpClientRequest>
>;

currentTracerPropagation

Added in v1.0.0 Source

Signature

declare const currentTracerPropagation: FiberRef.FiberRef<boolean>;

SpanNameGenerator

Added in v1.0.0 Source

Signature

declare const SpanNameGenerator: any;

SpanNameGenerator interface

Added in v1.0.0 Source

Signature

interface SpanNameGenerator {
  readonly _: typeof _;
}

withSpanNameGenerator

Added in v1.0.0 Source

Customizes the span names for tracing.

Signature

declare const withSpanNameGenerator: {
  (f: (request: HttpClientRequest) => string): <E, R>(self: With<E, R>) => With<E, R>;
  <E, R>(self: With<E, R>, f: (request: HttpClientRequest) => string): With<E, R>;
};

Example

import { FetchHttpClient, HttpClient } from "@effect/platform"
import { NodeRuntime } from "@effect/platform-node"
import { Effect } from "effect"

Effect.gen(function* () {
  const client = (yield* HttpClient.HttpClient).pipe(
    // Customize the span names for this HttpClient
    HttpClient.withSpanNameGenerator((request) => `http.client ${request.method} ${request.url}`),
  )

  yield* client.get("https://jsonplaceholder.typicode.com/posts/1")
}).pipe(Effect.provide(FetchHttpClient.layer), NodeRuntime.runMain)

withTracerDisabledWhen

Added in v1.0.0 Source

Disables tracing for specific requests based on a provided predicate.

Signature

declare const withTracerDisabledWhen: {
  (predicate: Predicate<HttpClientRequest>): <E, R>(self: With<E, R>) => With<E, R>;
  <E, R>(self: With<E, R>, predicate: Predicate<HttpClientRequest>): With<E, R>;
};

withTracerPropagation

Added in v1.0.0 Source

Enables or disables tracing propagation for the request.

Signature

declare const withTracerPropagation: {
  (enabled: boolean): <E, R>(self: With<E, R>) => With<E, R>;
  <E, R>(self: With<E, R>, enabled: boolean): With<E, R>;
};

Type Ids

TypeId

Added in v1.0.0 Source

Signature

declare const TypeId: unique symbol;

TypeId type

Added in v1.0.0 Source

Signature

type TypeId = typeof TypeId;