HttpApiClient unstable

Builds HTTP clients from HttpApi declarations.

The client methods are derived from the groups and endpoints in an HttpApi and run through an HttpClient. They use the same schema-driven contract as the server: request parts are encoded from endpoint schemas, client middleware is applied, the HTTP request is executed, and declared success or error responses are decoded. This module also includes helpers for building a client for only one group, one endpoint, or only the encoded URL.

10 exports Since v4.0.0 Source

Constructors

endpoint

unstable

Since v4.0.0

Builds the typed client method for one endpoint in one API group, using the supplied HttpClient and endpoint metadata.

Signature

declare function endpoint<ApiId extends string, Groups extends Constraint, GroupIdentifier extends string, EndpointIdentifier extends string, E, R>(api: HttpApi<ApiId, Groups>, options: {
  readonly baseUrl?: string | URL;
  readonly endpoint: EndpointIdentifier;
  readonly group: GroupIdentifier;
  readonly httpClient: With<E, R>;
  readonly transformClient?: (client: With<E, R>) => With<E, R>;
  readonly transformResponse?: (effect: Effect<unknown, unknown, unknown>) => Effect<unknown, unknown, unknown>;
}): EndpointReturn<Groups, GroupIdentifier, EndpointIdentifier, E, R>

group

unstable

Since v4.0.0

Builds a typed client object for a single API group from the supplied HttpClient, filtering the API to that group.

Signature

declare function group<ApiId extends string, Groups extends Constraint, GroupIdentifier extends string, E, R>(api: HttpApi<ApiId, Groups>, options: {
  readonly baseUrl?: string | URL;
  readonly group: GroupIdentifier;
  readonly httpClient: With<E, R>;
  readonly transformResponse?: (effect: Effect<unknown, unknown, unknown>) => Effect<unknown, unknown, unknown>;
}): Effect<GroupByEndpoint<Extract<Groups, {
  readonly identifier: GroupIdentifier;
}>, E, R>, never, MiddlewareClient<Middleware<Endpoints<Extract<Groups, {
  readonly identifier: GroupIdentifier;
}>>>>>

make

unstable

Since v4.0.0

Constructs a type-safe client for an HTTP API using the HttpClient service, endpoint schemas, middleware, and optional client or response transformations.

Signature

declare function make<ApiId extends string, Groups extends Constraint>(api: HttpApi<ApiId, Groups>, options?: {
  readonly baseUrl?: string | URL;
  readonly transformClient?: (client: HttpClient) => HttpClient;
  readonly transformResponse?: (effect: Effect<unknown, unknown, unknown>) => Effect<unknown, unknown, unknown>;
}): Effect<Simplify<{ [Group in {
  readonly topLevel: false;
} & Constraint]: GroupByEndpoint<Group, never, never> } & TopLevelMethods<Groups, never, never>>, never, HttpClient | MiddlewareClient<Middleware<Endpoints<Groups>>>>

makeWith

unstable

Since v4.0.0

Constructs a type-safe client for an HTTP API from the supplied HttpClient, using the API metadata to encode requests, execute middleware, and decode responses.

Signature

declare function makeWith<ApiId extends string, Groups extends Constraint, E, R>(api: HttpApi<ApiId, Groups>, options: {
  readonly baseUrl?: string | URL;
  readonly httpClient: With<E, R>;
  readonly transformResponse?: (effect: Effect<unknown, unknown, unknown>) => Effect<unknown, unknown, unknown>;
}): Effect<Simplify<{ [Group in {
  readonly topLevel: false;
} & Constraint]: GroupByEndpoint<Group, Exclude<E, HttpClientError>, R> } & TopLevelMethods<Groups, Exclude<E, HttpClientError>, R>>, never, MiddlewareClient<Middleware<Endpoints<Groups>>>>

urlBuilder

unstable

Since v4.0.0

Creates a type-safe URL builder that mirrors HttpApiClient.make.

Signature

declare function urlBuilder<Api extends Constraint>(api: Api, options?: {
  readonly baseUrl?: string | URL;
}): UrlBuilder<Api>

Example Building typed URLs

import { Schema } from "effect"
import { HttpApi, HttpApiClient, HttpApiEndpoint, HttpApiGroup } from "effect/http-api"

const Api = HttpApi.make("Api").add(
  HttpApiGroup.make("users").add(
    HttpApiEndpoint.get("getUser", "/users/:id", {
      params: { id: Schema.String }
    })
  )
)

const buildUrl = HttpApiClient.urlBuilder(Api, {
  baseUrl: "https://api.example.com"
})

buildUrl.users.getUser({
  params: { id: "123" }
}) // => "https://api.example.com/users/123"

Models

Client

type unstable

Since v4.0.0

The type-safe client shape generated from HTTP API groups, with non-top-level groups exposed as nested objects and top-level endpoints exposed as methods.

Signature

type Client<Groups extends HttpApiGroup.Constraint, E = never, R = never> = Simplify<{ [Group in Extract<Groups, {
  readonly topLevel: false;
}>]: Client.Group<Group, E, R> } & Client.TopLevelMethods<Groups, E, R>>

UrlBuilder

type unstable

Since v4.0.0

The type-safe URL builder shape for an HTTP API, mirroring the generated client layout while returning URL strings instead of executing requests.

Signature

type UrlBuilder<Api extends HttpApi.Constraint> = Api extends HttpApi.HttpApi<infer _ApiId, infer Groups> ? [Extract<Groups, {
  readonly topLevel: true;
}>] extends [never] ? UrlBuilderGroups<Groups> : [Extract<Groups, {
  readonly topLevel: false;
}>] extends [never] ? UrlBuilderTopLevelMethods<Groups> : Simplify<UrlBuilderGroups<Groups> & UrlBuilderTopLevelMethods<Groups>> : never

Other

Client

unstable

Since v4.0.0

Helper types used to describe generated HTTP API clients, including endpoint methods, response modes, and grouped client shapes.

Utility Types

ForApi

type unstable

Since v4.0.0

Derives the typed client interface for an HttpApi, preserving any additional client error and service requirements supplied by the caller.

Signature

type ForApi<Api extends HttpApi.Constraint, E = never, R = never> = Api extends HttpApi.HttpApi<infer _Id, infer Groups> ? Client<Groups, E, R> : never

SuccessType

type unstable

Since v4.0.0

Computes the decoded success value a client receives for an endpoint success schema, including headers, streaming Server-Sent Events, and streaming byte responses.

Signature

type SuccessType<S> = S extends HttpApiSchema.WithHeaders<infer _Inner, infer _Headers> ? HttpApiSchema.withHeaders<SuccessType<_Inner>, _Headers["Type"]> : S extends HttpApiSchema.StreamSse<infer _Events, infer _Error, infer _Value> ? Stream.Stream<_Value, _Error["Type"] | HttpClientError.HttpClientError | Schema.SchemaError | Sse.Retry | Sse.SseError, never> : S extends HttpApiSchema.StreamUint8Array ? Stream.Stream<Uint8Array, HttpClientError.HttpClientError, never> : S extends Schema.Constraint ? S["Type"] : never