HttpApiClient.ts

HttpApiClient.ts overview

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.

Since v4.0.0

---

Exports Grouped by Category

• constructors
  • endpoint
  • group
  • make
  • makeWith
  • urlBuilder
• models
  • Client (type alias)
  • ForApi (type alias)
  • UrlBuilder (type alias)
• utils
  • Client (namespace)
    • ResponseMode (type alias)
    • Response (type alias)
    • Group (type alias)
    • Method (type alias)
    • TopLevelMethods (type alias)

---

constructors

endpoint

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

Signature

declare const endpoint: <
  ApiId extends string,
  Groups extends HttpApiGroup.Constraint,
  const GroupIdentifier extends HttpApiGroup.Identifier<Groups>,
  const EndpointIdentifier extends HttpApiGroup.EndpointsWithIdentifier<Groups, GroupIdentifier>["identifier"],
  E,
  R
>(
  api: HttpApi.HttpApi<ApiId, Groups>,
  options: {
    readonly group: GroupIdentifier
    readonly endpoint: EndpointIdentifier
    readonly httpClient: HttpClient.HttpClient.With<E, R>
    readonly transformClient?:
      | ((client: HttpClient.HttpClient.With<E, R>) => HttpClient.HttpClient.With<E, R>)
      | undefined
    readonly transformResponse?:
      | ((effect: Effect.Effect<unknown, unknown, unknown>) => Effect.Effect<unknown, unknown, unknown>)
      | undefined
    readonly baseUrl?: URL | string | undefined
  }
) => EndpointReturn<Groups, GroupIdentifier, EndpointIdentifier, E, R>

Source

Since v4.0.0

group

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

Signature

declare const group: <
  ApiId extends string,
  Groups extends HttpApiGroup.Constraint,
  const GroupIdentifier extends HttpApiGroup.Identifier<Groups>,
  E,
  R
>(
  api: HttpApi.HttpApi<ApiId, Groups>,
  options: {
    readonly group: GroupIdentifier
    readonly httpClient: HttpClient.HttpClient.With<E, R>
    readonly transformResponse?:
      | ((effect: Effect.Effect<unknown, unknown, unknown>) => Effect.Effect<unknown, unknown, unknown>)
      | undefined
    readonly baseUrl?: URL | string | undefined
  }
) => Effect.Effect<
  Client.Group<HttpApiGroup.WithIdentifier<Groups, GroupIdentifier>, E, R>,
  never,
  HttpApiGroup.MiddlewareClient<HttpApiGroup.WithIdentifier<Groups, GroupIdentifier>>
>

Source

Since v4.0.0

make

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

Signature

declare const make: <ApiId extends string, Groups extends HttpApiGroup.Constraint>(
  api: HttpApi.HttpApi<ApiId, Groups>,
  options?: {
    readonly transformClient?: ((client: HttpClient.HttpClient) => HttpClient.HttpClient) | undefined
    readonly transformResponse?:
      | ((effect: Effect.Effect<unknown, unknown, unknown>) => Effect.Effect<unknown, unknown, unknown>)
      | undefined
    readonly baseUrl?: URL | string | undefined
  }
) => Effect.Effect<Client<Groups>, never, HttpClient.HttpClient | HttpApiGroup.MiddlewareClient<Groups>>

Source

Since v4.0.0

makeWith

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 const makeWith: <ApiId extends string, Groups extends HttpApiGroup.Constraint, E, R>(
  api: HttpApi.HttpApi<ApiId, Groups>,
  options: {
    readonly httpClient: HttpClient.HttpClient.With<E, R>
    readonly transformResponse?:
      | ((effect: Effect.Effect<unknown, unknown, unknown>) => Effect.Effect<unknown, unknown, unknown>)
      | undefined
    readonly baseUrl?: URL | string | undefined
  }
) => Effect.Effect<
  Client<Groups, Exclude<E, HttpClientError.HttpClientError>, R>,
  never,
  HttpApiGroup.MiddlewareClient<Groups>
>

Source

Since v4.0.0

urlBuilder

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

Example (Building typed URLs)

import { Schema } from "effect"
import { HttpApi, HttpApiClient, HttpApiEndpoint, HttpApiGroup } from "effect/unstable/httpapi"

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"

Signature

declare const urlBuilder: <Api extends HttpApi.Constraint>(
  api: Api,
  options?: { readonly baseUrl?: URL | string | undefined }
) => UrlBuilder<Api>

Source

Since v4.0.0

models

Client (type alias)

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, E, R> = Simplify<
  {
    readonly [Group in Extract<Groups, { readonly topLevel: false }> as HttpApiGroup.Identifier<Group>]: Client.Group<
      Group,
      E,
      R
    >
  } & Client.TopLevelMethods<Groups, E, R>
>

Source

Since v4.0.0

ForApi (type alias)

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

Signature

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

Source

Since v4.0.0

UrlBuilder (type alias)

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> =
  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

Source

Since v4.0.0

utils

Client (namespace)

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

Source

Since v4.0.0

ResponseMode (type alias)

The response mode accepted by generated client methods, controlling whether a call returns the decoded success value, the raw response, or both.

Signature

type ResponseMode = HttpApiEndpoint.ClientResponseMode

Source

Since v4.0.0

Response (type alias)

Computes the value returned by a client method for a success type and response mode.

Signature

type Response<Success, Mode> = [Mode] extends ["decoded-and-response"]
  ? [Success, HttpClientResponse.HttpClientResponse]
  : [Mode] extends ["response-only"]
    ? HttpClientResponse.HttpClientResponse
    : Success

Source

Since v4.0.0

Group (type alias)

The client object for one API group, mapping each endpoint identifier in that group to its typed client method.

Signature

type Client.Group<Group, E, R> = GroupByEndpoint<Group, E, R>

Source

Since v4.0.0

Method (type alias)

The typed function generated for an endpoint, accepting the endpoint request shape and returning an effect whose success, error, and service channels reflect the endpoint schemas, middleware, and selected response mode.

Signature

type Method<Endpoint, E, R> = <Mode extends ResponseMode = ResponseMode>(
  request: Simplify<
    HttpApiEndpoint.ClientRequest<
      Endpoint["~Params"],
      Endpoint["~Query"],
      Endpoint["~Payload"],
      Endpoint["~Headers"],
      Mode
    >
  >
) => MethodReturn<Endpoint, E, R, Mode>

Source

Since v4.0.0

TopLevelMethods (type alias)

Extracts client methods for endpoints in top-level groups so they can be exposed directly on the generated client object.

Signature

type TopLevelMethods<Groups, E, R> = {
  readonly [Endpoint in Extract<
    HttpApiGroup.Endpoints<Extract<Groups, { readonly topLevel: true }>>,
    HttpApiEndpoint.ConstraintRequest
  > as Endpoint["identifier"]]: Method<Endpoint, E, R>
}

Source

Since v4.0.0