Skip to content

HttpApiEndpoint

Defines endpoint declarations used inside an HTTP API group.

An endpoint records a stable identifier, HTTP method, router path, request schemas, response schemas, declared errors, middleware, and annotations. Endpoint values are declarations, not handlers: builders use them to decode requests, type handler input, encode responses, generate OpenAPI metadata, and derive generated-client call signatures. This module also includes HTTP method constructors, payload and response schema helpers, and type utilities used by builders and generated clients.

57 exports Added in v4.0.0 Source

Constructors

get

Added in v4.0.0 Source

Creates a GET endpoint declaration.

Signature

declare const get: {
  <Identifier extends string, Path extends PathInput, Params extends Top | Fields = never, Query extends Top | Fields = never, Payload extends Record<string, Top> = never, Headers extends Top | Fields = never, Success extends SuccessConstraint = NoContent, Error extends Top | readonly Array<Top> = never>(identifier: Identifier, path: Path, options?: {
    readonly disableCodecs?: false;
    readonly error?: Error & ErrorNoStream<NoInfer<Error>>;
    readonly headers?: Headers;
    readonly params?: Params;
    readonly payload?: Payload;
    readonly query?: Query;
    readonly success?: Success;
  }): HttpApiEndpoint<Identifier, "GET", Path, ToStringTreeCodec<Params>, ToStringTreeCodec<Query>, ToStringTreeCodec<ToSchema<Payload>>, ToStringTreeCodec<Headers>, ToSuccessCodec<Success>, ToJsonCodec<Error extends readonly Array<Constraint> ? Error[number] : Error>>;
  <Identifier extends string, Path extends PathInput, Params extends ParamsConstraint = never, Query extends QueryConstraint = never, Payload extends Record<string, Encoder<string | readonly Array<string> | undefined, unknown>> = never, Headers extends HeadersConstraint = never, Success extends SuccessConstraint = NoContent, Error extends ErrorConstraint = never>(identifier: Identifier, path: Path, options?: {
    readonly disableCodecs: true;
    readonly error?: Error & ErrorNoStream<NoInfer<Error>>;
    readonly headers?: Headers;
    readonly params?: Params;
    readonly payload?: Payload;
    readonly query?: Query;
    readonly success?: Success;
  }): HttpApiEndpoint<Identifier, "GET", Path, Params extends Fields ? Struct<Params> : Params, Query extends Fields ? Struct<Query> : Query, ToSchema<Payload>, ToSchema<Headers>, UnwrapReadonlyArray<Success>, Error extends readonly Array<Constraint> ? Error[number] : Error>;
}

make

Added in v4.0.0 Source

Creates endpoint constructors for a specific HTTP method. The resulting constructor builds an HttpApiEndpoint from an identifier, path, and optional request and response schemas, applying automatic JSON or string-tree codecs unless disableCodecs is enabled.

Signature

declare function make<Method extends HttpMethod>(method: Method): {
  <Identifier extends string, Path extends PathInput, Params extends Top | Fields = never, Query extends Top | Fields = never, Payload extends Top | readonly Array<Top> | Record<string, Top> = never, Headers extends Top | Fields = never, Success extends SuccessConstraint = NoContent, Error extends Top | readonly Array<Top> = never>(identifier: Identifier, path: Path, options?: {
    readonly disableCodecs?: false;
    readonly error?: Error & ErrorNoStream<NoInfer<Error>>;
    readonly headers?: Headers;
    readonly params?: Params;
    readonly payload?: Payload;
    readonly query?: Query;
    readonly success?: Success;
  }): HttpApiEndpoint<Identifier, Method, Path, ToStringTreeCodec<Params>, ToStringTreeCodec<Query>, Method extends WithBody ? ToJsonCodec<ToSchema<Payload>> : ToStringTreeCodec<ToSchema<Payload>>, ToStringTreeCodec<Headers>, ToSuccessCodec<Success>, ToJsonCodec<Error extends readonly Array<Constraint> ? Error[number] : Error>>;
  <Identifier extends string, Path extends PathInput, Params extends ParamsConstraint = never, Query extends QueryConstraint = never, Payload extends Top | readonly Array<Top> | Record<string, Encoder<string | readonly Array<string> | undefined, unknown>> = never, Headers extends HeadersConstraint = never, Success extends SuccessConstraint = NoContent, Error extends ErrorConstraint = never>(identifier: Identifier, path: Path, options?: {
    readonly disableCodecs: true;
    readonly error?: Error & ErrorNoStream<NoInfer<Error>>;
    readonly headers?: Headers;
    readonly params?: Params;
    readonly payload?: Payload;
    readonly query?: Query;
    readonly success?: Success;
  }): HttpApiEndpoint<Identifier, Method, Path, Params extends Fields ? Struct<Params> : Params, Query extends Fields ? Struct<Query> : Query, ToSchema<Payload>, ToSchema<Headers>, UnwrapReadonlyArray<Success>, Error extends readonly Array<Constraint> ? Error[number] : Error>;
}

options

Added in v4.0.0 Source

Creates an OPTIONS endpoint declaration.

Signature

declare const options: {
  <Identifier extends string, Path extends PathInput, Params extends Top | Fields = never, Query extends Top | Fields = never, Payload extends Record<string, Top> = never, Headers extends Top | Fields = never, Success extends SuccessConstraint = NoContent, Error extends Top | readonly Array<Top> = never>(identifier: Identifier, path: Path, options?: {
    readonly disableCodecs?: false;
    readonly error?: Error & ErrorNoStream<NoInfer<Error>>;
    readonly headers?: Headers;
    readonly params?: Params;
    readonly payload?: Payload;
    readonly query?: Query;
    readonly success?: Success;
  }): HttpApiEndpoint<Identifier, "OPTIONS", Path, ToStringTreeCodec<Params>, ToStringTreeCodec<Query>, ToStringTreeCodec<ToSchema<Payload>>, ToStringTreeCodec<Headers>, ToSuccessCodec<Success>, ToJsonCodec<Error extends readonly Array<Constraint> ? Error[number] : Error>>;
  <Identifier extends string, Path extends PathInput, Params extends ParamsConstraint = never, Query extends QueryConstraint = never, Payload extends Record<string, Encoder<string | readonly Array<string> | undefined, unknown>> = never, Headers extends HeadersConstraint = never, Success extends SuccessConstraint = NoContent, Error extends ErrorConstraint = never>(identifier: Identifier, path: Path, options?: {
    readonly disableCodecs: true;
    readonly error?: Error & ErrorNoStream<NoInfer<Error>>;
    readonly headers?: Headers;
    readonly params?: Params;
    readonly payload?: Payload;
    readonly query?: Query;
    readonly success?: Success;
  }): HttpApiEndpoint<Identifier, "OPTIONS", Path, Params extends Fields ? Struct<Params> : Params, Query extends Fields ? Struct<Query> : Query, ToSchema<Payload>, ToSchema<Headers>, UnwrapReadonlyArray<Success>, Error extends readonly Array<Constraint> ? Error[number] : Error>;
}

patch

Added in v4.0.0 Source

Creates a PATCH endpoint declaration.

Signature

declare const patch: {
  <Identifier extends string, Path extends PathInput, Params extends Top | Fields = never, Query extends Top | Fields = never, Payload extends Top | readonly Array<Top> = never, Headers extends Top | Fields = never, Success extends SuccessConstraint = NoContent, Error extends Top | readonly Array<Top> = never>(identifier: Identifier, path: Path, options?: {
    readonly disableCodecs?: false;
    readonly error?: Error & ErrorNoStream<NoInfer<Error>>;
    readonly headers?: Headers;
    readonly params?: Params;
    readonly payload?: Payload;
    readonly query?: Query;
    readonly success?: Success;
  }): HttpApiEndpoint<Identifier, "PATCH", Path, ToStringTreeCodec<Params>, ToStringTreeCodec<Query>, ToJsonCodec<ToSchema<Payload>>, ToStringTreeCodec<Headers>, ToSuccessCodec<Success>, ToJsonCodec<Error extends readonly Array<Constraint> ? Error[number] : Error>>;
  <Identifier extends string, Path extends PathInput, Params extends ParamsConstraint = never, Query extends QueryConstraint = never, Payload extends Top | readonly Array<Top> = never, Headers extends HeadersConstraint = never, Success extends SuccessConstraint = NoContent, Error extends ErrorConstraint = never>(identifier: Identifier, path: Path, options?: {
    readonly disableCodecs: true;
    readonly error?: Error & ErrorNoStream<NoInfer<Error>>;
    readonly headers?: Headers;
    readonly params?: Params;
    readonly payload?: Payload;
    readonly query?: Query;
    readonly success?: Success;
  }): HttpApiEndpoint<Identifier, "PATCH", Path, Params extends Fields ? Struct<Params> : Params, Query extends Fields ? Struct<Query> : Query, ToSchema<Payload>, ToSchema<Headers>, UnwrapReadonlyArray<Success>, Error extends readonly Array<Constraint> ? Error[number] : Error>;
}

post

Added in v4.0.0 Source

Creates a POST endpoint declaration.

Signature

declare const post: {
  <Identifier extends string, Path extends PathInput, Params extends Top | Fields = never, Query extends Top | Fields = never, Payload extends Top | readonly Array<Top> = never, Headers extends Top | Fields = never, Success extends SuccessConstraint = NoContent, Error extends Top | readonly Array<Top> = never>(identifier: Identifier, path: Path, options?: {
    readonly disableCodecs?: false;
    readonly error?: Error & ErrorNoStream<NoInfer<Error>>;
    readonly headers?: Headers;
    readonly params?: Params;
    readonly payload?: Payload;
    readonly query?: Query;
    readonly success?: Success;
  }): HttpApiEndpoint<Identifier, "POST", Path, ToStringTreeCodec<Params>, ToStringTreeCodec<Query>, ToJsonCodec<ToSchema<Payload>>, ToStringTreeCodec<Headers>, ToSuccessCodec<Success>, ToJsonCodec<Error extends readonly Array<Constraint> ? Error[number] : Error>>;
  <Identifier extends string, Path extends PathInput, Params extends ParamsConstraint = never, Query extends QueryConstraint = never, Payload extends Top | readonly Array<Top> = never, Headers extends HeadersConstraint = never, Success extends SuccessConstraint = NoContent, Error extends ErrorConstraint = never>(identifier: Identifier, path: Path, options?: {
    readonly disableCodecs: true;
    readonly error?: Error & ErrorNoStream<NoInfer<Error>>;
    readonly headers?: Headers;
    readonly params?: Params;
    readonly payload?: Payload;
    readonly query?: Query;
    readonly success?: Success;
  }): HttpApiEndpoint<Identifier, "POST", Path, Params extends Fields ? Struct<Params> : Params, Query extends Fields ? Struct<Query> : Query, ToSchema<Payload>, ToSchema<Headers>, UnwrapReadonlyArray<Success>, Error extends readonly Array<Constraint> ? Error[number] : Error>;
}

put

Added in v4.0.0 Source

Creates a PUT endpoint declaration.

Signature

declare const put: {
  <Identifier extends string, Path extends PathInput, Params extends Top | Fields = never, Query extends Top | Fields = never, Payload extends Top | readonly Array<Top> = never, Headers extends Top | Fields = never, Success extends SuccessConstraint = NoContent, Error extends Top | readonly Array<Top> = never>(identifier: Identifier, path: Path, options?: {
    readonly disableCodecs?: false;
    readonly error?: Error & ErrorNoStream<NoInfer<Error>>;
    readonly headers?: Headers;
    readonly params?: Params;
    readonly payload?: Payload;
    readonly query?: Query;
    readonly success?: Success;
  }): HttpApiEndpoint<Identifier, "PUT", Path, ToStringTreeCodec<Params>, ToStringTreeCodec<Query>, ToJsonCodec<ToSchema<Payload>>, ToStringTreeCodec<Headers>, ToSuccessCodec<Success>, ToJsonCodec<Error extends readonly Array<Constraint> ? Error[number] : Error>>;
  <Identifier extends string, Path extends PathInput, Params extends ParamsConstraint = never, Query extends QueryConstraint = never, Payload extends Top | readonly Array<Top> = never, Headers extends HeadersConstraint = never, Success extends SuccessConstraint = NoContent, Error extends ErrorConstraint = never>(identifier: Identifier, path: Path, options?: {
    readonly disableCodecs: true;
    readonly error?: Error & ErrorNoStream<NoInfer<Error>>;
    readonly headers?: Headers;
    readonly params?: Params;
    readonly payload?: Payload;
    readonly query?: Query;
    readonly success?: Success;
  }): HttpApiEndpoint<Identifier, "PUT", Path, Params extends Fields ? Struct<Params> : Params, Query extends Fields ? Struct<Query> : Query, ToSchema<Payload>, ToSchema<Headers>, UnwrapReadonlyArray<Success>, Error extends readonly Array<Constraint> ? Error[number] : Error>;
}

Guards

isHttpApiEndpoint

Added in v4.0.0 Source

Returns true when a value is an HttpApiEndpoint, narrowing the value to the endpoint interface.

Signature

declare function isHttpApiEndpoint(u: unknown): u is Top;

Models

ClientResponseMode type

Added in v4.0.0 Source

Controls what a generated client method returns: the decoded success value, the decoded value paired with the raw response, or only the raw response.

Signature

type ClientResponseMode = "decoded-only" | "decoded-and-response" | "response-only";

Constraint interface

Added in v4.0.0 Source

A widened HttpApiEndpoint type used when the concrete method, path, schemas, and middleware types are not needed.

Signature

interface Constraint {
  readonly "~effect/httpapi/HttpApiEndpoint": "~effect/httpapi/HttpApiEndpoint";
  readonly "~Error": Constraint;
  readonly "~Request": unknown;
  readonly "~RequestRaw": unknown;
  readonly "~Success": Constraint;
  readonly identifier: string;
}

ConstraintRequest interface

Added in v4.0.0 Source

A widened endpoint type that preserves request and middleware pipeline phantom fields.

Signature

interface ConstraintRequest extends Constraint {
  readonly "~Headers": Constraint;
  readonly "~Middleware": unknown;
  readonly "~Params": Constraint;
  readonly "~Payload": Constraint;
  readonly "~Query": Constraint;
}

HttpApiEndpoint interface

Added in v4.0.0 Source

Represents an API endpoint. An API endpoint is mapped to a single route on the underlying HttpRouter.

Signature

interface HttpApiEndpoint<
  out Identifier extends string,
  out Method extends HttpMethod,
  out Path extends string,
  out Params extends Schema.Top = never,
  out Query extends Schema.Top = never,
  out Payload extends Schema.Top = never,
  out Headers extends Schema.Top = never,
  out Success extends Schema.Top = typeof HttpApiSchema.NoContent,
  out Error extends Schema.Top = never,
  in out Middleware = never,
  out MiddlewareServices = never,
> extends Pipeable {
  constructor(_: never);
  readonly "~effect/httpapi/HttpApiEndpoint": "~effect/httpapi/HttpApiEndpoint";
  readonly "~Error": Error;
  readonly "~Headers": Headers;
  readonly "~Middleware": Middleware;
  readonly "~MiddlewareServices": MiddlewareServices;
  readonly "~Params": Params;
  readonly "~Payload": Payload;
  readonly "~Query": Query;
  readonly "~Request": RequestFromParts<
    HttpApiEndpoint<
      Identifier,
      Method,
      Path,
      Params,
      Query,
      Payload,
      Headers,
      Success,
      Error,
      Middleware,
      MiddlewareServices
    >,
    Params["Type"],
    Query["Type"],
    Payload["Type"],
    Headers["Type"]
  >;
  readonly "~RequestRaw": RequestRawFromParts<
    HttpApiEndpoint<
      Identifier,
      Method,
      Path,
      Params,
      Query,
      Payload,
      Headers,
      Success,
      Error,
      Middleware,
      MiddlewareServices
    >,
    Params["Type"],
    Query["Type"],
    Headers["Type"]
  >;
  readonly "~Success": Success;
  readonly annotations: Context<never>;
  readonly error: ReadonlySet<Top>;
  readonly headers: Top | undefined;
  readonly identifier: Identifier;
  readonly method: Method;
  readonly middlewares: ReadonlySet<Key<Middleware, any>>;
  readonly params: Top | undefined;
  readonly path: Path;
  readonly payload: PayloadMap;
  readonly query: Top | undefined;
  readonly success: ReadonlySet<Top>;
  annotate<I, S>(
    key: Key<I, S>,
    value: NoInfer<S>,
  ): HttpApiEndpoint<
    Identifier,
    Method,
    Path,
    Params,
    Query,
    Payload,
    Headers,
    Success,
    Error,
    Middleware,
    MiddlewareServices
  >;
  annotateMerge<I>(
    annotations: Context<I>,
  ): HttpApiEndpoint<
    Identifier,
    Method,
    Path,
    Params,
    Query,
    Payload,
    Headers,
    Success,
    Error,
    Middleware,
    MiddlewareServices
  >;
  middleware<I extends AnyId, S>(
    middleware: Key<I, S>,
  ): HttpApiEndpoint<
    Identifier,
    Method,
    Path,
    Params,
    Query,
    Payload,
    Headers,
    Success,
    Error,
    Middleware | I,
    ApplyServices<I, MiddlewareServices>
  >;
  prefix<Prefix extends PathInput>(
    prefix: Prefix,
  ): HttpApiEndpoint<
    Identifier,
    Method,
    `${Prefix}${Path}`,
    Params,
    Query,
    Payload,
    Headers,
    Success,
    Error,
    Middleware,
    MiddlewareServices
  >;
}

PayloadMap type

Added in v4.0.0 Source

Maps normalized media types to a payload encoding strategy and one or more schemas. Each schema retains its declared content type in its encoding annotation.

Signature

type PayloadMap = ReadonlyMap<
  string,
  {
    readonly encoding: HttpApiSchema.PayloadEncoding;
    readonly schemas: readonly [Schema.Top, ...Array<Schema.Top>];
  }
>;

Top interface

Added in v4.0.0 Source

A widened endpoint type that preserves concrete runtime properties such as method, path, schemas, annotations, and middleware sets.

Signature

interface Top extends HttpApiEndpoint<
  string,
  HttpMethod,
  string,
  Schema.Top,
  Schema.Top,
  Schema.Top,
  Schema.Top,
  Schema.Top,
  Schema.Top,
  any,
  unknown
> {
  constructor(_: never);
}

Other

delete

Source

Signature

declare const delete: {
  <Identifier extends string, Path extends PathInput, Params extends Top | Fields = never, Query extends Top | Fields = never, Payload extends Top | readonly Array<Top> = never, Headers extends Top | Fields = never, Success extends SuccessConstraint = NoContent, Error extends Top | readonly Array<Top> = never>(identifier: Identifier, path: Path, options?: {
    readonly disableCodecs?: false;
    readonly error?: Error & ErrorNoStream<NoInfer<Error>>;
    readonly headers?: Headers;
    readonly params?: Params;
    readonly payload?: Payload;
    readonly query?: Query;
    readonly success?: Success;
  }): HttpApiEndpoint<Identifier, "DELETE", Path, ToStringTreeCodec<Params>, ToStringTreeCodec<Query>, ToJsonCodec<ToSchema<Payload>>, ToStringTreeCodec<Headers>, ToSuccessCodec<Success>, ToJsonCodec<Error extends readonly Array<Constraint> ? Error[number] : Error>>;
  <Identifier extends string, Path extends PathInput, Params extends ParamsConstraint = never, Query extends QueryConstraint = never, Payload extends Top | readonly Array<Top> = never, Headers extends HeadersConstraint = never, Success extends SuccessConstraint = NoContent, Error extends ErrorConstraint = never>(identifier: Identifier, path: Path, options?: {
    readonly disableCodecs: true;
    readonly error?: Error & ErrorNoStream<NoInfer<Error>>;
    readonly headers?: Headers;
    readonly params?: Params;
    readonly payload?: Payload;
    readonly query?: Query;
    readonly success?: Success;
  }): HttpApiEndpoint<Identifier, "DELETE", Path, Params extends Fields ? Struct<Params> : Params, Query extends Fields ? Struct<Query> : Query, ToSchema<Payload>, ToSchema<Headers>, UnwrapReadonlyArray<Success>, Error extends readonly Array<Constraint> ? Error[number] : Error>;
}

Utility Types

AddMiddleware type

Added in v4.0.0 Source

Returns an endpoint type with additional middleware applied and the endpoint's middleware service requirements updated accordingly.

Signature

type AddMiddleware<Endpoint, M extends HttpApiMiddleware.AnyId> =
  Endpoint extends HttpApiEndpoint<
    infer _Identifier,
    infer _Method,
    infer _Path,
    infer _Params,
    infer _Query,
    infer _Payload,
    infer _Headers,
    infer _Success,
    infer _Error,
    infer _M,
    infer _MR
  >
    ? HttpApiEndpoint<
        _Identifier,
        _Method,
        _Path,
        _Params,
        _Query,
        _Payload,
        _Headers,
        _Success,
        _Error,
        _M | M,
        HttpApiMiddleware.ApplyServices<M, _MR>
      >
    : never;

AddPrefix type

Added in v4.0.0 Source

Returns an endpoint type with the supplied path prefix prepended while preserving the endpoint's schemas, method, errors, and middleware.

Signature

type AddPrefix<Endpoint, Prefix extends HttpRouter.PathInput> =
  Endpoint extends HttpApiEndpoint<
    infer _Identifier,
    infer _Method,
    infer _Path,
    infer _Params,
    infer _Query,
    infer _Payload,
    infer _Headers,
    infer _Success,
    infer _Error,
    infer _M,
    infer _MR
  >
    ? HttpApiEndpoint<
        _Identifier,
        _Method,
        `${Prefix}${_Path}`,
        _Params,
        _Query,
        _Payload,
        _Headers,
        _Success,
        _Error,
        _M,
        _MR
      >
    : never;

ClientRequest type

Added in v4.0.0 Source

Builds the request object accepted by a generated client method, including only the params, query, headers, payload, and response mode fields required by the endpoint. Multipart payloads are supplied as FormData.

Signature

type ClientRequest<
  Params extends Schema.Constraint,
  Query extends Schema.Constraint,
  Payload extends Schema.Constraint,
  Headers extends Schema.Constraint,
  ResponseMode extends ClientResponseMode,
> = [Params["Type"]] extends [never]
  ? {}
  : {
        readonly params: Params["Type"];
      } & [Query["Type"]] extends [never]
    ? {}
    : {
          readonly query: Query["Type"];
        } & [Headers["Type"]] extends [never]
      ? {}
      : {
            readonly headers: Headers["Type"];
          } & [Payload["Type"]] extends [never]
        ? {}
        : Payload["Type"] extends infer P
          ? P extends
              | Brand<HttpApiSchema.MultipartTypeId>
              | Brand<HttpApiSchema.MultipartStreamTypeId>
            ? {
                readonly payload: FormData;
              }
            : {
                readonly payload: Payload["Type"];
              }
          : {
                readonly payload: Payload["Type"];
              } extends infer Req
            ? keyof Req extends never
              ? void | {
                  readonly responseMode?: ResponseMode;
                }
              : Req & {
                  readonly responseMode?: ResponseMode;
                }
            : void;

ClientServices type

Added in v4.0.0 Source

Computes the services required on the client to encode endpoint requests and decode endpoint success or error responses.

Signature

type ClientServices<Endpoint> = Endpoint extends ConstraintRequest
  ?
      | Endpoint["~Params"]["EncodingServices"]
      | Endpoint["~Query"]["EncodingServices"]
      | Endpoint["~Payload"]["EncodingServices"]
      | Endpoint["~Headers"]["EncodingServices"]
      | SuccessDecodingServices<Endpoint["~Success"]>
      | Endpoint["~Error"]["DecodingServices"]
  : never;

Error type

Added in v4.0.0 Source

Extracts the error schema associated with an endpoint.

Signature

type Error<Endpoint> = Endpoint extends Constraint ? Endpoint["~Error"] : never;

ErrorConstraint type

Added in v4.0.0 Source

Constraint for error response schemas, allowing either a single schema or a readonly array of schemas.

Signature

type ErrorConstraint = Schema.Top | ReadonlyArray<Schema.Top>;

Errors type

Added in v4.0.0 Source

Computes the full error value union for an endpoint, including the endpoint error schema's type and errors introduced by middleware.

Signature

type Errors<Endpoint> = Endpoint extends ConstraintRequest
  ? Endpoint["~Error"]["Type"] | HttpApiMiddleware.Error<Endpoint["~Middleware"]>
  : never;

ErrorServicesDecode type

Added in v4.0.0 Source

Computes the services required to decode an endpoint's error responses, including services required by middleware error decoders.

Signature

type ErrorServicesDecode<Endpoint> = Endpoint extends ConstraintRequest
  ?
      | Endpoint["~Error"]["DecodingServices"]
      | HttpApiMiddleware.ErrorServicesDecode<Endpoint["~Middleware"]>
  : never;

ErrorServicesEncode type

Added in v4.0.0 Source

Computes the services required to encode an endpoint's error responses, including services required by middleware error encoders.

Signature

type ErrorServicesEncode<Endpoint> = Endpoint extends ConstraintRequest
  ?
      | Endpoint["~Error"]["EncodingServices"]
      | HttpApiMiddleware.ErrorServicesEncode<Endpoint["~Middleware"]>
  : never;

ErrorsWithIdentifier type

Added in v4.0.0 Source

Computes the full error value union for the endpoint with the specified identifier in an endpoint union.

Signature

type ErrorsWithIdentifier<Endpoints extends Constraint, Identifier extends string> = Errors<
  WithIdentifier<Endpoints, Identifier>
>;

ExcludeIdentifier type

Added in v4.0.0 Source

Removes endpoints with the specified identifier from a union of endpoints.

Signature

type ExcludeIdentifier<Endpoints, Identifier extends string> = Exclude<
  Endpoints,
  {
    readonly identifier: Identifier;
  }
>;

ExcludeProvided type

Added in v4.0.0 Source

Removes services provided by the HTTP router and endpoint middleware from a service requirement union.

Signature

type ExcludeProvided<Endpoint extends Constraint, R> = Exclude<
  R,
  HttpRouter.Provided | HttpApiMiddleware.Provides<Middleware<Endpoint>>
>;

ExcludeProvidedWithIdentifier type

Added in v4.0.0 Source

Removes services provided by the HTTP router and the selected endpoint's middleware from a service requirement union.

Signature

type ExcludeProvidedWithIdentifier<
  Endpoints extends Constraint,
  Identifier extends string,
  R,
> = ExcludeProvided<WithIdentifier<Endpoints, Identifier>, R>;

Handler type

Added in v4.0.0 Source

The normal server handler for an endpoint, accepting the decoded request shape and returning either the endpoint success value or a custom HttpServerResponse.

Signature

type Handler<Endpoint extends Constraint, E, R> = (
  request: Simplify<Endpoint["~Request"]>,
) => Effect<
  SuccessType<Endpoint["~Success"]> | HttpServerResponse,
  Endpoint["~Error"]["Type"] | E,
  R
>;

HandlerRaw type

Added in v4.0.0 Source

The raw server handler for an endpoint, receiving a request shape without a decoded payload so the handler can read the raw HttpServerRequest directly.

Signature

type HandlerRaw<Endpoint extends Constraint, E, R> = (
  request: Simplify<Endpoint["~RequestRaw"]>,
) => Effect<
  SuccessType<Endpoint["~Success"]> | HttpServerResponse,
  Endpoint["~Error"]["Type"] | E,
  R
>;

HandlerRawWithIdentifier type

Added in v4.0.0 Source

Derives the raw handler type for the endpoint with the specified identifier in an endpoint union.

Signature

type HandlerRawWithIdentifier<
  Endpoints extends Constraint,
  Identifier extends string,
  E,
  R,
> = HandlerRaw<WithIdentifier<Endpoints, Identifier>, E, R>;

HandlerWithIdentifier type

Added in v4.0.0 Source

Derives the normal handler type for the endpoint with the specified identifier in an endpoint union.

Signature

type HandlerWithIdentifier<Endpoints extends Constraint, Identifier extends string, E, R> = Handler<
  WithIdentifier<Endpoints, Identifier>,
  E,
  R
>;

Headers type

Added in v4.0.0 Source

Extracts the schema used for an endpoint's request headers.

Signature

type Headers<Endpoint> = Endpoint extends ConstraintRequest ? Endpoint["~Headers"] : never;

HeadersConstraint type

Added in v4.0.0 Source

Constraint for header schemas: each header must encode to string | undefined, or the schema must encode to a record of those values.

Signature

type HeadersConstraint =
  | Record<string, Schema.Encoder<string | undefined, unknown>>
  | Schema.Encoder<Record<string, string | undefined>, unknown>;

Identifier type

Added in v4.0.0 Source

Extracts the endpoint identifier literal from an HttpApiEndpoint.

Signature

type Identifier<Endpoint> = Endpoint extends Constraint ? Endpoint["identifier"] : never;

Middleware type

Added in v4.0.0 Source

Extracts the middleware identifiers attached to an endpoint.

Signature

type Middleware<Endpoint> = Endpoint extends {
  readonly "~Middleware": infer M;
}
  ? M
  : never;

MiddlewareClient type

Added in v4.0.0 Source

Computes the client-side middleware services required by an endpoint.

Signature

type MiddlewareClient<Endpoint> = HttpApiMiddleware.MiddlewareClient<Middleware<Endpoint>>;

MiddlewareError type

Added in v4.0.0 Source

Computes the error types that can be produced by the middleware attached to an endpoint.

Signature

type MiddlewareError<Endpoint> = HttpApiMiddleware.Error<Middleware<Endpoint>>;

MiddlewareProvides type

Added in v4.0.0 Source

Computes the services provided by the middleware attached to an endpoint.

Signature

type MiddlewareProvides<Endpoint> = HttpApiMiddleware.Provides<Middleware<Endpoint>>;

MiddlewareServices type

Added in v4.0.0 Source

Extracts the additional services required by middleware applied to an endpoint.

Signature

type MiddlewareServices<Endpoint> = Endpoint extends {
  readonly "~MiddlewareServices": infer R;
}
  ? R
  : never;

MiddlewareServicesWithIdentifier type

Added in v4.0.0 Source

Extracts the middleware service requirements for the endpoint with the specified identifier in an endpoint union.

Signature

type MiddlewareServicesWithIdentifier<
  Endpoints extends Constraint,
  Identifier extends string,
> = MiddlewareServices<WithIdentifier<Endpoints, Identifier>>;

MiddlewareWithIdentifier type

Added in v4.0.0 Source

Extracts the middleware identifiers for the endpoint with the specified identifier in an endpoint union.

Signature

type MiddlewareWithIdentifier<Endpoints extends Constraint, Identifier extends string> = Middleware<
  WithIdentifier<Endpoints, Identifier>
>;

Params type

Added in v4.0.0 Source

Extracts the schema used for an endpoint's path parameters.

Signature

type Params<Endpoint> = Endpoint extends ConstraintRequest ? Endpoint["~Params"] : never;

ParamsConstraint type

Added in v4.0.0 Source

Constraint for path parameter schemas: each parameter must encode to string | undefined, or the schema must encode to a record of those values.

Signature

type ParamsConstraint =
  | Record<string, Schema.Encoder<string | undefined, unknown>>
  | Schema.Encoder<Record<string, string | undefined>, unknown>;

Payload type

Added in v4.0.0 Source

Extracts the schema used for an endpoint's request payload.

Signature

type Payload<Endpoint> = Endpoint extends ConstraintRequest ? Endpoint["~Payload"] : never;

PayloadConstraint type

Added in v4.0.0 Source

Payload schema depends on the HTTP method: - for no-body methods, payload is modeled as query params, so each field must encode to string | ReadonlyArray<string> | undefined and OpenAPI can expand it into in: query parameters - for body methods, payload may be any Schema.Top (or content-type keyed schemas) and OpenAPI uses requestBody instead of parameters

Signature

type PayloadConstraint<Method extends HttpMethod> = Method extends HttpMethod.NoBody
  ? Record<string, Schema.Encoder<string | ReadonlyArray<string> | undefined, unknown>>
  : Schema.Top | ReadonlyArray<Schema.Top>;

PayloadConstraintCodecs type

Added in v4.0.0 Source

Payload constraint used when automatic codecs are enabled: no-body methods accept field records for query-style encoding, while body methods accept one or more schemas.

Signature

type PayloadConstraintCodecs<Method extends HttpMethod> = Method extends HttpMethod.NoBody
  ? Record<string, Schema.Top>
  : Schema.Top | ReadonlyArray<Schema.Top>;

Query type

Added in v4.0.0 Source

Extracts the schema used for an endpoint's query parameters.

Signature

type Query<Endpoint> = Endpoint extends ConstraintRequest ? Endpoint["~Query"] : never;

QueryConstraint type

Added in v4.0.0 Source

Constraint for query schemas: each field must encode to string, an array of strings, or undefined, or the schema must encode to a record of those values.

Signature

type QueryConstraint =
  | Record<string, Schema.Encoder<string | ReadonlyArray<string> | undefined, unknown>>
  | Schema.Encoder<string | ReadonlyArray<string> | undefined, unknown>;

Request type

Added in v4.0.0 Source

Builds the decoded request shape passed to a normal endpoint handler, including available params, query, payload, headers, the raw request, endpoint, and group. Multipart stream payloads are exposed as streams of parts.

Signature

type Request<Endpoint> = Endpoint extends ConstraintRequest ? Endpoint["~Request"] : {};

RequestRaw type

Added in v4.0.0 Source

Builds the request shape passed to a raw endpoint handler, including decoded params, query, and headers plus the raw request, endpoint, and group, while leaving payload handling to the raw request.

Signature

type RequestRaw<Endpoint> = Endpoint extends ConstraintRequest ? Endpoint["~RequestRaw"] : {};

ServerServices type

Added in v4.0.0 Source

Computes the services required on the server to decode endpoint inputs and encode endpoint success, error, and middleware error responses.

Signature

type ServerServices<Endpoint> = Endpoint extends ConstraintRequest
  ?
      | Endpoint["~Params"]["DecodingServices"]
      | Endpoint["~Query"]["DecodingServices"]
      | Endpoint["~Payload"]["DecodingServices"]
      | Endpoint["~Headers"]["DecodingServices"]
      | SuccessEncodingServices<Endpoint["~Success"]>
      | Endpoint["~Error"]["EncodingServices"]
      | HttpApiMiddleware.ErrorServicesEncode<Endpoint["~Middleware"]>
  : never;

ServerServicesWithIdentifier type

Added in v4.0.0 Source

Computes the server-side service requirements for the endpoint with the specified identifier in an endpoint union.

Signature

type ServerServicesWithIdentifier<
  Endpoints extends Constraint,
  Identifier extends string,
> = ServerServices<WithIdentifier<Endpoints, Identifier>>;

Success type

Added in v4.0.0 Source

Extracts the success schema associated with an endpoint.

Signature

type Success<Endpoint> = Endpoint extends Constraint ? Endpoint["~Success"] : never;

SuccessConstraint type

Added in v4.0.0 Source

Constraint for success response schemas, allowing either a single schema or a readonly array of schemas.

Signature

type SuccessConstraint = Schema.Top | ReadonlyArray<Schema.Top>;

SuccessWithIdentifier type

Added in v4.0.0 Source

Extracts the decoded success value type for the endpoint with the specified identifier in an endpoint union.

Signature

type SuccessWithIdentifier<Endpoints extends Constraint, Identifier extends string> =
  Success<WithIdentifier<Endpoints, Identifier>> extends infer S ? SuccessType<S> : never;

WithIdentifier type

Added in v4.0.0 Source

Selects the endpoint with the specified identifier from a union of endpoints.

Signature

type WithIdentifier<Endpoints, Identifier extends string> = Extract<
  Endpoints,
  {
    readonly identifier: Identifier;
  }
>;