Fastify TOAB (Typed OpenAPI + BullMQ)

Fastify TOAB is a plugin for Fastify that provides strongly-typed OpenAPI route generation and seamless BullMQ worker integration. It comes with CLI code generation to scaffold controllers, services, middleware, and workers.

Table of Contents

1. Installation
2. Features
3. Code Generation
4. Setup
5. Controller
6. Service
7. Middleware
8. Worker
9. Registries
10. Testing
11. Contributing
12. License

---

Installation

Install the package via npm or pnpm:

1npm install @csi-foxbyte/fastify-toab
2# or using pnpm
3pnpm add @csi-foxbyte/fastify-toab

Features

• Typed Controllers & Routes with built-in OpenAPI support
• Service Container for dependency injection
• Middleware creation with shared context
• BullMQ Worker registration and queue integration
• CLI for scaffolding boilerplate code

Code Generation

Generate a new controller or service:

1pnpm fastify-toab create <controller|service> <Name>

Generate a new worker under an existing service:

1pnpm fastify-toab create worker <ParentService> <Name>

Generate a middleware template:

1pnpm fastify-toab create middleware <Name>

Note: Workers must live under a service component. Create the service first before adding workers.

Setup

Register the plugin in your Fastify application:

1import Fastify from "fastify";
2import fastifyToab from "@csi-foxbyte/fastify-toab";
3import { getRegistries } from "./registries.js";
4
5const fastify = Fastify();
6
7fastify.register(fastifyToab, { getRegistries });
8
9(async () => {
10  await fastify.ready();
11
12  await fastify.listen({
13    host: "0.0.0.0",
14    port: Number(process.env.PORT ?? 5000),
15  });
16})();

• getRegistries: Function that returns all registered controllers, services, middleware, and workers (auto-generated).

Controller

Controllers define HTTP routes in a typed manner. Example:

1import { createController } from "@csi-foxbyte/fastify-toab";
2import { authMiddleware } from "../auth/auth.middleware.js";
3
4export const userController = createController()
5  .use(authMiddleware)
6  .rootPath("/user");
7
8userController.addRoute("GET", "/test").handler(async (req, res) => {
9  // req and res are strongly typed based on OpenAPI schemas
10  return { message: "Hallo Welt!" };
11});

Each controller must be exported and registered via the generated registries.

Service

Services encapsulate business logic and can depend on other services.

1import {
2  createService,
3  InferService,
4  ServiceContainer,
5} from "@csi-foxbyte/fastify-toab";
6
7export const userService = createService("user", async () => {
8  // implement your service methods here
9  return {
10    getSession: async () => { /* ... */ },
11    // etc.
12  };
13});
14
15export type UserService = InferService<typeof userService>;
16
17export function getUserService(deps: ServiceContainer): UserService {
18  return deps.get(userService.name);
19}

• createService: Define a new service namespace.
• InferService: Type helper to infer the service interface.
• ServiceContainer: DI container for accessing services.

Middleware

Middleware allows injecting shared context into routes.

1import { createMiddleware, GenericRouteError } from "@csi-foxbyte/fastify-toab";
2import { getAuthService } from "./auth.service.js";
3
4export const authMiddleware = createMiddleware(async ({ ctx, services }, next) => {
5  const auth = getAuthService(services);
6  const session = await auth.getSession();
7
8  if (!session) {
9    throw new GenericRouteError(
10      "UNAUTHORIZED",
11      "User must be authenticated",
12      { session },
13    );
14  }
15
16  // extend context with session
17  await next({ ctx: { ...ctx, session } });
18});

• createMiddleware: Wraps route handlers to provide shared logic and context.
• GenericRouteError: Standardized error for HTTP responses.

Worker

Workers process background jobs using BullMQ.

1import {
2  createWorker,
3  QueueContainer,
4  WorkerContainer,
5  Job,
6} from "@csi-foxbyte/fastify-toab";
7
8export const deleteUserWorker = createWorker()
9  .queue("deleteUser-queue")
10  .job<Job<{ userId: string }, void>>()
11  .connection({ /* BullMQ connection options */ })
12  .processor(async (job) => {
13    // process job.data.userId
14    return;
15  });
16
17export function getDeleteUserWorker(deps: WorkerContainer) {
18  return deps.get(deleteUserWorker.queueName);
19}
20
21export function getDeleteUserWorkerQueue(deps: QueueContainer) {
22  return deps.get(deleteUserWorker.queueName);
23}

• createWorker: Starts a worker builder.
• queue: Sets the queue name.
• job: Defines job data and return types.
• connection: Configures Redis/BullMQ connection.
• processor: Job handler function.

Registries

Registries are auto-generated indexes of all controllers, services, middleware, and workers. They live in ./src/registries.js (or .ts).

1pnpm fastify-toab rebuild

This command regenerates the registries after creating new artifacts.

Testing

For examples and integration tests, refer to the tests/ directory:

1pnpm test

Ensure your generated code passes the existing test suite and add new tests for custom logic.

Contributing

1. Fork the repository
2. Create a feature branch
3. Commit your changes with clear messages
4. Open a pull request and describe the feature / bugfix

Please follow the repository’s code style guidelines.

License

LGPL3.0 © CSI Foxbyte