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