HttpApiEndpoint.ts

HttpApiEndpoint.ts overview

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.

Since v4.0.0

---

Exports Grouped by Category

• constraints
  • ErrorConstraint (type alias)
  • HeadersConstraint (type alias)
  • ParamsConstraint (type alias)
  • PayloadConstraint (type alias)
  • PayloadConstraintCodecs (type alias)
  • QueryConstraint (type alias)
  • SuccessConstraint (type alias)
• constructors
  • delete
  • get
  • head
  • make
  • options
  • patch
  • post
  • put
• guards
  • isHttpApiEndpoint
• models
  • AddMiddleware (type alias)
  • AddPrefix (type alias)
  • ClientRequest (type alias)
  • ClientResponseMode (type alias)
  • ClientServices (type alias)
  • Constraint (interface)
  • ConstraintRequest (interface)
  • Error (type alias)
  • ErrorServicesDecode (type alias)
  • ErrorServicesEncode (type alias)
  • Errors (type alias)
  • ErrorsWithIdentifier (type alias)
  • ExcludeIdentifier (type alias)
  • ExcludeProvided (type alias)
  • ExcludeProvidedWithIdentifier (type alias)
  • Handler (type alias)
  • HandlerRaw (type alias)
  • HandlerRawWithIdentifier (type alias)
  • HandlerWithIdentifier (type alias)
  • Headers (type alias)
  • HttpApiEndpoint (interface)
  • Identifier (type alias)
  • Middleware (type alias)
  • MiddlewareClient (type alias)
  • MiddlewareError (type alias)
  • MiddlewareProvides (type alias)
  • MiddlewareServices (type alias)
  • MiddlewareServicesWithIdentifier (type alias)
  • MiddlewareWithIdentifier (type alias)
  • Params (type alias)
  • Payload (type alias)
  • PayloadMap (type alias)
  • Query (type alias)
  • Request (type alias)
  • RequestRaw (type alias)
  • ServerServices (type alias)
  • ServerServicesWithIdentifier (type alias)
  • Success (type alias)
  • SuccessWithIdentifier (type alias)
  • Top (interface)
  • WithIdentifier (type alias)

---

constraints

ErrorConstraint (type alias)

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

Signature

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

Source

Since v4.0.0

HeadersConstraint (type alias)

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>

Source

Since v4.0.0

ParamsConstraint (type alias)

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>

Source

Since v4.0.0

PayloadConstraint (type alias)

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> = Method extends HttpMethod.NoBody
  ? Record<string, Schema.Encoder<string | ReadonlyArray<string> | undefined, unknown>>
  : Schema.Top | ReadonlyArray<Schema.Top>

Source

Since v4.0.0

PayloadConstraintCodecs (type alias)

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> = Method extends HttpMethod.NoBody
  ? Record<string, Schema.Top>
  : Schema.Top | ReadonlyArray<Schema.Top>

Source

Since v4.0.0

QueryConstraint (type alias)

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>

Source

Since v4.0.0

SuccessConstraint (type alias)

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

Signature

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

Source

Since v4.0.0

constructors

delete

Creates a DELETE endpoint declaration.

Signature

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

Source

Since v4.0.0

get

Creates a GET endpoint declaration.

Signature

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

Source

Since v4.0.0

head

Creates a HEAD endpoint declaration.

Signature

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

Source

Since v4.0.0

make

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 const make: <Method extends HttpMethod>(
  method: Method
) => {
  <
    const Identifier extends string,
    const Path extends HttpRouter.PathInput,
    Params extends Schema.Top | Schema.Struct.Fields = never,
    Query extends Schema.Top | Schema.Struct.Fields = never,
    Payload extends PayloadConstraintCodecs<Method> = never,
    Headers extends Schema.Top | Schema.Struct.Fields = never,
    const Success extends SuccessConstraint = HttpApiSchema.NoContent,
    const Error extends Schema.Top | ReadonlyArray<Schema.Top> = never
  >(
    identifier: Identifier,
    path: Path,
    options?: {
      readonly disableCodecs?: false | undefined
      readonly params?: Params | undefined
      readonly query?: Query | undefined
      readonly headers?: Headers | undefined
      readonly payload?: Payload | undefined
      readonly success?: Success | undefined
      readonly error?: (Error & ErrorNoStream<Types.NoInfer<Error>>) | undefined
    }
  ): HttpApiEndpoint<
    Identifier,
    Method,
    Path,
    ToStringTreeCodec<Params>,
    ToStringTreeCodec<Query>,
    Method extends HttpMethod.WithBody ? ToJsonCodec<ToSchema<Payload>> : ToStringTreeCodec<ToSchema<Payload>>,
    ToStringTreeCodec<Headers>,
    ToSuccessCodec<Success>,
    ToJsonCodec<Error extends ReadonlyArray<Schema.Constraint> ? Error[number] : Error>
  >
  <
    const Identifier extends string,
    const Path extends HttpRouter.PathInput,
    Params extends ParamsConstraint = never,
    Query extends QueryConstraint = never,
    Payload extends PayloadConstraint<Method> = never,
    Headers extends HeadersConstraint = never,
    const Success extends SuccessConstraint = HttpApiSchema.NoContent,
    const Error extends ErrorConstraint = never
  >(
    identifier: Identifier,
    path: Path,
    options?: {
      readonly disableCodecs: true
      readonly params?: Params | undefined
      readonly query?: Query | undefined
      readonly headers?: Headers | undefined
      readonly payload?: Payload | undefined
      readonly success?: Success | undefined
      readonly error?: (Error & ErrorNoStream<Types.NoInfer<Error>>) | undefined
    }
  ): HttpApiEndpoint<
    Identifier,
    Method,
    Path,
    Params extends Schema.Struct.Fields ? Schema.Struct<Params> : Params,
    Query extends Schema.Struct.Fields ? Schema.Struct<Query> : Query,
    ToSchema<Payload>,
    ToSchema<Headers>,
    UnwrapReadonlyArray<Success>,
    Error extends ReadonlyArray<Schema.Constraint> ? Error[number] : Error
  >
}

Source

Since v4.0.0

options

Creates an OPTIONS endpoint declaration.

Signature

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

Source

Since v4.0.0

patch

Creates a PATCH endpoint declaration.

Signature

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

Source

Since v4.0.0

post

Creates a POST endpoint declaration.

Signature

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

Source

Since v4.0.0

put

Creates a PUT endpoint declaration.

Signature

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

Source

Since v4.0.0

guards

isHttpApiEndpoint

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

Signature

declare const isHttpApiEndpoint: (u: unknown) => u is Top

Source

Since v4.0.0

models

AddMiddleware (type alias)

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

Signature

type AddMiddleware<Endpoint, M> =
  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

Source

Since v4.0.0

AddPrefix (type alias)

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

Source

Since v4.0.0

ClientRequest (type alias)

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, Query, Payload, Headers, ResponseMode> = ([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

Source

Since v4.0.0

ClientResponseMode (type alias)

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"

Source

Since v4.0.0

ClientServices (type alias)

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

Source

Since v4.0.0

Constraint (interface)

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

Signature

export interface Constraint {
  readonly [TypeId]: typeof TypeId
  readonly identifier: string
  readonly ["~Success"]: Schema.Constraint
  readonly ["~Error"]: Schema.Constraint
  readonly ["~Request"]: unknown
  readonly ["~RequestRaw"]: unknown
}

Source

Since v4.0.0

ConstraintRequest (interface)

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

Signature

export interface ConstraintRequest extends Constraint {
  readonly ["~Params"]: Schema.Constraint
  readonly ["~Query"]: Schema.Constraint
  readonly ["~Payload"]: Schema.Constraint
  readonly ["~Headers"]: Schema.Constraint
  readonly ["~Middleware"]: unknown
}

Source

Since v4.0.0

Error (type alias)

Extracts the error schema associated with an endpoint.

Signature

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

Source

Since v4.0.0

ErrorServicesDecode (type alias)

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

Source

Since v4.0.0

ErrorServicesEncode (type alias)

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

Source

Since v4.0.0

Errors (type alias)

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

Source

Since v4.0.0

ErrorsWithIdentifier (type alias)

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

Signature

type ErrorsWithIdentifier<Endpoints, Identifier> = Errors<WithIdentifier<Endpoints, Identifier>>

Source

Since v4.0.0

ExcludeIdentifier (type alias)

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

Signature

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

Source

Since v4.0.0

ExcludeProvided (type alias)

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

Signature

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

Source

Since v4.0.0

ExcludeProvidedWithIdentifier (type alias)

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

Signature

type ExcludeProvidedWithIdentifier<Endpoints, Identifier, R> = ExcludeProvided<WithIdentifier<Endpoints, Identifier>, R>

Source

Since v4.0.0

Handler (type alias)

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, E, R> = (
  request: Simplify<Endpoint["~Request"]>
) => Effect<SuccessType<Endpoint["~Success"]> | HttpServerResponse, Endpoint["~Error"]["Type"] | E, R>

Source

Since v4.0.0

HandlerRaw (type alias)

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, E, R> = (
  request: Simplify<Endpoint["~RequestRaw"]>
) => Effect<SuccessType<Endpoint["~Success"]> | HttpServerResponse, Endpoint["~Error"]["Type"] | E, R>

Source

Since v4.0.0

HandlerRawWithIdentifier (type alias)

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

Signature

type HandlerRawWithIdentifier<Endpoints, Identifier, E, R> = HandlerRaw<WithIdentifier<Endpoints, Identifier>, E, R>

Source

Since v4.0.0

HandlerWithIdentifier (type alias)

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

Signature

type HandlerWithIdentifier<Endpoints, Identifier, E, R> = Handler<WithIdentifier<Endpoints, Identifier>, E, R>

Source

Since v4.0.0

Headers (type alias)

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

Signature

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

Source

Since v4.0.0

HttpApiEndpoint (interface)

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

Signature

export 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 {
  new (_: never): {}
  readonly [TypeId]: typeof TypeId
  readonly "~Params": Params
  readonly "~Query": Query
  readonly "~Headers": Headers
  readonly "~Payload": Payload
  readonly "~Success": Success
  readonly "~Error": Error
  readonly "~Middleware": Middleware
  readonly "~MiddlewareServices": MiddlewareServices
  readonly "~Request": RequestFromParts<this, Params["Type"], Query["Type"], Payload["Type"], Headers["Type"]>
  readonly "~RequestRaw": RequestRawFromParts<this, Params["Type"], Query["Type"], Headers["Type"]>

  readonly identifier: Identifier
  readonly path: Path
  readonly method: Method
  readonly params: Schema.Top | undefined
  readonly query: Schema.Top | undefined
  readonly headers: Schema.Top | undefined
  readonly payload: PayloadMap
  readonly success: ReadonlySet<Schema.Top>
  readonly error: ReadonlySet<Schema.Top>
  readonly annotations: Context.Context<never>
  readonly middlewares: ReadonlySet<Context.Key<Middleware, any>>

  /**
   * Add a prefix to the path of the endpoint.
   */
  prefix<const Prefix extends HttpRouter.PathInput>(
    prefix: Prefix
  ): HttpApiEndpoint<
    Identifier,
    Method,
    `${Prefix}${Path}`,
    Params,
    Query,
    Payload,
    Headers,
    Success,
    Error,
    Middleware,
    MiddlewareServices
  >

  /**
   * Add an `HttpApiMiddleware` to the endpoint.
   */
  middleware<I extends HttpApiMiddleware.AnyId, S>(
    middleware: Context.Key<I, S>
  ): HttpApiEndpoint<
    Identifier,
    Method,
    Path,
    Params,
    Query,
    Payload,
    Headers,
    Success,
    Error,
    Middleware | I,
    HttpApiMiddleware.ApplyServices<I, MiddlewareServices>
  >

  /**
   * Add an annotation on the endpoint.
   */
  annotate<I, S>(
    key: Context.Key<I, S>,
    value: Types.NoInfer<S>
  ): HttpApiEndpoint<
    Identifier,
    Method,
    Path,
    Params,
    Query,
    Payload,
    Headers,
    Success,
    Error,
    Middleware,
    MiddlewareServices
  >

  /**
   * Merge the annotations of the endpoint with the provided context.
   */
  annotateMerge<I>(
    annotations: Context.Context<I>
  ): HttpApiEndpoint<
    Identifier,
    Method,
    Path,
    Params,
    Query,
    Payload,
    Headers,
    Success,
    Error,
    Middleware,
    MiddlewareServices
  >
}

Source

Since v4.0.0

Identifier (type alias)

Extracts the endpoint identifier literal from an HttpApiEndpoint.

Signature

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

Source

Since v4.0.0

Middleware (type alias)

Extracts the middleware identifiers attached to an endpoint.

Signature

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

Source

Since v4.0.0

MiddlewareClient (type alias)

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

Signature

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

Source

Since v4.0.0

MiddlewareError (type alias)

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

Signature

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

Source

Since v4.0.0

MiddlewareProvides (type alias)

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

Signature

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

Source

Since v4.0.0

MiddlewareServices (type alias)

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

Signature

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

Source

Since v4.0.0

MiddlewareServicesWithIdentifier (type alias)

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

Signature

type MiddlewareServicesWithIdentifier<Endpoints, Identifier> = MiddlewareServices<WithIdentifier<Endpoints, Identifier>>

Source

Since v4.0.0

MiddlewareWithIdentifier (type alias)

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

Signature

type MiddlewareWithIdentifier<Endpoints, Identifier> = Middleware<WithIdentifier<Endpoints, Identifier>>

Source

Since v4.0.0

Params (type alias)

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

Signature

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

Source

Since v4.0.0

Payload (type alias)

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

Signature

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

Source

Since v4.0.0

PayloadMap (type alias)

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

Source

Since v4.0.0

Query (type alias)

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

Signature

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

Source

Since v4.0.0

Request (type alias)

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"] : {}

Source

Since v4.0.0

RequestRaw (type alias)

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"] : {}

Source

Since v4.0.0

ServerServices (type alias)

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

Source

Since v4.0.0

ServerServicesWithIdentifier (type alias)

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

Signature

type ServerServicesWithIdentifier<Endpoints, Identifier> = ServerServices<WithIdentifier<Endpoints, Identifier>>

Source

Since v4.0.0

Success (type alias)

Extracts the success schema associated with an endpoint.

Signature

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

Source

Since v4.0.0

SuccessWithIdentifier (type alias)

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

Signature

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

Source

Since v4.0.0

Top (interface)

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

Signature

export interface Top extends HttpApiEndpoint<
  string,
  HttpMethod,
  string,
  Schema.Top,
  Schema.Top,
  Schema.Top,
  Schema.Top,
  Schema.Top,
  Schema.Top,
  any,
  unknown
> {}

Source

Since v4.0.0

WithIdentifier (type alias)

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

Signature

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

Source

Since v4.0.0