notaphplover

Posted on Nov 7

Build HTTP APIs with Dependency Injection in TypeScript — Meet the Inversify Framework

#typescript #dependencyinversion #openapi

If you love clean architecture and TypeScript, this guide will show you how to build fast, maintainable HTTP APIs using the Inversify Framework — a decorator-driven, DI-first toolkit on top of InversifyJS.

Why another HTTP framework? (Short answer: DI done right)

Inversify brings a familiar pattern from large-scale systems — dependency injection — to your Node.js APIs with first-class TypeScript support. The result is code that’s:

Strongly typed: Compile-time safety and IDE autocomplete everywhere.
Lightning fast: Minimal overhead with production-ready performance.
Decorator-driven: Clean route, middleware, and schema definitions.
Framework agnostic: Use Express, Fastify, or others via adapters.
Highly extensible: Compose features with container modules and plugins.
Battle-tested: Used by thousands, with comprehensive docs.

Explore the docs: https://inversify.io/framework/

What we’ll build in this post

A tiny “Users” API that demonstrates:

A DI container wiring services and repositories
A REST controller using decorators
OpenAPI (v3.1.1) schemas and Swagger UI
An Express server bootstrapped via an adapter

The code snippets are taken from the repository example so you can trust the APIs match the real thing.

1) Install required dependencies

Install the core runtime, HTTP adapters, OpenAPI tooling, and supporting libraries:

npm install inversify reflect-metadata \
  @inversifyjs/http-core @inversifyjs/http-express @inversifyjs/http-open-api @inversifyjs/open-api-types \
  express lmdb

Install express types:

npm install -D typescript @types/express

2) Create a controller with decorators

Controllers are plain classes. Routes and bindings are expressed through decorators from @inversifyjs/http-core. Here’s a trimmed version of a real controller:

@Controller('/users')
@OasSummary('User management routes')
export class UserController {
  constructor(
    @inject(UserService) private readonly userService: UserService,
  ) {}

  @OasDescription('Registers a new user in the system')
  @OasOperationId('createUser')
  @OasRequestBody(
    (toSchema: ToSchemaFunction): OpenApi3Dot1RequestBodyObject => ({
      content: { 'application/json': { schema: toSchema(UserCreateQuery) } },
      description: 'User create query',
      required: true,
    }),
  )
  @OasResponse(
    HttpStatusCode.OK,
    (toSchema: ToSchemaFunction): OpenApi3Dot1ResponseObject => ({
      content: { 'application/json': { schema: toSchema(User) } },
      description: 'User created',
    }),
  )
  @OasTag('Users')
  @Post()
  public async register(@Body() userCreateQuery: UserCreateQuery): Promise<UserType> {
    const [user] = await this.userService.create(userCreateQuery);
    return user;
  }
}

What’s happening:

@Controller('/users') declares a route base.
@Post() maps the method to POST /users.
@Body() injects the request body.
OpenAPI decorators specify request/response schemas for docs and validation.

3) Model with OpenAPI schemas

Use decorators to describe your DTOs. This keeps your runtime types and your OpenAPI spec in sync:

import { OasSchema, OasSchemaProperty } from '@inversifyjs/http-open-api';

@OasSchema(undefined, {
  customAttributes: { unevaluatedProperties: false },
  name: 'User',
})
export class User {
  @OasSchemaProperty({ format: 'uuid', type: 'string' })
  public id!: string;

  @OasSchemaProperty({ format: 'email', type: 'string' })
  public email!: string;

  @OasSchemaProperty()
  public name!: string;

  @OasSchemaProperty()
  public surname!: string;
}

4) Business logic with DI (service + repository)

Services and repositories are classes annotated with @injectable() and wired with the container. They can be referenced by class or by token.

@injectable()
export class UserService {
  constructor(
    @inject(userPersistenceServiceServiceIdentifier)
    private readonly userPersistenceService: UserPersistenceService,
  ) {}

  public async create(...users: [UserCreateQueryType]): Promise<[UserType]>;
  public async create(...users: UserCreateQueryType[]): Promise<UserType[]>;
  public async create(...users: UserCreateQueryType[]): Promise<UserType[]> {
    return this.userPersistenceService.insert(...users);
  }
}

A simple repository implemented with LMDB (key-value store) looks like this:

@injectable()
export class LmdbUserRepository implements UserPersistenceService {
  constructor(@inject(lmdbDbServiceIdentifier) private readonly db: RootDatabase) {}

  public async insert(...userCreateQueries: UserCreateQueryDb[]): Promise<UserDb[]> {
    const users: UserDb[] = [];

    await this.db.transaction(async () => {
      for (const q of userCreateQueries) {
        const user: UserDb = { ...q, id: randomUUID() };
        await this.db.put(user.id, user);
        users.push(user);
      }
    });

    return users;
  }
}

5) Wire everything with container modules

Container modules are a clean way to keep bindings organized and composable:

export class UserContainerModule extends ContainerModule {
  constructor() {
    super((options: ContainerModuleLoadOptions) => {
      options.bind(UserController).toSelf().inSingletonScope();
      options.bind(UserService).toSelf().inSingletonScope();
    });
  }
}

Binding a token to a concrete repository:

export class UserLmdbContainerModule extends ContainerModule {
  constructor() {
    super((options: ContainerModuleLoadOptions) => {
      options
        .bind(userPersistenceServiceServiceIdentifier)
        .to(LmdbUserRepository)
        .inSingletonScope();
    });
  }
}

6) Bootstrap an Express server (and docs) in a few lines

Use the Express adapter and the Swagger UI provider from the framework packages:

const PORT = 3000;

export async function bootstrap(): Promise<void> {
  const container = new Container();

  await container.load(
    new LmdbContainerModule(),
    new UserContainerModule(),
    new UserLmdbContainerModule(),
  );

  const adapter = new InversifyExpressHttpAdapter(container, {
    logger: true,
    useCookies: false,
    useJson: true,
  });

  const swaggerProvider = new SwaggerUiProvider({
    api: {
      openApiObject: {
        info: { title: 'My awesome API', version: '1.0.0' },
        openapi: '3.1.1',
      },
      path: '/docs',
    },
    ui: { title: 'My awesome API docs' },
  });

  swaggerProvider.provide(container);

  const app: express.Application = await adapter.build();
  app.listen(PORT, () => {
    console.log(`Server started on http://localhost:${PORT}`);
  });
}

That’s it — your routes are discovered via the container, and your OpenAPI docs are available at /docs.

Where does this shine?

Large codebases: Constructor injection makes testing and refactoring painless.
Cross-cutting concerns: Middleware, logging, and auth are cleanly composed.
Multiple runtimes: Swap adapters (Express, Fastify, …) without rewriting controllers.
Schema-first teams: Generate and serve OpenAPI (v3.1.1) docs from your code.

Learn more and go deeper

Framework homepage: https://inversify.io/framework/
GitHub monorepo: https://github.com/inversify/monorepo
Example code in this post: https://github.com/inversify/monorepo/tree/main/packages/framework/http/tools/http-openapi-example
Community: Discord — https://discord.gg/jXcMagAPnm

Final thoughts

Inversify makes HTTP APIs feel like well-structured applications, not scripts. If you value clean boundaries, testability, and TypeScript ergonomics, it’s a perfect fit. Start small with a controller and a service — the DI container will grow with you.

DEV Community