Forem: notaphplover

Building a Catalog GraphQL API with InversifyJS - Part 4: Subscriptions & Redis

notaphplover — Sat, 03 Jan 2026 22:15:51 +0000

In Part 3, we implemented the core resolvers for Queries and Mutations. In Part 4, we will add real-time capabilities to our API using GraphQL Subscriptions and Redis.

Step 1: Update Docker Compose

We need a Redis instance to handle our PubSub messaging.

Update docker-compose.yml to add the redis service:

      - db:/var/lib/postgresql/data
      - ./posgresql/init_shadow_db.sql:/docker-entrypoint-initdb.d/init_shadow_db.sql

+   redis:
+     image: redis:8.4.0-alpine
+     ports:
+       - '6379:6379'
+     networks:
+       - academy_manager
+
  networks:
    academy_manager:
      external: true

Step 2: Update GraphQL Schema

We need to define the Subscription type in our schema.

Update graphql/schemas/schema.graphql:

  type Mutation {
    createCategory(input: CreateCategoryInput!): Category!
    createProduct(input: CreateProductInput!): Product!
  }
+
+ type Subscription {
+   productAdded: Product!
+ }

Step 3: Redis Infrastructure

We need to set up the infrastructure to communicate with Redis. We'll use ioredis for this.

First, install the necessary dependencies:

pnpm add @inversifyjs/apollo-subscription-ws ioredis

PubSub Channels

Create src/foundation/redis/models/PubSubChannels.ts:

export enum PubSubChannel {
  productAdded = 'product:added',
}

Service Identifiers

We need identifiers for our Redis publisher and subscriber clients.

Create src/foundation/redis/models/ioredisPublisherServiceIdentifier.ts:

import { type ServiceIdentifier } from 'inversify';
import { type Redis } from 'ioredis';

export const ioredisPublisherServiceIdentifier: ServiceIdentifier<Redis> =
  Symbol.for(
    '@inversifyjs/example-catalog-graphql-api/ioredisPublisherService',
  );

Create src/foundation/redis/models/ioredisSubscriberServiceIdentifier.ts:

import { type ServiceIdentifier } from 'inversify';
import { type Redis } from 'ioredis';

export const ioredisSubscriberServiceIdentifier: ServiceIdentifier<Redis> =
  Symbol.for(
    '@inversifyjs/example-catalog-graphql-api/ioredisSubscriberService',
  );

PubSub Service

Now we implement the PubSubService which handles publishing and subscribing to Redis channels.

Create src/foundation/redis/services/PubSubService.ts:

import { inject, injectable } from 'inversify';
import { type Redis } from 'ioredis';

import { ioredisPublisherServiceIdentifier } from '../models/ioredisPublisherServiceIdentifier.js';
import { ioredisSubscriberServiceIdentifier } from '../models/ioredisSubscriberServiceIdentifier.js';

@injectable()
export class PubSubService {
  readonly #publisher: Redis;
  readonly #subscriber: Redis;

  constructor(
    @inject(ioredisPublisherServiceIdentifier)
    publisher: Redis,
    @inject(ioredisSubscriberServiceIdentifier)
    subscriber: Redis,
  ) {
    this.#publisher = publisher;
    this.#subscriber = subscriber;
  }

  public async publish(channel: string, message: unknown): Promise<void> {
    await this.#publisher.publish(channel, JSON.stringify(message));
  }

  public async *subscribe<T>(channel: string): AsyncGenerator<T> {
    await this.#subscriber.subscribe(channel);

    try {
      for await (const [
        receivedChannel,
        message,
      ] of this.#createMessageIterator()) {
        if (receivedChannel === channel) {
          yield JSON.parse(message) as T;
        }
      }
    } finally {
      await this.#subscriber.unsubscribe(channel);
    }
  }

  async *#createMessageIterator(): AsyncGenerator<[string, string]> {
    const messageQueue: Array<[string, string]> = [];
    let resolveNext:
      | ((value: IteratorResult<[string, string]>) => void)
      | null = null;

    const messageHandler: (channel: string, message: string) => void = (
      channel: string,
      message: string,
    ): void => {
      const item: [string, string] = [channel, message];
      if (resolveNext !== null) {
        resolveNext({ done: false, value: item });
        resolveNext = null;
      } else {
        messageQueue.push(item);
      }
    };

    this.#subscriber.on('message', messageHandler);

    try {
      // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
      while (true) {
        if (messageQueue.length > 0) {
          const item: [string, string] | undefined = messageQueue.shift();
          if (item !== undefined) {
            yield item;
          }
        } else {
          await new Promise<IteratorResult<[string, string]>>(
            (resolve: (value: IteratorResult<[string, string]>) => void) => {
              resolveNext = resolve;
            },
          ).then((result: IteratorResult<[string, string]>): void => {
            if (result.done === false) {
              messageQueue.push(result.value);
            }
          });
        }
      }
    } finally {
      this.#subscriber.off('message', messageHandler);
    }
  }
}

Redis Container Module

We need to bind the Redis clients and the PubSub service in a container module.

Create src/foundation/redis/modules/IoredisContainerModule.ts:

import 'dotenv/config';

import { ContainerModule, type ContainerModuleLoadOptions } from 'inversify';
import { Redis } from 'ioredis';

import { ioredisPublisherServiceIdentifier } from '../models/ioredisPublisherServiceIdentifier.js';
import { ioredisSubscriberServiceIdentifier } from '../models/ioredisSubscriberServiceIdentifier.js';
import { PubSubService } from '../services/PubSubService.js';

export class IoredisContainerModule extends ContainerModule {
  constructor() {
    super((options: ContainerModuleLoadOptions): void => {
      const redisConfig: { host: string; port: number } = {
        host: process.env['REDIS_HOST'] as string,
        port: parseInt(process.env['REDIS_PORT'] as string, 10),
      };

      options
        .bind(ioredisPublisherServiceIdentifier)
        .toConstantValue(new Redis(redisConfig));

      options
        .bind(ioredisSubscriberServiceIdentifier)
        .toConstantValue(new Redis(redisConfig));

      options.bind(PubSubService).toSelf().inSingletonScope();
    });
  }
}

Step 4: Implement Subscription Resolvers

Now we can implement the SubscriptionResolvers to handle the productAdded subscription.

Create src/app/resolvers/SubscriptionResolvers.ts:

import { inject, injectable } from 'inversify';

import { PubSubChannel } from '../../foundation/redis/models/PubSubChannels.js';
import { PubSubService } from '../../foundation/redis/services/PubSubService.js';
import { Context } from '../../graphql/models/Context.js';
import * as graphqlModels from '../../graphql/models/types.js';

@injectable()
export class SubscriptionResolvers implements graphqlModels.SubscriptionResolvers<Context> {
  public readonly productAdded: graphqlModels.SubscriptionSubscriberObject<
    graphqlModels.ResolverTypeWrapper<graphqlModels.Product>,
    'productAdded',
    unknown,
    Context,
    unknown
  >;

  readonly #pubSubService: PubSubService;

  constructor(
    @inject(PubSubService)
    pubSubService: PubSubService,
  ) {
    this.#pubSubService = pubSubService;

    const pubSubServiceRef: PubSubService = this.#pubSubService;

    this.productAdded = {
      subscribe: async function* (): AsyncGenerator<{
        productAdded: graphqlModels.ResolverTypeWrapper<graphqlModels.Product>;
      }> {
        for await (const product of pubSubServiceRef.subscribe<graphqlModels.Product>(
          PubSubChannel.productAdded,
        )) {
          yield { productAdded: product };
        }
      },
    };
  }
}

Step 5: Update Mutation Resolvers

We need to update the createProduct mutation to publish a message when a product is created.

Update src/app/resolvers/MutationResolvers.ts:

  import { inject, injectable } from 'inversify';
  import {
    type Category as CategoryDb,
    type Product as ProductDb,
  } from '../../../generated/index.js';
  import { CategoryRepository } from '../../category/repositories/CategoryRepository.js';
+ import { PubSubChannel } from '../../foundation/redis/models/PubSubChannels.js';
+ import { PubSubService } from '../../foundation/redis/services/PubSubService.js';
  import { type Context } from '../../graphql/models/Context.js';
  import type * as graphqlModels from '../../graphql/models/types.js';
  import { ProductRepository } from '../../product/repositories/ProductRepository.js';

  @injectable()
  export class MutationResolvers implements graphqlModels.MutationResolvers<Context> {
    readonly #categoryRepository: CategoryRepository;
    readonly #productRepository: ProductRepository;
+   readonly #pubSubService: PubSubService;

    constructor(
      @inject(CategoryRepository)
      categoryRepository: CategoryRepository,
      @inject(ProductRepository)
      productRepository: ProductRepository,
+     @inject(PubSubService)
+     pubSubService: PubSubService,
    ) {
      this.#categoryRepository = categoryRepository;
      this.#productRepository = productRepository;
+     this.#pubSubService = pubSubService;
    }

    public async createCategory(
      _parent: unknown,
      args: graphqlModels.MutationCreateCategoryArgs,
    ): Promise<graphqlModels.Category> {
      const category: CategoryDb = await this.#categoryRepository.createOne(
        args.input.name,
        args.input.slug,
      );

      return {
        id: category.id,
        name: category.name,
        products: {
          edges: [],
          pageInfo: {
            endCursor: null,
            hasNextPage: false,
            hasPreviousPage: false,
            startCursor: null,
            },
            totalCount: 0,
          },
          slug: category.slug,
        };
      }

    public async createProduct(
      _parent: unknown,
      args: graphqlModels.MutationCreateProductArgs,
    ): Promise<graphqlModels.Product> {
      const product: ProductDb = await this.#productRepository.createOne(
        args.input.categoryId,
        args.input.title,
        args.input.description,
        args.input.currency,
        args.input.price,
      );

-     return {
+     const productPayload: graphqlModels.Product = {
        currency: product.currency,
        description: product.description,
        id: product.id,
        price: product.price,
        title: product.title,
      };
+
+     await this.#pubSubService.publish(
+       PubSubChannel.productAdded,
+       productPayload,
+     );
+
+     return productPayload;
    }
  }

Step 6: Update App Container Module

Bind the SubscriptionResolvers in the AppContainerModule.

Update src/app/modules/AppContainerModule.ts:

  import { ContainerModule, type ContainerModuleLoadOptions } from 'inversify';
  import { AppResolvers } from '../resolvers/AppResolvers.js';
  import { MutationResolvers } from '../resolvers/MutationResolvers.js';
  import { QueryResolvers } from '../resolvers/QueryResolvers.js';
+ import { SubscriptionResolvers } from '../resolvers/SubscriptionResolvers.js';

  export class AppContainerModule extends ContainerModule {
    constructor() {
      super((options: ContainerModuleLoadOptions): void => {
        options.bind(AppResolvers).toSelf().inSingletonScope();
        options.bind(MutationResolvers).toSelf().inSingletonScope();
        options.bind(QueryResolvers).toSelf().inSingletonScope();
+       options.bind(SubscriptionResolvers).toSelf().inSingletonScope();
      });
    }
  }

Step 7: Update App Resolvers

Add the Subscription resolver to AppResolvers.

Update src/app/resolvers/AppResolvers.ts:

  import { inject, injectable } from 'inversify';
  import { CategoryResolvers } from '../../category/resolvers/CategoryResolvers.js';
  import { type Context } from '../../graphql/models/Context.js';
  import type * as graphqlModels from '../../graphql/models/types.js';
  import { MutationResolvers } from './MutationResolvers.js';
  import { QueryResolvers } from './QueryResolvers.js';
+ import { SubscriptionResolvers } from './SubscriptionResolvers.js';

  @injectable()
  export class AppResolvers implements Partial<graphqlModels.Resolvers<Context>> {
    public readonly Category: graphqlModels.CategoryResolvers<Context>;
    public readonly Mutation: graphqlModels.MutationResolvers<Context>;
    public readonly Query: graphqlModels.QueryResolvers<Context>;
+   public readonly Subscription: graphqlModels.SubscriptionResolvers<Context>;

    constructor(
      @inject(CategoryResolvers)
      categoryResolvers: CategoryResolvers,
      @inject(MutationResolvers)
      mutationResolvers: MutationResolvers,
      @inject(QueryResolvers)
      queryResolvers: QueryResolvers,
+     @inject(SubscriptionResolvers)
+     subscriptionResolvers: SubscriptionResolvers,
    ) {
      this.Category = categoryResolvers;
      this.Mutation = mutationResolvers;
      this.Query = queryResolvers;
+     this.Subscription = subscriptionResolvers;
    }
  }

Step 8: Update Server Bootstrap

Finally, we need to load the IoredisContainerModule and the ApolloSubscriptionServerContainerModule in our bootstrap script.

Update src/app/scripts/bootstrap.ts:

  import type http from 'node:http';
  import { type ExpressContextFunctionArgument } from '@as-integrations/express5';
  import {
    type InversifyApolloProvider,
    inversifyApolloProviderServiceIdentifier,
  } from '@inversifyjs/apollo-core';
  import { ApolloExpressServerContainerModule } from '@inversifyjs/apollo-express';
+ import { ApolloSubscriptionServerContainerModule } from '@inversifyjs/apollo-subscription-ws';
  import { readSchemas } from '@inversifyjs/graphql-codegen';
  import { InversifyExpressHttpAdapter } from '@inversifyjs/http-express';
  import { Container } from 'inversify';

  import { CategoryContainerModule } from '../../category/modules/CategoryContainerModule.js';
  import { PrismaModule } from '../../foundation/db/modules/PrismaModule.js';
+ import { IoredisContainerModule } from '../../foundation/redis/modules/IoredisContainerModule.js';
  import { type Context } from '../../graphql/models/Context.js';
  import { ProductContainerModule } from '../../product/modules/ProductContainerModule.js';
  import { AppContainerModule } from '../modules/AppContainerModule.js';
  import { AppResolvers } from '../resolvers/AppResolvers.js';

  const PORT: number = 3000;

  const container: Container = new Container();

  await container.load(
    new AppContainerModule(),
    ApolloExpressServerContainerModule.graphServerFromOptions<Context>(
      {
        controllerOptions: {
          path: '',
        },
        getContext: async (
          arg: ExpressContextFunctionArgument,
        ): Promise<Context> => ({
          request: arg.req,
        }),
      },
      {
        resolverServiceIdentifier: AppResolvers,
        typeDefs: await readSchemas({
          glob: {
            patterns: ['./graphql/schemas/**/*.graphql'],
          },
        }),
      },
    ),
+   new ApolloSubscriptionServerContainerModule({
+     path: '/subscriptions',
+   }),
    new CategoryContainerModule(),
+   new IoredisContainerModule(),
    new PrismaModule(),
    new ProductContainerModule(),
  );

  const adapter: InversifyExpressHttpAdapter = new InversifyExpressHttpAdapter(
    container,
  );

Conclusion

We have successfully added real-time capabilities to our API! We can now subscribe to productAdded events and receive updates whenever a new product is created.

Building a Catalog GraphQL API with InversifyJS - Part 3: Implementing Resolvers & Server Setup

notaphplover — Sat, 03 Jan 2026 22:15:34 +0000

In Part 2, we set up our database with Prisma and implemented our repositories. Now, in Part 3, we will implement the GraphQL resolvers and wire everything together using InversifyJS to create a running Apollo Server.

Step 1: Defining the Context

First, let's define the Context interface that will be passed to our resolvers. This usually contains the request object and any other global state.

Create src/graphql/models/Context.ts:

import type express from 'express';

export interface Context {
  readonly request: express.Request;
}

Step 2: Updating Repositories

Before we implement the resolvers, we need to add some methods to our repositories to support the queries and mutations we'll be implementing.

Category Repository

Update src/category/repositories/CategoryRepository.ts to add createOne, findPaginatedAll, and findOneById:

  import { inject, injectable } from "inversify";
- import { PrismaClient } from "../../../generated/index.js";
+ import { Category, PrismaClient } from "../../../generated/index.js";

  @injectable()
  export class CategoryRepository {
    readonly #client: PrismaClient;

    constructor(@inject(PrismaClient) client: PrismaClient) {
      this.#client = client;
    }

    public async count(): Promise<number> {
      return this.#client.category.count();
    }
+
+   public async createOne(name: string, slug: string): Promise<Category> {
+     return this.#client.category.create({
+       data: {
+         name,
+         slug,
+       },
+     });
+   }
+
+   public async findPaginatedAll(
+     first: number,
+     after?: string,
+   ): Promise<Category[]> {
+     return this.#client.category.findMany({
+       cursor: after ? { id: after } : undefined,
+       skip: after ? 1 : 0,
+       take: first,
+     });
+   }
+
+   public async findOneById(id: string): Promise<Category | undefined> {
+     const category = await this.#client.category.findUnique({
+       where: { id },
+     });
+     return category ?? undefined;
+   }
  }

Product Repository

Update src/product/repositories/ProductRepository.ts to add createOne, findPaginatedAllByCategoryId, countByCategoryId, and findOneById:

  import { inject, injectable } from "inversify";
- import { PrismaClient } from "../../../generated/index.js";
+ import { PrismaClient, Product } from "../../../generated/index.js";

  @injectable()
  export class ProductRepository {
    readonly #client: PrismaClient;

    constructor(@inject(PrismaClient) client: PrismaClient) {
      this.#client = client;
    }

    public async count(): Promise<number> {
      return this.#client.product.count();
    }
+
+   public async createOne(
+     categoryId: string,
+     title: string,
+     description: string,
+     currency: string,
+     price: number,
+   ): Promise<Product> {
+     return this.#client.product.create({
+       data: {
+         categoryId,
+         currency,
+         description,
+         price,
+         title,
+       },
+     });
+   }
+
+   public async findPaginatedAllByCategoryId(
+     categoryId: string,
+     first: number,
+     after?: string,
+   ): Promise<Product[]> {
+     return this.#client.product.findMany({
+       cursor: after ? { id: after } : undefined,
+       skip: after ? 1 : 0,
+       take: first,
+       where: { categoryId },
+     });
+   }
+
+   public async countByCategoryId(categoryId: string): Promise<number> {
+     return this.#client.product.count({
+       where: { categoryId },
+     });
+   }
+
+   public async findOneById(id: string): Promise<Product | undefined> {
+     const product = await this.#client.product.findUnique({
+       where: { id },
+     });
+     return product ?? undefined;
+   }
  }

Step 3: Implementing Resolvers

We will implement our resolvers as injectable classes. This allows us to inject our repositories directly into them.

Category Resolvers

We need to implement the Category field resolvers, specifically for the products field, to handle the relationship between Category and Product. We'll implement full pagination logic here.

Create src/category/resolvers/CategoryResolvers.ts:

import { inject, injectable } from 'inversify';
import { type Product as ProductDb } from '../../../generated/index.js';
import { Context } from '../../graphql/models/Context.js';
import type * as graphqlModels from '../../graphql/models/types.js';
import { ProductRepository } from '../../product/repositories/ProductRepository.js';

const MAX_ELEMENTS_PER_PAGE: number = 20;

@injectable()
export class CategoryResolvers implements graphqlModels.CategoryResolvers<Context> {
  readonly #productRepository: ProductRepository;

  constructor(
    @inject(ProductRepository)
    productRepository: ProductRepository,
  ) {
    this.#productRepository = productRepository;
  }

  public id(parent: graphqlModels.Category): string {
    return parent.id;
  }

  public name(parent: graphqlModels.Category): string {
    return parent.name;
  }

  public async products(
    parent: graphqlModels.Category,
    args: Partial<graphqlModels.CategoryProductsArgs>,
  ): Promise<graphqlModels.ProductConnection> {
    const firstValue: number = Math.max(
      Math.min(args.first ?? MAX_ELEMENTS_PER_PAGE, MAX_ELEMENTS_PER_PAGE),
      0,
    );

    const [productsDb, totalCount]: [ProductDb[], number] = await Promise.all([
      this.#productRepository.findPaginatedAllByCategoryId(
        parent.id,
        firstValue,
        args.after ?? undefined,
      ),
      this.#productRepository.countByCategoryId(parent.id),
    ]);

    const endCursor: string | null =
      productsDb.length > 0
        ? (productsDb[productsDb.length - 1]?.id ?? null)
        : null;

    const startCursor: string | null =
      productsDb.length > 0 ? (productsDb[0]?.id ?? null) : null;

    return {
      edges: productsDb.map((product: ProductDb) => ({
        cursor: product.id,
        node: {
          currency: product.currency,
          description: product.description,
          id: product.id,
          price: product.price,
          title: product.title,
        },
      })),
      pageInfo: {
        endCursor,
        hasNextPage: productsDb.length === firstValue,
        hasPreviousPage: args.after != null,
        startCursor,
      },
      totalCount,
    };
  }

  public slug(parent: graphqlModels.Category): string {
    return parent.slug;
  }
}

Query Resolvers

Now let's implement the root Query resolvers, including pagination for categories and fetching individual items.

Create src/app/resolvers/QueryResolvers.ts:

import { inject, injectable } from 'inversify';
import {
  type Category as CategoryDb,
  type Product as ProductDb,
} from '../../../generated/index.js';
import { CategoryRepository } from '../../category/repositories/CategoryRepository.js';
import { type Context } from '../../graphql/models/Context.js';
import type * as graphqlModels from '../../graphql/models/types.js';
import { ProductRepository } from '../../product/repositories/ProductRepository.js';

const MAX_ELEMENTS_PER_PAGE: number = 20;

@injectable()
export class QueryResolvers implements graphqlModels.QueryResolvers<Context> {
  readonly #categoryRepository: CategoryRepository;
  readonly #productRepository: ProductRepository;

  constructor(
    @inject(CategoryRepository)
    categoryRepository: CategoryRepository,
    @inject(ProductRepository)
    productRepository: ProductRepository,
  ) {
    this.#categoryRepository = categoryRepository;
    this.#productRepository = productRepository;
  }

  public async categories(
    _parent: unknown,
    args: graphqlModels.QueryCategoriesArgs,
  ): Promise<graphqlModels.CategoryConnection> {
    const firstValue: number = Math.max(
      Math.min(args.first ?? MAX_ELEMENTS_PER_PAGE, MAX_ELEMENTS_PER_PAGE),
      0,
    );

    const [categoriesDb, totalCount]: [CategoryDb[], number] =
      await Promise.all([
        this.#categoryRepository.findPaginatedAll(
          firstValue,
          args.after ?? undefined,
        ),
        this.#categoryRepository.count(),
      ]);

    const endCursor: string | null =
      categoriesDb.length > 0
        ? (categoriesDb[categoriesDb.length - 1]?.id ?? null)
        : null;

    const startCursor: string | null =
      categoriesDb.length > 0 ? (categoriesDb[0]?.id ?? null) : null;

    return {
      edges: categoriesDb.map((category: CategoryDb) => ({
        cursor: category.id,
        node: {
          id: category.id,
          name: category.name,
          slug: category.slug,
        },
      })),
      pageInfo: {
        endCursor,
        hasNextPage: categoriesDb.length === firstValue,
        hasPreviousPage: args.after != null,
        startCursor,
      },
      totalCount,
    };
  }

  public async category(
    _parent: unknown,
    args: graphqlModels.QueryCategoryArgs,
  ): Promise<Partial<graphqlModels.Category> | null> {
    const categoryDb: CategoryDb | undefined =
      await this.#categoryRepository.findOneById(args.id);

    if (categoryDb === undefined) {
      return null;
    }

    return {
      id: categoryDb.id,
      name: categoryDb.name,
      slug: categoryDb.slug,
    };
  }

  public async product(
    _parent: unknown,
    args: graphqlModels.QueryProductArgs,
  ): Promise<graphqlModels.Product | null> {
    const productDb: ProductDb | undefined =
      await this.#productRepository.findOneById(args.id);

    if (productDb === undefined) {
      return null;
    }

    return {
      currency: productDb.currency,
      description: productDb.description,
      id: productDb.id,
      price: productDb.price,
      title: productDb.title,
    };
  }
}

Mutation Resolvers

Create src/app/resolvers/MutationResolvers.ts:

import { inject, injectable } from 'inversify';
import {
  type Category as CategoryDb,
  type Product as ProductDb,
} from '../../../generated/index.js';
import { CategoryRepository } from '../../category/repositories/CategoryRepository.js';
import { type Context } from '../../graphql/models/Context.js';
import type * as graphqlModels from '../../graphql/models/types.js';
import { ProductRepository } from '../../product/repositories/ProductRepository.js';

@injectable()
export class MutationResolvers implements graphqlModels.MutationResolvers<Context> {
  readonly #categoryRepository: CategoryRepository;
  readonly #productRepository: ProductRepository;

  constructor(
    @inject(CategoryRepository)
    categoryRepository: CategoryRepository,
    @inject(ProductRepository)
    productRepository: ProductRepository,
  ) {
    this.#categoryRepository = categoryRepository;
    this.#productRepository = productRepository;
  }

  public async createCategory(
    _parent: unknown,
    args: graphqlModels.MutationCreateCategoryArgs,
  ): Promise<graphqlModels.Category> {
    const category: CategoryDb = await this.#categoryRepository.createOne(
      args.input.name,
      args.input.slug,
    );

    return {
      id: category.id,
      name: category.name,
      products: {
        edges: [],
        pageInfo: {
          endCursor: null,
          hasNextPage: false,
          hasPreviousPage: false,
          startCursor: null,
        },
        totalCount: 0,
      },
      slug: category.slug,
    };
  }

  public async createProduct(
    _parent: unknown,
    args: graphqlModels.MutationCreateProductArgs,
  ): Promise<graphqlModels.Product> {
    const product: ProductDb = await this.#productRepository.createOne(
      args.input.categoryId,
      args.input.title,
      args.input.description,
      args.input.currency,
      args.input.price,
    );

    return {
      currency: product.currency,
      description: product.description,
      id: product.id,
      price: product.price,
      title: product.title,
    };
  }
}

App Resolvers

Finally, we aggregate all resolvers into a single AppResolvers class.

Create src/app/resolvers/AppResolvers.ts:

import { inject, injectable } from 'inversify';
import { CategoryResolvers } from '../../category/resolvers/CategoryResolvers.js';
import { type Context } from '../../graphql/models/Context.js';
import type * as graphqlModels from '../../graphql/models/types.js';
import { MutationResolvers } from './MutationResolvers.js';
import { QueryResolvers } from './QueryResolvers.js';

@injectable()
export class AppResolvers implements Partial<graphqlModels.Resolvers<Context>> {
  public readonly Category: graphqlModels.CategoryResolvers<Context>;
  public readonly Mutation: graphqlModels.MutationResolvers<Context>;
  public readonly Query: graphqlModels.QueryResolvers<Context>;

  constructor(
    @inject(CategoryResolvers)
    categoryResolvers: CategoryResolvers,
    @inject(MutationResolvers)
    mutationResolvers: MutationResolvers,
    @inject(QueryResolvers)
    queryResolvers: QueryResolvers,
  ) {
    this.Category = categoryResolvers;
    this.Mutation = mutationResolvers;
    this.Query = queryResolvers;
  }
}

Step 4: Wiring the Container

We need to bind our resolvers in the Inversify container.

Update Category Container Module

We need to update the CategoryContainerModule to bind the CategoryResolvers.

Update src/category/modules/CategoryContainerModule.ts:

  import { ContainerModule, type ContainerModuleLoadOptions } from 'inversify';
  import { CategoryRepository } from '../repositories/CategoryRepository.js';
+ import { CategoryResolvers } from '../resolvers/CategoryResolvers.js';

  export class CategoryContainerModule extends ContainerModule {
    constructor() {
      super((options: ContainerModuleLoadOptions): void => {
        options.bind(CategoryRepository).toSelf().inSingletonScope();
+       options.bind(CategoryResolvers).toSelf().inSingletonScope();
      });
    }
  }

Create App Container Module

We also need a module for the application-level resolvers.

Create src/app/modules/AppContainerModule.ts:

import { ContainerModule, type ContainerModuleLoadOptions } from 'inversify';
import { AppResolvers } from '../resolvers/AppResolvers.js';
import { MutationResolvers } from '../resolvers/MutationResolvers.js';
import { QueryResolvers } from '../resolvers/QueryResolvers.js';

export class AppContainerModule extends ContainerModule {
  constructor() {
    super((options: ContainerModuleLoadOptions): void => {
      options.bind(AppResolvers).toSelf().inSingletonScope();
      options.bind(MutationResolvers).toSelf().inSingletonScope();
      options.bind(QueryResolvers).toSelf().inSingletonScope();
    });
  }
}

Step 5: Server Bootstrap

Now we will create the entry point of our application, where we set up the Inversify container, load all modules, and start the Apollo Server.

Create src/app/scripts/bootstrap.ts:

import type http from 'node:http';
import { type ExpressContextFunctionArgument } from '@as-integrations/express5';
import {
  type InversifyApolloProvider,
  inversifyApolloProviderServiceIdentifier,
} from '@inversifyjs/apollo-core';
import { ApolloExpressServerContainerModule } from '@inversifyjs/apollo-express';
import { readSchemas } from '@inversifyjs/graphql-codegen';
import { InversifyExpressHttpAdapter } from '@inversifyjs/http-express';
import { Container } from 'inversify';

import { CategoryContainerModule } from '../../category/modules/CategoryContainerModule.js';
import { PrismaModule } from '../../foundation/db/modules/PrismaModule.js';
import { type Context } from '../../graphql/models/Context.js';
import { ProductContainerModule } from '../../product/modules/ProductContainerModule.js';
import { AppContainerModule } from '../modules/AppContainerModule.js';
import { AppResolvers } from '../resolvers/AppResolvers.js';

const PORT: number = 3000;

const container: Container = new Container();

await container.load(
  new AppContainerModule(),
  ApolloExpressServerContainerModule.graphServerFromOptions<Context>(
    {
      controllerOptions: {
        path: '',
      },
      getContext: async (
        arg: ExpressContextFunctionArgument,
      ): Promise<Context> => ({
        request: arg.req,
      }),
    },
    {
      resolverServiceIdentifier: AppResolvers,
      typeDefs: await readSchemas({
        glob: {
          patterns: ['./graphql/schemas/**/*.graphql'],
        },
      }),
    },
  ),
  new CategoryContainerModule(),
  new PrismaModule(),
  new ProductContainerModule(),
);

const adapter: InversifyExpressHttpAdapter = new InversifyExpressHttpAdapter(
  container,
);

await adapter.build();

const inversifyApolloProvider: InversifyApolloProvider<http.Server> =
  await container.getAsync(inversifyApolloProviderServiceIdentifier);

await new Promise<void>((resolve: () => void) => {
  inversifyApolloProvider.server.listen(PORT, () => {
    resolve();
  });
});

console.log(`Server is running on http://localhost:${PORT.toString()}`);

And finally, update src/index.ts to import the bootstrap script:

import './app/scripts/bootstrap.js';

Conclusion

We have successfully implemented our GraphQL resolvers and set up the Apollo Server using InversifyJS. We can now run our application and interact with our API!

In the next part, we will implement graphql subscriptions on top of web sockets and a Redis Pub/Sub pattern.

Building a Catalog GraphQL API with InversifyJS - Part 2: Database Setup with Prisma & Docker

notaphplover — Sat, 03 Jan 2026 22:15:16 +0000

In Part 1, we set up our project structure and GraphQL type generation. In this second part, we will focus on the persistence layer. We will set up a PostgreSQL database using Docker, configure Prisma as our ORM, and implement our first repositories.

Step 1: Setting up PostgreSQL with Docker

To keep our development environment clean and consistent, we will run our database in a Docker container. We also need to create a shadow database for Prisma migrations. We'll use an initialization script for this.

First, create a directory postgresql and a file init_shadow_db.sql inside it:

CREATE DATABASE catalog_db_shadow;

Now, create a docker-compose.yml file in the root of your project:

services:
  db:
    image: postgres:16-alpine
    environment:
      - POSTGRES_USER=postgres_user
      - POSTGRES_PASSWORD=password
      - POSTGRES_DB=catalog_db
    ports:
      - '5432:5432'
    volumes:
      - db_data:/var/lib/postgresql/data
      - ./postgresql/init_shadow_db.sql:/docker-entrypoint-initdb.d/init_shadow_db.sql

volumes:
  db_data:
    driver: local

Now, you can start the database by running:

docker compose up -d

This will start a PostgreSQL instance listening on port 5432.

Step 2: Installing and Configuring Prisma

Prisma is a modern ORM that we will use to interact with our database.

First, install the dependencies:

pnpm add @prisma/client @prisma/adapter-pg
pnpm add -D prisma

Initialize Prisma in your project:

pnpm exec prisma init

This creates a prisma directory with a schema.prisma file and adds a .env file to your project.

We will use a prisma.config.mjs file to configure Prisma. Create this file in the root of your project:

import path from 'node:path';
import 'dotenv/config';
import { defineConfig, env } from 'prisma/config';

export default defineConfig({
  datasource: {
    url: env('DATABASE_CONNECTION_STRING'),
    shadowDatabaseUrl: env('SHADOW_DATABASE_CONNECTION_STRING'),
  },
  schema: path.join('prisma', 'schema.prisma'),
});

Update your .env file to point to your local Docker database:

DATABASE_CONNECTION_STRING="postgresql://postgres_user:password@localhost:5432/catalog_db?schema=public"
SHADOW_DATABASE_CONNECTION_STRING="postgresql://postgres_user:password@localhost:5432/catalog_db_shadow?schema=public"

Step 3: Defining the Data Model

Open prisma/schema.prisma and define your data models. We will create Category and Product models. Note that we are generating the client to a custom location ../generated to keep it within our project structure.

generator client {
  provider = "prisma-client-js"
  output   = "../generated"
}

datasource db {
  provider = "postgresql"
}

model Category {
  id        String    @id @default(uuid(7)) @db.Uuid
  name      String
  slug      String    @unique
  createdAt DateTime  @default(now())
  updatedAt DateTime  @default(now()) @updatedAt
  products  Product[]

  @@map("category")
}

model Product {
  id          String   @id @default(uuid(7)) @db.Uuid
  categoryId  String   @db.Uuid
  title       String
  description String
  currency    String
  price       Float
  createdAt   DateTime @default(now())
  updatedAt   DateTime @default(now()) @updatedAt
  category    Category @relation(fields: [categoryId], references: [id], onDelete: NoAction)

  @@map("product")
}

Step 4: Running Migrations

Now that we have our schema defined, let's create a migration to apply these changes to the database.

pnpm exec prisma migrate dev --name init

This command will:

Generate a SQL migration file.
Execute the SQL against your database.
Generate the Prisma Client.

Step 5: Implementing Repositories

We will use the Repository Pattern to abstract our data access logic. This makes our code more testable and decoupled.

First, we need to make sure PrismaClient is available for injection. We will import it from our generated client.

Category Repository

Create src/category/repositories/CategoryRepository.ts:

import { inject, injectable } from 'inversify';
import { PrismaClient } from '../../../generated/index.js';

@injectable()
export class CategoryRepository {
  readonly #client: PrismaClient;

  constructor(
    @inject(PrismaClient) client: PrismaClient
  ) {
    this.#client = client;
  }

  public async count(): Promise<number> {
    return this.#client.category.count();
  }
}

Product Repository

Create src/product/repositories/ProductRepository.ts:

import { inject, injectable } from 'inversify';
import { PrismaClient } from '../../../generated/index.js';

@injectable()
export class ProductRepository {
  readonly #client: PrismaClient;

  constructor(
    @inject(PrismaClient) client: PrismaClient
  ) {
    this.#client = client;
  }

  public async count(): Promise<number> {
    return this.#client.product.count();
  }
}

Step 6: Dependency Injection Setup

Now that we have our repositories, we need to configure our InversifyJS container modules. We will create separate modules for our database connection and our domain features.

Prisma Module

First, let's create a module to manage the PrismaClient instance. This ensures we have a single instance of the database client throughout our application. We will use the PrismaPg adapter for PostgreSQL.

Create src/foundation/db/modules/PrismaModule.ts:

import { PrismaPg } from '@prisma/adapter-pg';
import { ContainerModule, type ContainerModuleLoadOptions } from 'inversify';
import { PrismaClient } from '../../../../generated/index.js';

export class PrismaModule extends ContainerModule {
  constructor() {
    super((options: ContainerModuleLoadOptions) => {
      options.bind(PrismaClient).toConstantValue(
        new PrismaClient({
          adapter: new PrismaPg({
            connectionString:
              'postgresql://postgres_user:password@localhost:5432/catalog_db?schema=public',
          }),
        }),
      );
    });
  }
}

Category Module

Next, we create a module for the Category feature. This module will bind the CategoryRepository.

Create src/category/modules/CategoryContainerModule.ts:

import { ContainerModule, type ContainerModuleLoadOptions } from 'inversify';
import { CategoryRepository } from '../repositories/CategoryRepository.js';

export class CategoryContainerModule extends ContainerModule {
  constructor() {
    super((options: ContainerModuleLoadOptions): void => {
      options.bind(CategoryRepository).toSelf().inSingletonScope();
    });
  }
}

Product Module

Similarly, we create a module for the Product feature.

Create src/product/modules/ProductContainerModule.ts:

import { ContainerModule, type ContainerModuleLoadOptions } from 'inversify';
import { ProductRepository } from '../repositories/ProductRepository.js';

export class ProductContainerModule extends ContainerModule {
  constructor() {
    super((options: ContainerModuleLoadOptions): void => {
      options.bind(ProductRepository).toSelf().inSingletonScope();
    });
  }
}

Conclusion

In this part, we have successfully:

Set up a PostgreSQL database using Docker.
Configured Prisma and defined our database schema.
Implemented our repositories using InversifyJS for dependency injection.
Created InversifyJS container modules to manage our dependencies.

In the next part, we will wire everything together in the main application container and start building our GraphQL resolvers.

Building a Catalog GraphQL API with InversifyJS - Part 1: Project Setup & Type Generation

notaphplover — Sat, 03 Jan 2026 22:14:52 +0000

Welcome to this series where we will build a complete Catalog GraphQL API using InversifyJS. In this first part, we will set up our project structure, configure TypeScript, and establish a build flow that automatically generates TypeScript types from our GraphQL schemas.

Overview

We are going to build a backend service that allows managing products and categories. We will use:

Node.js & TypeScript as our runtime and language.
InversifyJS for Dependency Injection.
GraphQL for our API query language.
Apollo Server to serve our GraphQL API.
Prisma (in later parts) for database access.

You can access the final implementation in our framework examples monorepo.

Step 1: Project Initialization

First, let's create a new directory for our project and initialize it. We will be setting this up as a standalone repository (not a monorepo).

mkdir catalog-graphql-api
cd catalog-graphql-api
pnpm init

Now, let's install the necessary dependencies.

Runtime Dependencies

pnpm add inversify reflect-metadata graphql @apollo/server express @inversifyjs/http-express @inversifyjs/apollo-express @inversifyjs/http-core @inversifyjs/apollo-core dotenv

Development Dependencies

We need TypeScript and some tools for our build process.

pnpm add -D typescript @types/node ts-node @inversifyjs/graphql-codegen rimraf prettier

Configure ESM

We will be using ECMAScript Modules (ESM) for this project. Open your package.json and ensure you have "type": "module" set. This is important for top-level await support in our scripts.

{
  "name": "catalog-graphql-api",
  "version": "1.0.0",
  "type": "module",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  }
}

Step 2: TypeScript Configuration

Create a tsconfig.json file in the root of your project. This configures how TypeScript compiles our code.

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "lib": ["ES2022"],
    "outDir": "./lib",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  },
  "include": ["src"]
}

Note: experimentalDecorators and emitDecoratorMetadata are crucial for InversifyJS to work correctly.

Step 3: Defining GraphQL Schemas

We will define our GraphQL schemas in .graphql files. This allows us to keep our schema definitions clean and separate from our code.

Create a directory structure graphql/schemas:

mkdir -p graphql/schemas

Let's create a common schema file graphql/schemas/common.graphql for shared types:

type PageInfo {
  hasNextPage: Boolean!
  hasPreviousPage: Boolean!
  startCursor: String
  endCursor: String
}

interface Node {
  id: ID!
}

And a main schema file graphql/schemas/schema.graphql. We'll add a simple query to start with:

# import * from "common.graphql"

type Query {
  hello: String
}

Step 4: Generating TypeScript Types

One of the best practices in GraphQL development is to generate TypeScript types from your schema. This ensures that your resolvers are type-safe and match your schema definition.

We will use @inversifyjs/graphql-codegen for this. Create a script file at src/scripts/generateGraphqlTypes.ts.

import { generateTsModels } from '@inversifyjs/graphql-codegen';
import * as prettier from 'prettier';

// Basic prettier config
const prettierConfig: prettier.Options = {
  parser: 'typescript',
  singleQuote: true,
  trailingComma: 'all',
};

await generateTsModels({
  destinationPath: './src/graphql/models/types.ts',
  pluginConfig: {
    avoidOptionals: false,
    enumsAsTypes: true,
    resolverTypeWrapperSignature: 'Partial<T> | Promise<Partial<T>>',
    useIndexSignature: false,
  },
  prettierConfig,
  schemas: {
    glob: {
      patterns: ['./graphql/schemas/*.graphql'],
    },
  },
});

This script does the following:

Reads all .graphql files in graphql/schemas.
Generates TypeScript interfaces and types.
Saves them to src/graphql/models/types.ts.

Step 5: Configuring Build Scripts

Now, let's add some scripts to our package.json to run the generation and build the project.

Update the scripts section in package.json:

"scripts": {
  "build": "tsc && pnpm run generate:graphql:types",
  "build:clean": "rimraf lib",
  "generate:graphql:types": "ts-node ./src/scripts/generateGraphqlTypes.ts",
  "prebuild": "pnpm run build:clean"
}

We use ts-node to run our generation script directly without compiling it first.

Step 6: Running the Build

Now you can run the build command:

pnpm run build

If everything is set up correctly, you should see a new file generated at src/graphql/models/types.ts containing the TypeScript definitions for your GraphQL schema.

Conclusion

We have successfully set up our project structure and a build pipeline that ensures our TypeScript types are always in sync with our GraphQL schema.

In the next part, we will implement the InversifyJS container, set up the Apollo Server, and create our first resolvers.

Build a Type-Safe Live Chat with Inversify and SSE

notaphplover — Sun, 07 Dec 2025 01:15:21 +0000

Real-time applications are everywhere. From live support chats to stock tickers, users expect instant updates. While WebSockets are often the go-to solution, Server-Sent Events (SSE) provide a simpler, lighter alternative for unidirectional (server-to-client) data flow.

In this tutorial, we'll build a multi-channel live chat API using InversifyJS for dependency injection and Hono as our high-performance web framework.

💡 Get the Code: The complete source code for this example is available in the InversifyJS Framework Examples repository.

Why this stack?

InversifyJS: Provides powerful Dependency Injection (DI) to keep your services and controllers decoupled and testable.
Hono: A small, fast, and web-standards based web framework that runs anywhere (Node.js, Bun, Deno, Cloudflare Workers).
SSE: Native browser support, automatic reconnection, and no need for heavy WebSocket protocols for simple broadcast scenarios.

1. Project Setup

First, let's install the necessary dependencies. We need inversify for DI, hono for the server, and the Inversify adapters.

npm install hono inversify reflect-metadata @inversifyjs/http-hono @inversifyjs/http-sse @hono/node-server

Note: Make sure you have experimentalDecorators and emitDecoratorMetadata enabled in your tsconfig.json.

2. Define the Typed Message

We start by defining what our chat message looks like. Using TypeScript interfaces ensures type safety throughout our app.

// src/types/ChatMessage.ts
export interface ChatMessage {
  content: string;
  sender: string;
  timestamp?: string;
}

3. The Channel Service

The heart of our real-time logic. This service manages active SSE connections (streams) for each chat channel.

// src/services/ChannelService.ts
import { injectable } from 'inversify';
import { SseStream } from '@inversifyjs/http-sse';
import { ChatMessage } from '../types/ChatMessage.js';

@injectable()
export class ChannelService {
  // Store active streams per channel
  private readonly channels: Map<string, Set<SseStream>> = new Map();

  public subscribe(channelId: string): SseStream {
    if (!this.channels.has(channelId)) {
      this.channels.set(channelId, new Set());
    }

    const streams = this.channels.get(channelId);
    if (!streams) {
      throw new Error(`Channel ${channelId} not found`);
    }

    const stream = new SseStream();
    streams.add(stream);

    // Cleanup on disconnect
    stream.on('close', () => {
      streams.delete(stream);
      if (streams.size === 0) {
        this.channels.delete(channelId);
      }
    });

    return stream;
  }

  public async publish(channelId: string, message: ChatMessage): Promise<void> {
    const streams = this.channels.get(channelId);
    if (!streams) return;

    // Broadcast message to all connected clients in the channel
    const promises = Array.from(streams).map(async (stream) =>
      stream.writeMessageEvent({
        data: JSON.stringify(message),
        type: 'message',
      }),
    );

    await Promise.all(promises);
  }
}

4. The Controller

We use Inversify's @Controller to define our API endpoints.

GET /channels/:channelId/messages: Subscribes a client to the channel using @SsePublisher.
POST /channels/:channelId/messages: Publishes a new message.

// src/controllers/ChannelController.ts
import { Controller, Get, Post, Body, Params } from '@inversifyjs/http-core';
import {
  SsePublisher,
  SsePublisherOptions,
  SseStream,
} from '@inversifyjs/http-sse';
import { inject } from 'inversify';
import { ChannelService } from '../services/ChannelService.js';
import { ChatMessage } from '../types/ChatMessage.js';

@Controller('/channels')
export class ChannelController {
  constructor(
    @inject(ChannelService) private readonly channelService: ChannelService,
  ) {}

  @Get('/:channelId/messages')
  public subscribe(
    @Params('channelId') channelId: string,
    @SsePublisher() publisher: (options: SsePublisherOptions) => unknown,
  ): unknown {
    const stream: SseStream = this.channelService.subscribe(channelId);
    // Return the stream wrapped in the publisher
    return publisher({ events: stream });
  }

  @Post('/:channelId/messages')
  public async publish(
    @Params('channelId') channelId: string,
    @Body() body: ChatMessage,
  ): Promise<void> {
    await this.channelService.publish(channelId, body);
  }
}

5. Wiring It All Together

Finally, we set up the Inversify container and the Hono adapter.

// src/index.ts
import 'reflect-metadata';
import { Container } from 'inversify';
import { InversifyHonoHttpAdapter } from '@inversifyjs/http-hono';
import { serve } from '@hono/node-server';
import { ChannelService } from './services/ChannelService.js';
import { ChannelController } from './controllers/ChannelController.js';

async function main() {
  const container = new Container();

  // Bind dependencies
  container.bind(ChannelService).toSelf().inSingletonScope();
  container.bind(ChannelController).toSelf();

  // Create the Hono App with Inversify
  const adapter = new InversifyHonoHttpAdapter(container);
  const app = await adapter.build();

  console.log('Server started on http://localhost:3000');

  serve({
    fetch: app.fetch,
    port: 3000,
  });
}

await main();

Conclusion

With just a few files, we've created a scalable, type-safe architecture for real-time communication. The combination of Hono's speed and InversifyJS's structure makes it easy to build and maintain complex applications.

Check out the full InversifyJS framework Documentation for more examples!

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

notaphplover — Fri, 07 Nov 2025 12:37:47 +0000

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.