Skip to main content Link Search Menu Expand Document (external link)
effect

HttpApiBuilder overview

Added in v1.0.0

Table of contents

constructors

api

Create a top-level HttpApi layer.

Signature

export declare const api: <Id extends string, Groups extends HttpApiGroup.HttpApiGroup.Any, E, R>(
  api: HttpApi.HttpApi<Id, Groups, E, R>
) => Layer.Layer<
  HttpApi.Api,
  never,
  HttpApiGroup.HttpApiGroup.ToService<Id, Groups> | R | HttpApiGroup.HttpApiGroup.ErrorContext<Groups>
>

Added in v1.0.0

httpApp

Construct an HttpApp from an HttpApi instance.

Signature

export declare const httpApp: Effect.Effect<
  Effect.Effect<A, E, HttpServerRequest.HttpServerRequest | R>,
  never,
  HttpApi.Api | Router | Middleware
>

Added in v1.0.0

serve

Build an HttpApp from an HttpApi instance, and serve it using an HttpServer.

Optionally, you can provide a middleware function that will be applied to the HttpApp before serving.

Signature

export declare const serve: <R = never>(
  middleware?: (httpApp: HttpApp.Default) => HttpApp.Default<never, R>
) => Layer.Layer<
  never,
  never,
  | HttpServer.HttpServer
  | HttpRouter.HttpRouter.DefaultServices
  | Exclude<R, Scope | HttpServerRequest.HttpServerRequest>
  | HttpApi.Api
>

Added in v1.0.0

toWebHandler

Construct an http web handler from an HttpApi instance.

Signature

export declare const toWebHandler: <LA, LE>(
  layer: Layer.Layer<LA | HttpApi.Api | HttpRouter.HttpRouter.DefaultServices, LE>,
  options?: {
    readonly middleware?: (
      httpApp: HttpApp.Default
    ) => HttpApp.Default<never, HttpApi.Api | Router | HttpRouter.HttpRouter.DefaultServices>
    readonly memoMap?: Layer.MemoMap
  }
) => {
  readonly handler: (request: Request, context?: Context.Context<never> | undefined) => Promise<Response>
  readonly dispose: () => Promise<void>
}

Example

import { HttpApi, HttpApiBuilder, HttpServer } from "@effect/platform"
import { Layer } from "effect"

class MyApi extends HttpApi.make("api") {}

const MyApiLive = HttpApiBuilder.api(MyApi)

const { dispose, handler } = HttpApiBuilder.toWebHandler(
  Layer.mergeAll(
    MyApiLive,
    // you could also use NodeHttpServer.layerContext, depending on your
    // server's platform
    HttpServer.layerContext
  )
)

Added in v1.0.0

global

MiddlewareFn (type alias)

Signature

export type MiddlewareFn<Error, R = HttpRouter.HttpRouter.Provided> = (
  httpApp: HttpApp.Default
) => HttpApp.Default<Error, R>

Added in v1.0.0

handlers

Handlers (interface)

Represents a handled HttpApi.

Signature

export interface Handlers<E, Provides, R, Endpoints extends HttpApiEndpoint.HttpApiEndpoint.Any = never>
  extends Pipeable {
  readonly [HandlersTypeId]: {
    _Endpoints: Covariant<Endpoints>
  }
  readonly group: HttpApiGroup.HttpApiGroup.AnyWithProps
  readonly handlers: Chunk.Chunk<Handlers.Item<E, R>>

  /**
   * Add the implementation for an `HttpApiEndpoint` to a `Handlers` group.
   */
  handle<Name extends HttpApiEndpoint.HttpApiEndpoint.Name<Endpoints>, R1>(
    name: Name,
    handler: HttpApiEndpoint.HttpApiEndpoint.HandlerWithName<Endpoints, Name, E, R1>
  ): Handlers<
    E,
    Provides,
    | R
    | Exclude<
        HttpApiEndpoint.HttpApiEndpoint.ExcludeProvided<
          Endpoints,
          Name,
          R1 | HttpApiEndpoint.HttpApiEndpoint.ContextWithName<Endpoints, Name>
        >,
        Provides
      >,
    HttpApiEndpoint.HttpApiEndpoint.ExcludeName<Endpoints, Name>
  >

  /**
   * Add the implementation for an `HttpApiEndpoint` to a `Handlers` group.
   * This version of the api allows you to return the full response object.
   */
  handleRaw<Name extends HttpApiEndpoint.HttpApiEndpoint.Name<Endpoints>, R1>(
    name: Name,
    handler: HttpApiEndpoint.HttpApiEndpoint.HandlerResponseWithName<Endpoints, Name, E, R1>
  ): Handlers<
    E,
    Provides,
    | R
    | Exclude<
        HttpApiEndpoint.HttpApiEndpoint.ExcludeProvided<
          Endpoints,
          Name,
          R1 | HttpApiEndpoint.HttpApiEndpoint.ContextWithName<Endpoints, Name>
        >,
        Provides
      >,
    HttpApiEndpoint.HttpApiEndpoint.ExcludeName<Endpoints, Name>
  >
}

Added in v1.0.0

Handlers (namespace)

Added in v1.0.0

Any (interface)

Signature

export interface Any {
  readonly [HandlersTypeId]: any
}

Added in v1.0.0

Context (type alias)

Signature

export type Context<A> =
  A extends Handlers<infer _E, infer _Provides, infer _R, infer _Endpoints>
    ? _R
    : A extends Effect.Effect<Handlers<infer _E, infer _Provides, infer _R, infer _Endpoints>, infer _EX, infer _RX>
      ? _R | _RX
      : never

Added in v1.0.0

Error (type alias)

Signature

export type Error<A> =
  A extends Effect.Effect<Handlers<infer _E, infer _Provides, infer _R, infer _Endpoints>, infer _EX, infer _RX>
    ? _EX
    : never

Added in v1.0.0

FromGroup (type alias)

Signature

export type FromGroup<ApiError, ApiR, Group extends HttpApiGroup.HttpApiGroup.Any> = Handlers<
  ApiError | HttpApiGroup.HttpApiGroup.Error<Group>,
  HttpApiMiddleware.HttpApiMiddleware.ExtractProvides<ApiR> | HttpApiGroup.HttpApiGroup.Provides<Group>,
  never,
  HttpApiGroup.HttpApiGroup.Endpoints<Group>
>

Added in v1.0.0

Item (type alias)

Signature

export type Item<E, R> = {
  readonly endpoint: HttpApiEndpoint.HttpApiEndpoint.Any
  readonly handler: HttpApiEndpoint.HttpApiEndpoint.Handler<any, E, R>
  readonly withFullResponse: boolean
}

Added in v1.0.0

Middleware (type alias)

Signature

export type Middleware<E, R, E1, R1> = (self: HttpRouter.Route.Middleware<E, R>) => HttpApp.Default<E1, R1>

Added in v1.0.0

ValidateReturn (type alias)

Signature

export type ValidateReturn<A> = A extends
  | Handlers<infer _E, infer _Provides, infer _R, infer _Endpoints>
  | Effect.Effect<Handlers<infer _E, infer _Provides, infer _R, infer _Endpoints>, infer _EX, infer _RX>
  ? [_Endpoints] extends [never]
    ? A
    : `Endpoint not handled: ${HttpApiEndpoint.HttpApiEndpoint.Name<_Endpoints>}`
  : `Must return the implemented handlers`

Added in v1.0.0

HandlersTypeId

Signature

export declare const HandlersTypeId: typeof HandlersTypeId

Added in v1.0.0

HandlersTypeId (type alias)

Signature

export type HandlersTypeId = typeof HandlersTypeId

Added in v1.0.0

group

Create a Layer that will implement all the endpoints in an HttpApi.

An unimplemented Handlers instance is passed to the build function, which you can use to add handlers to the group.

You can implement endpoints using the handlers.handle api.

Signature

export declare const group: <
  ApiId extends string,
  Groups extends HttpApiGroup.HttpApiGroup.Any,
  ApiError,
  ApiR,
  const Name extends HttpApiGroup.HttpApiGroup.Name<Groups>,
  Return
>(
  api: HttpApi.HttpApi<ApiId, Groups, ApiError, ApiR>,
  groupName: Name,
  build: (
    handlers: Handlers.FromGroup<ApiError, ApiR, HttpApiGroup.HttpApiGroup.WithName<Groups, Name>>
  ) => Handlers.ValidateReturn<Return>
) => Layer.Layer<
  HttpApiGroup.ApiGroup<ApiId, Name>,
  Handlers.Error<Return>,
  Handlers.Context<Return> | HttpApiGroup.HttpApiGroup.MiddlewareWithName<Groups, Name>
>

Added in v1.0.0

handler

Create a Handler for a single endpoint.

Signature

export declare const handler: <
  ApiId extends string,
  Groups extends HttpApiGroup.HttpApiGroup.Any,
  ApiError,
  ApiR,
  const GroupName extends Groups["identifier"],
  const Name extends HttpApiGroup.HttpApiGroup.EndpointsWithName<Groups, GroupName>["name"],
  R
>(
  _api: HttpApi.HttpApi<ApiId, Groups, ApiError, ApiR>,
  _groupName: GroupName,
  _name: Name,
  f: HttpApiEndpoint.HttpApiEndpoint.HandlerWithName<
    HttpApiGroup.HttpApiGroup.EndpointsWithName<Groups, GroupName>,
    Name,
    ApiError | HttpApiGroup.HttpApiGroup.ErrorWithName<Groups, GroupName>,
    R
  >
) => HttpApiEndpoint.HttpApiEndpoint.HandlerWithName<
  HttpApiGroup.HttpApiGroup.EndpointsWithName<Groups, GroupName>,
  Name,
  ApiError | HttpApiGroup.HttpApiGroup.ErrorWithName<Groups, GroupName>,
  R
>

Added in v1.0.0

middleware

Middleware (class)

Signature

export declare class Middleware

Added in v1.0.0

middleware

Create an HttpApi level middleware Layer.

Signature

export declare const middleware: {
  <EX = never, RX = never>(
    middleware: MiddlewareFn<never> | Effect.Effect<MiddlewareFn<never>, EX, RX>,
    options?: { readonly withContext?: false | undefined }
  ): Layer.Layer<never, EX, RX>
  <R, EX = never, RX = never>(
    middleware: MiddlewareFn<never, R> | Effect.Effect<MiddlewareFn<never, R>, EX, RX>,
    options: { readonly withContext: true }
  ): Layer.Layer<never, EX, HttpRouter.HttpRouter.ExcludeProvided<R> | RX>
  <ApiId extends string, Groups extends HttpApiGroup.HttpApiGroup.Any, Error, ErrorR, EX = never, RX = never>(
    api: HttpApi.HttpApi<ApiId, Groups, Error, ErrorR>,
    middleware: MiddlewareFn<NoInfer<Error>> | Effect.Effect<MiddlewareFn<NoInfer<Error>>, EX, RX>,
    options?: { readonly withContext?: false | undefined }
  ): Layer.Layer<never, EX, RX>
  <ApiId extends string, Groups extends HttpApiGroup.HttpApiGroup.Any, Error, ErrorR, R, EX = never, RX = never>(
    api: HttpApi.HttpApi<ApiId, Groups, Error, ErrorR>,
    middleware: MiddlewareFn<NoInfer<Error>, R> | Effect.Effect<MiddlewareFn<NoInfer<Error>, R>, EX, RX>,
    options: { readonly withContext: true }
  ): Layer.Layer<never, EX, HttpRouter.HttpRouter.ExcludeProvided<R> | RX>
}

Added in v1.0.0

middlewareCors

A CORS middleware layer that can be provided to the HttpApiBuilder.serve layer.

Signature

export declare const middlewareCors: (
  options?:
    | {
        readonly allowedOrigins?: ReadonlyArray<string> | undefined
        readonly allowedMethods?: ReadonlyArray<string> | undefined
        readonly allowedHeaders?: ReadonlyArray<string> | undefined
        readonly exposedHeaders?: ReadonlyArray<string> | undefined
        readonly maxAge?: number | undefined
        readonly credentials?: boolean | undefined
      }
    | undefined
) => Layer.Layer<never>

Added in v1.0.0

middlewareOpenApi

A middleware that adds an openapi.json endpoint to the API.

Signature

export declare const middlewareOpenApi: (
  options?: { readonly path?: HttpRouter.PathInput | undefined } | undefined
) => Layer.Layer<never, never, HttpApi.Api>

Added in v1.0.0

middlewareScoped

Create an HttpApi level middleware Layer, that has a Scope provided to the constructor.

Signature

export declare const middlewareScoped: {
  <EX, RX>(
    middleware: Effect.Effect<MiddlewareFn<never>, EX, RX>,
    options?: { readonly withContext?: false | undefined }
  ): Layer.Layer<never, EX, Exclude<RX, Scope>>
  <R, EX, RX>(
    middleware: Effect.Effect<MiddlewareFn<never, R>, EX, RX>,
    options: { readonly withContext: true }
  ): Layer.Layer<never, EX, HttpRouter.HttpRouter.ExcludeProvided<R> | Exclude<RX, Scope>>
  <ApiId extends string, Groups extends HttpApiGroup.HttpApiGroup.Any, Error, ErrorR, EX, RX>(
    api: HttpApi.HttpApi<ApiId, Groups, Error, ErrorR>,
    middleware: Effect.Effect<MiddlewareFn<NoInfer<Error>>, EX, RX>,
    options?: { readonly withContext?: false | undefined }
  ): Layer.Layer<never, EX, Exclude<RX, Scope>>
  <ApiId extends string, Groups extends HttpApiGroup.HttpApiGroup.Any, Error, ErrorR, R, EX, RX>(
    api: HttpApi.HttpApi<ApiId, Groups, Error, ErrorR>,
    middleware: Effect.Effect<MiddlewareFn<NoInfer<Error>, R>, EX, RX>,
    options: { readonly withContext: true }
  ): Layer.Layer<never, EX, HttpRouter.HttpRouter.ExcludeProvided<R> | Exclude<RX, Scope>>
}

Added in v1.0.0

securitySetCookie

Set a cookie from an HttpApiSecurity.HttpApiKey instance.

You can use this api before returning a response from an endpoint handler.

handlers.handle("authenticate", (_) => HttpApiBuilder.securitySetCookie(security, "secret123"))

Signature

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

Added in v1.0.0

router

Router (class)

The router that the API endpoints are attached to.

Signature

export declare class Router

Added in v1.0.0

security

securityDecode

Signature

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

Added in v1.0.0