Skip to content

HttpClientResponse

Represents responses returned by the Effect HTTP client.

An HttpClientResponse keeps the original request together with the response status, headers, cookies, and body accessors from the shared incoming-message model. This module includes constructors, schema-based decoders, helpers for streaming response bodies, and utilities for matching or filtering by HTTP status.

12 exports Added in v4.0.0 Source

Accessors

stream

Added in v4.0.0 Source

Converts an effect producing an HttpClientResponse into a stream of response body bytes.

Signature

declare function stream<E, R>(
  effect: Effect<HttpClientResponse, E, R>,
): Stream<Uint8Array<ArrayBufferLike>, HttpClientError | E, R>;

Constructors

fromWeb

Added in v4.0.0 Source

Wraps a Web Response and its original HttpClientRequest as an HttpClientResponse.

Signature

declare function fromWeb(request: HttpClientRequest, source: Response): HttpClientResponse;

Filtering

filterStatus

Added in v4.0.0 Source

Succeeds with the response when its status satisfies the predicate, otherwise fails with HttpClientError.

Signature

declare const filterStatus: {
  (
    f: (status: number) => boolean,
  ): (self: HttpClientResponse) => Effect<HttpClientResponse, HttpClientError>;
  (
    self: HttpClientResponse,
    f: (status: number) => boolean,
  ): Effect<HttpClientResponse, HttpClientError>;
};

filterStatusOk

Added in v4.0.0 Source

Succeeds with the response only when its status is in the 2xx range, otherwise fails with HttpClientError.

Signature

declare function filterStatusOk(
  self: HttpClientResponse,
): Effect<HttpClientResponse, HttpClientError>;

Models

HttpClientResponse interface

Added in v4.0.0 Source

Model of an HTTP client response, including the original request, status, cookies, headers, and body accessors.

Signature

interface HttpClientResponse extends HttpIncomingMessage<Error.HttpClientError>, Pipeable {
  readonly "~effect/http/HttpClientResponse": "~effect/http/HttpClientResponse";
  readonly cookies: Cookies;
  readonly formData: Effect<FormData, HttpClientError>;
  readonly request: HttpClientRequest;
  readonly status: number;
}

Pattern Matching

matchStatus

Added in v4.0.0 Source

Pattern matches on a response status, checking exact status handlers before status-class handlers and orElse.

Signature

declare const matchStatus: {
  <
    Cases extends {
      [status: number]: (_: HttpClientResponse) => any;
      readonly "2xx"?: (_: HttpClientResponse) => any;
      readonly "3xx"?: (_: HttpClientResponse) => any;
      readonly "4xx"?: (_: HttpClientResponse) => any;
      readonly "5xx"?: (_: HttpClientResponse) => any;
      readonly orElse: (_: HttpClientResponse) => any;
    },
  >(
    cases: Cases,
  ): (self: HttpClientResponse) => Cases[keyof Cases] extends (_: any) => R ? Unify<R> : never;
  <
    Cases extends {
      [status: number]: (_: HttpClientResponse) => any;
      readonly "2xx"?: (_: HttpClientResponse) => any;
      readonly "3xx"?: (_: HttpClientResponse) => any;
      readonly "4xx"?: (_: HttpClientResponse) => any;
      readonly "5xx"?: (_: HttpClientResponse) => any;
      readonly orElse: (_: HttpClientResponse) => any;
    },
  >(
    self: HttpClientResponse,
    cases: Cases,
  ): Cases[keyof Cases] extends (_: any) => R ? Unify<R> : never;
};

Schemas

schemaBodyJson

Added in v4.0.0 Source

Creates a decoder that reads an incoming message's JSON body and decodes it with the supplied schema.

Signature

declare function schemaBodyJson<S extends Constraint>(
  schema: S,
  options?: ParseOptions,
): <E>(self: HttpIncomingMessage<E>) => Effect<S["Type"], SchemaError | E, S["DecodingServices"]>;

schemaBodyUrlParams

Added in v4.0.0 Source

Creates a decoder that reads an incoming message's URL-encoded body parameters and decodes them with the supplied schema.

Signature

declare function schemaBodyUrlParams<A, I extends Readonly<Record<string, string | readonly Array<string> | undefined>>, RD>(schema: ConstraintCodec<A, I, RD, unknown>, options?: ParseOptions): <E>(self: HttpIncomingMessage<E>) => Effect<A, SchemaError | E, RD>

schemaHeaders

Added in v4.0.0 Source

Creates a decoder that validates and decodes an incoming message's headers with the supplied schema.

Signature

declare function schemaHeaders<A, I extends Readonly<Record<string, string | undefined>>, RD>(
  schema: ConstraintCodec<A, I, RD, unknown>,
  options?: ParseOptions,
): <E>(self: HttpIncomingMessage<E>) => Effect<A, SchemaError, RD>;

schemaJson

Added in v4.0.0 Source

Creates a decoder for a response's status, headers, and JSON body using the supplied schema.

Signature

declare function schemaJson<
  A,
  I extends {
    readonly body?: unknown;
    readonly headers?: Readonly<Record<string, string | undefined>>;
    readonly status?: number;
  },
  RD,
>(
  schema: ConstraintCodec<A, I, RD, unknown>,
  options?: ParseOptions,
): (self: HttpClientResponse) => Effect<A, SchemaError | HttpClientError, RD>;

schemaNoBody

Added in v4.0.0 Source

Creates a decoder for a response's status and headers without reading a response body.

Signature

declare function schemaNoBody<
  A,
  I extends {
    readonly headers?: Readonly<Record<string, string>>;
    readonly status?: number;
  },
  RD,
  RE,
>(
  schema: Codec<A, I, RD, RE>,
  options?: ParseOptions,
): (self: HttpClientResponse) => Effect<A, SchemaError, RD>;

Type IDs

TypeId

Added in v4.0.0 Source

Type identifier for HttpClientResponse values.

Signature

declare const TypeId: "~effect/http/HttpClientResponse";