Skip to main content

InversifyHttpAdapter

The base class all HTTP adapters extend (Express 4/5, Fastify, Hono, etc.). It wires controllers, guards, pipes, middleware, and interceptors into a working HTTP server. You generally consume its public methods from an adapter instance; if you are building a new adapter, implement the protected abstract methods described below.

Type parameters​

class InversifyHttpAdapter<
  TRequest,
  TResponse,
  // eslint-disable-next-line @typescript-eslint/no-explicit-any
  TNextFunction extends (err?: any) => Promise<void> | void,
  TResult,
  TOptions extends HttpAdapterOptions = HttpAdapterOptions,
>
  • TRequest: Native request type from the underlying framework (e.g., express.Request, FastifyRequest, HonoRequest).
  • TResponse: Native response type from the underlying framework (e.g., express.Response, FastifyReply, Context).
  • TNextFunction: Native “next” function type for chaining handlers.
  • TResult: Adapter-specific return type for handlers and replies.
  • TOptions: Adapter options shape. Defaults to HttpAdapterOptions.

Constructor​

constructor(
  container: Container,
  defaultHttpAdapterOptions: RequiredOptions<TOptions>,
  httpAdapterOptions: TOptions | undefined,
  awaitableRequestMethodParamTypes?: Iterable<RequestMethodParameterType> | undefined,
)

Creates an adapter instance bound to a DI container. Adapters typically invoke this from their subclass constructor and then expose a build() method that prepares the server.

  • container: The Inversify container that holds controllers, guards, pipes, middleware, interceptors, and filters.
  • defaultHttpAdapterOptions: The baseline options; merged with httpAdapterOptions.
  • httpAdapterOptions: Optional overrides. If logger is not false, route mappings will be logged on build.
  • awaitableRequestMethodParamTypes: Parameter types that should be awaited when building controller method arguments (e.g., when a parameter is resolved asynchronously). See parameter decorators under Controller.
Custom loggers

httpAdapterOptions can be use to provide a custom logger by setting the logger property to an object that implements the Logger interface from @inversifyjs/logger. This allows you to integrate your own logging solution with the adapter's logging mechanism.

Refer to the logger page for more details on how to implement and use a custom logger.

Public methods​

applyGlobalMiddleware​

applyGlobalMiddleware(
  ...middlewareList: (Newable<Middleware> | ApplyMiddlewareOptions)[]
): void

Registers global middleware to run for every route.

  • middlewareList: Either middleware classes or a structured object with preHandlerMiddlewareList and postHandlerMiddlewareList to control the phase. See Middleware.

Notes:

  • Must be called before the server is built; calling it after build() throws an error.
  • Pre-handler middleware run before the controller handler (after guards); post-handler middleware run after the handler.

useGlobalFilters​

useGlobalFilters(
  ...errorFilterList: Newable<ErrorFilter>[]
): void

Registers global error filters. When a handler, guard, pipe, middleware, or interceptor throws, the adapter looks up the most specific filter whose handled Error type matches the thrown error (by walking the prototype chain), or a catch-all filter bound to null if provided.

  • errorFilterList: Error filter classes to register globally.

Behavior:

  • If no filter handles the error, an InternalServerError response is produced unless the error itself is an ErrorHttpResponse, which is sent as-is.

applyGlobalGuards​

applyGlobalGuards(
  ...guardList: Newable<Guard<TRequest>>[]
): void

Registers global guards that run before middleware and route handlers. See Guard.

  • guardList: Guard classes to evaluate for every request.

Notes:

  • Must be called before the server is built; calling it after build() throws an error.
  • If any guard returns false, a 403 Forbidden is returned (unless the guard throws a specific ErrorHttpResponse).

useGlobalInterceptors​

useGlobalInterceptors(
  ...interceptorList: Newable<Interceptor<TRequest, TResponse>>[]
): void

Registers global interceptors that wrap route execution. Interceptors can run logic before and after the handler and may transform the handler result. See Interceptor.

  • interceptorList: Interceptor classes to apply globally.

Notes:

  • Must be called before the server is built; calling it after build() throws an error.

useGlobalPipe​

useGlobalPipe(
  ...pipeList: (Newable<Pipe> | Pipe)[]
): void

Registers global pipes that transform/validate controller method parameters immediately after extraction. See Pipe.

  • pipeList: Pipe classes or instances. Instances are used as provided; classes are resolved from the container per request.

Order of execution:

  • Global pipes run before parameter-level pipes declared via parameter decorators (e.g., @Body(ParseNumberPipe)).

build​

build(): Promise<unknown>

Abstract. Implemented by concrete adapters to build and return the underlying HTTP server or framework instance.