HttpEffect.ts

HttpEffect.ts overview

Runs Effect HTTP server handlers at platform boundaries.

This module turns effects that produce HttpServerResponse values into Web Request handlers and other server adapters. It also applies middleware, converts failures into responses, runs hooks before a response is sent, and manages request scopes for streamed responses.

Since v4.0.0

Exports Grouped by Category

Pre-response handlers
- PreResponseHandler (type alias)
combinators
- toHandled
converting
fiber refs
resource management
- scopeDisableClose
- scopeTransferToStream

Pre-response handlers

PreResponseHandler (type alias)

Function run with the current request and response just before the response is sent, allowing the response to be replaced or failing with HttpServerError.

Signature

type PreResponseHandler = (
  request: HttpServerRequest,
  response: HttpServerResponse
) => Effect.Effect<HttpServerResponse, HttpServerError>

Source

Since v4.0.0

combinators

toHandled

Runs an HTTP server effect, sends the produced response with the supplied handler, and converts failures into HTTP responses.

Signature

declare const toHandled: <E, R, EH, RH>(
  self: Effect.Effect<HttpServerResponse, E, R>,
  handleResponse: (request: HttpServerRequest, response: HttpServerResponse) => Effect.Effect<unknown, EH, RH>,
  middleware?: HttpMiddleware | undefined
) => Effect.Effect<void, never, Exclude<R | RH | HttpServerRequest, Scope.Scope>>

Source

Since v4.0.0

converting

fromWebHandler

Adapts a Web Request handler into an HTTP server effect for the current HttpServerRequest.

Signature

declare const fromWebHandler: (
  handler: (request: Request) => Promise<Response>
) => Effect.Effect<HttpServerResponse, HttpServerError, HttpServerRequest>

Source

Since v4.0.0

toWebHandler

Converts an HTTP server effect into a Web Request handler using an empty base context.

Signature

declare const toWebHandler: <E>(
  self: Effect.Effect<HttpServerResponse, E, HttpServerRequest | Scope.Scope>,
  middleware?: HttpMiddleware | undefined
) => (request: Request, context?: Context.Context<never> | undefined) => Promise<globalThis.Response>

Source

Since v4.0.0

toWebHandlerLayer

Builds a Web Request handler for an HTTP server effect using a layer to provide its services, returning the handler with a dispose function.

Signature

declare const toWebHandlerLayer: <E, R, Provided, LE, ReqR = Exclude<R, Scope.Scope | HttpServerRequest | Provided>>(
  self: Effect.Effect<HttpServerResponse, E, R>,
  layer: Layer.Layer<Provided, LE>,
  options?:
    | { readonly middleware?: HttpMiddleware | undefined; readonly memoMap?: Layer.MemoMap | undefined }
    | undefined
) => {
  readonly dispose: () => Promise<void>
  readonly handler: [ReqR] extends [never]
    ? (request: Request, context?: Context.Context<never> | undefined) => Promise<globalThis.Response>
    : (request: Request, context: Context.Context<ReqR>) => Promise<globalThis.Response>
}

Source

Since v4.0.0

toWebHandlerLayerWith

Builds a Web Request handler from a layer and handler factory, returning the handler with a dispose function for the layer scope.

Signature

declare const toWebHandlerLayerWith: <
  E,
  Provided,
  LE,
  R,
  ReqR = Exclude<R, Scope.Scope | HttpServerRequest | Provided>
>(
  layer: Layer.Layer<Provided, LE>,
  options: {
    readonly toHandler: (
      context: Context.Context<Provided>
    ) => Effect.Effect<Effect.Effect<HttpServerResponse, E, R>, LE>
    readonly middleware?: HttpMiddleware | undefined
    readonly memoMap?: Layer.MemoMap | undefined
  }
) => {
  readonly dispose: () => Promise<void>
  readonly handler: [ReqR] extends [never]
    ? (request: Request, context?: Context.Context<never> | undefined) => Promise<globalThis.Response>
    : (request: Request, context: Context.Context<ReqR>) => Promise<globalThis.Response>
}

Source

Since v4.0.0

toWebHandlerWith

Converts an HTTP server effect into a Web Request handler using the supplied base context and optional middleware.

Signature

declare const toWebHandlerWith: <Provided, R = never, ReqR = Exclude<R, Scope.Scope | HttpServerRequest | Provided>>(
  context: Context.Context<Provided>
) => <E>(
  self: Effect.Effect<HttpServerResponse, E, R>,
  middleware?: HttpMiddleware | undefined
) => [ReqR] extends [never]
  ? (request: Request, context?: Context.Context<never> | undefined) => Promise<globalThis.Response>
  : (request: Request, context: Context.Context<ReqR>) => Promise<globalThis.Response>

Source

Since v4.0.0

fiber refs

appendPreResponseHandler

Registers an additional pre-response handler for the current HTTP server request.

Signature

declare const appendPreResponseHandler: (handler: PreResponseHandler) => Effect.Effect<void, never, HttpServerRequest>

Source

Since v4.0.0

appendPreResponseHandlerUnsafe

Registers a pre-response handler for the supplied HTTP server request.

Signature

declare const appendPreResponseHandlerUnsafe: (request: HttpServerRequest, handler: PreResponseHandler) => void

Source

Since v4.0.0

withPreResponseHandler

Runs an effect after registering a pre-response handler for the current HTTP server request.

Signature

declare const withPreResponseHandler: {
  (handler: PreResponseHandler): <A, E, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R | HttpServerRequest>
  <A, E, R>(self: Effect.Effect<A, E, R>, handler: PreResponseHandler): Effect.Effect<A, E, R | HttpServerRequest>
}

Source

Since v4.0.0

resource management

scopeDisableClose

Disables automatic closing for an HTTP request scope.

Gotchas

Use only when another owner will close the scope; otherwise resources attached to the request scope can leak.

Signature

declare const scopeDisableClose: (scope: Scope.Scope) => void

Source

Since v4.0.0

scopeTransferToStream

Returns a streaming server response that closes the request scope when the body stream exits.

Signature

declare const scopeTransferToStream: (response: HttpServerResponse) => HttpServerResponse

Source

Since v4.0.0