Skip to content

HttpEffect

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.

12 exports Added in v4.0.0 Source

Combinators

toHandled

Added in v4.0.0 Source

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

Signature

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

Converting

fromWebHandler

Added in v4.0.0 Source

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

Signature

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

toWebHandler

Added in v4.0.0 Source

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,
) => (request: Request, context?: Context.Context<never>) => Promise<globalThis.Response>;

toWebHandlerLayer

Added in v4.0.0 Source

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

toWebHandlerLayerWith

Added in v4.0.0 Source

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

Signature

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

toWebHandlerWith

Added in v4.0.0 Source

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

Signature

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

Handlers

appendPreResponseHandler

Added in v4.0.0 Source

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

Signature

declare function appendPreResponseHandler(
  handler: PreResponseHandler,
): Effect<void, never, HttpServerRequest>;

PreResponseHandler type

Added in v4.0.0 Source

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

withPreResponseHandler

Added in v4.0.0 Source

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<A, E, R>) => Effect<A, E, HttpServerRequest | R>;
  <A, E, R>(
    self: Effect<A, E, R>,
    handler: PreResponseHandler,
  ): Effect<A, E, HttpServerRequest | R>;
};

Resource Management

scopeDisableClose

Added in v4.0.0 Source

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 function scopeDisableClose(scope: Scope): void;

scopeTransferToStream

Added in v4.0.0 Source

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

Signature

declare function scopeTransferToStream(response: HttpServerResponse): HttpServerResponse;

Unsafe

appendPreResponseHandlerUnsafe

Added in v4.0.0 Source

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

Signature

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