HttpClientResponse unstable

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.

13 exports Since v4.0.0 Source

Accessors

stream

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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

Signature

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

Converting

toWeb

unstable

Since v4.0.0

Returns the original Web Response of a fetch-backed HttpClientResponse.

When to use

Use to hand a response body to a Web API without copying it, such as writing a fetched file to Cloudflare R2. The original body keeps runtime capabilities, such as workerd's known length, that a stream converted from stream does not.

Details

Returns Some for responses created with fromWeb, which includes every response from FetchHttpClient, and None for other backends.

Calling toWeb hands the body over: the response is no longer aborted when the HttpClientResponse is garbage collected, so read or cancel the body through the returned Response.

Gotchas

The body can be read once. After converting, read it from the returned Response, not from the HttpClientResponse.

After the hand-off, Effect aborts the request only when the scope of HttpClient.withScope closes. When the request streams its body, finishing or cancelling the returned body does not stop the upload; execute the request with HttpClient.withScope and close the scope to stop it.

Signature

declare function toWeb(self: HttpClientResponse): Option<Response>

Filtering

filterStatus

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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 unstable

Since v4.0.0

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;
  readonly upgrade: Effect<Socket, HttpClientError>;
  readonly url: string;
}

Pattern Matching

matchStatus

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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 & JsonOptions): <E>(self: HttpIncomingMessage<E>) => Effect<S["Type"], SchemaError | E, S["DecodingServices"]>

schemaBodyUrlParams

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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 & JsonOptions): (self: HttpClientResponse) => Effect<A, SchemaError | HttpClientError, RD>

schemaNoBody

unstable

Since v4.0.0

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

unstable

Since v4.0.0

Type identifier for HttpClientResponse values.

Signature

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