HttpApiEndpoint unstable

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.

58 exports Since v4.0.0 Source

Constructors

get

unstable

Since v4.0.0

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

head

unstable

Since v4.0.0

Creates a HEAD endpoint declaration.

Signature

declare const head: {
  <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, "HEAD", 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, "HEAD", 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

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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

query

unstable

Since v4.0.0

Creates a QUERY endpoint declaration.

Signature

declare const query: {
  <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, "QUERY", 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, "QUERY", 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

unstable

Since v4.0.0

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 unstable

Since v4.0.0

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 unstable

Since v4.0.0

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

Signature

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

ConstraintRequest

interface unstable

Since v4.0.0

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 unstable

Since v4.0.0

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/http-api/HttpApiEndpoint": "~effect/http-api/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 disableCodecs: boolean;
  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 unstable

Since v4.0.0

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 unstable

Since v4.0.0

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

unstable

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 unstable

Since v4.0.0

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 unstable

Since v4.0.0

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 unstable

Since v4.0.0

Builds the request object accepted by a generated client method, including the params, query, headers, and payload required by the endpoint, plus optional response mode and SSE decoding options. 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;
  readonly sseOptions?: Sse.DecodeOptions;
} : Req & {
  readonly responseMode?: ResponseMode;
  readonly sseOptions?: Sse.DecodeOptions;
} : void

ClientServices

type unstable

Since v4.0.0

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 unstable

Since v4.0.0

Extracts the error schema associated with an endpoint.

Signature

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

ErrorConstraint

type unstable

Since v4.0.0

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 unstable

Since v4.0.0

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 unstable

Since v4.0.0

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 unstable

Since v4.0.0

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 unstable

Since v4.0.0

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 unstable

Since v4.0.0

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 unstable

Since v4.0.0

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 unstable

Since v4.0.0

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 unstable

Since v4.0.0

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 unstable

Since v4.0.0

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 unstable

Since v4.0.0

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 unstable

Since v4.0.0

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 unstable

Since v4.0.0

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

Signature

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

HeadersConstraint

type unstable

Since v4.0.0

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 unstable

Since v4.0.0

Extracts the endpoint identifier literal from an HttpApiEndpoint.

Signature

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

Middleware

type unstable

Since v4.0.0

Extracts the middleware identifiers attached to an endpoint.

Signature

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

MiddlewareClient

type unstable

Since v4.0.0

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

Signature

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

MiddlewareError

type unstable

Since v4.0.0

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 unstable

Since v4.0.0

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

Signature

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

MiddlewareServices

type unstable

Since v4.0.0

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 unstable

Since v4.0.0

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 unstable

Since v4.0.0

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 unstable

Since v4.0.0

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

Signature

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

ParamsConstraint

type unstable

Since v4.0.0

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 unstable

Since v4.0.0

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

Signature

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

PayloadConstraint

type unstable

Since v4.0.0

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 unstable

Since v4.0.0

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 unstable

Since v4.0.0

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

Signature

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

QueryConstraint

type unstable

Since v4.0.0

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 unstable

Since v4.0.0

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 unstable

Since v4.0.0

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 unstable

Since v4.0.0

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 unstable

Since v4.0.0

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 unstable

Since v4.0.0

Extracts the success schema associated with an endpoint.

Signature

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

SuccessConstraint

type unstable

Since v4.0.0

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 unstable

Since v4.0.0

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 unstable

Since v4.0.0

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

Signature

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