HttpApiBuilder.ts

HttpApiBuilder.ts overview

Builds server routes from declarative HttpApi contracts.

This module turns an HttpApi description plus group handlers into HttpRouter routes. At runtime it decodes request parts with schemas, runs middleware and security handlers, invokes the registered endpoint handler, and encodes successes or declared errors into HttpServerResponse values.

Since v4.0.0

Exports Grouped by Category

constructors
- layer
handlers
security
- securityDecode
- securitySetCookie
utils
- Handlers (namespace)

constructors

layer

Registers an HttpApi with a HttpRouter.

Signature

declare const layer: <Id extends string, Groups extends HttpApiGroup.Constraint>(
  api: HttpApi.HttpApi<Id, Groups>,
  options?: { readonly openapiPath?: `/${string}` | undefined }
) => Layer.Layer<
  never,
  never,
  Etag.Generator | HttpRouter.HttpRouter | FileSystem | HttpPlatform | Path | HttpApiGroup.ToService<Id, Groups>
>

Source

Since v4.0.0

handlers

Handlers (interface)

Mutable handler collection for one HttpApi group.

Details

Each call to handle or handleRaw registers an endpoint implementation and adds that endpoint identifier to the type-level set of implemented endpoints. Endpoint identifiers that were already handled are rejected at the type level.

Signature

export interface Handlers<
  R,
  EndpointsByIdentifier extends Record<string, HttpApiEndpoint.Constraint> = {},
  HandledIdentifiers extends keyof EndpointsByIdentifier = never
> extends Pipeable {
  readonly [HandlersTypeId]: typeof HandlersTypeId
  readonly "~EndpointsByIdentifier": EndpointsByIdentifier
  readonly "~HandledIdentifiers": HandledIdentifiers
  /** @internal */
  readonly group: HttpApiGroup.Top
  /** @internal */
  readonly handlers: Map<string, HandlerRuntime>

  /**
   * Add the implementation for an unhandled `HttpApiEndpoint` to a `Handlers` group.
   */
  handle<Identifier extends keyof EndpointsByIdentifier, R1>(
    identifier: Identifier & NotHandledIdentifier<Identifier, HandledIdentifiers>,
    handler: HttpApiEndpoint.Handler<
      EndpointsByIdentifier[Identifier],
      HttpApiEndpoint.MiddlewareError<EndpointsByIdentifier[Identifier]>,
      R1
    >,
    options?: { readonly uninterruptible?: boolean | undefined } | undefined
  ): Handlers<
    R | HandlerRequirements<EndpointsByIdentifier[Identifier], R1>,
    EndpointsByIdentifier,
    HandledIdentifiers | Identifier
  >

  /**
   * Add implementations for unhandled `HttpApiEndpoint`s in a `Handlers` group.
   */
  handleAll<const HandlersByIdentifier extends HandleAllHandlers<Omit<EndpointsByIdentifier, HandledIdentifiers>>>(
    handlers: HandlersByIdentifier &
      HandleAllExtraKeys<Omit<EndpointsByIdentifier, HandledIdentifiers>, HandlersByIdentifier>
  ): Handlers<
    R | HandleAllRequirements<EndpointsByIdentifier, HandlersByIdentifier>,
    EndpointsByIdentifier,
    HandledIdentifiers | (keyof HandlersByIdentifier & keyof EndpointsByIdentifier)
  >

  /**
   * Add the implementation for an unhandled `HttpApiEndpoint` to a `Handlers` group.
   * This version opts out of automatic payload decoding and provides the raw request.
   */
  handleRaw<Identifier extends keyof EndpointsByIdentifier, R1>(
    identifier: Identifier & NotHandledIdentifier<Identifier, HandledIdentifiers>,
    handler: HttpApiEndpoint.HandlerRaw<
      EndpointsByIdentifier[Identifier],
      HttpApiEndpoint.MiddlewareError<EndpointsByIdentifier[Identifier]>,
      R1
    >,
    options?: { readonly uninterruptible?: boolean | undefined } | undefined
  ): Handlers<
    R | HandlerRequirements<EndpointsByIdentifier[Identifier], R1>,
    EndpointsByIdentifier,
    HandledIdentifiers | Identifier
  >
}

Source

Since v4.0.0

endpoint

Builds the server-side HTTP effect for a single endpoint in an API group using the endpoint metadata, middleware, codecs, and supplied handler.

Signature

declare const endpoint: <
  ApiId extends string,
  Groups extends HttpApiGroup.Constraint,
  const GroupIdentifier extends HttpApiGroup.Identifier<Groups>,
  const EndpointIdentifier extends HttpApiGroup.Endpoints<
    HttpApiGroup.WithIdentifier<Groups, GroupIdentifier>
  >["identifier"],
  R
>(
  api: HttpApi.HttpApi<ApiId, Groups>,
  groupIdentifier: GroupIdentifier,
  endpointIdentifier: EndpointIdentifier,
  handler: NoInfer<
    HttpApiEndpoint.HandlerWithIdentifier<
      HttpApiGroup.Endpoints<HttpApiGroup.WithIdentifier<Groups, GroupIdentifier>>,
      EndpointIdentifier,
      never,
      R
    >
  >
) => EndpointReturn<Groups, GroupIdentifier, EndpointIdentifier, R>

Source

Since v4.0.0

group

Create a Layer that implements all endpoints in an HttpApi group.

Details

The build function receives an unimplemented Handlers instance that can be used to add handlers to the group. Implement endpoints with handlers.handle.

Signature

declare const group: <
  ApiId extends string,
  Groups extends HttpApiGroup.Constraint,
  const Identifier extends HttpApiGroup.Identifier<Groups>,
  Return
>(
  api: HttpApi.HttpApi<ApiId, Groups>,
  groupIdentifier: Identifier,
  build: (
    handlers: Handlers.FromGroup<HttpApiGroup.WithIdentifier<Groups, Identifier>>
  ) => Handlers.ValidateReturn<Return>
) => Layer.Layer<
  HttpApiGroup.Service<ApiId, Identifier>,
  Handlers.Error<Return>,
  Exclude<Handlers.Context<Return>, Scope.Scope>
>

Source

Since v4.0.0

security

securityDecode

Decodes credentials for an HTTP API security scheme from the current request, supporting bearer, API key, and basic authentication inputs.

Signature

declare const securityDecode: <Security extends HttpApiSecurity.HttpApiSecurity>(
  self: Security
) => Effect.Effect<
  HttpApiSecurity.HttpApiSecurity.Type<Security>,
  never,
  HttpServerRequest | Request.ParsedSearchParams
>

Source

Since v4.0.0

securitySetCookie

Registers a pre-response handler that sets an API-key cookie on the outgoing response, defaulting the cookie to secure and httpOnly unless overridden.

Signature

declare const securitySetCookie: (
  self: HttpApiSecurity.ApiKey,
  value: string | Redacted.Redacted,
  options?: Cookie["options"]
) => Effect.Effect<void, never, HttpServerRequest>

Source

Since v4.0.0

utils

Handlers (namespace)

Namespace containing helper types for HttpApiBuilder handler collections.

Source

Since v4.0.0

FromGroup (type alias)

Creates a handler collection for a group where every endpoint in the group is still awaiting an implementation.

Signature

type FromGroup<Group> = Handlers<never, Group["endpoints"]>

Source

Since v4.0.0

ValidateReturn (type alias)

Validates the return value of a group handler builder, preserving successful handler collections and producing a descriptive type error when endpoints remain unhandled.

Signature

type ValidateReturn<A> = ValidateHandlersReturn<A>

Source

Since v4.0.0

Error (type alias)

Extracts the error channel from an effect that produces a Handlers collection, returning never for non-effectful handler collections.

Signature

type Error<A> =
  A extends Effect.Effect<
    Handlers<infer _R, infer _EndpointsByIdentifier, infer _HandledIdentifiers>,
    infer _EX,
    infer _RX
  >
    ? _EX
    : never

Source

Since v4.0.0

Context (type alias)

Extracts the services required by a handler collection, including both handler requirements and the environment required to construct the handlers.

Signature

type Context<A> =
  A extends Handlers<infer _R, infer _EndpointsByIdentifier, infer _HandledIdentifiers>
    ? _R
    : A extends Effect.Effect<
          Handlers<infer _R, infer _EndpointsByIdentifier, infer _HandledIdentifiers>,
          infer _EX,
          infer _RX
        >
      ? _R | _RX
      : never

Source

Since v4.0.0