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.

Adapter-Specific Documentation​

For concrete adapter implementations with constructor signatures, options, and usage examples:

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​

Global context

Some of this methods set global middleware, guards, pipes, interceptors, or error filters that apply to all routes managed by this adapter instance. Routes not managed by this adapter (e.g., routes added directly to the underlying server) are unaffected.

applyGlobalMiddleware​

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

Registers global middleware to run for every route.

  • middlewareList: Either middleware service identifiers (class references or symbols) 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: ServiceIdentifier<Guard<TRequest>>[]
): void

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

  • guardList: Guard service identifiers (class references or symbols) 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: ServiceIdentifier<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 service identifiers (class references or symbols) to apply globally.

Notes:

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

useGlobalPipe​

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

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

  • pipeList: Pipe service identifiers (class references or symbols) or pipe instances. Instances are used as provided; service identifiers 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.