Skip to content

HttpApiClient

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.

9 exports Added in v4.0.0 Source

Constructors

endpoint

Added in v4.0.0 Source

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

Added in v4.0.0 Source

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

Added in v4.0.0 Source

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

Added in v4.0.0 Source

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

Added in v4.0.0 Source

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

Models

Client type

Added in v4.0.0 Source

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

Added in v4.0.0 Source

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

Added in v4.0.0 Source

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

Utility Types

ForApi type

Added in v4.0.0 Source

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;