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

HttpApiBuilder.ts overview

Since v1.0.0

Exports Grouped by Category

constructors

api

Create a top-level HttpApi layer.

Signature

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

Source

Since v1.0.0

httpApp

Construct an HttpApp from an HttpApi instance.

Signature

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

Source

Since 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

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
>

Source

Since v1.0.0

toWebHandler

Construct an http web handler from an HttpApi instance.

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

Signature

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

Source

Since v1.0.0

global

MiddlewareFn (type alias)

Signature

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

Source

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

Source

Since v1.0.0

Handlers (namespace)

Source

Since v1.0.0

Any (interface)

Signature

export interface Any {
  readonly [HandlersTypeId]: any
}

Source

Since v1.0.0

Middleware (type alias)

Signature

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

Source

Since v1.0.0

Item (type alias)

Signature

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

Source

Since v1.0.0

FromGroup (type alias)

Signature

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

Source

Since v1.0.0

ValidateReturn (type alias)

Signature

type any = 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`

Source

Since v1.0.0

Error (type alias)

Signature

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

Source

Since v1.0.0

Context (type alias)

Signature

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

Source

Since v1.0.0

HandlersTypeId

Signature

declare const HandlersTypeId: unique symbol

Source

Since v1.0.0

HandlersTypeId (type alias)

Signature

type HandlersTypeId = typeof HandlersTypeId

Source

Since 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

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>,
  Exclude<Handlers.Context<Return> | HttpApiGroup.HttpApiGroup.MiddlewareWithName<Groups, Name>, Scope>
>

Source

Since v1.0.0

handler

Create a Handler for a single endpoint.

Signature

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
>

Source

Since v1.0.0

middleware

Middleware (class)

Signature

declare class Middleware

Source

Since v1.0.0

middleware

Create an HttpApi level middleware Layer.

Signature

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, Exclude<RX, Scope>>
  <R, EX = never, RX = never>(
    middleware: MiddlewareFn<never, R> | Effect.Effect<MiddlewareFn<never, R>, EX, RX>,
    options: { readonly withContext: true }
  ): Layer.Layer<never, EX, Exclude<HttpRouter.HttpRouter.ExcludeProvided<R> | RX, Scope>>
  <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, Exclude<RX, Scope>>
  <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, Exclude<HttpRouter.HttpRouter.ExcludeProvided<R> | RX, Scope>>
}

Source

Since v1.0.0

middlewareCors

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

Signature

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>

Source

Since v1.0.0

middlewareOpenApi

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

Signature

declare const middlewareOpenApi: (
  options?:
    | {
        readonly path?: HttpApiEndpoint.PathSegment | undefined
        readonly additionalPropertiesStrategy?: OpenApi.AdditionalPropertiesStrategy | undefined
      }
    | undefined
) => Layer.Layer<never, never, HttpApi.Api>

Source

Since 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

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

Source

Since v1.0.0

router

Router (class)

The router that the API endpoints are attached to.

Signature

declare class Router

Source

Since v1.0.0

security

securityDecode

Signature

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

Source

Since v1.0.0