HttpApiBuilder

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.

7 exports Added in v4.0.0 Source

Handlers

endpoint

Added in v4.0.0 Source

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 function endpoint<
  ApiId extends string,
  Groups extends Constraint,
  GroupIdentifier extends string,
  EndpointIdentifier extends string,
  R,
>(
  api: HttpApi<ApiId, Groups>,
  groupIdentifier: GroupIdentifier,
  endpointIdentifier: EndpointIdentifier,
  handler: HandlerWithIdentifier<
    Endpoints<
      Extract<
        Groups,
        {
          readonly identifier: GroupIdentifier;
        }
      >
    >
  >,
): EndpointReturn<Groups, GroupIdentifier, EndpointIdentifier, R>;

group

Added in v4.0.0 Source

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 function group<
  ApiId extends string,
  Groups extends Constraint,
  Identifier extends string,
  Return,
>(
  api: HttpApi<ApiId, Groups>,
  groupIdentifier: Identifier,
  build: (
    handlers: FromGroup<
      Extract<
        Groups,
        {
          readonly identifier: Identifier;
        }
      >
    >,
  ) => ValidateHandlersReturn<Return>,
): Layer<Service<ApiId, Identifier>, Error<Return>, Exclude<Context<Return>, Scope>>;

Handlers interface

Added in v4.0.0 Source

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

interface Handlers<
  R,
  EndpointsByIdentifier extends Record<string, HttpApiEndpoint.Constraint> = {},
  HandledIdentifiers extends keyof EndpointsByIdentifier = never,
> extends Pipeable {
  readonly "~effect/httpapi/HttpApiBuilder/Handlers": "~effect/httpapi/HttpApiBuilder/Handlers";
  readonly "~EndpointsByIdentifier": EndpointsByIdentifier;
  readonly "~HandledIdentifiers": HandledIdentifiers;
  handle<Identifier extends string | number | symbol, R1>(
    identifier: Identifier & NotHandledIdentifier<Identifier, HandledIdentifiers>,
    handler: Handler<
      EndpointsByIdentifier[Identifier],
      MiddlewareError<EndpointsByIdentifier[Identifier]>,
      R1
    >,
    options?: {
      readonly uninterruptible?: boolean;
    },
  ): Handlers<
    | R
    | HandlerRequirements<
        EndpointsByIdentifier[Identifier],
        R1,
        | Exclude<R1, Provided | Provides<Middleware<EndpointsByIdentifier[Identifier]>>>
        | Exclude<
            ServerServices<EndpointsByIdentifier[Identifier]>,
            Provided | Provides<Middleware<EndpointsByIdentifier[Identifier]>>
          >
      >,
    EndpointsByIdentifier,
    HandledIdentifiers | Identifier
  >;
  handleAll<
    HandlersByIdentifier extends HandleAllHandlers<Omit<EndpointsByIdentifier, HandledIdentifiers>>,
  >(
    handlers: HandlersByIdentifier &
      HandleAllExtraKeys<Omit<EndpointsByIdentifier, HandledIdentifiers>, HandlersByIdentifier>,
  ): Handlers<
    R | HandleAllRequirements<EndpointsByIdentifier, HandlersByIdentifier>,
    EndpointsByIdentifier,
    HandledIdentifiers | (keyof HandlersByIdentifier & keyof EndpointsByIdentifier)
  >;
  handleRaw<Identifier extends string | number | symbol, R1>(
    identifier: Identifier & NotHandledIdentifier<Identifier, HandledIdentifiers>,
    handler: HandlerRaw<
      EndpointsByIdentifier[Identifier],
      MiddlewareError<EndpointsByIdentifier[Identifier]>,
      R1
    >,
    options?: {
      readonly uninterruptible?: boolean;
    },
  ): Handlers<
    | R
    | HandlerRequirements<
        EndpointsByIdentifier[Identifier],
        R1,
        | Exclude<R1, Provided | Provides<Middleware<EndpointsByIdentifier[Identifier]>>>
        | Exclude<
            ServerServices<EndpointsByIdentifier[Identifier]>,
            Provided | Provides<Middleware<EndpointsByIdentifier[Identifier]>>
          >
      >,
    EndpointsByIdentifier,
    HandledIdentifiers | Identifier
  >;
}

Layers

layer

Added in v4.0.0 Source

Registers an HttpApi with a HttpRouter.

Signature

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

Signature

declare function securityDecode<Security extends HttpApiSecurity>(
  self: Security,
): Effect<Type<Security>, never, HttpServerRequest | ParsedSearchParams>;

securitySetCookie

Added in v4.0.0 Source

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 function securitySetCookie(
  self: ApiKey,
  value: string | Redacted<string>,
  options?: {
    readonly domain?: string;
    readonly expires?: Date;
    readonly httpOnly?: boolean;
    readonly maxAge?: Input;
    readonly partitioned?: boolean;
    readonly path?: string;
    readonly priority?: "low" | "medium" | "high";
    readonly sameSite?: "none" | "lax" | "strict";
    readonly secure?: boolean;
  },
): Effect<void, never, HttpServerRequest>;