DEV Community: Orinda Felix Ochieng

KickJS: Decorator-Driven APIs on Express 5 — NestJS Ergonomics, Zero Overhead

Orinda Felix Ochieng — Thu, 26 Mar 2026 15:57:16 +0000

I built a Node.js framework. Yes, another one. But hear me out.

TL;DR

KickJS gives you NestJS-style decorators on top of Express 5 without RxJS, without Angular-style modules, and without a 30-minute setup. One command scaffolds a full DDD module with working tests.

npx @forinda/kickjs-cli new my-api
cd my-api && pnpm dev
# API running at localhost:3000 with Swagger UI at /docs

GitHub: github.com/forinda/kick-js

Why Though

Every new API project, I'd copy-paste the same setup:

Express + TypeScript boilerplate
Some DI solution (Inversify, tsyringe, or hand-rolled)
Zod schemas for validation
Swagger generation from... somewhere
Pagination, filtering, sorting helpers
Error handling middleware
Test setup with supertest

That's 500+ lines before writing any business logic. NestJS solves this, but I didn't want to learn Angular patterns for a REST API.

Show Me the Code

A complete CRUD controller:

import { Controller, Get, Post, Put, Delete, Autowired } from '@forinda/kickjs-core'
import { RequestContext } from '@forinda/kickjs-http'

@Controller()
class UserController {
  @Autowired() private createUser!: CreateUserUseCase
  @Autowired() private listUsers!: ListUsersUseCase

  @Get('/')
  async list(ctx: RequestContext) {
    return ctx.paginate(
      (query) => this.listUsers.execute(query),
      { filterable: ['email', 'role'], sortable: ['name', 'createdAt'] },
    )
  }

  @Post('/', { body: createUserSchema })
  async create(ctx: RequestContext) {
    // ctx.body is validated by Zod, typed automatically
    const user = await this.createUser.execute(ctx.body)
    ctx.created(user)
  }
}

What happens here:

@Controller() registers in the DI container
@Autowired() injects dependencies (property injection)
@Get('/') defines the route
{ body: createUserSchema } validates with Zod, returns 422 on failure
ctx.paginate() handles query parsing, filtering, sorting, pagination
The same Zod schema generates the OpenAPI spec for Swagger

Zero configuration files for any of this.

The CLI Is the Star

kick g module product

Generates 18 files:

src/modules/products/
├── presentation/
│   └── product.controller.ts
├── application/
│   ├── use-cases/
│   │   ├── create-product.use-case.ts
│   │   ├── get-product.use-case.ts
│   │   ├── list-products.use-case.ts
│   │   ├── update-product.use-case.ts
│   │   └── delete-product.use-case.ts
│   └── dtos/
│       ├── create-product.dto.ts
│       ├── update-product.dto.ts
│       └── product-response.dto.ts
├── domain/
│   ├── repositories/product.repository.ts
│   ├── services/product-domain.service.ts
│   └── entities/product.entity.ts
├── infrastructure/repositories/
│   ├── drizzle-product.repository.ts
│   └── in-memory-product.repository.ts  ← test stub!
├── __tests__/
│   ├── product.controller.test.ts
│   └── product.repository.test.ts
└── index.ts

The key: it generates both the ORM repository and an in-memory test stub. Tests pass immediately — no database needed.

kick g module product --repo drizzle
npx vitest run  # ✅ all tests pass

Supports DDD, CQRS, REST, and minimal patterns. Works with Drizzle, Prisma, Mongoose, or custom ORMs.

Built-in Middleware (No Extra Installs)

import {
  helmet, cors, requestId, requestLogger,
  csrf, rateLimit,
} from '@forinda/kickjs-http'

bootstrap({
  modules: [UserModule, ProductModule],
  middleware: [
    helmet(),           // Security headers
    cors({ origin: ['https://myapp.com'] }),
    requestId(),        // X-Request-Id
    requestLogger(),    // Pino: method, URL, status, duration
    csrf(),             // Double-submit cookie
    rateLimit(),        // Sliding window
    express.json(),
  ],
})

Everything is optional. No middleware runs unless you declare it.

Vite 8 Powers Everything

No webpack. No tsup. No esbuild config. One tool:

What	How
Dev server	`kick dev` — Vite Environment Runner, HMR in ~200ms
Production build	`kick build` — Vite library mode
Tests	Vitest 4 + SWC for decorator support
Package builds	All 19 packages built with `vite build`

HMR preserves database connections and port bindings. Save a file, Express handler swaps instantly. No restart, no reconnect.

836+ Real Tests

Not expect(true).toBe(true) stubs. Real integration tests:

import { createTestApp } from '@forinda/kickjs-testing'
import request from 'supertest'

it('GET /api/v1/users returns paginated list', async () => {
  const { expressApp } = await createTestApp({
    modules: [UserModule],
  })

  const res = await request(expressApp)
    .get('/api/v1/users')
    .expect(200)

  expect(res.body.data).toHaveLength(2)
  expect(res.body.total).toBe(2)
})

Auth middleware tests:

it('rejects expired tokens', async () => {
  const token = jwt.sign({ sub: 'u1' }, SECRET, { expiresIn: '-1s' })

  await request(expressApp)
    .get('/api/v1/protected/me')
    .set('Authorization', `Bearer ${token}`)
    .expect(401)
})

10 example apps including 4 full task management APIs (Drizzle, Prisma, Mongoose) with 100+ tests each.

The 19 Packages

Package	What
`core`	DI container, 20+ decorators, Pino logger
`http`	Express 5 app, RequestContext, all middleware
`config`	Zod env validation, `@Value` decorator
`swagger`	Auto OpenAPI from decorators + Zod
`cli`	Scaffolding, generators, custom commands
`testing`	`createTestApp`, `createTestModule`
`auth`	JWT, API key, OAuth strategies
`prisma`	Prisma 5/6/7 adapter
`drizzle`	Drizzle query adapter
`ws`	WebSocket with `@WsController`
`graphql`	`@Resolver`, `@Query`, `@Mutation`
`queue`	BullMQ, RabbitMQ, Kafka
`cron`	`@Cron('0 * * * *')` scheduling
`mailer`	SMTP, Resend, SES
`otel`	OpenTelemetry tracing + metrics
`devtools`	Debug dashboard at `/_debug`
`multi-tenant`	Header/subdomain/path resolution
`notifications`	Email, Slack, Discord, webhook

All lockstep versioned. Install what you need.

What's Coming

Open issues on the project board:

Graceful request draining on shutdown
Kubernetes readiness/liveness probes
Circuit breaker for external services
Request-scoped DI for multi-tenant apps
Auto-wired OpenTelemetry trace propagation
Runtime compatibility: CI on Node 20/22/24 + Bun/Deno smoke tests

Get Started

npx @forinda/kickjs-cli new my-api
cd my-api && pnpm dev

Visit localhost:3000/docs for Swagger UI.

forinda / kick-js

A declarative progressive backend framework

KickJS

A production-grade, decorator-driven Node.js framework built on Express 5 and TypeScript.

KickJS gives you the DX of NestJS — decorators, dependency injection, module system, code generators — without the weight. No RxJS, no class-transformer, no class-validator. Just TypeScript, Zod, and decorators.

Highlights

Custom DI container — constructor and property injection, no external dependency
Decorator-driven — @Controller, @Get, @Post, @Service, @Autowired, @Middleware
Zod-native validation — schemas double as OpenAPI documentation
Vite HMR — zero-downtime hot reload in development, preserves DB/Redis/Socket connections
DDD generators — kick g module users scaffolds entity, repository, service, use-cases, DTOs, controller
Auto OpenAPI — Swagger UI and ReDoc generated from your decorators and Zod schemas
Pluggable — adapters for database, auth, cache, swagger; schema parsers for Zod/Yup/Joi; query builders for Drizzle/Prisma/Sequelize
Extensible CLI — register project-specific commands in kick.config.ts
ESM + TypeScript strict — modern stack, tree-shakeable packages

Install the CLI

…

View on GitHub

Star it, file issues, send PRs. The project board has tagged issues for all skill levels.

Docs: forinda.github.io/kick-js

Building a Jira Clone with KickJS and Prisma: Lessons from Supporting Prisma 5, 6, and 7

Orinda Felix Ochieng — Wed, 25 Mar 2026 14:36:27 +0000

How we built a decorator-driven Node.js framework adapter for Prisma ORM, what worked, and what didn't.

We recently shipped Prisma support for KickJS, our decorator-driven Node.js framework built on Express 5 and TypeScript. The goal was to make kick g module --repo prisma generate a fully working DDD module with Prisma repositories — no manual wiring needed.

Along the way, we built a full Jira-style project management API as a reference app, migrated it across Prisma 5/6 and Prisma 7, and ran into some interesting type safety challenges. Here's what we learned.

What We Built

The @forinda/kickjs-prisma adapter provides:

PrismaAdapter — lifecycle adapter that registers PrismaClient in the DI container
PrismaQueryAdapter — translates parsed query strings into Prisma findMany arguments
PrismaModelDelegate — typed interface for model CRUD operations (more on this below)
CLI integration — kick g module users --repo prisma generates a complete DDD module with working Prisma repositories

The reference app (jira-prisma-api) is a 14-module Jira clone with auth, workspaces, projects, tasks, labels, comments, attachments, channels, messages, notifications, activities, and stats — all backed by Prisma + PostgreSQL.

The Adapter: Simple by Design

The adapter itself is intentionally thin:

export class PrismaAdapter implements AppAdapter {
  name = 'PrismaAdapter'
  private client: any

  constructor(private options: PrismaAdapterOptions) {
    this.client = options.client
  }

  beforeStart(_app: any, container: Container): void {
    // Set up logging (Prisma 5/6 vs 7+ detection)
    if (this.options.logging) {
      if (typeof this.client.$on === 'function') {
        // Prisma 5/6: event-based logging
        this.client.$on('query', (event: any) => {
          log.debug(`Query: ${event.query} — ${event.duration}ms`)
        })
      } else if (typeof this.client.$extends === 'function') {
        // Prisma 7+: $on removed, use Client Extensions
        this.client = this.client.$extends({
          query: {
            $allOperations({ operation, model, args, query }: any) {
              const start = performance.now()
              return query(args).then((result: any) => {
                log.debug(`${model}.${operation} — ${Math.round(performance.now() - start)}ms`)
                return result
              })
            },
          },
        })
      }
    }

    container.registerFactory(PRISMA_CLIENT, () => this.client, Scope.SINGLETON)
  }

  async shutdown(): Promise<void> {
    if (typeof this.client.$disconnect === 'function') {
      await this.client.$disconnect()
    }
  }
}

Why client: any? Prisma's PrismaClient type is generated per-project — it includes your specific models, enums, and relations. The adapter can't import a concrete type without coupling to a specific schema. Using any keeps it version-agnostic across Prisma 5, 6, and 7.

Shortcoming #1: This means the adapter has zero compile-time knowledge of which models exist. You won't get a type error if you pass a misconfigured client. We considered using generics (PrismaAdapter<T extends PrismaClient>), but that would require the adapter package to depend on your specific generated client — defeating the purpose of a reusable package.

The Type Safety Problem

When we built the CLI template for kick g module --repo prisma, we hit a fundamental tension:

The template generates code at scaffold time, but the Prisma schema doesn't exist yet (or the model hasn't been added).

Our first attempt looked like this:

// Generated by: kick g module user --repo prisma
@Repository()
export class PrismaUserRepository {
  @Inject(PRISMA_CLIENT) private prisma!: PrismaClient

  async findById(id: string) {
    return (this.prisma.user as any).findUnique({ where: { id } })
    //     ^^^^^^^^^^^^^^^^^^^^
    //     as any because 'user' model may not exist on PrismaClient yet
  }
}

Every single Prisma call needed as any because:

The generated PrismaClient type only includes models defined in your schema
The CLI template can't know which models will exist when you run it
TypeScript can't verify this.prisma.user without the generated types

Shortcoming #2: We had as any on every model accessor call — 6+ casts per repository file. For a framework that emphasizes TypeScript-first development, this was embarrassing.

The PrismaModelDelegate Solution

We introduced PrismaModelDelegate — a typed interface that describes the common CRUD operations every Prisma model delegate supports:

export interface PrismaModelDelegate {
  findUnique(args: { where: Record<string, unknown>; include?: Record<string, unknown> }): Promise<unknown>
  findFirst?(args?: Record<string, unknown>): Promise<unknown>
  findMany(args?: Record<string, unknown>): Promise<unknown[]>
  create(args: { data: Record<string, unknown> }): Promise<unknown>
  update(args: { where: Record<string, unknown>; data: Record<string, unknown> }): Promise<unknown>
  delete(args: { where: Record<string, unknown> }): Promise<unknown>
  deleteMany(args?: { where?: Record<string, unknown> }): Promise<{ count: number }>
  count(args?: { where?: Record<string, unknown> }): Promise<number>
}

Now the generated code type-narrows the injected client to just the model it needs:

@Repository()
export class PrismaUserRepository {
  @Inject(PRISMA_CLIENT) private prisma!: { user: PrismaModelDelegate }

  async findById(id: string) {
    return this.prisma.user.findUnique({ where: { id } }) as Promise<User | null>
  }

  async create(dto: CreateUserDTO) {
    return this.prisma.user.create({ data: dto as Record<string, unknown> }) as Promise<User>
  }
}

No as any on the model accessor. The { user: PrismaModelDelegate } type tells TypeScript that this.prisma.user exists and has CRUD methods with typed signatures.

Shortcoming #3: Methods return Promise<unknown> instead of Promise<User>. You still need as Promise<User> casts on return types. This is a safe downcast (narrowing unknown to a known type), not an unsafe any cast — but it's still a cast.

Shortcoming #4: The data parameter is typed as Record<string, unknown>, not Prisma.UserCreateInput. You lose field-level validation on writes. Passing { invalidField: true } compiles but fails at runtime.

The Upgrade Path

For production apps that need full type safety, we document a simple upgrade:

// Generated (works immediately, PrismaModelDelegate)
@Inject(PRISMA_CLIENT) private prisma!: { user: PrismaModelDelegate }

// Upgraded (full Prisma type safety)
import type { PrismaClient } from '@prisma/client'
@Inject(PRISMA_CLIENT) private prisma!: PrismaClient

One line change. After that, this.prisma.user.create({ data: dto }) validates dto against Prisma.UserCreateInput at compile time, returns User without casts, and gives you full autocomplete on where, include, select, etc.

Shortcoming #5: This upgrade requires knowing your Prisma client import path, which differs between Prisma 5/6 (@prisma/client) and Prisma 7 (@/generated/prisma/client). We added modules.prismaClientPath to the CLI config to address this, but the generated code always starts with PrismaModelDelegate regardless.

Prisma 7 Migration: What Changed

Prisma 7 introduced several breaking changes that affected our adapter:

1. No more `datasource.url` in schema

// Prisma 6
datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

// Prisma 7
datasource db {
  provider = "postgresql"
  // url moved to prisma.config.ts
}

2. Driver adapters required

// Prisma 6
const prisma = new PrismaClient()

// Prisma 7
import { PrismaPg } from '@prisma/adapter-pg'
import pg from 'pg'

const pool = new pg.Pool({ connectionString: process.env.DATABASE_URL })
const prisma = new PrismaClient({ adapter: new PrismaPg(pool) })

3. `$on` removed for logging

Our adapter detects this at runtime with typeof this.client.$on === 'function' and falls back to $extends. This is the one change that required code in the adapter itself.

4. Client generated to custom output

// Prisma 7
generator client {
  provider = "prisma-client"
  output   = "../src/generated/prisma"
}

All 47 import statements in our Jira example changed from @prisma/client to @/generated/prisma/client.

Shortcoming #6: The @prisma/client runtime package is still needed as a dependency even in Prisma 7 — the generated client imports from @prisma/client/runtime/client internally. This confused us initially when we tried to remove it.

The Query Adapter: Type-Safe Search Columns

Our PrismaQueryAdapter translates parsed URL query strings into Prisma findMany arguments:

GET /api/v1/users?page=2&limit=25&q=john&filter=role:eq:admin&sort=createdAt:desc

Becomes:

{
  where: {
    AND: [
      { role: { equals: 'admin' } },
      { OR: [
        { name: { contains: 'john', mode: 'insensitive' } },
        { email: { contains: 'john', mode: 'insensitive' } },
      ]}
    ]
  },
  orderBy: [{ createdAt: 'desc' }],
  skip: 25,
  take: 25,
}

We added a generic type parameter to validate searchColumns:

import type { User } from '@prisma/client'

const config: PrismaQueryConfig<User> = {
  searchColumns: ['name', 'email'],  // TypeScript validates these are User fields
  // searchColumns: ['invalid'],     // Compile error!
}

Shortcoming #7: This only validates searchColumns, not filterable or sortable fields. Those are validated at the controller layer via QueryParamsConfig from @forinda/kickjs-core, which uses plain string arrays. A unified type that validates across both layers would be better.

What We'd Do Differently

1. Start with the PrismaClient approach, not PrismaModelDelegate

PrismaModelDelegate was born from the constraint that the CLI generates code before the Prisma schema exists. In practice, most users add the model to their schema first, then generate the module. We should have made the full PrismaClient import the default and PrismaModelDelegate the fallback.

2. Generate a db/prisma.ts barrel file

Instead of importing PrismaClient in every repository, generate a single src/db/prisma.ts that re-exports the client and model types. Repositories import from there. When upgrading Prisma versions, you change one file.

3. Type-safe DTOs from Prisma schema

The generated DTOs use Zod schemas that duplicate what's already in the Prisma schema. Tools like zod-prisma-types or prisma-zod-generator could generate Zod schemas from the Prisma schema, eliminating the duplication.

4. Transaction support in the adapter

Our adapter registers a singleton PrismaClient. For transactions (prisma.$transaction), you need the client directly. We should expose a withTransaction helper or a @Transactional decorator that wraps the use case in prisma.$transaction.

Try It

# Scaffold a new project
npx @forinda/kickjs-cli new my-api
cd my-api

# Add Prisma
kick add prisma

# Generate a module
kick g module user --repo prisma

# Start dev server
kick dev

Or check out the full Jira clone examples:

jira-prisma-api (Prisma 6)
jira-prisma-v7-api (Prisma 7)

Summary of Shortcomings

#	Issue	Impact	Status
1	Adapter uses `client: any` — no compile-time client validation	Low — runtime errors are clear	By design
2	~~CLI template had `as any` on every model accessor~~	~~High~~	Fixed with PrismaModelDelegate
3	PrismaModelDelegate returns `Promise<unknown>` — return casts needed	Medium — safe narrowing, not unsafe `any`	By design
4	`data` param typed as `Record<string, unknown>` — no field validation on writes	Medium — runtime errors instead of compile-time	Upgrade to full PrismaClient
5	Prisma client import path differs between v6 and v7	Low — `prismaClientPath` config handles it	Fixed
6	`@prisma/client` runtime still needed in Prisma 7	Low — confusing but functional	Documented
7	`searchColumns` typed but `filterable`/`sortable` not unified	Low — validated at different layers	Planned

KickJS is an open-source, decorator-driven Node.js framework. If you're building REST APIs with TypeScript and want NestJS-like DX without the weight, check it out.

Building a Jira-Like Task API with KickJS — Auth, WebSocket Chat, SSE, Queues & More

Orinda Felix Ochieng — Sun, 22 Mar 2026 16:40:09 +0000

Update: This article documents the initial build and the problems encountered along the way. Many of the gotchas described here (ctx.set/get isolation, DI registration, controller HMR) have been resolved in KickJS v1.2.5–v1.2.7. The workarounds shown are still valid but no longer necessary on the latest version. See the complete project guide for the current patterns.

TL;DR

🏗️ Built a full Jira-like task management API (65 endpoints, 17 modules) using KickJS — a decorator-driven TypeScript framework
🔐 Auth with JWT + refresh tokens + role-based guards — and the debugging rabbit hole that came with it
💬 Real-time WebSocket chat with rooms, typing indicators, and read receipts
📡 Server-Sent Events for live dashboard updates on task changes
⚡ Background job queues with BullMQ for emails, reminders, and audit logs
🤕 10 gotchas that cost me hours so they don't have to cost you hours

Why This Exists

I wanted to stress-test KickJS beyond a "Hello World." So I built Vibed — a task management backend with categories, labels, sprints, comments, file attachments, real-time chat, SSE dashboards, background jobs, and cron-scheduled reminders.

Think Jira's API, but TypeScript-native, decorator-driven, and built in a weekend (okay, a long weekend).

Let's walk through the interesting parts.

The Stack

Concern	Tool
Framework	KickJS (Express under the hood)
Database	MongoDB + Mongoose
Auth	JWT access + refresh tokens
Email	Resend SDK
Real-time	WebSocket (native ws)
Live updates	Server-Sent Events
Job queue	BullMQ + Redis
Scheduled tasks	Cron module
Docs	Swagger / OpenAPI

Getting Started

KickJS has a CLI that scaffolds everything:

kick new vibed --pm pnpm
kick add auth ws mailer queue cron swagger devtools
kick g module tasks

That last command generates a full DDD module — controller, service, repository, DTOs, the works. More on that structure in a sec.

The DDD Module Pattern

Every feature in KickJS lives in a module. Each module follows a layered architecture:

src/modules/tasks/
├── task.module.ts          # Wires everything together
├── task.controller.ts      # HTTP routes + decorators
├── task.service.ts         # Business logic
├── task.repository.ts      # Mongoose queries
├── dto/
│   ├── create-task.dto.ts  # Validation schemas
│   └── update-task.dto.ts
├── schemas/
│   └── task.schema.ts      # Mongoose model
└── interfaces/
    └── task.interface.ts   # TypeScript types

Here's what a module registration looks like:

@Module({
  controllers: [TaskController],
  providers: [TaskService, TaskRepository],
  imports: [MongooseModule.forFeature([
    { name: 'Task', schema: TaskSchema }
  ])],
})
export class TaskModule {}

And a typical controller:

@Controller('/tasks')
@UseGuards(AuthGuard)
export class TaskController {
  @Autowired() private taskService!: TaskService;

  @Get('/')
  async findAll(ctx: Context) {
    const user = getUser(ctx);
    const query = ctx.query as ApiQueryParamsConfig;
    const tasks = await this.taskService.findByWorkspace(
      user.workspaceId,
      query
    );
    return ctx.json({ data: tasks });
  }

  @Post('/')
  @Validate(CreateTaskDto)
  async create(ctx: Context) {
    const user = getUser(ctx);
    const body = ctx.body as CreateTaskDto;
    const task = await this.taskService.create({
      ...body,
      createdBy: user._id,
      workspaceId: user.workspaceId,
    });
    return ctx.json({ data: task }, 201);
  }
}

Clean. Predictable. Every module follows the same shape.

Authentication — The Hard Way

This section is a debugging story. Buckle up.

Chapter 1: @public() Didn't Work

KickJS ships with an auth module that has a defaultPolicy: 'RESTRICTED' setting. Every route is locked down by default — which is great, until you need public routes.

The @Public() decorator is supposed to mark routes as open. Except... it wasn't working. Every public route still returned 401 Unauthorized.

After digging through the source, I found the issue: the resolveHandler in the auth config was throwing before the @Public() metadata could be checked. The auth middleware runs globally, and when resolveHandler fails, it short-circuits.

Chapter 2: The Bridge Middleware

Solution? I built authBridgeMiddleware — a global middleware that sits before the auth guard:

export function authBridgeMiddleware(
  ctx: Context,
  next: NextFunction
) {
  const token = ctx.headers.authorization?.split(' ')[1];

  if (!token) {
    ctx.set('user', null);
    return next();
  }

  try {
    const payload = verifyAccessToken(token);
    ctx.set('user', payload);
  } catch {
    ctx.set('user', null);
  }

  return next();
}

This way, the auth guard always has a user (or null) to work with, and @Public() routes can proceed even without a token.

Chapter 3: The ctx.set()/ctx.get() Fix

This used to be a major gotcha — ctx.set() in middleware was invisible to ctx.get() in the handler because each got a separate RequestContext instance with its own metadata Map.

Good news: fixed in KickJS v1.2.5. The metadata Map is now stored on req and shared across all RequestContext instances for the same request. ctx.set()/ctx.get() works exactly as you'd expect:

// In middleware:
ctx.set('user', payload);  // ✅ Sets on shared metadata

// In route handler:
const user = ctx.get<AuthUser>('user');  // ✅ Works!

A clean helper keeps it centralized:

export function getUser(ctx: Context): AuthUser {
  const user = ctx.get<AuthUser>('user');

  if (!user) {
    throw new UnauthorizedException('Not authenticated');
  }

  return user;
}

Real-Time Chat with WebSocket

KickJS has first-class WebSocket support via @WsController:

@WsController('/chat')
export class ChatGateway {
  @Autowired() private chatService!: ChatService;

  @OnConnect()
  async handleConnect(socket: WsSocket) {
    const user = await this.authenticateSocket(socket);
    socket.data = { userId: user._id };
    console.log(`🟢 ${user.name} connected`);
  }

  @OnMessage('join-room')
  async handleJoinRoom(
    socket: WsSocket,
    payload: { roomId: string }
  ) {
    socket.join(payload.roomId);
    socket.to(payload.roomId).emit('user-joined', {
      userId: socket.data.userId,
      timestamp: new Date(),
    });
  }

  @OnMessage('send-message')
  async handleMessage(
    socket: WsSocket,
    payload: { roomId: string; content: string }
  ) {
    const message = await this.chatService.create({
      roomId: payload.roomId,
      senderId: socket.data.userId,
      content: payload.content,
    });

    socket.to(payload.roomId).emit('new-message', message);
  }

  @OnMessage('typing')
  async handleTyping(
    socket: WsSocket,
    payload: { roomId: string; isTyping: boolean }
  ) {
    socket.to(payload.roomId).emit('user-typing', {
      userId: socket.data.userId,
      isTyping: payload.isTyping,
    });
  }
}

Rooms, typing indicators, message persistence — all decorator-driven. The socket.join() / socket.to() API mirrors Socket.IO, which makes it easy to reason about.

Live Dashboard with SSE

For the dashboard, I didn't want WebSocket overhead. SSE is perfect for one-way server-to-client updates:

@Get('/stream')
@UseGuards(AuthGuard)
async streamUpdates(ctx: Context) {
  const user = getUser(ctx);

  ctx.sse((send, close) => {
    const interval = setInterval(async () => {
      const stats = await this.dashboardService.getStats(
        user.workspaceId
      );
      send({ event: 'dashboard-update', data: stats });
    }, 5000);

    ctx.req.on('close', () => {
      clearInterval(interval);
      close();
    });
  });
}

ctx.sse() handles the headers (text/event-stream, Cache-Control, etc.) and gives you a clean send/close interface. The client just uses EventSource:

const es = new EventSource('/api/dashboard/stream', {
  headers: { Authorization: `Bearer ${token}` }
});

es.addEventListener('dashboard-update', (e) => {
  updateDashboard(JSON.parse(e.data));
});

Background Jobs That Actually Work

Email notifications, reminder scheduling, audit logging — all of this needs to happen off the request cycle. KickJS wraps BullMQ:

@Job('email-queue')
export class EmailJob {
  @Autowired() private mailer!: MailerService;

  @Process('send-welcome')
  async handleWelcome(job: JobData<WelcomePayload>) {
    await this.mailer.send({
      to: job.data.email,
      subject: 'Welcome to Vibed!',
      template: 'welcome',
      context: { name: job.data.name },
    });
  }

  @Process('send-reminder')
  async handleReminder(job: JobData<ReminderPayload>) {
    await this.mailer.send({
      to: job.data.email,
      subject: `Reminder: ${job.data.taskTitle}`,
      template: 'task-reminder',
      context: job.data,
    });
  }
}

Dispatching a job from anywhere:

@Autowired() private queueService!: QueueService;

async createTask(data: CreateTaskDto) {
  const task = await this.taskRepo.create(data);

  // Fire-and-forget background job
  await this.queueService.add('email-queue', 'send-reminder', {
    email: data.assigneeEmail,
    taskTitle: task.title,
    dueDate: task.dueDate,
  });

  return task;
}

Pro tip: In development, skip Redis entirely with the ConsoleProvider:

QueueModule.register({
  provider: process.env.NODE_ENV === 'development'
    ? 'console'    // Logs jobs to terminal
    : 'bullmq',   // Real Redis-backed queue
  connection: { host: 'localhost', port: 6379 },
})

File Uploads → Base64 → MongoDB

No S3, no Cloudinary. For a task management MVP, storing files as base64 in MongoDB is fine:

@Post('/attachments')
@FileUpload({ maxSize: 5 * 1024 * 1024 }) // 5MB
async uploadAttachment(ctx: Context) {
  const file = ctx.file;
  const user = getUser(ctx);

  const attachment = await this.attachmentService.create({
    taskId: ctx.params.taskId,
    fileName: file.originalname,
    mimeType: file.mimetype,
    data: file.buffer.toString('base64'),
    uploadedBy: user._id,
  });

  return ctx.json({ data: attachment }, 201);
}

Is this production-ready for large files? No. Is it perfect for an MVP with < 5MB attachments? Absolutely.

10 Gotchas That'll Save You Hours

These are the things I wish someone had told me before I started. Each one cost me at least 30 minutes of head-scratching.

1. Mongoose HMR Guard

Hot module reload re-runs your schema definitions. Mongoose hates that.

// ❌ Crashes on HMR
export const TaskModel = model('Task', TaskSchema);

// ✅ Guard it
export const TaskModel =
  models.Task || model('Task', TaskSchema);

2. Double-Slash Routes

If your module prefix is /api and your controller has @Controller('/tasks'), you get /api//tasks. Both start with /.

// ❌ Results in /api//tasks
@Module({ prefix: '/api' })
@Controller('/tasks')

// ✅ Drop the leading slash on one
@Module({ prefix: '/api' })
@Controller('tasks')

3. Global vs Route Middleware Signatures

Global middleware gets (ctx, next). Route middleware gets (ctx, next) too — but the ctx object is different. Global middleware runs on the raw Express context; route middleware runs on the KickJS-wrapped context.

// Global middleware — req/res under the hood
app.use((ctx, next) => {
  ctx.req.headers; // ✅ works
  ctx.body;        // ❌ might not be parsed yet
  next();
});

// Route middleware — full KickJS context
@UseMiddleware(myMiddleware)
// ctx.body ✅, ctx.query ✅, ctx.params ✅

4. ctx.set/get Shared Across Middleware/Handler (Fixed in v1.2.5)

This was a pain point in earlier versions but is now fixed. Use ctx.set()/ctx.get() directly — no res.locals workaround needed.

5. @Inject for Constructors, @Autowired for Properties

// Constructor injection
class TaskService {
  constructor(@Inject(TaskRepository) private repo: TaskRepository) {}
}

// Property injection (no constructor needed)
class TaskController {
  @Autowired() private taskService!: TaskService;
}

Mix them up and you get silent undefined values. Pick one pattern per class.

6. QueueAdapter Wants String Names, Not Classes

// ❌ Nope
this.queueService.add(EmailJob, 'send-welcome', data);

// ✅ String name matching @Job('email-queue')
this.queueService.add('email-queue', 'send-welcome', data);

7. Route-less Modules Crash Express

If a module has no controllers (e.g., a pure service module), KickJS still tries to register it as a router. Empty router = Express crash.

// ✅ Add a health controller or use forRoot() pattern
@Module({
  controllers: [],  // This can cause issues
  providers: [MyService],
})

// ✅ Better: export the service from a module that HAS routes

8. Auth defaultPolicy Blocks When resolveHandler Fails

If your resolveHandler throws, every route gets a 401 — even @Public() ones. Always wrap it:

authConfig({
  defaultPolicy: 'RESTRICTED',
  resolveHandler: async (ctx) => {
    try {
      return await verifyToken(ctx);
    } catch {
      return null;  // Let @Public() routes through
    }
  },
})

9. ApiQueryParamsConfig Type Name

The type for pagination/filter/sort query params is called ApiQueryParamsConfig, not QueryParams, not ApiQuery, not PaginationOptions. Ask me how many times I searched for the wrong name.

import { ApiQueryParamsConfig } from '@kickjs/core';

@Get('/')
async findAll(ctx: Context) {
  const query = ctx.query as ApiQueryParamsConfig;
  // query.page, query.limit, query.sort, query.filter
}

10. loadEnv() Type Erasure

loadEnv() returns Record<string, string>. Everything is a string. Your "boolean" ENABLE_SWAGGER=true is the string "true".

// ❌ This is always truthy (it's a non-empty string)
if (env.ENABLE_SWAGGER) { ... }

// ✅ Compare strings explicitly
if (env.ENABLE_SWAGGER === 'true') { ... }

// ✅ Or parse once at startup
const config = {
  enableSwagger: env.ENABLE_SWAGGER === 'true',
  port: parseInt(env.PORT, 10) || 3000,
};

The Numbers

After a long weekend of building:

Metric	Count
Modules	17
API Endpoints	65
MongoDB Collections	13
TypeScript Files	159
Type Errors	0

Modules include: auth, users, workspaces, projects, sprints, tasks, task-comments, task-labels, task-categories, task-attachments, task-reminders, chat, notifications, dashboard, audit-log, file-uploads, and health.

What I'd Do Differently

Start with the auth bridge middleware — don't fight @Public() for two hours first
Use property injection everywhere — @Autowired() is simpler than constructor @Inject()
String-based queue names from day one — saves a refactor later
Build the getUser(ctx) helper immediately — uses ctx.get<AuthUser>('user') under the hood, called in every guarded route

What's Next

In the next article in this series, I'll cover:

Role-based access control — workspace admins vs members vs viewers
Advanced query filtering — how to build a flexible filter/sort/paginate layer on top of Mongoose
Deployment — containerizing the whole stack with Docker Compose

If you've been looking for a NestJS alternative that's lighter, faster to scaffold, and doesn't require a PhD in dependency injection — give KickJS a shot.

Star KickJS on GitHub

Got questions? Drop them in the comments — I'll answer everything. If you hit any of these gotchas yourself, I'd love to hear your war stories too.

KickJS Module Generator: 4 Architecture Patterns for Every Backend Need

Orinda Felix Ochieng — Sun, 22 Mar 2026 16:35:23 +0000

One of the things I appreciate most about working with a framework is when it meets me where I am. Not every feature I build needs the same level of ceremony. A health check endpoint does not need domain-driven design. A real-time collaboration feature probably does. The KickJS module generator understands this distinction, and it changed how I think about scaffolding backend code.

The command is simple:

kick g module <name> --pattern <pattern>

That --pattern flag is where the magic lives. KickJS ships four architecture patterns: minimal, rest, ddd, and cqrs. Each one generates a different number of files with a different structural philosophy. Instead of forcing you into one way of building modules, the generator lets you pick the right level of complexity for the job at hand. I have been building Vibed, a Jira-like task management backend, with KickJS for several months now. Along the way I have used all four patterns, and I want to walk through what each one gives you and when to reach for it.

Pattern 1: minimal (2 files)

kick g module health --pattern minimal

This is the lightest possible module. Two files. That is it.

health/
├── index.ts
└── health.controller.ts

The index.ts file is your module definition. It implements AppModule, registers nothing in the DI container, and returns a single route pointing at the controller:

import type { AppModule, ModuleRoutes, Container } from '@forinda/kickjs-core';
import { buildRoutes } from '@forinda/kickjs-http';
import { HealthController } from './health.controller';

export class HealthModule implements AppModule {
  register(_container: Container): void {
    // No DI bindings needed
  }

  routes(): ModuleRoutes {
    return {
      path: '/',
      router: buildRoutes(HealthController),
      controller: HealthController,
    };
  }
}

The controller is equally lean. No services, no repositories, no DTOs. Just decorated route handlers returning responses directly:

import { Controller, Get } from '@forinda/kickjs-core';
import type { RequestContext } from '@forinda/kickjs-http';

@Controller()
export class HealthController {
  @Get('/health')
  async check(ctx: RequestContext) {
    ctx.json({ status: 'ok', timestamp: new Date().toISOString() });
  }
}

I use the minimal pattern for endpoints that do not touch the database or require any business logic. Health checks, version endpoints, static configuration responses, debug routes during development. In Vibed, the StatsModule started as a minimal module before it grew to need actual service dependencies. The pattern gives you a place to put code without imposing structure you do not need yet.

When to use it: Quick prototypes, static endpoints, health checks, anything where a controller alone is sufficient.

Pattern 2: rest (11 files)

kick g module cats --pattern rest

This is the workhorse pattern. Eleven files in a flat structure that covers the full CRUD lifecycle:

cats/
├── index.ts
├── cats.controller.ts
├── cats.service.ts
├── cats.repository.ts
├── cats.types.ts
├── cats.dto.ts
├── cats.config.ts
├── cats.controller.test.ts
├── cats.service.test.ts
├── cats.repository.test.ts
└── _glob.ts

The service wraps the repository, the controller delegates to the service, and DTOs handle validation. No subdirectories, no layers to navigate. Everything for the cats module lives in one folder.

The generated repository ships with an in-memory implementation by default:

import type { Cat, CreateCatDto, UpdateCatDto } from './cats.types';

export class CatsRepository {
  private items: Cat[] = [];
  private nextId = 1;

  async findAll(): Promise<Cat[]> {
    return [...this.items];
  }

  async findById(id: string): Promise<Cat | null> {
    return this.items.find(item => item.id === id) ?? null;
  }

  async create(dto: CreateCatDto): Promise<Cat> {
    const item: Cat = { id: String(this.nextId++), ...dto, createdAt: new Date(), updatedAt: new Date() };
    this.items.push(item);
    return item;
  }

  // ... update, delete methods
}

This is intentional. You get a working module the instant the generator finishes. No database setup required. When you are ready, you swap the in-memory store for your real persistence layer. A comment in the generated file even tells you where to make the swap for Drizzle or Prisma. In Vibed, we use MongoDB with Mongoose, so we replaced these with Mongo repository implementations, but the interface stayed the same.

The cats.config.ts file contains a QueryFieldConfig for pagination:

import type { ApiQueryParamsConfig } from '@forinda/kickjs-core';

export const CATS_QUERY_CONFIG: ApiQueryParamsConfig = {
  filterable: ['breed', 'color'],
  sortable: ['name', 'createdAt'],
  searchable: ['name'],
};

This integrates directly with ctx.paginate() and @ApiQueryParams() for Swagger documentation. In Vibed, we centralized these configs in shared/constants/query-configs.ts, but the generator gives each module its own config file so it works out of the box.

The _glob.ts file is the auto-wiring mechanism:

import.meta.glob(['./*.ts', '!./_glob.ts', '!./*.test.ts'], { eager: true });

I will explain why this matters in a dedicated section below.

When to use it: Most CRUD modules, rapid development, any time you want a flat structure with no ceremony. This is the pattern I reach for most often.

Pattern 3: ddd (18 files)

kick g module cats --pattern ddd

Eighteen files across a full domain-driven design directory structure:

cats/
├── index.ts
├── _glob.ts
├── presentation/
│   └── cats.controller.ts
├── application/
│   ├── dtos/
│   │   ├── create-cat.dto.ts
│   │   └── update-cat.dto.ts
│   └── use-cases/
│       ├── create-cat.use-case.ts
│       ├── get-cat.use-case.ts
│       ├── list-cats.use-case.ts
│       ├── update-cat.use-case.ts
│       └── delete-cat.use-case.ts
├── domain/
│   ├── entities/
│   │   └── cat.entity.ts
│   ├── value-objects/
│   │   └── cat-id.vo.ts
│   ├── services/
│   │   └── cat-domain.service.ts
│   └── repositories/
│       └── cat.repository.ts
└── infrastructure/
    └── repositories/
        └── in-memory-cat.repository.ts

This is where things get interesting. The generator does not just create more files. It creates files with real architectural opinions baked in.

The domain entity uses a private constructor with factory methods:

export class Cat {
  private constructor(
    public readonly id: CatId,
    public name: string,
    public breed: string,
    public age: number,
    public readonly createdAt: Date,
    public updatedAt: Date,
  ) {}

  static create(props: { name: string; breed: string; age: number }): Cat {
    return new Cat(
      CatId.generate(),
      props.name,
      props.breed,
      props.age,
      new Date(),
      new Date(),
    );
  }

  static reconstitute(props: {
    id: string; name: string; breed: string; age: number;
    createdAt: Date; updatedAt: Date;
  }): Cat {
    return new Cat(
      CatId.from(props.id),
      props.name,
      props.breed,
      props.age,
      props.createdAt,
      props.updatedAt,
    );
  }
}

The create factory is for new entities. The reconstitute factory is for rehydrating from persistence. This distinction matters because creation might involve generating IDs, setting defaults, or validating invariants, while reconstitution assumes the data is already valid. It is a pattern from the DDD playbook that the generator hands you for free.

The CatId value object wraps the raw string identifier:

export class CatId {
  private constructor(private readonly value: string) {}

  static generate(): CatId {
    return new CatId(crypto.randomUUID());
  }

  static from(value: string): CatId {
    return new CatId(value);
  }

  toString(): string {
    return this.value;
  }

  equals(other: CatId): boolean {
    return this.value === other.value;
  }
}

The domain service layer is separate from the use cases. Use cases orchestrate application flow -- they call repositories, invoke domain services, and return results. Domain services contain business rules that do not belong to a single entity. This separation means your business logic survives even if you swap out your application framework.

The repository interface lives in domain/repositories/, and the implementation lives in infrastructure/repositories/. The use cases depend only on the interface:

@Service()
export class CreateCatUseCase {
  constructor(
    @Inject(TOKENS.CAT_REPOSITORY) private catRepo: ICatRepository,
  ) {}

  async execute(dto: CreateCatDto): Promise<Cat> {
    const cat = Cat.create(dto);
    return this.catRepo.save(cat);
  }
}

Five use cases are generated: create, get, list, update, delete. Each one is a single-responsibility class. The controller uses @Autowired() to inject them all, and each route handler delegates to exactly one use case. This is the exact pattern we use throughout Vibed for modules like workspaces, tasks, and projects.

The _glob.ts in the DDD pattern casts a wider net:

import.meta.glob([
  './presentation/**/*.ts',
  './application/**/*.ts',
  './domain/services/**/*.ts',
  './infrastructure/**/*.ts',
  '!./**/*.test.ts',
], { eager: true });

It reaches into every layer to ensure all decorated classes are loaded and registered in the DI container.

When to use it: Complex business logic, team projects where multiple developers touch the same module, long-lived codebases where you need clear boundaries between layers.

Pattern 4: cqrs (17 files)

kick g module cats --pattern cqrs

Seventeen files with command/query separation and an event system:

cats/
├── index.ts
├── _glob.ts
├── commands/
│   ├── create-cat.command.ts
│   ├── update-cat.command.ts
│   └── delete-cat.command.ts
├── queries/
│   ├── get-cat.query.ts
│   └── list-cats.query.ts
├── events/
│   ├── cat-events.ts
│   ├── cat-created.handler.ts
│   ├── cat-updated.handler.ts
│   └── cat-deleted.handler.ts
├── dtos/
│   ├── create-cat.dto.ts
│   └── update-cat.dto.ts
├── cats.controller.ts
├── cats.types.ts
├── cats.repository.ts
└── cats.event-emitter.ts

The core idea here is that reads and writes are different operations with different concerns. Commands mutate state. Queries read it. Events broadcast what happened so other parts of the system can react.

The event emitter is strongly typed with a domain event map:

import { EventEmitter } from 'events';
import type { Cat } from './cats.types';

export interface CatEventMap {
  'cat.created': [cat: Cat];
  'cat.updated': [cat: Cat];
  'cat.deleted': [id: string];
}

class CatEventEmitter extends EventEmitter {
  emit<K extends keyof CatEventMap>(event: K, ...args: CatEventMap[K]): boolean {
    return super.emit(event, ...args);
  }

  on<K extends keyof CatEventMap>(event: K, listener: (...args: CatEventMap[K]) => void): this {
    return super.on(event, listener as any);
  }
}

export const catEvents = new CatEventEmitter();

This is not just a generic EventEmitter. The type parameter on CatEventMap means TypeScript enforces that you emit the right payload for each event name. If cat.created expects a Cat object, you cannot accidentally emit a string.

Commands emit events after performing their mutation:

@Service()
export class CreateCatCommand {
  constructor(@Inject(TOKENS.CAT_REPOSITORY) private repo: CatsRepository) {}

  async execute(dto: CreateCatDto): Promise<Cat> {
    const cat = await this.repo.create(dto);
    catEvents.emit('cat.created', cat);
    return cat;
  }
}

Event handlers pick up those events for side effects:

import { catEvents } from '../cats.event-emitter';

// WebSocket broadcast
catEvents.on('cat.created', (cat) => {
  // Broadcast via WS adapter
  console.log(`[WS] Broadcasting cat.created: ${cat.id}`);
});

// Queue dispatch
catEvents.on('cat.created', (cat) => {
  // Dispatch to BullMQ for async processing
  console.log(`[Queue] Dispatching cat.created job: ${cat.id}`);
});

The handlers are stubs, but they show you where to plug in WebSocket broadcasts, queue dispatches, audit trail logging, or cache invalidation. In Vibed, we use this pattern for features like real-time notifications and activity feeds, where creating a task should trigger events that multiple subsystems consume.

The _glob.ts for CQRS covers all the directories:

import.meta.glob([
  './commands/**/*.ts',
  './queries/**/*.ts',
  './events/**/*.ts',
  '!./**/*.test.ts',
], { eager: true });

When to use it: Event-driven features, real-time applications, systems that need audit trails, anything where the write path and read path have fundamentally different requirements.

Auto-Wiring: The Generator Updates Your Module Registry

When you run kick g module, the generator does not just create files in a new directory. It also updates src/modules/index.ts automatically. In Vibed, that file looks like this:

import type { AppModuleClass } from '@forinda/kickjs-core';
import { AuthModule } from './auth/auth.module';
import { UsersModule } from './users/users.module';
import { WorkspacesModule } from './workspaces/workspaces.module';
// ... other imports

export const modules: AppModuleClass[] = [
  AuthModule,
  UsersModule,
  WorkspacesModule,
  // ... other modules
];

The generator appends your new module's import and adds it to the array. No manual wiring. This matters more than it sounds, because forgetting to register a module is one of those bugs that gives you no error message -- your routes simply do not exist, and you spend twenty minutes wondering why Postman returns 404.

The import.meta.glob Pattern

Every generated pattern except minimal includes a _glob.ts file (or inlines the glob in index.ts). This file uses Vite's import.meta.glob with { eager: true }:

import.meta.glob(['./**/*.ts', '!./**/*.test.ts'], { eager: true });

Why does this exist? In KickJS, decorated classes (@Service(), @Controller(), etc.) register themselves in the DI container as a side effect of being imported. If a file is never imported, its decorators never run, and the container does not know it exists.

Explicit imports work, but they are fragile. Every time you add a new use case or service, you have to remember to import it somewhere. import.meta.glob solves this by loading all .ts files in the module directory tree at build time.

Here is what happens under the hood:

Vite evaluates the glob pattern at build time, resolving it to a static list of file paths.
The { eager: true } option loads all matched files synchronously, as if you had written individual import statements for each one.
Each imported file's top-level code executes, which includes decorator registration as a side effect.
During HMR, when a file changes, Vite re-evaluates the glob and re-imports the affected modules.

This is why the pattern survives hot module replacement. The glob re-evaluates on every rebuild, picking up new files and dropping deleted ones without any manual intervention. You add a new use case file, save it, and HMR ensures it is registered in the container immediately.

Choosing a Pattern: The Decision Matrix

After months of building with all four patterns, here is how I decide:

Scenario	Pattern	Why
Prototype or spike	`minimal`	Two files, zero overhead, prove the concept first
Standard CRUD resource	`rest`	Flat structure, fast to navigate, covers 80% of modules
Complex business domain	`ddd`	Layer separation protects invariants, scales with team size
Event-driven feature	`cqrs`	Command/query split, typed events, natural fit for real-time

The patterns are not mutually exclusive within a project. In Vibed, we have modules at different complexity levels. The stats module is essentially minimal. The workspaces module follows DDD conventions. If we were to add a live collaboration feature, CQRS would be the natural choice. KickJS does not enforce uniformity -- you pick the right tool for each module.

The --repo Flag

The generator also accepts a --repo flag to control what persistence layer the generated repository uses:

kick g module cats --pattern rest --repo inmemory
kick g module cats --pattern rest --repo drizzle
kick g module cats --pattern rest --repo prisma

The inmemory option is the default. It gives you a working module with no database dependency, which is great for prototyping and testing. The drizzle option generates a repository that uses Drizzle ORM with typed schemas. The prisma option generates one that delegates to a Prisma client.

In Vibed, we use MongoDB with Mongoose, which is not one of the generator's built-in options. We wrote our repository implementations by hand, following the interface contracts that the DDD pattern generates. The key point is that the generator gives you a starting point and a clear interface boundary. Whether you use the generated repository or write your own, the rest of the module -- controllers, use cases, DTOs -- does not change.

Wrapping Up

The kick g module command is more than a code generator. It is a decision framework. By offering four distinct patterns, it forces you to think about the architectural needs of each module before you write a single line of business logic. The minimal pattern keeps you honest about simplicity. The rest pattern gets you moving fast. The DDD pattern protects your domain. The CQRS pattern embraces events as first-class citizens.

After building Vibed across all four patterns, my advice is straightforward: start with minimal or rest, and promote to ddd or cqrs when the module's complexity demands it. The generator makes that promotion path cheap, and import.meta.glob ensures you never have to manually wire up your DI container along the way.

# Start simple
kick g module health --pattern minimal

# Standard CRUD
kick g module cats --pattern rest

# When the domain gets complex
kick g module billing --pattern ddd

# When events drive the feature
kick g module notifications --pattern cqrs

Four commands, four architectures, one framework. That is the kind of flexibility I want in a backend toolkit.

KickJS Query Engine Deep Dive: Filtering, Sorting, Search, and Pagination with MongoDB

Orinda Felix Ochieng — Sun, 22 Mar 2026 16:32:46 +0000

KickJS Query Engine Deep Dive: Filtering, Sorting, Search, and Pagination with MongoDB

When you're building an API with 60+ endpoints and 10+ list views, you can't afford inconsistency. Some endpoints return everything. Some paginate but don't filter. Some sort by createdAt, others by name, and the client has no idea which is which.

We solved this in Vibed — a Jira-like task management backend — by building a querying pipeline that flows from URL query strings, through KickJS's ctx.paginate(), into MongoDB helpers, and back out as a standardized paginated response. Every list endpoint works the same way.

Here's how the full pipeline works.

The Query Pipeline

Client request
  GET /api/v1/projects/abc/tasks?status=eq:open&priority=in:high,critical&sort=-dueDate&search=login&page=2&limit=10
       │
       ▼
  ctx.paginate(fetcher, TASK_QUERY_CONFIG)
       │
       ├── ctx.qs(config) parses the query string
       │   → filters: [{ field: 'status', operator: 'eq', value: 'open' }, ...]
       │   → sort: [{ field: 'dueDate', direction: 'desc' }]
       │   → search: 'login'
       │   → pagination: { page: 2, limit: 10, offset: 10 }
       │
       ▼
  fetcher(parsed) → repository.findPaginated(parsed)
       │
       ├── buildMongoFilter(filters) → { status: 'open', priority: { $in: ['high', 'critical'] } }
       ├── buildMongoSort(sort)      → { dueDate: -1 }
       ├── buildMongoSearch(search)  → { $text: { $search: 'login' } }
       │
       ▼
  MongoDB: Model.find(filter).sort(sort).skip(10).limit(10) + countDocuments(filter)
       │
       ▼
  Response: { data: [...], meta: { page: 2, limit: 10, total: 47, totalPages: 5, hasNext: true, hasPrev: true } }

One pipeline. Every endpoint. Let's break down each layer.

Layer 1: Query Configs

The foundation is a centralized config file that declares what each endpoint supports:

// src/shared/constants/query-configs.ts
import type { ApiQueryParamsConfig } from '@forinda/kickjs-core';

export const TASK_QUERY_CONFIG: ApiQueryParamsConfig = {
  filterable: ['status', 'priority', 'assigneeId', 'labelId', 'projectId'],
  sortable: ['createdAt', 'title', 'priority', 'dueDate', 'orderIndex'],
  searchable: ['title', 'description'],
};

export const WORKSPACE_QUERY_CONFIG: ApiQueryParamsConfig = {
  sortable: ['name', 'createdAt'],
  searchable: ['name', 'description'],
};

export const NOTIFICATION_QUERY_CONFIG: ApiQueryParamsConfig = {
  filterable: ['type', 'isRead'],
  sortable: ['createdAt'],
};

Each config serves three purposes:

Runtime parsing — ctx.qs(config) only parses fields listed here, ignoring anything else
Swagger docs — @ApiQueryParams(config) generates query parameter documentation automatically
Validation — prevents clients from filtering or sorting on fields you haven't whitelisted

We defined 11 configs for our endpoints: tasks, users, notifications, activity, labels, channels, workspaces, projects, comments, attachments, and members.

Layer 2: The Controller

The controller is where it all comes together — one decorator and one method call:

@Get('/projects/:projectId/tasks', {
  params: z.object({ projectId: z.string() }),
})
@Middleware(projectAccessGuard)
@ApiQueryParams(TASK_QUERY_CONFIG)
async list(ctx: RequestContext) {
  await ctx.paginate(
    async (parsed) => {
      // Inject the projectId as an additional filter
      parsed.filters.push({
        field: 'projectId',
        operator: 'eq',
        value: ctx.params.projectId,
      });
      return this.taskRepo.findPaginated(parsed);
    },
    TASK_QUERY_CONFIG,
  );
}

ctx.paginate() does everything:

Calls ctx.qs(config) internally to parse the query string
Passes the parsed result to your fetcher function
Wraps the { data, total } response with pagination metadata
Sends the JSON response

You never call ctx.qs() separately. You never manually build the response envelope. You just return { data, total } from the fetcher.

Injecting extra filters

Notice parsed.filters.push() — this is how you scope queries to a parent resource. The URL already has ?status=eq:open, and we add projectId programmatically. Both end up in the same MongoDB filter.

For simpler cases, you can pass the scope filter directly:

// Labels scoped to a workspace
async list(ctx: RequestContext) {
  await ctx.paginate(
    (parsed) => this.labelRepo.findPaginated(parsed, {
      workspaceId: ctx.params.workspaceId,
    }),
    LABEL_QUERY_CONFIG,
  );
}

Layer 3: The MongoDB Helpers

Three small functions translate the parsed query into MongoDB operations.

buildMongoFilter — 10 operators

export function buildMongoFilter(
  filters: Array<{ field: string; operator: string; value: string }>
): Record<string, any> {
  const mongoFilter: Record<string, any> = {};

  for (const { field, operator, value } of filters) {
    switch (operator) {
      case 'eq':       mongoFilter[field] = value; break;
      case 'neq':      mongoFilter[field] = { $ne: value }; break;
      case 'gt':       mongoFilter[field] = { $gt: value }; break;
      case 'gte':      mongoFilter[field] = { $gte: value }; break;
      case 'lt':       mongoFilter[field] = { $lt: value }; break;
      case 'lte':      mongoFilter[field] = { $lte: value }; break;
      case 'between': {
        const [min, max] = value.split(',');
        mongoFilter[field] = { $gte: min, $lte: max };
        break;
      }
      case 'in':       mongoFilter[field] = { $in: value.split(',') }; break;
      case 'contains': mongoFilter[field] = { $regex: value, $options: 'i' }; break;
      case 'starts':   mongoFilter[field] = { $regex: `^${value}`, $options: 'i' }; break;
      case 'ends':     mongoFilter[field] = { $regex: `${value}$`, $options: 'i' }; break;
      default:         mongoFilter[field] = value;
    }
  }

  return mongoFilter;
}

The URL syntax is field=operator:value:

?status=eq:open → { status: 'open' }
?priority=in:high,critical → { priority: { $in: ['high', 'critical'] } }
?dueDate=lte:2026-04-01 → { dueDate: { $lte: '2026-04-01' } }
?title=contains:auth → { title: { $regex: 'auth', $options: 'i' } }
?points=between:3,8 → { points: { $gte: '3', $lte: '8' } }

buildMongoSort — with default fallback

export function buildMongoSort(
  sort: Array<{ field: string; direction: 'asc' | 'desc' }>
): Record<string, 1 | -1> {
  const mongoSort: Record<string, 1 | -1> = {};
  for (const { field, direction } of sort) {
    mongoSort[field] = direction === 'asc' ? 1 : -1;
  }
  if (Object.keys(mongoSort).length === 0) {
    mongoSort.createdAt = -1; // default: newest first
  }
  return mongoSort;
}

URL syntax: ?sort=-dueDate,title → { dueDate: -1, title: 1 }. Prefix - means descending.

buildMongoSearch — full-text search

export function buildMongoSearch(search: string): Record<string, any> {
  if (!search) return {};
  return { $text: { $search: search } };
}

Uses MongoDB's $text operator, which requires a text index on the schema:

taskSchema.index({ title: 'text', description: 'text' });
userSchema.index({ firstName: 'text', lastName: 'text', email: 'text' });

URL: ?search=authentication searches across all indexed text fields.

Layer 4: The Repository

The findPaginated method brings it all together:

async findPaginated(
  parsed: any,
  extraFilter: Record<string, any> = {},
): Promise<{ data: TaskEntity[]; total: number }> {
  const {
    filters = [],
    sort = [],
    pagination = { page: 1, limit: 20, offset: 0 },
    search = '',
  } = parsed;

  const mongoFilter = {
    ...extraFilter,
    ...buildMongoFilter(filters),
    ...buildMongoSearch(search),
  };
  const mongoSort = buildMongoSort(sort);

  const [data, total] = await Promise.all([
    TaskModel.find(mongoFilter)
      .sort(mongoSort)
      .skip(pagination.offset)
      .limit(pagination.limit)
      .lean(),
    TaskModel.countDocuments(mongoFilter),
  ]);

  return { data: data as any[], total };
}

Key details:

extraFilter merges with parsed filters — used for scoping (e.g., { workspaceId })
Promise.all runs the data query and count query in parallel
.lean() returns plain objects instead of Mongoose documents (faster, smaller)
Returns { data, total } — that's the contract ctx.paginate() expects

For aggregation pipelines ($lookup)

When you need joins — like listing workspaces with the user's role — use aggregation instead:

async findPaginatedForUser(parsed: any, userId: string) {
  const { filters = [], sort = [], pagination = { ... } } = parsed;
  const matchStage = {
    userId: new mongoose.Types.ObjectId(userId),
    ...buildMongoFilter(filters),
  };
  const mongoSort = buildMongoSort(sort);

  const pipeline = [
    { $match: matchStage },
    { $lookup: {
      from: 'workspaces',
      localField: 'workspaceId',
      foreignField: '_id',
      as: 'workspace',
    }},
    { $unwind: '$workspace' },
    { $project: {
      _id: '$workspace._id',
      name: '$workspace.name',
      slug: '$workspace.slug',
      role: '$role',
      createdAt: '$workspace.createdAt',
    }},
    { $sort: mongoSort },
  ];

  const countPipeline = [...pipeline, { $count: 'total' }];
  const dataPipeline = [...pipeline, { $skip: pagination.offset }, { $limit: pagination.limit }];

  const [countResult, data] = await Promise.all([
    WorkspaceMemberModel.aggregate(countPipeline),
    WorkspaceMemberModel.aggregate(dataPipeline),
  ]);

  return { data, total: countResult[0]?.total ?? 0 };
}

Same { data, total } contract. ctx.paginate() doesn't care whether you used find() or aggregate().

The Response Shape

Every paginated endpoint returns the same structure:

{
  "data": [
    { "_id": "abc", "title": "Fix login bug", "status": "open", "priority": "high" },
    { "_id": "def", "title": "Add dark mode", "status": "todo", "priority": "medium" }
  ],
  "meta": {
    "page": 2,
    "limit": 10,
    "total": 47,
    "totalPages": 5,
    "hasNext": true,
    "hasPrev": true
  }
}

Frontend developers love this. They get hasNext/hasPrev for pagination controls, total for "showing 11-20 of 47 results", and totalPages for page number navigation. No guessing.

Real API Examples

Here are actual queries you can make against the Vibed API:

# Tasks in a project, filtered by status and priority, sorted by due date
GET /api/v1/projects/abc/tasks?status=eq:in-progress&priority=in:high,critical&sort=-dueDate&limit=5

# Search tasks by title/description
GET /api/v1/projects/abc/tasks?search=authentication&sort=-createdAt

# Labels in a workspace, sorted alphabetically
GET /api/v1/workspaces/xyz/labels?sort=name&limit=50

# Workspace members filtered by role
GET /api/v1/workspaces/xyz/members?role=eq:admin&sort=-joinedAt

# Notifications, unread only, newest first
GET /api/v1/notifications?isRead=eq:false&sort=-createdAt&page=1&limit=20

# Activity feed for a project, filtered by action type
GET /api/v1/projects/abc/activity?action=eq:task.created&sort=-createdAt

All return the same { data, meta } shape. All support the same filter operators.

Adding a New Paginated Endpoint

The process is mechanical — about 5 minutes per endpoint:

Define the query config in query-configs.ts:

export const INVOICE_QUERY_CONFIG: ApiQueryParamsConfig = {
  filterable: ['status', 'clientId', 'dueDate'],
  sortable: ['createdAt', 'amount', 'dueDate'],
  searchable: ['number', 'clientName'],
};

Add findPaginated to the repository (copy-paste the pattern, change the model name)
Update the controller:

@ApiQueryParams(INVOICE_QUERY_CONFIG)
async list(ctx: RequestContext) {
  await ctx.paginate(
    (parsed) => this.invoiceRepo.findPaginated(parsed, { workspaceId: ctx.params.workspaceId }),
    INVOICE_QUERY_CONFIG,
  );
}

That's it. Swagger docs, query parsing, filtering, sorting, search, pagination — all handled.

What We'd Change

A few things that could be better:

Type the parsed parameter — right now it's any. A ParsedQuery type from KickJS would make the contract explicit.
Date coercion — buildMongoFilter passes values as strings. Date fields like dueDate=lte:2026-04-01 should be coerced to Date objects. We handle this per-field in some repos but it should be generic.
Aggregation helper — The findPaginated pattern for $lookup pipelines is more boilerplate than the simple find() version. A buildPaginatedAggregation(pipeline, parsed) helper would reduce that.
Cursor-based pagination — For real-time feeds (messages, activity), offset-based pagination has issues with insertions shifting pages. Our messages controller uses cursor-based (before/after) pagination, which is better for those cases.

Conclusion

The full querying pipeline — query configs, ctx.paginate(), buildMongo* helpers, and the findPaginated repository pattern — gives us:

Consistency: every list endpoint works the same way
Discoverability: Swagger docs auto-generated from the same config
Safety: only whitelisted fields can be filtered/sorted
Performance: parallel data + count queries, MongoDB indexes
DX: adding a new paginated endpoint takes 5 minutes

If you're building an API with more than a handful of list endpoints, standardize early. Your frontend team will thank you.

This article is part of a series on building Vibed, a Jira-like task management backend with KickJS. Check out the complete project guide for the full walkthrough.

Building a Complete Jira-like Task Management Backend with KickJS — From Scaffold to Production

Orinda Felix Ochieng — Sun, 22 Mar 2026 16:30:10 +0000

TL;DR

This is the complete project guide for Vibed — a Jira-like task management backend built with KickJS v1.2.2. It covers everything from initial scaffold to production-ready features: 14 modules, 65+ endpoints, real-time WebSocket chat, SSE live dashboards, BullMQ background jobs, cron scheduling, and the framework issues we filed along the way.

If you've been following the article series, this brings it all together. If you're starting here, this is everything you need to build a non-trivial backend with KickJS.

1. Project Overview and Tech Stack

Vibed is a task management platform modeled after Jira's API surface. It supports workspaces, projects, task boards with drag-and-drop reordering, comments with @mentions, file attachments, real-time chat channels, live dashboard stats, email notifications, and activity feeds.

Concern	Technology
Framework	KickJS v1.2.2 (`@forinda/kickjs-*` packages)
Language	TypeScript (ESM)
Database	MongoDB via Mongoose 9
Cache / Queue broker	Redis (ioredis)
Background jobs	BullMQ
Auth	JWT (access + refresh token rotation), bcryptjs
Email	Resend (production) / ConsoleProvider (development)
Real-time	WebSocket chat (Socket.IO via WsAdapter)
Live updates	Server-Sent Events via `ctx.sse()`
Scheduled jobs	CronAdapter (overdue reminders, daily digest, token cleanup, presence cleanup)
API docs	Swagger via SwaggerAdapter
Dev tools	DevToolsAdapter at `/_debug/*`
Build	Vite + SWC
Package manager	pnpm

KickJS is a decorator-driven Node.js framework built on Express 5. It uses TypeScript decorators for routing (@Get, @Post), dependency injection (@Service, @Inject, @Autowired), validation (@Validate with Zod), and documentation (@ApiTags, @ApiOperation). If you've used NestJS, the patterns will feel familiar — but KickJS is lighter, uses Express directly, and emphasizes convention over configuration.

2. Project Setup

Scaffolding

kick new vibed --pm pnpm
kick add auth ws mailer queue cron swagger devtools

The first command scaffolds a KickJS project with the REST template. The second adds adapter packages for auth, WebSocket, email, queues, cron, Swagger, and dev tools.

Module Generation

kick g module tasks
kick g module workspaces
kick g module comments
# ... repeat for each module

Each kick g module creates the full DDD directory structure:

module/
├── <name>.module.ts              # AppModule: register() + routes()
├── presentation/
│   └── <name>.controller.ts      # @Controller, @Get, @Post, etc.
├── application/
│   ├── dtos/                     # Zod validation schemas
│   └── use-cases/                # Single-purpose business logic classes
├── domain/
│   ├── entities/                 # TypeScript interfaces
│   └── repositories/            # Repository interfaces
└── infrastructure/
    ├── schemas/                  # Mongoose schemas + models
    └── repositories/            # Mongo repository implementations

Environment Configuration with Zod

All environment variables are validated at startup via Zod:

// src/config/env.ts
import { z } from 'zod';
import { defineEnv, loadEnv } from '@forinda/kickjs-config';

const envSchema = defineEnv((base) =>
  base.extend({
    MONGODB_URI: z.string().url(),
    REDIS_URL: z.string().url(),
    JWT_SECRET: z.string().min(32),
    JWT_REFRESH_SECRET: z.string().min(32),
    JWT_ACCESS_EXPIRES_IN: z.string().default('15m'),
    JWT_REFRESH_EXPIRES_IN: z.string().default('7d'),
    RESEND_API_KEY: z.string().min(1),
    MAIL_FROM_NAME: z.string().default('Vibed'),
    MAIL_FROM_EMAIL: z.string().email(),
    APP_URL: z.string().url(),
    APP_NAME: z.string().default('Vibed'),
  }),
);

export const env = loadEnv(envSchema);

If any required variable is missing or invalid, the app fails fast at startup with a clear Zod validation error. No more "undefined is not a function" errors 10 minutes into runtime because REDIS_URL was misspelled.

Entry Point

The entry point is deliberately minimal — all configuration is delegated to dedicated files:

// src/index.ts
import 'reflect-metadata';
import { bootstrap } from '@forinda/kickjs-http';
import { modules } from './modules';
import { adapters } from './config/adapters';
import { middleware } from './config/middleware';

bootstrap({
  modules,
  apiPrefix: '/api',
  defaultVersion: 1,
  middleware,
  adapters,
});

Global middleware uses Express signatures (not KickJS RequestContext):

// src/config/middleware.ts
import express from 'express';
import cors from 'cors';
import helmet from 'helmet';
import { requestIdMiddleware } from '@/shared/presentation/middlewares/request-id.middleware';

export const middleware = [
  requestIdMiddleware,
  cors(),
  helmet(),
  express.json({ limit: '5mb' }),
  express.urlencoded({ extended: true }),
];

3. Authentication: JWT with Refresh Rotation

The Auth Controller

Auth endpoints are public — no authBridgeMiddleware:

@ApiTags('Auth')
@Controller()
export class AuthController {
  @Autowired() private registerUseCase!: RegisterUseCase;
  @Autowired() private loginUseCase!: LoginUseCase;
  @Autowired() private refreshTokenUseCase!: RefreshTokenUseCase;
  @Autowired() private logoutUseCase!: LogoutUseCase;

  @Post('/register', { body: registerSchema })
  @Public()
  @ApiOperation({ summary: 'Register a new user account' })
  async register(ctx: RequestContext) {
    const result = await this.registerUseCase.execute(ctx.body);
    ctx.created(successResponse(result, 'Registration successful'));
  }

  @Post('/login', { body: loginSchema })
  @Public()
  async login(ctx: RequestContext) {
    const result = await this.loginUseCase.execute(ctx.body);
    ctx.json(successResponse(result, 'Login successful'));
  }

  @Post('/refresh', { body: refreshTokenSchema })
  @Public()
  async refresh(ctx: RequestContext) {
    const result = await this.refreshTokenUseCase.execute(ctx.body);
    ctx.json(successResponse(result));
  }
}

DTOs are Zod schemas:

// register.dto.ts
export const registerSchema = z.object({
  email: z.string().email(),
  password: z.string().min(8).max(128),
  firstName: z.string().min(1).max(50),
  lastName: z.string().min(1).max(50),
});

// login.dto.ts
export const loginSchema = z.object({
  email: z.string().email(),
  password: z.string().min(1),
});

The Auth Bridge Middleware

Every protected controller uses authBridgeMiddleware at the class level:

// src/shared/presentation/middlewares/auth-bridge.middleware.ts
export const authBridgeMiddleware: MiddlewareHandler = (ctx: RequestContext, next) => {
  const user = (ctx.req as any).user;
  if (user) {
    ctx.set('user', user);
  }
  next();
};

The AuthAdapter with JwtStrategy validates the JWT and puts the user on req.user. The bridge middleware copies it to ctx metadata so handlers can use ctx.get('user') or the getUser() helper.

The getUser Helper

// src/shared/utils/auth.ts
export function getUser(ctx: RequestContext): AuthUser {
  const user = ctx.get<AuthUser>('user');
  if (!user) throw HttpException.unauthorized('Authentication required');
  return user;
}

Every controller that needs the current user calls getUser(ctx) instead of accessing context directly. This abstraction saved us when the framework fixed the ctx.set/get sharing bug in v1.2.5 — one file changed, zero controllers touched.

Guards

Role-based access uses guard middleware that composes with authBridgeMiddleware:

// src/shared/guards/workspace-membership.guard.ts
export const workspaceMembershipGuard: MiddlewareHandler = async (ctx, next) => {
  const user = ctx.get('user');
  if (!user) throw HttpException.unauthorized('Authentication required');

  const workspaceId = ctx.params.workspaceId;
  if (!workspaceId) return next();

  const container = Container.getInstance();
  const memberRepo = container.resolve<IWorkspaceMemberRepository>(
    TOKENS.WORKSPACE_MEMBER_REPOSITORY,
  );
  const member = await memberRepo.findByUserAndWorkspace(user.id, workspaceId);

  if (!member) throw HttpException.forbidden(ErrorCode.NOT_WORKSPACE_MEMBER);

  ctx.set('workspaceMember', member);
  next();
};

Guards resolve repositories from the DI container at request time via Container.getInstance(). This avoids circular dependency issues that arise when guards depend on repositories that depend on modules.

4. Core Modules: DDD Structure Walkthrough

The Module Registry

All modules are registered in src/modules/index.ts:

import type { AppModuleClass } from '@forinda/kickjs-core';
import { AuthModule } from './auth/auth.module';
import { UsersModule } from './users/users.module';
import { WorkspacesModule } from './workspaces/workspaces.module';
import { ProjectsModule } from './projects/projects.module';
import { TasksModule } from './tasks/tasks.module';
import { CommentsModule } from './comments/comments.module';
import { LabelsModule } from './labels/labels.module';
import { ChannelsModule } from './channels/channels.module';
import { MessagesModule } from './messages/messages.module';
import { NotificationsModule } from './notifications/notifications.module';
import { ActivityModule } from './activity/activity.module';
import { AttachmentsModule } from './attachments/attachments.module';
import { StatsModule } from './stats/stats.module';
import { QueueModule } from './queue/queue.module';

export const modules: AppModuleClass[] = [
  QueueModule,
  AuthModule,
  UsersModule,
  WorkspacesModule,
  ProjectsModule,
  LabelsModule,
  TasksModule,
  CommentsModule,
  AttachmentsModule,
  ActivityModule,
  NotificationsModule,
  ChannelsModule,
  MessagesModule,
  StatsModule,
];

Tasks Module — A Complete Walkthrough

The tasks module is the most feature-rich. Let me walk through each layer.

Module registration maps the DI token to the concrete repository:

// src/modules/tasks/tasks.module.ts
export class TasksModule implements AppModule {
  register(container: Container): void {
    container.registerFactory(TOKENS.TASK_REPOSITORY, () =>
      container.resolve(MongoTaskRepository),
    );
  }

  routes(): ModuleRoutes {
    return {
      path: '/',
      router: buildRoutes(TasksController),
      controller: TasksController,
    };
  }
}

The path: '/' means routes are mounted at the API root. The controller defines the full paths: /projects/:projectId/tasks, /tasks/:taskId, etc.

Mongoose schema with HMR guard:

// src/modules/tasks/infrastructure/schemas/task.schema.ts
const taskSchema = new Schema<TaskDocument>(
  {
    projectId: { type: Schema.Types.ObjectId, ref: 'Project', required: true, index: true },
    workspaceId: { type: Schema.Types.ObjectId, ref: 'Workspace', required: true, index: true },
    key: { type: String, required: true, unique: true, index: true },
    title: { type: String, required: true, trim: true },
    description: { type: String },
    status: { type: String, default: 'todo' },
    priority: { type: String, enum: ['critical', 'high', 'medium', 'low', 'none'], default: 'none' },
    assigneeIds: [{ type: Schema.Types.ObjectId, ref: 'User' }],
    reporterId: { type: Schema.Types.ObjectId, ref: 'User', required: true },
    labelIds: [{ type: Schema.Types.ObjectId, ref: 'Label' }],
    parentTaskId: { type: Schema.Types.ObjectId, ref: 'Task' },
    dueDate: { type: Date },
    estimatePoints: { type: Number },
    orderIndex: { type: Number, default: 0 },
  },
  { timestamps: true },
);

// HMR guard — REQUIRED for Vite dev server
export const TaskModel =
  (mongoose.models.Task as mongoose.Model<TaskDocument>) ||
  mongoose.model<TaskDocument>('Task', taskSchema);

Without the HMR guard, every file save that triggers a re-import crashes with OverwriteModelError.

Use case with constructor DI injection:

// src/modules/tasks/application/use-cases/create-task.use-case.ts
@Service()
export class CreateTaskUseCase {
  constructor(
    @Inject(TOKENS.TASK_REPOSITORY) private taskRepo: ITaskRepository,
    @Inject(TOKENS.PROJECT_REPOSITORY) private projectRepo: IProjectRepository,
  ) {}

  async execute(projectId: string, userId: string, dto: CreateTaskDto) {
    const project = await this.projectRepo.findById(projectId);
    if (!project) throw new Error('Project not found');

    const counter = await this.projectRepo.incrementTaskCounter(projectId);
    const key = `${project.key}-${counter}`;

    const maxOrderTask = await this.taskRepo.findByProject(projectId);
    const maxOrder = maxOrderTask.length > 0
      ? Math.max(...maxOrderTask.filter(t => t.status === dto.status).map(t => t.orderIndex))
      : -1;

    return this.taskRepo.create({
      ...dto,
      projectId: projectId as any,
      workspaceId: project.workspaceId,
      key,
      reporterId: userId as any,
      orderIndex: maxOrder + 1,
    });
  }
}

The task key pattern (PROJ-1, PROJ-2, etc.) mirrors Jira's issue keys. incrementTaskCounter atomically increments a counter on the project document to ensure uniqueness.

Controller with property injection via @Autowired():

@ApiTags('Tasks')
@ApiBearerAuth()
@Middleware(authBridgeMiddleware)
@Controller()
export class TasksController {
  @Autowired() private createTaskUseCase!: CreateTaskUseCase;
  @Autowired() private taskRepo!: MongoTaskRepository;

  @Post('/projects/:projectId/tasks', {
    params: z.object({ projectId: z.string() }),
    body: createTaskSchema,
  })
  @Middleware(projectAccessGuard)
  @ApiOperation({ summary: 'Create a new task in a project' })
  @ApiResponse({ status: 201, description: 'Task created successfully' })
  async create(ctx: RequestContext) {
    const user = ctx.get('user');
    const result = await this.createTaskUseCase.execute(ctx.params.projectId, user.id, ctx.body);
    ctx.created(successResponse(result, 'Task created'));
  }

  @Get('/projects/:projectId/tasks', {
    params: z.object({ projectId: z.string() }),
  })
  @Middleware(projectAccessGuard)
  @ApiQueryParams(TASK_QUERY_CONFIG)
  async list(ctx: RequestContext) {
    await ctx.paginate(
      async (parsed) => {
        parsed.filters.push({ field: 'projectId', operator: 'eq', value: ctx.params.projectId });
        return this.taskRepo.findPaginated(parsed);
      },
      TASK_QUERY_CONFIG,
    );
  }
}

DI Pattern Summary

Where	Technique	When to Use
Controller properties	`@Autowired()`	Concrete classes (use cases, repos)
Use case constructor	`@Inject(TOKENS.X)`	Interface-based repos via Symbol tokens
Processor constructor	`@Inject(MAILER)`	Framework service symbols
Module `register()`	`container.registerFactory()`	Mapping tokens to implementations

Critical rule: @Inject(TOKEN) only works on constructor parameters. @Autowired() only works on properties (resolves by class type). Mixing them up causes silent failures.

5. Supporting Modules

Labels

Workspace-scoped label CRUD. Labels can be attached to tasks via labelIds. Nothing complex — standard CRUD with workspaceMembershipGuard.

Comments

Comment CRUD with @mention parsing. Creating a comment triggers a notification job via BullMQ. The @mention pattern is parsed from the comment content and stored as a mentions array on the comment document.

Attachments

File upload using multipart form data. Files are converted to base64 and stored in MongoDB (not ideal for production, but keeps the stack simple). The controller increments task.attachmentCount for denormalized display.

Notifications

In-app notification system. Notifications are created by background jobs (not directly by controllers). Endpoints: list paginated, mark as read, mark all as read, unread count. The unread count endpoint is what the frontend polls for the notification badge.

6. Real-Time: WebSocket Chat and SSE Stats

WebSocket Chat

The ChatWsController handles real-time messaging via Socket.IO rooms:

@WsController('/chat')
export class ChatWsController {
  @Autowired() private messageRepo!: MongoMessageRepository;

  @OnConnect()
  handleConnect(ctx: WsContext) {
    const token = ctx.data?.token || '';
    const payload = jwt.verify(token, env.JWT_SECRET) as any;
    ctx.set('userId', payload.sub);
    onlineUsers.set(ctx.id, { userId: payload.sub, userName: payload.email });
    ctx.broadcastAll('presence:online', { userId: payload.sub, userName: payload.email });
  }

  @OnMessage('channel:join')
  handleJoin(ctx: WsContext) {
    const channelId = ctx.data?.channelId;
    ctx.join(`channel:${channelId}`);
    ctx.to(`channel:${channelId}`).send('channel:user_joined', {
      channelId,
      userId: ctx.get('userId'),
    });
  }

  @OnMessage('channel:typing')
  handleTyping(ctx: WsContext) {
    const { channelId } = ctx.data || {};
    const info = onlineUsers.get(ctx.id);
    ctx.to(`channel:${channelId}`).send('channel:typing', {
      channelId,
      userId: ctx.get('userId'),
      userName: info?.userName,
    });
  }

  @OnMessage('message:send')
  async handleSend(ctx: WsContext) {
    const userId = ctx.get('userId');
    const { channelId, content } = ctx.data || {};

    const message = await this.messageRepo.create({
      channelId, senderId: userId, content, mentions: [],
    });

    const payload = {
      messageId: message._id.toString(),
      channelId,
      senderId: userId,
      content: message.content,
      createdAt: message.createdAt,
    };

    ctx.to(`channel:${channelId}`).send('message:new', payload);
    ctx.send('message:new', payload); // Echo to sender
  }
}

WebSocket events: channel:join, channel:leave, message:send, message:edit, message:delete, channel:typing, channel:stop_typing.

REST endpoints handle message history and editing: GET /channels/:channelId/messages, PATCH /messages/:messageId, DELETE /messages/:messageId.

SSE Live Stats

The stats module uses ctx.sse() for server-pushed updates:

@Controller()
@Middleware(authBridgeMiddleware)
export class StatsController {
  @Autowired() private taskRepo!: MongoTaskRepository;

  @Get('/projects/:projectId/stats/live')
  @Middleware(projectAccessGuard)
  async projectLive(ctx: RequestContext) {
    const sse = ctx.sse();
    const projectId = ctx.params.projectId;

    const sendStats = async () => {
      const tasksByStatus = await this.taskRepo.countByStatus(projectId);
      const totalTasks = Object.values(tasksByStatus).reduce((sum, c) => sum + c, 0);
      const doneTasks = tasksByStatus['done'] ?? 0;
      const completionRate = totalTasks > 0 ? Math.round((doneTasks / totalTasks) * 100) : 0;

      sse.send({ tasksByStatus, totalTasks, completionRate }, 'stats:update');
    };

    await sendStats();
    const interval = setInterval(sendStats, 10000);
    sse.onClose(() => clearInterval(interval));
  }
}

SSE endpoints: workspace live stats, project live stats, workspace activity live.

7. Background Jobs: BullMQ Processors

Queue Configuration

// src/config/adapters.ts
const queueAdapter = new QueueAdapter({
  redis: {
    host: redisUrl.hostname,
    port: Number(redisUrl.port) || 6379,
    password: redisUrl.password || undefined,
  },
  queues: ['email', 'notifications', 'activity'],
  concurrency: 5,
});

Email Processor

@Service()
@Job('email')
export class EmailProcessor {
  @Autowired(MAILER) private mailer!: MailerService;

  @Process('send-welcome-email')
  async sendWelcome(job: BullMQJob<{ email: string; firstName: string }>) {
    logger.info(`Sending welcome email to ${job.data.email}`);
    await this.mailer.send({
      to: job.data.email,
      subject: `Welcome to Vibed, ${job.data.firstName}!`,
      html: `<h1>Welcome to Vibed!</h1><p>Hi ${job.data.firstName}, your account is ready.</p>`,
    });
  }

  @Process('send-task-assigned')
  async sendTaskAssigned(job: BullMQJob<{ email: string; taskKey: string; taskTitle: string }>) {
    await this.mailer.send({
      to: job.data.email,
      subject: `You were assigned to ${job.data.taskKey}: ${job.data.taskTitle}`,
      html: `<p>You were assigned to <strong>${job.data.taskKey}</strong></p>`,
    });
  }

  @Process('send-overdue-reminder')
  async sendOverdueReminder(job: BullMQJob<{ email: string; taskKey: string; dueDate: string }>) {
    await this.mailer.send({
      to: job.data.email,
      subject: `Overdue: ${job.data.taskKey}`,
      html: `<p>Task ${job.data.taskKey} was due on ${job.data.dueDate}</p>`,
    });
  }
}

The QueueModule imports processors as side-effects so @Job() decorators register in the job registry:

// src/modules/queue/queue.module.ts
import './infrastructure/processors/email.processor';
import './infrastructure/processors/notification.processor';
import './infrastructure/processors/activity.processor';

export class QueueModule implements AppModule {
  register(_container: Container): void {
    // QueueAdapter v1.2.6+ auto-registers @Job classes
  }

  routes(): ModuleRoutes | null {
    return null; // No HTTP routes
  }
}

Cron Jobs

@Service()
export class PresenceCronJobs {
  @Cron('*/5 * * * *', { description: 'Clean up stale presence entries' })
  async cleanupPresence() {
    logger.info('Running presence cleanup...');
  }
}

Cron services are registered in the CronAdapter, not in the modules array:

new CronAdapter({
  services: [TaskCronJobs, DigestCronJobs, CleanupCronJobs, PresenceCronJobs, HealthCheckCronJobs],
  enabled: true,
});

8. Pagination: ctx.paginate and Query Configs

Defining Query Configs

All query configurations are centralized in shared/constants/query-configs.ts:

import type { ApiQueryParamsConfig } from '@forinda/kickjs-core';

export const TASK_QUERY_CONFIG: ApiQueryParamsConfig = {
  filterable: ['status', 'priority', 'assigneeId', 'labelId', 'projectId'],
  sortable: ['createdAt', 'title', 'priority', 'dueDate', 'orderIndex'],
  searchable: ['title', 'description'],
};

export const WORKSPACE_QUERY_CONFIG: ApiQueryParamsConfig = {
  sortable: ['name', 'createdAt'],
  searchable: ['name', 'description'],
};

Using ctx.paginate

The controller passes a fetcher function and the config to ctx.paginate():

@Get('/projects/:projectId/tasks')
@ApiQueryParams(TASK_QUERY_CONFIG)
async list(ctx: RequestContext) {
  await ctx.paginate(
    async (parsed) => {
      parsed.filters.push({ field: 'projectId', operator: 'eq', value: ctx.params.projectId });
      return this.taskRepo.findPaginated(parsed);
    },
    TASK_QUERY_CONFIG,
  );
}

ctx.paginate() calls ctx.qs() internally to parse query string parameters, then calls the fetcher with the parsed result. The response includes pagination metadata:

{
  "data": [...],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 42,
    "totalPages": 3,
    "hasNext": true,
    "hasPrev": false
  }
}

Query Helpers

Repositories use helper functions to convert parsed query params to Mongoose operations:

export function buildMongoFilter(
  filters: Array<{ field: string; operator: string; value: string }>,
): Record<string, any> {
  const mongoFilter: Record<string, any> = {};
  for (const { field, operator, value } of filters) {
    switch (operator) {
      case 'eq': mongoFilter[field] = value; break;
      case 'neq': mongoFilter[field] = { $ne: value }; break;
      case 'in': mongoFilter[field] = { $in: value.split(',') }; break;
      case 'contains': mongoFilter[field] = { $regex: value, $options: 'i' }; break;
      // ... gt, gte, lt, lte, between, starts, ends
    }
  }
  return mongoFilter;
}

export function buildMongoSort(
  sort: Array<{ field: string; direction: 'asc' | 'desc' }>,
): Record<string, 1 | -1> {
  const mongoSort: Record<string, 1 | -1> = {};
  for (const { field, direction } of sort) {
    mongoSort[field] = direction === 'asc' ? 1 : -1;
  }
  if (Object.keys(mongoSort).length === 0) mongoSort.createdAt = -1;
  return mongoSort;
}

9. DI Tokens

All DI Symbol tokens are centralized in one file:

// src/shared/constants/tokens.ts
export const TOKENS = {
  USER_REPOSITORY: Symbol('UserRepository'),
  REFRESH_TOKEN_REPOSITORY: Symbol('RefreshTokenRepository'),
  WORKSPACE_REPOSITORY: Symbol('WorkspaceRepository'),
  WORKSPACE_MEMBER_REPOSITORY: Symbol('WorkspaceMemberRepository'),
  PROJECT_REPOSITORY: Symbol('ProjectRepository'),
  TASK_REPOSITORY: Symbol('TaskRepository'),
  COMMENT_REPOSITORY: Symbol('CommentRepository'),
  LABEL_REPOSITORY: Symbol('LabelRepository'),
  CHANNEL_REPOSITORY: Symbol('ChannelRepository'),
  MESSAGE_REPOSITORY: Symbol('MessageRepository'),
  NOTIFICATION_REPOSITORY: Symbol('NotificationRepository'),
  ACTIVITY_REPOSITORY: Symbol('ActivityRepository'),
  ATTACHMENT_REPOSITORY: Symbol('AttachmentRepository'),
  PRESENCE_SERVICE: Symbol('PresenceService'),
  QUEUE_SERVICE: Symbol('QueueService'),
} as const;

10. Full Module Structure

src/
├── index.ts                          # Entry point
├── config/
│   ├── env.ts                        # Zod env validation
│   ├── adapters.ts                   # All adapter configurations
│   └── middleware.ts                  # Global Express middleware
├── shared/
│   ├── constants/
│   │   ├── tokens.ts                 # DI Symbol tokens
│   │   ├── error-codes.ts            # Error code enum
│   │   └── query-configs.ts          # Pagination configs
│   ├── guards/
│   │   ├── workspace-membership.guard.ts
│   │   ├── project-access.guard.ts
│   │   └── channel-membership.guard.ts
│   ├── presentation/middlewares/
│   │   ├── auth-bridge.middleware.ts
│   │   └── request-id.middleware.ts
│   ├── utils/
│   │   └── auth.ts                   # getUser(ctx) helper
│   └── infrastructure/
│       ├── database/
│       │   ├── mongoose.adapter.ts
│       │   └── query-helpers.ts
│       ├── redis/
│       │   └── redis.config.ts
│       └── mail/
│           └── resend.provider.ts
└── modules/
    ├── index.ts                      # Module registry
    ├── auth/                         # Register, login, refresh, logout
    ├── users/                        # Profile CRUD
    ├── workspaces/                   # CRUD + membership + invite
    ├── projects/                     # CRUD + board view
    ├── tasks/                        # CRUD + status/priority/assignees/reorder
    ├── comments/                     # CRUD + @mention parsing
    ├── labels/                       # Workspace-scoped label CRUD
    ├── channels/                     # Chat channel CRUD + membership
    ├── messages/                     # REST history + WebSocket chat
    ├── notifications/                # In-app notifications + unread count
    ├── activity/                     # Activity feed
    ├── attachments/                  # File upload
    ├── stats/                        # SSE live dashboards
    ├── queue/                        # BullMQ processors
    └── cron/                         # Scheduled jobs

11. API Endpoint Summary

Base prefix: /api/v1

Auth (`/api/v1/auth`) — No auth required

Method	Path	Description
POST	`/register`	Register new user
POST	`/login`	Login with credentials
POST	`/refresh`	Refresh JWT token pair
POST	`/logout`	Logout (invalidate refresh)

Users (`/api/v1/users`)

Method	Path	Description
GET	`/me`	Current user profile
PATCH	`/me`	Update profile
GET	`/:id`	Get user by ID
GET	`/`	List users (paginated)

Workspaces (`/api/v1/workspaces`)

Method	Path	Description
POST	`/`	Create workspace
GET	`/`	List user's workspaces
GET	`/:workspaceId`	Get workspace
PATCH	`/:workspaceId`	Update workspace
DELETE	`/:workspaceId`	Delete workspace
POST	`/:workspaceId/invite`	Invite member
GET	`/:workspaceId/members`	List members
PATCH	`/:workspaceId/members/:userId`	Update member role
DELETE	`/:workspaceId/members/:userId`	Remove member
POST	`/:workspaceId/leave`	Leave workspace

Projects (`/api/v1`)

Method	Path	Description
POST	`/workspaces/:workspaceId/projects`	Create project
GET	`/workspaces/:workspaceId/projects`	List projects
GET	`/projects/:projectId`	Get project
PATCH	`/projects/:projectId`	Update project
DELETE	`/projects/:projectId`	Delete project
GET	`/projects/:projectId/board`	Board view

Tasks (`/api/v1`)

Method	Path	Description
POST	`/projects/:projectId/tasks`	Create task
GET	`/projects/:projectId/tasks`	List tasks (paginated)
GET	`/tasks/:taskId`	Get task
PATCH	`/tasks/:taskId`	Update task
DELETE	`/tasks/:taskId`	Delete task
PATCH	`/tasks/:taskId/status`	Change status
PATCH	`/tasks/:taskId/assignees`	Update assignees
POST	`/tasks/:taskId/reorder`	Reorder in column
GET	`/tasks/:taskId/subtasks`	List subtasks

Comments (`/api/v1`)

Method	Path	Description
POST	`/tasks/:taskId/comments`	Create comment
GET	`/tasks/:taskId/comments`	List comments
PATCH	`/comments/:commentId`	Update comment
DELETE	`/comments/:commentId`	Delete comment

Labels (`/api/v1`)

Method	Path	Description
POST	`/workspaces/:workspaceId/labels`	Create label
GET	`/workspaces/:workspaceId/labels`	List labels
PATCH	`/labels/:labelId`	Update label
DELETE	`/labels/:labelId`	Delete label

Attachments (`/api/v1`)

Method	Path	Description
POST	`/tasks/:taskId/attachments`	Upload
GET	`/tasks/:taskId/attachments`	List
GET	`/attachments/:attachmentId`	Metadata
GET	`/attachments/:attachmentId/download`	Download
DELETE	`/attachments/:attachmentId`	Delete

Channels (`/api/v1`)

Method	Path	Description
POST	`/workspaces/:workspaceId/channels`	Create channel
GET	`/workspaces/:workspaceId/channels`	List channels
GET	`/channels/:channelId`	Get channel
DELETE	`/channels/:channelId`	Delete channel
POST	`/channels/:channelId/members`	Add member
DELETE	`/channels/:channelId/members/:userId`	Remove member

Messages (`/api/v1`)

Method	Path	Description
GET	`/channels/:channelId/messages`	Message history
PATCH	`/messages/:messageId`	Edit message
DELETE	`/messages/:messageId`	Delete message

Notifications (`/api/v1/notifications`)

Method	Path	Description
GET	`/`	List (paginated)
PATCH	`/:id/read`	Mark as read
POST	`/read-all`	Mark all as read
GET	`/unread-count`	Unread count

Activity (`/api/v1`)

Method	Path	Description
GET	`/workspaces/:workspaceId/activity`	Workspace activity
GET	`/projects/:projectId/activity`	Project activity
GET	`/tasks/:taskId/activity`	Task activity

Stats — SSE (`/api/v1`)

Method	Path	Description
GET	`/workspaces/:workspaceId/stats/live`	SSE workspace stats
GET	`/projects/:projectId/stats/live`	SSE project stats
GET	`/workspaces/:workspaceId/activity/live`	SSE activity stream

WebSocket (`/ws/chat`)

Event	Direction	Description
`channel:join`	Client -> Server	Join room
`channel:leave`	Client -> Server	Leave room
`message:send`	Client -> Server	Send message
`message:edit`	Client -> Server	Edit message
`message:delete`	Client -> Server	Delete message
`channel:typing`	Client -> Server	Typing indicator
`channel:stop_typing`	Client -> Server	Stop typing

12. Framework Issues and Contributing Back

We tracked 18 framework issues in framework-filed-issues/ — 13 bug reports, 1 documentation issue, and 4 feature requests. Seven issues were fixed across four KickJS releases (v1.2.3, v1.2.5, v1.2.6, v1.2.7).

Key issues and their resolutions:

Issue	Problem	Resolution
KICK-003	Modules without routes crash Express	v1.2.3: `routes()` can return `null`
KICK-009	`ctx.set/get` not shared across middleware/handler	v1.2.5: Metadata Map stored on `req`
KICK-016	`@Service + @Job` not auto-registered in DI	v1.2.6: QueueAdapter auto-registers
KICK-017	`@Service()` should mean auto-DI-registration	v1.2.7: Container.bootstrap() scans

The feedback loop that made this work: discover the bug during development, build a workaround, file a detailed issue with a suggested fix, validate the upstream fix, remove the workaround, update the docs.

13. What's Next

Features planned but not yet implemented:

Typed API Client (KICK-018)

A kick generate:client command that produces a tRPC-like typed client from the existing route decorators and Zod DTOs. All the metadata exists — it just needs to be surfaced to a client generator.

Subtask CRUD

The task schema already has parentTaskId. Full subtask CRUD (create, list, reparent, delete) is the next module addition.

Forgot Password Flow

The email processor already has send-password-reset. The missing piece is the auth controller endpoint (POST /auth/forgot-password) and a time-limited reset token stored in Redis.

Redis-Backed Presence

The current in-memory onlineUsers Map works for single-instance deployments. For horizontal scaling, presence needs to move to Redis with the @socket.io/redis-adapter.

Full-Text Search Upgrade

The current $text search works but is limited. Moving to MongoDB Atlas Search or Elasticsearch would enable fuzzy matching, typo tolerance, and field-weighted ranking.

Quick Reference

Commands

kick dev              # Dev server with Vite HMR
kick build            # Production build
kick start            # Run production build
kick g module <name>  # Generate DDD module scaffold
kick g controller <n> # Generate controller
kick g dto <name>     # Generate Zod DTO

What Survives HMR

Controller logic, use cases, DTOs, guards, middleware, Mongoose schemas (with guard)

What Needs Full Restart

Adapter config changes, new modules in array, new adapters, queue processor class changes

Key File Paths

File	Purpose
`src/index.ts`	Entry point
`src/config/adapters.ts`	All adapter configurations
`src/config/env.ts`	Zod env validation
`src/modules/index.ts`	Module registry
`src/shared/constants/tokens.ts`	DI Symbol tokens
`src/shared/constants/query-configs.ts`	Pagination configs
`src/shared/utils/auth.ts`	`getUser(ctx)` helper
`src/shared/guards/`	Access control guards
`framework-filed-issues/`	Framework issue tracker

This is the final article in the "Building with KickJS" series. The full project source is available on GitHub. If you build something with KickJS, I'd genuinely like to hear about it.

Real-Time Typing Indicators and Presence Tracking with KickJS and Socket.IO

Orinda Felix Ochieng — Sun, 22 Mar 2026 16:26:13 +0000

TL;DR

KickJS WsAdapter wraps Socket.IO with decorator-driven WebSocket controllers
Room-based broadcasting (ctx.join(), ctx.to().send()) is the right abstraction for channel-based apps like Slack or Jira comments
Typing indicators use channel:typing / channel:stop_typing events with room-scoped broadcasting
In-memory presence tracking with a Map<socketId, userInfo> handles online/offline status
A cron job cleans up stale presence entries for resilience
Rooms beat individual socket tracking for multi-channel apps because they eliminate manual fan-out logic

The Setup: WebSocket Namespaces with KickJS

Vibed has a real-time chat system built into its task management backend. Users join workspace channels and exchange messages in real time. The WebSocket layer handles message delivery, typing indicators, and presence — while REST endpoints handle message history, editing, and deletion.

KickJS wraps Socket.IO behind a decorator-driven API via WsAdapter. The adapter is configured in config/adapters.ts:

import { WsAdapter } from '@forinda/kickjs-ws';

const wsAdapter = new WsAdapter({
  path: '/ws',
  heartbeatInterval: 30000,
  maxPayload: 1048576, // 1MB
});

export const adapters = [
  // ... other adapters
  wsAdapter,
  // ...
];

The path: '/ws' sets the Socket.IO handshake endpoint. Clients connect with:

const socket = io('http://localhost:3000', { path: '/ws' });

The heartbeatInterval: 30000 means Socket.IO pings every 30 seconds to detect dead connections. The maxPayload caps message size at 1MB to prevent abuse.

The WebSocket Controller

KickJS provides decorators for WebSocket event handling that mirror the HTTP controller pattern. Instead of @Get and @Post, you use @OnConnect, @OnDisconnect, and @OnMessage.

Here's the complete ChatWsController from Vibed:

import { WsController, OnConnect, OnDisconnect, OnMessage } from '@forinda/kickjs-ws';
import type { WsContext } from '@forinda/kickjs-ws';
import { Autowired, Logger } from '@forinda/kickjs-core';
import jwt from 'jsonwebtoken';
import { env } from '@/config/env';
import { MongoMessageRepository } from '../infrastructure/repositories/mongo-message.repository';

const logger = Logger.for('ChatWsController');

// In-memory online users map
const onlineUsers = new Map<string, { userId: string; userName: string }>();

@WsController('/chat')
export class ChatWsController {
  @Autowired() private messageRepo!: MongoMessageRepository;

  @OnConnect()
  handleConnect(ctx: WsContext) {
    try {
      const token = ctx.data?.token || '';
      const payload = jwt.verify(token, env.JWT_SECRET) as any;
      const userId = payload.sub;
      const email = payload.email;

      ctx.set('userId', userId);
      ctx.set('email', email);
      onlineUsers.set(ctx.id, { userId, userName: email });

      ctx.send('welcome', { id: ctx.id, userId });
      ctx.broadcastAll('presence:online', { userId, userName: email });
      logger.info(`User ${email} connected (${ctx.id})`);
    } catch {
      ctx.send('error', { message: 'Invalid authentication token' });
      logger.warn(`Connection rejected: invalid token (${ctx.id})`);
    }
  }

  @OnDisconnect()
  handleDisconnect(ctx: WsContext) {
    const info = onlineUsers.get(ctx.id);
    if (info) {
      ctx.broadcastAll('presence:offline', { userId: info.userId });
      onlineUsers.delete(ctx.id);
      logger.info(`User ${info.userName} disconnected (${ctx.id})`);
    }
  }

  // ... message and typing handlers below
}

The @WsController('/chat') decorator registers this controller under the /chat namespace. So the full connection URL is ws://localhost:3000/ws/chat. The namespace is important — it means Vibed could add other namespaces later (like /notifications for real-time notification push) without interference.

Authentication on Connect

WebSocket connections don't carry HTTP headers the same way REST calls do. I handle auth during the connection handshake by requiring the client to send a JWT token in the connection payload:

// Client-side
const socket = io('http://localhost:3000/chat', {
  path: '/ws',
  auth: { token: accessToken },
});

On the server, ctx.data?.token reads the auth payload. If jwt.verify() throws, the connection stays alive but the user gets an error event. In a stricter setup, you could disconnect them immediately — but for Vibed, I let the connection stay open so the client can retry with a fresh token.

The verified user info is stored in two places:

ctx.set('userId', userId) — for the current connection's context, so later event handlers can read it
onlineUsers.set(ctx.id, ...) — for the global presence map, so other connections can query who's online

Room-Based Broadcasting

This is the core concept that makes channel-based chat work efficiently. Instead of maintaining a list of socket IDs per channel and manually emitting to each one, Socket.IO (and KickJS's WsContext) provides rooms.

Joining and Leaving Rooms

When a user opens a channel in the UI, the client emits channel:join. When they navigate away, it emits channel:leave:

@OnMessage('channel:join')
handleJoin(ctx: WsContext) {
  const channelId = ctx.data?.channelId;
  if (!channelId) return;
  ctx.join(`channel:${channelId}`);
  ctx.to(`channel:${channelId}`).send('channel:user_joined', {
    channelId,
    userId: ctx.get('userId'),
  });
}

@OnMessage('channel:leave')
handleLeave(ctx: WsContext) {
  const channelId = ctx.data?.channelId;
  if (!channelId) return;
  ctx.leave(`channel:${channelId}`);
  ctx.to(`channel:${channelId}`).send('channel:user_left', {
    channelId,
    userId: ctx.get('userId'),
  });
}

The key methods:

ctx.join('channel:abc') — Adds this socket to the channel:abc room. The socket can be in multiple rooms simultaneously (a user can have multiple channels open in tabs).
ctx.leave('channel:abc') — Removes this socket from the room.
ctx.to('channel:abc').send(event, data) — Broadcasts to all sockets in the room except the sender.

The room name is prefixed with channel: as a namespace convention. This prevents collisions if I later add project: or workspace: rooms for different broadcast purposes.

Sending Messages

When a user sends a message, it's persisted to MongoDB via the message repository and then broadcast to the room:

@OnMessage('message:send')
async handleSend(ctx: WsContext) {
  const userId = ctx.get('userId');
  if (!userId) return ctx.send('error', { message: 'Not authenticated' });

  const { channelId, content } = ctx.data || {};
  if (!channelId || !content) return;

  const message = await this.messageRepo.create({
    channelId: channelId as any,
    senderId: userId as any,
    content,
    mentions: [],
  });

  const info = onlineUsers.get(ctx.id);
  const payload = {
    messageId: message._id.toString(),
    channelId,
    senderId: userId,
    senderName: info?.userName ?? 'Unknown',
    content: message.content,
    createdAt: message.createdAt,
  };

  ctx.to(`channel:${channelId}`).send('message:new', payload);
  ctx.send('message:new', payload); // Echo back to sender
}

Notice that ctx.to().send() excludes the sender, so I explicitly send the message back to the sender with ctx.send(). This is intentional — the sender needs the server-generated messageId and createdAt to update their local UI. In an optimistic-UI approach, you'd show the message immediately and then reconcile when the echo arrives.

Typing Indicators

Typing indicators are the "X is typing..." status you see in Slack, Discord, and every modern chat app. They need to be fast (low latency), cheap (no database writes), and scoped (only visible to users in the same channel).

The Events

Two events handle the full lifecycle:

@OnMessage('channel:typing')
handleTyping(ctx: WsContext) {
  const { channelId } = ctx.data || {};
  if (!channelId) return;
  const info = onlineUsers.get(ctx.id);
  ctx.to(`channel:${channelId}`).send('channel:typing', {
    channelId,
    userId: ctx.get('userId'),
    userName: info?.userName,
  });
}

@OnMessage('channel:stop_typing')
handleStopTyping(ctx: WsContext) {
  const { channelId } = ctx.data || {};
  if (!channelId) return;
  ctx.to(`channel:${channelId}`).send('channel:stop_typing', {
    channelId,
    userId: ctx.get('userId'),
  });
}

The server is a pure relay here. It doesn't track typing state — it just broadcasts the event to the room. This is by design: typing indicators are ephemeral, and storing them adds complexity with zero value.

Client-Side Implementation

The client needs debouncing to avoid flooding the server with typing events on every keystroke:

// Client-side typing indicator logic
let typingTimeout: ReturnType<typeof setTimeout> | null = null;
let isTyping = false;

function handleInput(channelId: string) {
  if (!isTyping) {
    socket.emit('channel:typing', { channelId });
    isTyping = true;
  }

  if (typingTimeout) clearTimeout(typingTimeout);

  typingTimeout = setTimeout(() => {
    socket.emit('channel:stop_typing', { channelId });
    isTyping = false;
  }, 2000); // Stop typing after 2 seconds of inactivity
}

// Listening for others typing
const typingUsers = new Map<string, string>();

socket.on('channel:typing', ({ userId, userName }) => {
  typingUsers.set(userId, userName);
  updateTypingUI();
});

socket.on('channel:stop_typing', ({ userId }) => {
  typingUsers.delete(userId);
  updateTypingUI();
});

function updateTypingUI() {
  const names = Array.from(typingUsers.values());
  if (names.length === 0) {
    typingLabel.textContent = '';
  } else if (names.length === 1) {
    typingLabel.textContent = `${names[0]} is typing...`;
  } else if (names.length === 2) {
    typingLabel.textContent = `${names[0]} and ${names[1]} are typing...`;
  } else {
    typingLabel.textContent = `${names[0]} and ${names.length - 1} others are typing...`;
  }
}

The debounce pattern: emit typing on first keystroke, then wait 2 seconds after the last keystroke to emit stop_typing. This gives a natural "typing..." experience without sending an event per character.

Why Rooms Make This Trivial

Without rooms, the typing handler would need to:

Look up which users are in the channel (database query or in-memory lookup)
Find their socket IDs (another lookup)
Emit to each socket individually (loop)
Handle the case where a user has multiple tabs open (deduplication)

With rooms, it's one line: ctx.to('channel:${channelId}').send(...). Socket.IO handles fan-out, multi-tab, and cleanup automatically. This is why rooms exist — they're the right primitive for group-scoped broadcasting.

In-Memory Presence Tracking

Presence tracking answers the question: "Who's online right now?" Vibed uses a module-level Map for this:

const onlineUsers = new Map<string, { userId: string; userName: string }>();

The key is the socket ID (ctx.id), and the value contains the user's identity. This map is updated on connect and disconnect:

// On connect
onlineUsers.set(ctx.id, { userId, userName: email });
ctx.broadcastAll('presence:online', { userId, userName: email });

// On disconnect
const info = onlineUsers.get(ctx.id);
if (info) {
  ctx.broadcastAll('presence:offline', { userId: info.userId });
  onlineUsers.delete(ctx.id);
}

The ctx.broadcastAll() sends to every connected socket, not just a room. Presence is a global concern — you want to show who's online in the workspace sidebar, not just in a specific channel.

Multi-Tab Handling

One user might have multiple tabs open, each with its own socket connection. The onlineUsers map has one entry per socket, not per user. This means a user with 3 tabs has 3 entries.

When broadcasting presence:offline, you need to check whether the user has other connections still alive:

@OnDisconnect()
handleDisconnect(ctx: WsContext) {
  const info = onlineUsers.get(ctx.id);
  if (info) {
    onlineUsers.delete(ctx.id);

    // Check if user has other active connections
    const stillOnline = Array.from(onlineUsers.values())
      .some(u => u.userId === info.userId);

    if (!stillOnline) {
      ctx.broadcastAll('presence:offline', { userId: info.userId });
    }

    logger.info(`User ${info.userName} disconnected (${ctx.id})`);
  }
}

Without this check, closing one tab would show the user as offline while they're still active in another tab.

Exporting the Presence Map

The onlineUsers map is exported so other parts of the application can query it. For example, the SSE stats endpoint uses it to show the number of online users:

// In chat.ws-controller.ts
export function getOnlineUsers() {
  return onlineUsers;
}

// In stats.controller.ts
import { getOnlineUsers } from '@/modules/messages/presentation/chat.ws-controller';

@Get('/workspaces/:workspaceId/stats/live')
@Middleware(workspaceMembershipGuard)
async workspaceLive(ctx: RequestContext) {
  const sse = ctx.sse();

  const sendStats = async () => {
    const onlineUsers = getOnlineUsers();
    sse.send({
      onlineUsersCount: onlineUsers.size,
      timestamp: new Date().toISOString(),
    }, 'stats:update');
  };

  await sendStats();
  const interval = setInterval(sendStats, 10000);
  sse.onClose(() => clearInterval(interval));
}

This bridges WebSocket presence data into the SSE-powered dashboard. The SSE endpoint pushes the online user count every 10 seconds without the dashboard needing a WebSocket connection itself.

Presence Cleanup Cron

In-memory presence tracking is fast but fragile. If the server crashes, all presence data is lost. If a client disconnects without a clean disconnect event (network failure, browser kill), the onlineUsers entry becomes stale.

KickJS's CronAdapter provides scheduled job support. I use it to clean up stale presence entries:

import { Service, Logger } from '@forinda/kickjs-core';
import { Cron } from '@forinda/kickjs-cron';

const logger = Logger.for('PresenceCronJobs');

@Service()
export class PresenceCronJobs {
  @Cron('*/5 * * * *', { description: 'Clean up stale presence entries' })
  async cleanupPresence() {
    logger.info('Running presence cleanup...');
    // Check Redis presence hash, remove entries with stale heartbeats
  }
}

The cron runs every 5 minutes. In a production implementation, you'd:

Store each user's last heartbeat timestamp in Redis
On each cron run, find entries where the heartbeat is older than the heartbeatInterval (30 seconds) plus some grace period
Remove those entries from both Redis and the in-memory map
Broadcast presence:offline for cleaned-up users

The cron adapter is registered in config/adapters.ts:

import { CronAdapter } from '@forinda/kickjs-cron';
import { PresenceCronJobs } from '@/modules/cron/infrastructure/jobs/presence-cleanup.cron';

new CronAdapter({
  services: [PresenceCronJobs, /* other cron services */],
  enabled: true,
});

Why Rooms Beat Individual Socket Tracking

For channel-based applications, rooms are categorically better than tracking individual sockets. Here's the comparison:

Without Rooms (Manual Tracking)

// You'd need to maintain this yourself
const channelMembers = new Map<string, Set<string>>(); // channelId -> socketIds

function joinChannel(channelId: string, socketId: string) {
  if (!channelMembers.has(channelId)) {
    channelMembers.set(channelId, new Set());
  }
  channelMembers.get(channelId)!.add(socketId);
}

function broadcastToChannel(channelId: string, event: string, data: any, excludeId?: string) {
  const members = channelMembers.get(channelId);
  if (!members) return;
  for (const socketId of members) {
    if (socketId === excludeId) continue;
    const socket = io.sockets.get(socketId);
    if (socket) {
      socket.emit(event, data);
    } else {
      // Socket disconnected without cleanup — stale entry
      members.delete(socketId);
    }
  }
}

function leaveChannel(channelId: string, socketId: string) {
  channelMembers.get(channelId)?.delete(socketId);
  if (channelMembers.get(channelId)?.size === 0) {
    channelMembers.delete(channelId);
  }
}

You're managing membership, fan-out, cleanup, and stale detection manually. Every edge case (disconnect without leave, server crash, multi-tab) needs explicit handling.

With Rooms (Socket.IO + KickJS)

// Join
ctx.join(`channel:${channelId}`);

// Broadcast to room (excludes sender automatically)
ctx.to(`channel:${channelId}`).send('channel:typing', { userId, userName });

// Leave
ctx.leave(`channel:${channelId}`);

// Automatic cleanup on disconnect — Socket.IO removes the socket from all rooms

Four lines replace 30+ lines of manual tracking. Socket.IO handles:

Membership management: join() and leave() maintain the room's socket set
Fan-out: to().send() iterates the room's members and emits to each
Disconnect cleanup: When a socket disconnects, Socket.IO automatically removes it from all rooms
Multi-tab: Each socket (each tab) joins independently; closing one tab doesn't affect other tabs in the same room

When Individual Tracking Makes Sense

Rooms aren't always the answer. For direct messages (1-to-1), you might track socket IDs per user because there's no "room" concept. For notifications, you might use the user ID as a room name (room:user_${userId}) and join every socket for that user.

But for channel-based communication — Slack channels, Discord servers, Jira project boards — rooms are the natural primitive. They match the domain model: a channel is a group, a room is a group.

The Complete Event Flow

Here's how all the pieces fit together for a typical interaction:

User A opens #general channel
  → Client emits: channel:join { channelId: 'general' }
  → Server: ctx.join('channel:general')
  → Server broadcasts to room: channel:user_joined { userId: 'A' }

User A starts typing
  → Client emits: channel:typing { channelId: 'general' }
  → Server: ctx.to('channel:general').send('channel:typing', { userId: 'A', userName: 'alice' })
  → User B's client receives: channel:typing → shows "alice is typing..."

User A sends a message
  → Client emits: message:send { channelId: 'general', content: 'Hello!' }
  → Server: persists message to MongoDB
  → Server: ctx.to('channel:general').send('message:new', { ... })
  → Server: ctx.send('message:new', { ... }) // echo to sender
  → User B receives: message:new → renders message in chat
  → User A receives: message:new echo → confirms delivery, gets messageId

User A stops typing (2s timeout on client)
  → Client emits: channel:stop_typing { channelId: 'general' }
  → Server: ctx.to('channel:general').send('channel:stop_typing', { userId: 'A' })
  → User B's client receives: channel:stop_typing → removes typing indicator

User A navigates away from #general
  → Client emits: channel:leave { channelId: 'general' }
  → Server: ctx.leave('channel:general')
  → Server broadcasts to room: channel:user_left { userId: 'A' }

The REST API handles everything that needs persistence or history:

GET /channels/:channelId/messages   → Paginated message history
PATCH /messages/:messageId          → Edit message (author only)
DELETE /messages/:messageId         → Soft-delete message (author only)

WebSocket handles everything that's ephemeral or real-time: message delivery, typing indicators, presence, and join/leave events.

Scaling Considerations

The in-memory onlineUsers Map works for a single server instance. For horizontal scaling, you'd need:

Redis-backed presence: Store presence in a Redis hash instead of (or in addition to) the in-memory map. All server instances read/write the same Redis store.
Socket.IO Redis adapter: @socket.io/redis-adapter makes rooms work across multiple server instances. A join() on server 1 is visible to to().send() on server 2.
Sticky sessions: Socket.IO long-polling fallback requires sticky sessions. WebSocket transport doesn't, but the initial handshake does.

KickJS's WsAdapter uses Socket.IO under the hood, so the Redis adapter integration is straightforward:

import { createAdapter } from '@socket.io/redis-adapter';
import { createClient } from 'redis';

const pubClient = createClient({ url: env.REDIS_URL });
const subClient = pubClient.duplicate();

const wsAdapter = new WsAdapter({
  path: '/ws',
  heartbeatInterval: 30000,
  adapter: createAdapter(pubClient, subClient), // Multi-instance rooms
});

Key Takeaways

Use rooms for group-scoped events — channels, projects, workspaces. Don't manually track socket sets.
Keep typing indicators stateless on the server — the server is a relay, not a state machine. Clients manage their own typing debounce timers.
Export presence data for cross-concern access — the SSE stats endpoint needs WebSocket presence data. Export the map, don't duplicate the tracking.
Clean up stale presence with cron — in-memory tracking is fast but fragile. A periodic cleanup prevents ghost users.
Separate persistence from real-time — messages are persisted via REST or during WebSocket message:send. Typing indicators and presence are never persisted. Use the right transport for the right data.
Auth on connect, not on every message — verify the JWT once during @OnConnect, store the user in context, and trust it for the connection's lifetime. Re-auth on reconnect.

This is part of a series on building a Jira-like backend with KickJS. Next up: the complete project guide covering everything from scaffold to production.

Filing KickJS Framework Issues as You Build — A Living Bug Tracker That Improves Your Tools

Orinda Felix Ochieng — Sun, 22 Mar 2026 16:24:04 +0000

TL;DR

We created framework-filed-issues/ inside our project to track every KickJS bug and quirk we hit while building Vibed
Each issue follows a consistent template: Status, Severity, Found in, Fixed in, Description, Steps to Reproduce, Workaround, Suggested Fix
Filing detailed issues with reproduction steps and suggested fixes led to actual framework releases (v1.2.3, v1.2.5, v1.2.6, v1.2.7)
The feedback loop — discover, workaround, file, fix, validate, update docs — is the most effective way to improve the tools you depend on
Tips for working with small/personal framework maintainers without burning them out

Why Track Framework Issues Inside Your Project?

When I started building Vibed — a Jira-like task management backend — with KickJS v1.2.2, I knew I was adopting a young framework. The docs were good enough to get started, but any non-trivial project was going to surface edge cases the framework author hadn't hit yet.

The question was: what do I do when I hit those edges?

Option one: complain on Twitter. Option two: switch frameworks. Option three: document every issue systematically, build workarounds, and file them upstream so they get fixed.

I went with option three, and it changed the trajectory of both my project and the framework itself.

The first thing I did was create a framework-filed-issues/ directory right in the project root. Not a separate repo. Not a Notion doc. Not a GitHub issue dump. A structured directory of markdown files, living alongside the code that surfaced the bugs.

vibed/
├── src/
├── framework-issues.md           # Quick reference of known issues
├── framework-filed-issues/
│   ├── README.md                 # Issue index with status table
│   ├── KICK-001.md
│   ├── KICK-002.md
│   ├── ...
│   └── KICK-018.md
└── articles/

Why inside the project? Because the issues are discovered in context. The reproduction steps reference real code. The workarounds are applied in real files. When an issue gets fixed upstream, I need to update both the workaround code and the issue file. Keeping them together means nothing falls through the cracks.

The Issue Template

Every issue file follows a consistent structure. I modeled it after the KickJS GitHub issue templates (bug_report.yml, feature_request.yml, documentation.yml) so that when I'm ready to file upstream, I can copy-paste with minimal reformatting.

Here's the template:

# KICK-NNN: Short descriptive title

- **Status**: Open | Confirmed | In Progress | Fixed | Released | Won't Fix
- **Severity**: Critical | High | Medium | Low
- **Found in**: v1.2.2
- **Fixed in**: —
- **Component**: http | core | queue | auth | mailer | cli

## Description
What's broken, in 2-3 sentences.

## Steps to Reproduce
1. Numbered steps
2. That anyone can follow
3. To trigger the bug

## Expected Behavior
What should happen.

## Actual Behavior
What actually happens, including error messages.

## Error / Stack Trace

Paste the actual error output here


## Environment
- Node.js version
- OS
- Package manager

## Workaround
What I'm doing right now to get past this.

## Suggested Fix
How I think the framework should fix it, with code if possible.

The Status field is the most important one. It tracks the issue through its lifecycle:

Status	Meaning
Open	Filed locally, not yet submitted upstream
Confirmed	Framework maintainer acknowledged
In Progress	Fix being worked on
Fixed	Fix merged, awaiting release
Released	Fix available in a published version
Won't Fix	Intentional behavior or out of scope

And the README.md file serves as an index table that gives me a bird's-eye view of all issues at a glance:

| ID | Title | Package | Severity | Status | Fixed In |
|---|---|---|---|---|---|
| KICK-001 | `kick new` interactive prompt not scriptable | cli | Low | Open | — |
| KICK-003 | Modules without routes crash Express | http | High | Released | v1.2.3 |
| KICK-009 | `ctx.set()`/`ctx.get()` not shared | http | Critical | Released | v1.2.5 |
| KICK-016 | `@Service()` + `@Job()` not auto-registered | queue, core | High | Released | v1.2.6 |

Real Example: KICK-009 — The Critical Context Bug

This is the issue that cost me the most hours and ultimately drove the most impactful framework fix.

I was building the auth middleware for Vibed. The pattern was simple: middleware validates the JWT, stores the user in context, handler reads the user from context. Every framework works this way.

// Middleware: validate JWT and store user
export const authBridgeMiddleware: MiddlewareHandler = (ctx, next) => {
  const token = ctx.headers.authorization?.split(' ')[1];
  const payload = jwt.verify(token, env.JWT_SECRET);
  ctx.set('user', { id: payload.sub, email: payload.email });
  next();
};

// Handler: read user from context
async create(ctx: RequestContext) {
  const user = ctx.get<AuthUser>('user'); // undefined!
  // TypeError: Cannot read properties of undefined (reading 'id')
}

ctx.get('user') returned undefined. Every single time. The middleware was running — I could verify that with console logs — but the handler couldn't see what the middleware had set.

After digging into the KickJS source, I found the root cause: router-builder.ts created a new RequestContext instance for each middleware and each handler. Every instance had its own private metadata Map. ctx.set() in middleware wrote to Map A. ctx.get() in the handler read from Map B. They were completely isolated.

Here's what I filed in KICK-009:

# KICK-009: `ctx.set()`/`ctx.get()` not shared between middleware and handler

- **Status**: Released
- **Severity**: Critical
- **Found in**: v1.2.2
- **Fixed in**: v1.2.5
- **Component**: http

## Description
In `router-builder.ts`, each middleware and handler receive separate
`new RequestContext(req, res, next)` instances. The `metadata` property
is a private `new Map()` per instance. `ctx.set('user', user)` in
middleware is invisible to `ctx.get('user')` in the handler.

## Suggested Fix
Attach the metadata Map to `req` on first creation, then reuse it:

function getOrCreateContext(req, res, next) {
  if (!req.__ctx) {
    req.__ctx = new RequestContext(req, res, next);
  }
  return req.__ctx;
}

The workaround I used in Vibed while waiting for the fix was to mutate req directly:

// Workaround: store on req, read with a helper
export const authBridgeMiddleware: MiddlewareHandler = (ctx, next) => {
  const user = (ctx.req as any).user; // Set by AuthAdapter
  if (user) {
    ctx.set('user', user);
  }
  next();
};

// Helper that abstracts the workaround
export function getUser(ctx: RequestContext): AuthUser {
  const user = ctx.get<AuthUser>('user');
  if (!user) throw HttpException.unauthorized('Authentication required');
  return user;
}

By wrapping the workaround in getUser(), every controller called one function. When v1.2.5 fixed the underlying issue, I updated the middleware and the helper — zero changes needed in 14 controllers.

Real Example: KICK-016 — DI Auto-Registration

This one hit when I was adding BullMQ job processors. The pattern should have been straightforward:

@Service()
@Job('email')
export class EmailProcessor {
  @Autowired(MAILER) private mailer!: MailerService;

  @Process('send-welcome-email')
  async sendWelcome(job: BullMQJob<{ email: string; firstName: string }>) {
    await this.mailer.send({
      to: job.data.email,
      subject: `Welcome to Vibed, ${job.data.firstName}!`,
      html: `<h1>Welcome!</h1>`,
    });
  }
}

But when the app started, I got:

Error: No binding found for: EmailProcessor
    at Container.resolve (container.ts:105:13)
    at QueueAdapter.beforeStart (queue.adapter.ts:75:35)

The @Service() decorator only set metadata. It did not call container.register(). So when QueueAdapter.beforeStart() tried to resolve the processor class, the container had no idea it existed.

My workaround was a ProcessorRegistrarAdapter that manually registered processor classes before the QueueAdapter:

export class ProcessorRegistrarAdapter implements AppAdapter {
  name = 'ProcessorRegistrarAdapter';

  beforeStart(_app: any, container: Container) {
    if (!container.has(EmailProcessor)) {
      container.register(EmailProcessor, EmailProcessor);
    }
  }
}

// In adapters array — MUST come before queueAdapter
export const adapters = [
  new ProcessorRegistrarAdapter(),
  queueAdapter,
  // ...
];

In my issue file, I suggested two fix options. The framework implemented Option B first in v1.2.6 — QueueAdapter.beforeStart() auto-registers @Job classes before resolving them. Then v1.2.7 implemented the more general fix: Container.bootstrap() now auto-registers all @Service()-decorated classes.

Real Example: KICK-017 — Feature Request

Not every issue is a bug. KICK-017 was a feature request born from the KICK-016 workaround. After filing the bug, I realized the real problem was deeper: @Service() should mean "this class is resolvable from the container" without any manual registration step.

# KICK-017: `@Service()` classes should be auto-registered in DI container

- **Status**: Released
- **Type**: Feature Request
- **Fixed in**: v1.2.6 (QueueAdapter), v1.2.7 (Container auto-registration)

## Problem
The `@Service()` decorator only sets metadata — it does not register
the class in the DI container. Any code that calls
`container.resolve(ServiceClass)` fails unless the consumer manually
calls `container.register()`.

The distinction between bug reports and feature requests matters. Bugs say "this is broken." Feature requests say "this could be better." Framework maintainers prioritize differently based on the category. A critical bug blocking adoption gets immediate attention. A feature request goes into the backlog. Filing them correctly respects the maintainer's time.

The Feedback Loop

Over the course of building Vibed, a clear pattern emerged:

Discover → Workaround → File → Fix → Validate → Update Docs

Discover: Hit a bug during development. The error message is usually cryptic. Spend time understanding the root cause by reading the framework source.

Workaround: Build a workaround that unblocks development. Keep the workaround isolated (in a helper function, in a custom adapter) so it's easy to remove later.

File: Write the issue in framework-filed-issues/ using the template. Include the root cause, reproduction steps, and a suggested fix. The suggested fix is the most valuable part — it tells the maintainer exactly what to change.

Fix: The framework author publishes a new version with the fix.

Validate: Update the project to the new version. Verify the fix actually solves the issue. Remove the workaround code.

Update Docs: Update the issue file status to "Released." Update framework-issues.md with the resolution. Update any articles or documentation that referenced the workaround.

Here's the timeline for Vibed's issues:

Version	Issues Fixed	What Changed
v1.2.3	KICK-003, KICK-004, KICK-010	Modules without routes, env typing, `@Public()` resolution
v1.2.5	KICK-009	Shared `RequestContext` metadata across middleware/handler
v1.2.6	KICK-013, KICK-016	Queue processor DI auto-registration, HMR DI rebinding
v1.2.7	KICK-017	`Container.bootstrap()` auto-registers all `@Service()` classes

Four releases. Seven issues fixed. All because structured bug reports with suggested fixes made the maintainer's job easier.

Tips for Working with Small Framework Maintainers

KickJS is maintained by a solo developer. Most of the Node.js ecosystem runs on projects maintained by one or two people. Here's what I've learned about filing issues productively:

1. Do Your Homework First

Before filing, read the framework source. Understand whether it's actually a bug or a misunderstanding. Half the issues I initially thought were bugs turned out to be undocumented behavior. I still filed them — as documentation issues — but knowing the difference saved back-and-forth.

2. Include the Suggested Fix

The single most impactful thing you can do is include a concrete, code-level suggestion for how to fix the issue. Not "you should fix this" but "here's the specific function in router-builder.ts that creates separate contexts, and here's what it should do instead." The maintainer can disagree with your approach, but you've saved them the debugging time.

3. Separate Bugs from Feature Requests

KICK-016 was a bug: "this doesn't work." KICK-017 was a feature request: "this should work differently." Filing them separately lets the maintainer triage appropriately.

4. Document Your Workaround

If your workaround is good, the maintainer might adopt it as the official fix. If your workaround is terrible, the maintainer knows the pain point and can design something better. Either way, showing that you found a way forward demonstrates that the issue is solvable.

5. Track Resolution Publicly

When an issue gets fixed, update your tracker, update your docs, and thank the maintainer. Open source runs on acknowledgment. A "this is fixed in v1.2.5, thank you" comment on a GitHub issue takes 10 seconds and provides outsized motivation.

6. Batch Related Issues

Don't file 10 issues in one day. Group related issues, reference each other, and space them out. KICK-016 (the bug) and KICK-017 (the feature request) were filed together because they had the same root cause. That context helped the maintainer see the bigger picture.

The README as a Living Dashboard

The framework-filed-issues/README.md file became the project's dashboard for framework health. At any point during development, I could glance at the index table and know:

Which issues were still blocking (severity + status)
Which workarounds were still in the codebase
Which framework versions I needed to upgrade to
Which issues were candidates for upstream filing

## Issue Index

### Bug Reports

| ID | Title | Severity | Status | Fixed In |
|---|---|---|---|---|
| KICK-003 | Modules without routes crash Express | High | Released | v1.2.3 |
| KICK-009 | ctx.set/get not shared | Critical | Released | v1.2.5 |
| KICK-016 | @Service + @Job not auto-registered | High | Released | v1.2.6 |
| KICK-011 | @Inject doesn't work as property decorator | Medium | Open | — |

### Feature Requests

| ID | Title | Status |
|---|---|---|
| KICK-015 | `kick readme` CLI command | Open |
| KICK-017 | @Service auto-registration in DI | Released |
| KICK-018 | Type-safe API client generation | Open |

The "Open" issues tell me what workarounds are still in my codebase. The "Released" issues tell me which versions I should upgrade to. The feature requests tell me what I'm hoping for in future releases.

Why Not Just Use GitHub Issues?

I do file on GitHub — eventually. But the local tracker serves a different purpose:

Speed: I can document an issue the moment I hit it without context-switching to GitHub
Context: The issue file lives next to the code that triggered it
Completeness: I can iterate on the description, reproduction steps, and suggested fix before filing publicly
Cross-referencing: I can reference issue files from code comments, from framework-issues.md, and from articles
Offline-friendly: I can work on issue documentation without an internet connection

The local file is the draft. The GitHub issue is the published version. The two stay in sync via the status field.

What This Approach Gave Us

After 18 issues tracked — 13 bug reports, 1 documentation issue, and 4 feature requests — here's what we got:

7 issues fixed across 4 framework releases
Zero abandoned workarounds — every workaround was either removed (when the fix shipped) or documented (when it's still needed)
Clean upgrade path — when v1.2.5 dropped, I knew exactly which workarounds to remove and which code to update
Better framework — KickJS is genuinely better for having been stress-tested by a real project
Better project — forcing myself to understand root causes made me a better debugger

The cost was maybe 30 minutes per issue for documentation. The return was hundreds of hours of debugging saved for everyone who uses KickJS after me.

If you're building with a young framework — or any framework, really — consider creating a framework-issues/ directory in your project. It's the most productive form of complaining I've ever found.

This is part of a series on building a Jira-like backend with KickJS. The full project source is available on GitHub.

KickJS Custom CLI Commands for Seeding, Resetting, and Testing — Zero Extra Dependencies

Orinda Felix Ochieng — Sun, 22 Mar 2026 15:55:19 +0000

Custom CLI Commands for Seeding, Resetting, and Testing — Zero Extra Dependencies

Every project accumulates scripts. First it is npm run seed. Then npm run db:reset. Then npm run seed:staging, npm run test:integration, npm run format:check, and before you know it, your package.json has 18 scripts and nobody remembers what half of them do.

For Vibed, our Jira-like task management backend built on KickJS, I moved all operational commands into the framework's kick.config.ts file. The result: kick seed, kick db:reset, kick check -- discoverable, documented, and composable. No extra CLI framework, no commander.js, no yargs. Just a config file and the kick binary you already have.

Here is how it works, what the seed and reset scripts look like, and why CLI-level commands beat npm scripts for developer experience.

kick.config.ts: The Command Registry

KickJS uses a kick.config.ts file at the project root for framework configuration. It tells the scaffolding generator where modules live, what patterns to follow, and -- the feature I care about here -- what custom commands to register.

// kick.config.ts
import { defineConfig } from '@forinda/kickjs-cli'

export default defineConfig({
  pattern: 'rest',
  modulesDir: 'src/modules',
  defaultRepo: 'inmemory',

  commands: [
    {
      name: 'seed',
      description: 'Populate database with sample data',
      steps: 'npx vite-node src/db/seed.ts',
    },
    {
      name: 'db:reset',
      description: 'Drop database and reseed',
      steps: ['npx vite-node src/db/reset.ts', 'npx vite-node src/db/seed.ts'],
    },
    {
      name: 'test',
      description: 'Run tests with Vitest',
      steps: 'npx vitest run',
    },
    {
      name: 'format',
      description: 'Format code with Prettier',
      steps: 'npx prettier --write src/',
    },
    {
      name: 'format:check',
      description: 'Check formatting without writing',
      steps: 'npx prettier --check src/',
    },
    {
      name: 'check',
      description: 'Run typecheck + format check',
      steps: ['npx tsc --noEmit', 'npx prettier --check src/'],
      aliases: ['verify', 'ci'],
    },
  ],
})

Each command has a name, a description (shown when you run kick --help), and steps which can be a single string or an array of strings. Arrays execute sequentially -- if any step fails, the chain stops. The optional aliases field lets you run the same command under different names.

After this config, your terminal gets:

kick seed          # Insert test data
kick db:reset      # Drop everything and reseed
kick test          # Run Vitest
kick format        # Format with Prettier
kick format:check  # Check formatting
kick check         # Typecheck + format check
kick verify        # Same as check (alias)
kick ci            # Same as check (alias)

All discoverable with kick --help.

The Seed Script: Realistic Test Data

The seed script is the most important operational script in any backend project. Bad seed data leads to bugs that only surface with real users. Good seed data exposes edge cases during development.

Here is the Vibed seed script in full:

// src/db/seed.ts
import 'reflect-metadata';
import mongoose from 'mongoose';
import bcrypt from 'bcryptjs';
import { UserModel }
  from '@/modules/users/infrastructure/schemas/user.schema';
import { WorkspaceModel }
  from '@/modules/workspaces/infrastructure/schemas/workspace.schema';
import { WorkspaceMemberModel }
  from '@/modules/workspaces/infrastructure/schemas/workspace-member.schema';
import { ProjectModel }
  from '@/modules/projects/infrastructure/schemas/project.schema';
import { LabelModel }
  from '@/modules/labels/infrastructure/schemas/label.schema';
import { TaskModel }
  from '@/modules/tasks/infrastructure/schemas/task.schema';
import { ChannelModel }
  from '@/modules/channels/infrastructure/schemas/channel.schema';

const MONGODB_URI = process.env.MONGODB_URI!;
if (!MONGODB_URI) {
  console.error('MONGODB_URI env variable is required');
  process.exit(1);
}

async function seed() {
  console.log('Connecting to MongoDB...');
  await mongoose.connect(MONGODB_URI);
  console.log('Connected. Seeding database...\n');

  // ── Users ──────────────────────────────────────────────
  const passwordHash = await bcrypt.hash('Password123!', 10);

  const users = await UserModel.insertMany([
    {
      email: 'admin@vibed.dev', passwordHash,
      firstName: 'Admin', lastName: 'User',
      globalRole: 'superadmin',
    },
    {
      email: 'alice@vibed.dev', passwordHash,
      firstName: 'Alice', lastName: 'Johnson',
      globalRole: 'user',
    },
    {
      email: 'bob@vibed.dev', passwordHash,
      firstName: 'Bob', lastName: 'Smith',
      globalRole: 'user',
    },
    {
      email: 'carol@vibed.dev', passwordHash,
      firstName: 'Carol', lastName: 'Williams',
      globalRole: 'user',
    },
  ]);
  console.log(`Created ${users.length} users`);

  const [admin, alice, bob, carol] = users;

  // ── Workspace ──────────────────────────────────────────
  const workspace = await WorkspaceModel.create({
    name: 'Vibed HQ',
    slug: 'vibed-hq',
    description: 'Main workspace for the Vibed team',
    ownerId: admin._id,
  });
  console.log(`Created workspace: ${workspace.name}`);

  // ── Workspace Members ──────────────────────────────────
  await WorkspaceMemberModel.insertMany([
    { workspaceId: workspace._id, userId: admin._id, role: 'admin' },
    { workspaceId: workspace._id, userId: alice._id, role: 'admin' },
    { workspaceId: workspace._id, userId: bob._id, role: 'member' },
    { workspaceId: workspace._id, userId: carol._id, role: 'member' },
  ]);
  console.log('Added 4 workspace members');

  // ── Labels ─────────────────────────────────────────────
  const labels = await LabelModel.insertMany([
    { workspaceId: workspace._id, name: 'bug', color: '#ef4444' },
    { workspaceId: workspace._id, name: 'feature', color: '#3b82f6' },
    { workspaceId: workspace._id, name: 'improvement', color: '#8b5cf6' },
    { workspaceId: workspace._id, name: 'docs', color: '#10b981' },
    { workspaceId: workspace._id, name: 'urgent', color: '#f97316' },
  ]);
  console.log(`Created ${labels.length} labels`);

  const [bugLabel, featureLabel, , docsLabel, urgentLabel] = labels;

  // ── Projects ───────────────────────────────────────────
  const backend = await ProjectModel.create({
    workspaceId: workspace._id,
    name: 'Backend API', key: 'API',
    description: 'KickJS backend for Vibed',
    leadId: alice._id, taskCounter: 6,
  });

  const frontend = await ProjectModel.create({
    workspaceId: workspace._id,
    name: 'Frontend App', key: 'FE',
    description: 'React frontend for Vibed',
    leadId: bob._id, taskCounter: 4,
  });
  console.log('Created 2 projects: Backend API, Frontend App');

  // ── Tasks ──────────────────────────────────────────────
  const backendTasks = await TaskModel.insertMany([
    {
      projectId: backend._id, workspaceId: workspace._id,
      key: 'API-1', title: 'Set up JWT authentication',
      status: 'done', priority: 'critical',
      assigneeIds: [alice._id], reporterId: admin._id,
      labelIds: [featureLabel._id], orderIndex: 0,
    },
    {
      projectId: backend._id, workspaceId: workspace._id,
      key: 'API-2', title: 'Add workspace CRUD and membership',
      status: 'done', priority: 'high',
      assigneeIds: [alice._id, bob._id], reporterId: admin._id,
      labelIds: [featureLabel._id], orderIndex: 1,
    },
    {
      projectId: backend._id, workspaceId: workspace._id,
      key: 'API-3', title: 'Implement task management',
      status: 'in-progress', priority: 'high',
      assigneeIds: [alice._id], reporterId: alice._id,
      labelIds: [featureLabel._id], orderIndex: 2,
    },
    // ... more tasks
  ]);

  const frontendTasks = await TaskModel.insertMany([
    {
      projectId: frontend._id, workspaceId: workspace._id,
      key: 'FE-1', title: 'Scaffold React app with Vite',
      status: 'done', priority: 'high',
      assigneeIds: [bob._id], reporterId: bob._id,
      labelIds: [featureLabel._id], orderIndex: 0,
    },
    {
      projectId: frontend._id, workspaceId: workspace._id,
      key: 'FE-2', title: 'Build kanban board component',
      status: 'in-progress', priority: 'high',
      assigneeIds: [bob._id, carol._id], reporterId: bob._id,
      labelIds: [featureLabel._id, urgentLabel._id], orderIndex: 1,
    },
    // ... more tasks
  ]);

  console.log(`Created ${backendTasks.length + frontendTasks.length} tasks`);

  // ── Channels ───────────────────────────────────────────
  await ChannelModel.insertMany([
    {
      workspaceId: workspace._id, name: 'general',
      description: 'General discussion', type: 'public',
      memberIds: [admin._id, alice._id, bob._id, carol._id],
      createdById: admin._id,
    },
    {
      workspaceId: workspace._id, projectId: backend._id,
      name: 'backend-dev', description: 'Backend development chat',
      type: 'public', memberIds: [alice._id, bob._id, carol._id],
      createdById: alice._id,
    },
    {
      workspaceId: workspace._id, projectId: frontend._id,
      name: 'frontend-dev', description: 'Frontend development chat',
      type: 'public', memberIds: [bob._id, carol._id],
      createdById: bob._id,
    },
  ]);
  console.log('Created 3 channels');

  // ── Summary ────────────────────────────────────────────
  console.log('\n--- Seed complete ---');
  console.log(`Users:      ${users.length}`);
  console.log(`Workspace:  1 (${workspace.name})`);
  console.log(`Projects:   2`);
  console.log(`Tasks:      ${backendTasks.length + frontendTasks.length}`);
  console.log(`Labels:     ${labels.length}`);
  console.log(`Channels:   3`);
  console.log('\nLogin credentials (all users): Password123!');
  console.log('Admin: admin@vibed.dev');
  console.log('Users: alice@vibed.dev, bob@vibed.dev, carol@vibed.dev');

  await mongoose.disconnect();
}

seed().catch((err) => {
  console.error('Seed failed:', err);
  process.exit(1);
});

A few design decisions worth explaining.

A shared password for all seed users

Every seed user gets Password123!. This is intentional for local development. When I (or a new team member) run kick seed and want to test the login flow, the password is right there in the console output. No need to look anything up.

Realistic relationships, not random data

The seed creates a proper hierarchy: users belong to a workspace, workspace has projects, projects have tasks with assignees, tasks have labels. This is not random UUIDs thrown into collections. It is a coherent dataset that exercises foreign key relationships, permission checks, and query filters.

For example, API-3 ("Implement task management") is assigned to Alice and has status in-progress. When I test the kanban board endpoint, I see a card in the right column. When I test the "my tasks" filter, Alice's tasks show up. When I test overdue reminders, FE-4 has a due date 3 days from now that will eventually trigger.

The order matters

Users are created first because workspaces need owner IDs. Workspaces before members. Labels before tasks (tasks reference label IDs). This sequential dependency is why insertMany is used per collection rather than some parallel bulk insert.

The Reset Script: Drop and Rebuild

Sometimes seed data gets corrupted during development. Maybe I manually deleted a user but left orphaned workspace members. Maybe a schema migration changed a field name. The reset script gives me a clean slate:

// src/db/reset.ts
import mongoose from 'mongoose';

const MONGODB_URI = process.env.MONGODB_URI!;
if (!MONGODB_URI) {
  console.error('MONGODB_URI env variable is required');
  process.exit(1);
}

async function reset() {
  console.log('Connecting to MongoDB...');
  await mongoose.connect(MONGODB_URI);

  const db = mongoose.connection.db!;
  const collections = await db.listCollections().toArray();

  for (const col of collections) {
    await db.dropCollection(col.name);
    console.log(`Dropped: ${col.name}`);
  }

  console.log(
    `\nReset complete — dropped ${collections.length} collections`
  );
  await mongoose.disconnect();
}

reset().catch((err) => {
  console.error('Reset failed:', err);
  process.exit(1);
});

It drops every collection in the database, then disconnects. It does not drop the database itself because that would require elevated permissions on some MongoDB hosting providers.

The kick db:reset command chains this with the seed:

{
  name: 'db:reset',
  description: 'Drop database and reseed',
  steps: ['npx vite-node src/db/reset.ts', 'npx vite-node src/db/seed.ts'],
},

Run kick db:reset and 10 seconds later you have a fresh database with all the test data. This is the command I run most often during development -- probably 5-10 times a day.

Using vite-node for Path Aliases

Notice that the seed script imports from @/modules/users/infrastructure/schemas/user.schema. That @/ prefix is a path alias configured in tsconfig.json that maps to src/. Standard node --loader ts-node does not resolve these aliases. Neither does tsx out of the box.

The solution is vite-node, which comes free with the KickJS dev setup (KickJS uses Vite under the hood for HMR). vite-node reads your vite.config.ts (or falls back to tsconfig.json paths) and resolves aliases the same way your dev server does.

npx vite-node src/db/seed.ts

This runs the TypeScript file directly, with full path alias support, ESM module resolution, and access to environment variables from .env. No compilation step, no intermediate JavaScript files. It just works.

If your project does not use Vite, tsx with tsconfig-paths achieves the same thing:

npx tsx --require tsconfig-paths/register src/db/seed.ts

But if you already have Vite in your stack, vite-node is the simpler choice.

The Check Command: Pre-Push Validation

The check command runs typecheck and format check in sequence:

{
  name: 'check',
  description: 'Run typecheck + format check',
  steps: ['npx tsc --noEmit', 'npx prettier --check src/'],
  aliases: ['verify', 'ci'],
},

I run this before every push. The aliases matter: kick ci is what our CI pipeline runs, and kick verify is what I tell new contributors to run before opening a PR. Same command, different mental models.

If tsc --noEmit finds type errors, the chain stops and prettier --check never runs. This is intentional -- there is no point checking formatting if the code does not compile.

Why CLI-Level Commands Beat npm Scripts

I have used npm scripts in every Node.js project for the last decade. They work. But kick commands are better for operational scripts, and here is why.

Discoverability

Run kick --help and you see every custom command with its description. Run npm run and you see a wall of script names with no context:

Lifecycle scripts included in vibed@1.2.7:
  test
    vitest run

available via `npm run-script`:
  dev
    kick dev
  build
    kick build
  ...

No descriptions. No grouping. No way to tell which scripts are for developers vs. CI vs. operations.

Composition

npm scripts compose awkwardly. You need && for sequencing, concurrently for parallelism, and cross-env for environment variables. kick commands support arrays for sequential steps natively:

steps: ['npx vite-node src/db/reset.ts', 'npx vite-node src/db/seed.ts'],

No shell operator gymnastics. If a step fails, it stops.

Coexistence with npm scripts

kick commands do not replace npm scripts. The standard lifecycle scripts (dev, build, start, test) still live in package.json because that is where CI tools, IDEs, and other developers expect them. But operational commands (seed, db:reset, check) work better in kick.config.ts.

In Vibed, the package.json scripts are thin wrappers:

{
  "scripts": {
    "dev": "kick dev",
    "build": "kick build",
    "start": "kick start",
    "test": "vitest run",
    "typecheck": "tsc --noEmit",
    "format": "prettier --write src/"
  }
}

Six scripts, all obvious. The operational commands live in kick.config.ts where they have descriptions and can compose steps.

No extra dependencies

I have seen projects pull in commander, yargs, inquirer, chalk, and ora just to build a CLI for seed scripts. That is five dependencies (and their transitive dependencies) for something that should be configuration.

KickJS's defineConfig reads the command list and registers them with the kick binary. No runtime overhead, no additional packages, no CLI framework to learn. If you already use kick dev and kick build, custom commands are free.

Practical Tips for Seed Scripts

After writing seed scripts for a dozen projects, here are the patterns that consistently work:

Print credentials at the end. Developers will forget the test passwords. Print them every time the seed runs.
Make seeds idempotent or make reset easy. Either use upsert so running seed twice does not fail on duplicate keys, or provide a reset command that clears everything first. I chose the reset approach because it is simpler and guarantees clean state.
Use real-looking data. "Test User 1" is useless for testing search, sorting, or display truncation. "Alice Johnson" tells you something when it shows up in a dropdown.
Create enough data to exercise pagination. If your API paginates at 20 items per page, seed at least 25 of something. Vibed seeds 10 tasks across 2 projects, which is enough for basic development but should grow as the API matures.
Seed all entity types. If your app has users, workspaces, projects, tasks, labels, and channels, the seed should create all of them with proper relationships. Skipping channels means you cannot test the messaging endpoints without manual setup.
Log counts, not data. Print Created 4 users not the full user objects. Keep the output scannable.

Putting It All Together

Here is my typical development workflow with these commands:

# First day on the project
kick seed

# Messed up the data
kick db:reset

# Before pushing
kick check

# Before opening a PR
kick test && kick check

# After pulling changes that modified schemas
kick db:reset

Five commands that cover the full development lifecycle. All discoverable with --help. All defined in a single config file. No dependency bloat, no shell script spaghetti, no undocumented tribal knowledge.

The key insight is that developer experience tooling does not need to be complex. A config file with a commands array, a script runner that supports path aliases, and sensible defaults cover 90% of what teams need. The remaining 10% -- interactive prompts, environment selection, dry-run modes -- can wait until you actually need them. Start simple, add complexity only when the pain demands it.

Vibed's entire operational CLI is 41 lines of configuration. That is the kind of leverage I want from my tools.

KickJS Cron-Driven Health Checks: Monitoring MongoDB, Redis, and Queues From Inside Your App

Orinda Felix Ochieng — Sun, 22 Mar 2026 15:28:01 +0000

Cron-Driven Health Checks: Monitoring MongoDB, Redis, and Queues From Inside Your App

External monitoring tools like Datadog, New Relic, and UptimeRobot are great. But they check your app from the outside -- is the HTTP endpoint responding? Internal health is a different question. Is MongoDB actually accepting writes? Is Redis reachable? Are your BullMQ workers processing jobs, or are they silently stalled?

For Vibed, our task management backend, I built cron-driven health checks that run inside the application process. They check every dependency, log structured results, and give me a single "Health OK" or "Health DEGRADED" line every minute in the logs. It took about 50 lines of code and caught a Redis connection leak two days later.

Here is how I built it with KickJS's CronAdapter and why internal monitoring complements -- not replaces -- external tools.

The CronAdapter Setup

KickJS provides a CronAdapter that discovers classes with @Cron decorators and schedules them using standard cron expressions. You register it in the adapter list:

// src/config/adapters.ts
import { CronAdapter } from '@forinda/kickjs-cron';
import { TaskCronJobs }
  from '@/modules/cron/infrastructure/jobs/overdue-reminders.cron';
import { DigestCronJobs }
  from '@/modules/cron/infrastructure/jobs/daily-digest.cron';
import { CleanupCronJobs }
  from '@/modules/cron/infrastructure/jobs/token-cleanup.cron';
import { PresenceCronJobs }
  from '@/modules/cron/infrastructure/jobs/presence-cleanup.cron';
import { HealthCheckCronJobs }
  from '@/modules/cron/infrastructure/jobs/health-check.cron';

export const adapters = [
  // ... other adapters (Mongoose, Redis, Auth, Queue, etc.)

  new CronAdapter({
    services: [
      TaskCronJobs,
      DigestCronJobs,
      CleanupCronJobs,
      PresenceCronJobs,
      HealthCheckCronJobs,
    ],
    enabled: true,
  }),
];

The services array lists every class that contains @Cron methods. The adapter instantiates them through the DI container (so @Autowired works) and starts the schedules when the app boots. The enabled flag is useful for disabling all cron jobs in test environments without removing the configuration.

Building the Health Check

The health check cron job is the simplest and most valuable class in the Vibed codebase. It checks three things every minute: MongoDB connectivity, Redis connectivity, and BullMQ queue availability.

// src/modules/cron/infrastructure/jobs/health-check.cron.ts
import { Service, Autowired, Logger } from '@forinda/kickjs-core';
import { Cron } from '@forinda/kickjs-cron';
import { QUEUE_MANAGER, type QueueService } from '@forinda/kickjs-queue';
import { TOKENS } from '@/shared/constants/tokens';
import mongoose from 'mongoose';
import type { Redis } from 'ioredis';

const logger = Logger.for('HealthCheckCron');

@Service()
export class HealthCheckCronJobs {
  @Autowired(TOKENS.REDIS) private redis!: Redis;
  @Autowired(QUEUE_MANAGER) private queueService!: QueueService;

  @Cron('* * * * *', { description: 'Run system health check every minute' })
  async healthCheck() {
    const results = {
      mongo: false,
      redis: false,
      queues: false,
    };

    try {
      results.mongo = mongoose.connection.readyState === 1;
    } catch { /* ignore */ }

    try {
      const pong = await this.redis.ping();
      results.redis = pong === 'PONG';
    } catch { /* ignore */ }

    try {
      const queueNames = this.queueService.getQueueNames();
      results.queues = queueNames.length > 0;
    } catch { /* ignore */ }

    const allHealthy = results.mongo && results.redis && results.queues;

    if (allHealthy) {
      logger.info('Health OK — mongo: ✓, redis: ✓, queues: ✓');
    } else {
      logger.warn(
        `Health DEGRADED — mongo: ${results.mongo ? '✓' : '✗'}, ` +
        `redis: ${results.redis ? '✓' : '✗'}, ` +
        `queues: ${results.queues ? '✓' : '✗'}`,
      );
    }
  }
}

Let me walk through the three checks.

MongoDB: `mongoose.connection.readyState`

Mongoose maintains a connection state enum: 0 (disconnected), 1 (connected), 2 (connecting), 3 (disconnecting). Checking === 1 tells me if the connection is fully established and healthy.

I do not need to inject Mongoose through DI here because mongoose is a singleton module -- importing it gives me the same connection that the MongooseAdapter established at startup. This is one of the few cases where a direct import is cleaner than DI.

Redis: `redis.ping()`

The Redis client is injected via @Autowired(TOKENS.REDIS). The TOKENS.REDIS symbol is defined in the shared constants:

// src/shared/constants/tokens.ts
export const TOKENS = {
  // Infrastructure
  MONGOOSE: Symbol('Mongoose'),
  REDIS: Symbol('Redis'),

  // Repositories
  USER_REPOSITORY: Symbol('UserRepository'),
  TASK_REPOSITORY: Symbol('TaskRepository'),
  // ... more tokens
} as const;

The Redis adapter registers the ioredis client under this symbol during setup. redis.ping() sends a PING command to the Redis server and expects "PONG" back. If it throws or returns something else, Redis is unhealthy.

BullMQ Queues: `queueService.getQueueNames()`

The QueueService is injected via @Autowired(QUEUE_MANAGER), where QUEUE_MANAGER is a Symbol exported from @forinda/kickjs-queue. Calling getQueueNames() returns the list of registered queue names (in our case, ['email', 'notifications', 'activity']). If this returns an empty array or throws, the queue infrastructure is not initialized.

This check does not tell me if workers are actively processing. For that, you would need to check queue.getWorkersCount() or monitor failed job counts. But knowing that the queue objects exist and are reachable covers the most common failure mode: Redis went down and queues cannot connect.

Why @Autowired Over Manual Resolution

You might wonder why I use @Autowired(TOKENS.REDIS) instead of resolving from the container manually. I tried both. Manual resolution looks like this:

// Not recommended — loses type safety and fails silently
const redis = Container.resolve<Redis>(TOKENS.REDIS);

The problem is that Container.resolve() is a static call that depends on the container being initialized. In cron jobs, the execution context is managed by the adapter, not by you. If you call Container.resolve() too early (before adapters finish setup) or if the container reference is wrong (after HMR in development), you get undefined with no error.

@Autowired() is better for three reasons:

Lazy resolution. The property is resolved when first accessed, not when the class is constructed. By the time the cron job fires, all adapters are fully initialized.
Type safety. The TypeScript type of the property matches what the container returns, and the framework validates the token at resolution time.
Testability. In tests, you can replace @Autowired properties with mocks by setting them directly on the instance. With static Container.resolve(), you need to mock the container itself.

Other Cron Jobs in Vibed

The health check is just one of five cron job classes in the Vibed codebase. Here are the others, each solving a different operational concern.

Overdue Task Reminders

Runs every day at 9 AM UTC. Queries for tasks past their due date and queues email reminders for each assignee:

// src/modules/cron/infrastructure/jobs/overdue-reminders.cron.ts
@Service()
export class TaskCronJobs {
  @Autowired(TOKENS.TASK_REPOSITORY) private taskRepo!: ITaskRepository;
  @Autowired(TOKENS.USER_REPOSITORY) private userRepo!: IUserRepository;
  @Autowired(QUEUE_MANAGER) private queueService!: QueueService;

  @Cron('0 9 * * *', {
    description: 'Send overdue task reminders',
    timezone: 'UTC',
  })
  async overdueReminders() {
    logger.info('Running overdue task reminders...');

    const overdueTasks = await this.taskRepo.findOverdue();
    for (const task of overdueTasks) {
      for (const assigneeId of task.assigneeIds) {
        const user = await this.userRepo.findById(assigneeId.toString());
        if (user) {
          await this.queueService.add('email', 'send-overdue-reminder', {
            email: user.email,
            taskKey: task.key,
            taskTitle: task.title,
            dueDate: task.dueDate?.toISOString(),
          });
        }
      }
    }
    logger.info(`Sent reminders for ${overdueTasks.length} overdue tasks`);
  }
}

This is a good example of cron jobs and queue jobs working together. The cron job identifies what work needs to happen. The queue job does the actual work (sending emails) with retry logic and concurrency control. Separation of scheduling from execution.

Token Cleanup

Runs at 3 AM UTC daily. Deletes expired refresh tokens from MongoDB:

// src/modules/cron/infrastructure/jobs/token-cleanup.cron.ts
@Service()
export class CleanupCronJobs {
  @Autowired(TOKENS.REFRESH_TOKEN_REPOSITORY)
  private tokenRepo!: IRefreshTokenRepository;

  @Cron('0 3 * * *', {
    description: 'Clean up expired refresh tokens',
    timezone: 'UTC',
  })
  async cleanupTokens() {
    logger.info('Running token cleanup...');
    const deleted = await this.tokenRepo.deleteExpired();
    logger.info(`Cleaned up ${deleted} expired refresh tokens`);
  }
}

Without this, the refresh tokens collection grows unbounded. Every login creates a token, and expired ones are never read again but still consume storage and slow down queries. A simple nightly cleanup keeps the collection lean.

Presence Cleanup

Runs every 5 minutes. Clears stale WebSocket presence entries from Redis:

// src/modules/cron/infrastructure/jobs/presence-cleanup.cron.ts
@Service()
export class PresenceCronJobs {
  @Cron('*/5 * * * *', { description: 'Clean up stale presence entries' })
  async cleanupPresence() {
    logger.info('Running presence cleanup... (placeholder)');
    // Check Redis presence hash, remove entries with stale heartbeats
  }
}

Daily Digest

Runs at 8 AM UTC on weekdays. Aggregates the previous day's activity per workspace and enqueues digest emails:

// src/modules/cron/infrastructure/jobs/daily-digest.cron.ts
@Service()
export class DigestCronJobs {
  @Cron('0 8 * * 1-5', {
    description: 'Send daily digest emails',
    timezone: 'UTC',
  })
  async dailyDigest() {
    logger.info('Running daily digest... (placeholder)');
    // Aggregate yesterday's activity per workspace, enqueue digest emails
  }
}

The cron expression 0 8 * * 1-5 means "at minute 0, hour 8, Monday through Friday." This is standard cron syntax, nothing KickJS-specific.

The Module That Has No Routes

One thing worth noting: the cron jobs are not part of a traditional module with HTTP routes. KickJS modules that return null from routes() work fine in the modules array. But there is a subtlety. The cron jobs are not registered through a module at all -- they are registered through the CronAdapter in the adapters configuration:

new CronAdapter({
  services: [
    TaskCronJobs,
    DigestCronJobs,
    CleanupCronJobs,
    PresenceCronJobs,
    HealthCheckCronJobs,
  ],
  enabled: true,
}),

The adapter handles DI resolution, schedule registration, and lifecycle management. The classes just need @Service() so the container knows how to construct them, and @Cron() so the adapter knows when to run them.

Logging: Health OK vs. Health DEGRADED

The choice to log at info level for healthy checks and warn level for degraded is deliberate. In production, I route warn and above to an alerting channel (Slack, PagerDuty, whatever). info goes to the regular log stream for debugging.

This means:

When everything is fine, the logs show a quiet heartbeat: Health OK every minute.
When something breaks, the log level changes and triggers an alert automatically.
Looking at historical logs, I can see exactly when a service went down and came back up.

The output looks like this in normal operation:

[2026-03-22T10:00:00Z] INFO  [HealthCheckCron] Health OK — mongo: ✓, redis: ✓, queues: ✓
[2026-03-22T10:01:00Z] INFO  [HealthCheckCron] Health OK — mongo: ✓, redis: ✓, queues: ✓

And when Redis drops:

[2026-03-22T10:02:00Z] WARN  [HealthCheckCron] Health DEGRADED — mongo: ✓, redis: ✗, queues: ✗
[2026-03-22T10:03:00Z] WARN  [HealthCheckCron] Health DEGRADED — mongo: ✓, redis: ✗, queues: ✗
[2026-03-22T10:04:00Z] INFO  [HealthCheckCron] Health OK — mongo: ✓, redis: ✓, queues: ✓

Notice that queues also go down when Redis drops. That is expected -- BullMQ uses Redis as its backing store. The health check captures this cascading failure automatically.

Why Internal Monitoring Matters

External monitoring tells you "the server returned a 503." Internal monitoring tells you why. Maybe MongoDB is fine but Redis is down. Maybe all services are up but the queue workers are stalled because of a bad deployment. Maybe the database is connected but writes are timing out because of a lock.

Internal health checks give you diagnostic information that external probes cannot. They run with the same permissions, connections, and configuration as your actual request handlers. If the health check can reach MongoDB, your API can too.

The combination I recommend:

External uptime monitoring (e.g., a /health HTTP endpoint checked by UptimeRobot) for "is the process alive?"
Internal cron-based checks (like what I described here) for "are all dependencies functional?"
Application-level metrics (request latency, error rates, queue depth) for "is performance acceptable?"

The cron-based health check covers layer 2 with minimal effort. No external infrastructure, no additional services, no monitoring SaaS bill. Just a class with three try/catch blocks that runs every minute.

Extending the Pattern

Once you have the basic structure, adding new checks is trivial. Want to verify that your S3 bucket is accessible? Add a headObject call. Need to check an external API dependency? Add a fetch with a timeout. Want to monitor queue depth?

try {
  const emailQueue = this.queueService.getQueue('email');
  const waiting = await emailQueue.getWaitingCount();
  results.queueDepth = waiting < 1000; // alert if backlog exceeds 1000
} catch { /* ignore */ }

The pattern scales because each check is independent and wrapped in its own try/catch. A failure in one check does not prevent the others from running. The results object gives you a clear snapshot of system health at any point in time.

Fifty lines of code. One minute of setup. It caught a Redis connection leak on day two of production. That is the kind of return on investment I like from infrastructure code.

BullMQ Job Processors with KickJS Decorator-Based DI — and Why Auto-Registration Matters

Orinda Felix Ochieng — Sun, 22 Mar 2026 14:19:41 +0000

BullMQ Job Processors with Decorator-Based DI — and Why Auto-Registration Matters

Every backend eventually outgrows synchronous request handling. For Vibed, our Jira-like task management app, that moment arrived when I tried to send a welcome email inside a registration endpoint and the response time jumped from 120ms to 2.4 seconds. The answer was obvious: background jobs. The implementation, however, taught me more about decorator metadata, DI containers, and framework internals than I expected.

This is the story of integrating BullMQ with KickJS's decorator-based dependency injection, the registration bug that haunted me for a week, and how the framework eventually fixed it upstream.

The Setup: QueueAdapter in KickJS

KickJS provides a QueueAdapter that wraps BullMQ with a decorator-driven API. You configure it in your adapter list alongside your database, auth, and other infrastructure:

// src/config/adapters.ts
import { QueueAdapter } from '@forinda/kickjs-queue';
import { env } from './env';

const redisUrl = new URL(env.REDIS_URL);

const queueAdapter = new QueueAdapter({
  redis: {
    host: redisUrl.hostname,
    port: Number(redisUrl.port) || 6379,
    password: redisUrl.password || undefined,
  },
  queues: ['email', 'notifications', 'activity'],
  concurrency: 5,
});

The queues array declares which named queues your app uses. Each name maps to a BullMQ Queue instance on the producer side and a Worker instance on the consumer side. The concurrency value sets how many jobs each worker processes in parallel.

The adapter also exposes a QueueService that you inject elsewhere to dispatch jobs:

import { QUEUE_MANAGER, type QueueService } from '@forinda/kickjs-queue';

That QUEUE_MANAGER is a Symbol token. More on why that matters later.

The @Job + @process Pattern

KickJS's queue package gives you two decorators: @Job('queueName') to bind a class to a named queue, and @Process('jobName') to mark individual methods as handlers for specific job types.

Here is the email processor from Vibed, which handles seven distinct job types on a single queue:

// src/modules/queue/infrastructure/processors/email.processor.ts
import { Service, Logger, Autowired } from '@forinda/kickjs-core';
import { Job, Process } from '@forinda/kickjs-queue';
import type { Job as BullMQJob } from 'bullmq';
import { MAILER, type MailerService } from '@forinda/kickjs-mailer';

const logger = Logger.for('EmailProcessor');

@Service()
@Job('email')
export class EmailProcessor {
  @Autowired(MAILER) private mailer!: MailerService;

  @Process('send-welcome-email')
  async sendWelcome(job: BullMQJob<{ email: string; firstName: string }>) {
    logger.info(`Sending welcome email to ${job.data.email}`);
    await this.mailer.send({
      to: job.data.email,
      subject: `Welcome to Vibed, ${job.data.firstName}!`,
      html: `<h1>Welcome to Vibed!</h1>
             <p>Hi ${job.data.firstName}, your account is ready.</p>`,
    });
  }

  @Process('send-task-assigned')
  async sendTaskAssigned(
    job: BullMQJob<{
      email: string;
      taskKey: string;
      taskTitle: string;
      assignerName: string;
    }>
  ) {
    logger.info(`Sending task assigned email to ${job.data.email}`);
    await this.mailer.send({
      to: job.data.email,
      subject: `You were assigned to ${job.data.taskKey}: ${job.data.taskTitle}`,
      html: `<p>${job.data.assignerName} assigned you to
             <strong>${job.data.taskKey}</strong>: ${job.data.taskTitle}</p>`,
    });
  }

  @Process('send-mentioned')
  async sendMentioned(
    job: BullMQJob<{ email: string; taskKey: string; mentionedBy: string }>
  ) {
    logger.info(`Sending mention email to ${job.data.email}`);
    await this.mailer.send({
      to: job.data.email,
      subject: `You were mentioned in ${job.data.taskKey}`,
      html: `<p>${job.data.mentionedBy} mentioned you in a comment on
             <strong>${job.data.taskKey}</strong></p>`,
    });
  }

  @Process('send-overdue-reminder')
  async sendOverdueReminder(
    job: BullMQJob<{
      email: string;
      taskKey: string;
      taskTitle: string;
      dueDate: string;
    }>
  ) {
    logger.info(`Sending overdue reminder to ${job.data.email}`);
    await this.mailer.send({
      to: job.data.email,
      subject: `Overdue: ${job.data.taskKey} - ${job.data.taskTitle}`,
      html: `<p>Task <strong>${job.data.taskKey}</strong>:
             ${job.data.taskTitle} was due on ${job.data.dueDate}</p>`,
    });
  }

  @Process('send-password-reset')
  async sendPasswordReset(
    job: BullMQJob<{ email: string; resetUrl: string }>
  ) {
    logger.info(`Sending password reset to ${job.data.email}`);
    await this.mailer.send({
      to: job.data.email,
      subject: 'Reset your password',
      html: `<p>Click <a href="${job.data.resetUrl}">here</a>
             to reset your password.</p>`,
    });
  }

  @Process('send-workspace-invite')
  async sendWorkspaceInvite(
    job: BullMQJob<{
      email: string;
      workspaceName: string;
      inviterName: string;
    }>
  ) {
    logger.info(`Sending workspace invite to ${job.data.email}`);
    await this.mailer.send({
      to: job.data.email,
      subject: `You've been invited to ${job.data.workspaceName}`,
      html: `<p>${job.data.inviterName} invited you to join
             <strong>${job.data.workspaceName}</strong> on Vibed.</p>`,
    });
  }

  @Process('send-daily-digest')
  async sendDailyDigest(
    job: BullMQJob<{ email: string; summary: string }>
  ) {
    logger.info(`Sending daily digest to ${job.data.email}`);
    await this.mailer.send({
      to: job.data.email,
      subject: 'Your Daily Vibed Digest',
      html: job.data.summary,
    });
  }
}

A few things to notice:

One class, one queue, many handlers. The @Job('email') decorator at the class level means every @Process method inside handles jobs from the email queue. The process name maps to the job name you pass when dispatching.
Full type safety on job data. Each @Process method receives a typed BullMQJob<T> generic, so job.data is fully typed. No guessing what fields are available.
DI via @Autowired(MAILER). The mailer service is injected using a Symbol token. This is the same MailerService configured by the MailerAdapter in the adapter list. In development, it resolves to a ConsoleProvider that logs emails to stdout. In production, it resolves to our Resend provider.

Dispatching Jobs from Use Cases

The other side of the equation is dispatching. In Vibed, use cases inject QueueService and call add():

// src/modules/auth/application/use-cases/register.use-case.ts
import { Service, Inject, HttpException, Logger } from '@forinda/kickjs-core';
import { QUEUE_MANAGER, type QueueService } from '@forinda/kickjs-queue';
import { TOKENS } from '@/shared/constants/tokens';
import type { IUserRepository } from '@/modules/users/domain/repositories/user.repository';
import type { RegisterDto } from '../dtos/register.dto';

@Service()
export class RegisterUseCase {
  constructor(
    @Inject(TOKENS.USER_REPOSITORY) private userRepo: IUserRepository,
    @Inject(QUEUE_MANAGER) private queueService: QueueService,
  ) {}

  async execute(dto: RegisterDto) {
    // ... create user, generate tokens ...

    // Queue welcome email (non-blocking)
    try {
      await this.queueService.add('email', 'send-welcome-email', {
        email: user.email,
        firstName: user.firstName,
      }, { delay: 5000 });
    } catch (err) {
      logger.warn('Failed to queue welcome email — continuing registration');
    }

    return { user, accessToken, refreshToken };
  }
}

The API is queueService.add(queueName, jobName, data, options?). The queue name matches what you declared in the QueueAdapter config and in the @Job decorator. The job name matches the @Process decorator on the handler method. BullMQ options like delay, attempts, and backoff pass through directly.

Notice the try/catch around queueService.add(). If Redis is momentarily unreachable, I do not want registration to fail. The welcome email is nice to have, not mission-critical. This is a pattern I use throughout: wrap queue dispatches in try/catch and log warnings on failure.

The DI Registration Problem

Here is where things got interesting. The decorators looked clean, the code compiled, and the server started without errors. But when a user registered, the welcome email never sent. No error in the processor. No error in the use case. The job just vanished into the queue and was never consumed.

After hours of debugging, I figured out what was happening. BullMQ workers were starting, but the EmailProcessor class was being instantiated with new EmailProcessor() by the queue adapter -- not resolved from the DI container. That meant @Autowired(MAILER) never ran. The mailer property was undefined. The job handler threw a silent Cannot read properties of undefined (reading 'send') that BullMQ caught and retried until max attempts.

The root cause: @Service() writes metadata to the class, but it does not register the class in the DI container. Registration happens when a module's register() method calls container.register(). But processors are not part of any module -- they are standalone classes discovered by the queue adapter through @Job decorator metadata.

The queue adapter found the classes (via a jobRegistry Map populated by @Job), but it instantiated them directly instead of resolving them from the container. So DI never kicked in.

The Journey to Auto-Registration

My first fix was manual. I created what I called a ProcessorRegistrarAdapter -- a custom adapter that ran before the queue adapter and pre-registered every processor class in the container:

// Early workaround (no longer needed)
export class ProcessorRegistrarAdapter implements Adapter {
  async setup(container: Container) {
    container.register(EmailProcessor, EmailProcessor);
    container.register(NotificationProcessor, NotificationProcessor);
    container.register(ActivityProcessor, ActivityProcessor);
  }
}

This worked but was terrible DX. Every time I added a processor, I had to remember to add a registration line. Forget it once and you get silent failures that are incredibly hard to debug.

My second attempt was an @AutoRegister decorator that hooked into the container at decoration time. This was clever but fragile -- the container might not exist yet when decorators run, depending on import order.

I filed an issue on the KickJS repo. The framework maintainer agreed this was a bug: if the adapter discovers classes via @Job metadata, it should also register them in the container before resolving. In v1.2.6, the QueueAdapter was updated to automatically call container.register() for every class in the jobRegistry before instantiating workers.

The fix meant our module became trivially simple:

// src/modules/queue/queue.module.ts
import type { AppModule, ModuleRoutes, Container } from '@forinda/kickjs-core';
// Side-effect imports ensure @Job() decorators populate the jobRegistry
import './infrastructure/processors/email.processor';
import './infrastructure/processors/notification.processor';
import './infrastructure/processors/activity.processor';

export class QueueModule implements AppModule {
  register(_container: Container): void {
    // No manual registration needed — QueueAdapter v1.2.6+ auto-registers
    // @Job classes in the container before resolving them.
  }

  routes(): ModuleRoutes | null {
    return null;
  }
}

The side-effect imports are still necessary. They ensure the @Job('email') decorator executes at load time and populates the internal job registry. Without them, the adapter would not know the processor exists. But the DI registration? That is fully automatic now.

Why This Matters Beyond KickJS

The pattern here -- decorator metadata vs. container registration -- is not unique to KickJS. If you use NestJS, Inversify, TSyringe, or any other TypeScript DI container, you will eventually run into a version of this problem.

Decorators write metadata. Containers resolve dependencies. These are two separate systems that need to stay in sync. When you add a new decorator-based pattern (like job processors, event handlers, or middleware), you need to ask: who is responsible for registering these classes in the container?

The options are:

Manual registration. Developer adds a line to a module or config file. Simple, but error-prone.
Auto-scanning. The framework scans the file system for decorated classes. Powerful, but slow and can cause surprising import side effects.
Adapter-level registration. The adapter that discovers classes via metadata also registers them. This is what KickJS v1.2.6 does, and I think it is the right default.

Adding More Processors

With auto-registration working, adding new processors is straightforward. Here is the notification processor, which writes to MongoDB instead of sending email:

// src/modules/queue/infrastructure/processors/notification.processor.ts
import { Service, Autowired, Logger } from '@forinda/kickjs-core';
import { Job, Process } from '@forinda/kickjs-queue';
import type { Job as BullMQJob } from 'bullmq';
import { MongoNotificationRepository }
  from '@/modules/notifications/infrastructure/repositories/mongo-notification.repository';

const logger = Logger.for('NotificationProcessor');

@Service()
@Job('notifications')
export class NotificationProcessor {
  @Autowired() private notificationRepo!: MongoNotificationRepository;

  @Process('create-notification')
  async createNotification(job: BullMQJob<{
    recipientId: string;
    type: string;
    title: string;
    body: string;
    metadata: Record<string, any>;
  }>) {
    logger.info(
      `Creating notification for ${job.data.recipientId}: ${job.data.type}`
    );
    await this.notificationRepo.create({
      recipientId: job.data.recipientId as any,
      type: job.data.type as any,
      title: job.data.title,
      body: job.data.body,
      metadata: job.data.metadata,
    });
  }
}

Notice that @Autowired() here has no token argument. That is because MongoNotificationRepository is a concrete class, not an interface behind a Symbol token. KickJS resolves it by class type. For framework-provided services like MAILER or QUEUE_MANAGER, you need the Symbol token because they are registered under those symbols by their respective adapters.

And the activity processor, which logs audit trail entries:

// src/modules/queue/infrastructure/processors/activity.processor.ts
@Service()
@Job('activity')
export class ActivityProcessor {
  @Autowired() private activityRepo!: MongoActivityRepository;

  @Process('log-activity')
  async logActivity(job: BullMQJob<{
    workspaceId: string;
    projectId?: string;
    taskId?: string;
    actorId: string;
    action: string;
    changes?: { field: string; from?: any; to?: any };
  }>) {
    logger.info(`Logging activity: ${job.data.action} by ${job.data.actorId}`);
    await this.activityRepo.create({
      workspaceId: job.data.workspaceId as any,
      projectId: job.data.projectId as any,
      taskId: job.data.taskId as any,
      actorId: job.data.actorId as any,
      action: job.data.action as any,
      changes: job.data.changes,
    });
  }
}

Three processors, three queues, nine job handlers total. All discoverable via decorators, all with proper DI, and zero manual registration boilerplate.

Lessons Learned

Silent failures are the worst kind. BullMQ swallowed the undefined errors because the default behavior is to retry failed jobs. Add explicit error logging in your processors, and set removeOnFail or attempts limits so bad jobs do not retry forever.
Side-effect imports are a code smell, but sometimes necessary. I would prefer auto-scanning, but explicit imports at least make the dependency graph visible.
Test your DI wiring, not just your business logic. My unit tests mocked the mailer, so they passed. Integration tests that resolved the processor from the actual container would have caught this immediately.
File framework issues. The auto-registration fix took the maintainer a few hours. My workarounds took me days. Open source works when you report problems.

The full Vibed codebase uses this pattern for all background work: emails, notifications, activity logging, and eventually file processing and report generation. Once the DI plumbing is right, adding new job types is a five-minute task. Getting the plumbing right, though -- that was the hard part.

Mongoose HMR Safety in KickJS: The One-Liner That Prevents OverwriteModelError

Orinda Felix Ochieng — Sun, 22 Mar 2026 14:18:48 +0000

Mongoose HMR Safety: The One-Liner That Prevents OverwriteModelError

If you have ever used Mongoose with Vite's dev server (or any HMR-capable bundler), you have seen this error:

OverwriteModelError: Cannot overwrite `User` model once compiled.

It crashes your dev server. It requires a full restart. It happens every time you save a file that is anywhere in the import chain of a schema file. And it is completely preventable with a single line of code.

I am going to explain why this happens, show the fix, and then cover the other HMR landmines I stepped on while building Vibed -- a task management backend running on KickJS (which uses Vite under the hood for development).

Why It Happens

Mongoose maintains a global registry of models. When you call mongoose.model('User', userSchema), it compiles the schema and stores the resulting model in mongoose.models.User. Call it again with the same name, and Mongoose throws OverwriteModelError.

In a traditional Node.js setup with ts-node or plain node, each file is evaluated exactly once. The model registers, and you are done.

Vite's HMR works differently. When you save a file, Vite re-evaluates the changed module and all modules that import it. If your controller imports a service that imports a repository that imports a schema, saving the controller causes the schema module to be re-evaluated. The mongoose.model() call runs again. The model is already registered. Boom.

Here is the timeline:

Server starts. mongoose.model('User', userSchema) runs. Model registered.
You edit users.controller.ts and save.
Vite's HMR re-evaluates the module graph. user.schema.ts gets re-evaluated.
mongoose.model('User', userSchema) runs again.
OverwriteModelError.

The error is Mongoose protecting you from accidentally registering two different schemas under the same name. But during HMR, it is the same schema -- just re-evaluated.

The Fix: Check Before Registering

The fix is a conditional that checks if the model already exists before registering it:

export const UserModel =
  (mongoose.models.User as mongoose.Model<UserDocument>) ||
  mongoose.model<UserDocument>('User', userSchema);

That is it. If mongoose.models.User exists (because this module was already evaluated), use the existing model. If it does not exist (first evaluation), register it. The as mongoose.Model<UserDocument> cast is necessary because mongoose.models is typed as { [name: string]: Model<any> } and we want the specific document type.

The Pattern in Practice

Here is a complete schema file from Vibed, the User model:

// src/modules/users/infrastructure/schemas/user.schema.ts
import mongoose, { Schema, type Document } from 'mongoose';
import type { UserEntity } from '../../domain/entities/user.entity';

export interface UserDocument extends Omit<UserEntity, '_id'>, Document {}

const userSchema = new Schema<UserDocument>(
  {
    email: { type: String, required: true, unique: true, index: true, lowercase: true, trim: true },
    passwordHash: { type: String, required: true },
    firstName: { type: String, required: true, trim: true },
    lastName: { type: String, required: true, trim: true },
    avatarUrl: { type: String },
    globalRole: { type: String, enum: ['superadmin', 'user'], default: 'user' },
    isActive: { type: Boolean, default: true },
    lastLoginAt: { type: Date },
  },
  { timestamps: true },
);

userSchema.index({ firstName: 'text', lastName: 'text', email: 'text' });

export const UserModel =
  (mongoose.models.User as mongoose.Model<UserDocument>) ||
  mongoose.model<UserDocument>('User', userSchema);

The critical line is the last export. Everything else is standard Mongoose. This pattern is identical across every schema file in the project. Here are a few more:

Task Model

const taskSchema = new Schema<TaskDocument>(
  {
    projectId: { type: Schema.Types.ObjectId, ref: 'Project', required: true, index: true },
    workspaceId: { type: Schema.Types.ObjectId, ref: 'Workspace', required: true, index: true },
    key: { type: String, required: true, unique: true, index: true },
    title: { type: String, required: true, trim: true },
    description: { type: String },
    status: { type: String, default: 'todo' },
    priority: { type: String, enum: ['critical', 'high', 'medium', 'low', 'none'], default: 'none' },
    assigneeIds: [{ type: Schema.Types.ObjectId, ref: 'User' }],
    reporterId: { type: Schema.Types.ObjectId, ref: 'User', required: true },
    labelIds: [{ type: Schema.Types.ObjectId, ref: 'Label' }],
    parentTaskId: { type: Schema.Types.ObjectId, ref: 'Task' },
    dueDate: { type: Date },
    estimatePoints: { type: Number },
    orderIndex: { type: Number, default: 0 },
    attachmentCount: { type: Number, default: 0 },
    commentCount: { type: Number, default: 0 },
  },
  { timestamps: true },
);

taskSchema.index({ projectId: 1, status: 1 });
taskSchema.index({ assigneeIds: 1 });
taskSchema.index({ dueDate: 1 });
taskSchema.index({ title: 'text', description: 'text' });

export const TaskModel =
  (mongoose.models.Task as mongoose.Model<TaskDocument>) ||
  mongoose.model<TaskDocument>('Task', taskSchema);

Workspace Member Model

const workspaceMemberSchema = new Schema<WorkspaceMemberDocument>(
  {
    workspaceId: { type: Schema.Types.ObjectId, ref: 'Workspace', required: true, index: true },
    userId: { type: Schema.Types.ObjectId, ref: 'User', required: true, index: true },
    role: { type: String, enum: ['admin', 'member'], default: 'member' },
    joinedAt: { type: Date, default: Date.now },
  },
  { timestamps: true },
);

workspaceMemberSchema.index({ workspaceId: 1, userId: 1 }, { unique: true });

export const WorkspaceMemberModel =
  (mongoose.models.WorkspaceMember as mongoose.Model<WorkspaceMemberDocument>) ||
  mongoose.model<WorkspaceMemberDocument>('WorkspaceMember', workspaceMemberSchema);

Notification Model

const notificationSchema = new Schema<NotificationDocument>(
  {
    recipientId: { type: Schema.Types.ObjectId, ref: 'User', required: true, index: true },
    type: {
      type: String,
      enum: ['task_assigned', 'mentioned', 'comment_added',
             'task_status_changed', 'due_date_reminder', 'workspace_invite'],
      required: true,
    },
    title: { type: String, required: true },
    body: { type: String, required: true },
    metadata: { type: Schema.Types.Mixed, default: {} },
    isRead: { type: Boolean, default: false },
  },
  { timestamps: true },
);

notificationSchema.index({ recipientId: 1, isRead: 1, createdAt: -1 });

export const NotificationModel =
  (mongoose.models.Notification as mongoose.Model<NotificationDocument>) ||
  mongoose.model<NotificationDocument>('Notification', notificationSchema);

Every single schema file follows the same pattern. No exceptions. I enforce this through code review -- if a PR introduces a new schema without the mongoose.models check, it gets sent back.

Why Not Use mongoose.modelNames()?

You might see alternative approaches online:

// Alternative #1: try/catch
let UserModel: mongoose.Model<UserDocument>;
try {
  UserModel = mongoose.model<UserDocument>('User');
} catch {
  UserModel = mongoose.model<UserDocument>('User', userSchema);
}

// Alternative #2: modelNames() check
export const UserModel = mongoose.modelNames().includes('User')
  ? mongoose.model<UserDocument>('User')
  : mongoose.model<UserDocument>('User', userSchema);

Both work, but the mongoose.models.X || mongoose.model() pattern is more concise. It is a single expression, easy to grep for in code review, and the intent is immediately clear. The try/catch approach obscures what is happening, and the modelNames() approach is unnecessarily verbose.

Other HMR Gotchas in a Backend Context

Mongoose models are the most common HMR issue, but they are not the only one. Here is what else I learned the hard way.

Adapter Configurations Need Full Restarts

KickJS adapter configurations (database connections, auth strategies, queue adapters, cron jobs) are evaluated once at startup and cached internally by the framework:

// src/config/adapters.ts
export const adapters = [
  new MongooseAdapter(env.MONGODB_URI),
  new RedisAdapter(env.REDIS_URL),
  new AuthAdapter({
    strategies: [
      new JwtStrategy({
        secret: env.JWT_SECRET,
        mapPayload: (payload: any) => ({
          id: payload.sub,
          email: payload.email,
          globalRole: payload.globalRole ?? 'user',
        }),
      }),
    ],
    defaultPolicy: 'protected',
  }),
  new QueueAdapter({
    redis: { host: redisUrl.hostname, port: Number(redisUrl.port) || 6379 },
    queues: ['email', 'notifications', 'activity'],
    concurrency: 5,
  }),
  new CronAdapter({
    services: [TaskCronJobs, DigestCronJobs, CleanupCronJobs, PresenceCronJobs, HealthCheckCronJobs],
    enabled: true,
  }),
  // ... more adapters
];

Changing anything here -- adding a new queue name, changing auth policy, updating Redis config -- requires a full server restart. Vite's HMR will re-evaluate the file, but the framework has already initialized with the original adapter instances. The new configuration is silently ignored.

I wasted a debugging session wondering why a new queue was not processing jobs. The queue was defined in the re-evaluated config, but QueueAdapter had already initialized with the original queue list. A full restart fixed it.

Queue Processor Classes Need Full Restarts

Queue processors are resolved from the DI container at initialization time. If you change the implementation of a @Job() processor class, HMR re-evaluates the class definition, but the queue worker is still running the old instance:

// This file is imported as a side-effect in the queue module
import './infrastructure/processors/email.processor';
import './infrastructure/processors/notification.processor';
import './infrastructure/processors/activity.processor';

Modifying email.processor.ts and saving will not update the running processor. You need a full restart. This is a known limitation of any system where long-lived worker instances are created at boot time.

DI Container Bindings Are Sticky

When a module registers a repository binding in its register() method, that binding persists across HMR reloads. If you change the binding (say, swapping MongoUserRepository for a PostgresUserRepository), the container still has the original binding. Full restart required.

However, the classes themselves (controllers, services, use cases) do get updated by HMR, because they are resolved fresh from the container on each request. This means:

HMR works for: Controller logic, use case business logic, DTO validation schemas, query helpers, utility functions
HMR does NOT work for: Adapter configs, DI bindings, queue processors, cron job schedules, model schemas (without the guard pattern)

New Modules Need Full Restarts

Adding a new module to the modules array requires re-evaluating the module registry, which the framework reads once at boot:

// src/modules/index.ts
export const modules = [
  new AuthModule(),
  new UsersModule(),
  new WorkspacesModule(),
  new ProjectsModule(),
  // Adding a new module here requires restart
];

HMR will re-evaluate this file, but the framework's router has already been built from the original module list. The new module's routes will not be registered until you restart.

Enforcing the Pattern

For the Mongoose guard specifically, I have a simple rule: every schema file in infrastructure/schemas/ must export its model using the mongoose.models.X || mongoose.model() pattern. Here is what I look for in code review:

// GOOD
export const FooModel =
  (mongoose.models.Foo as mongoose.Model<FooDocument>) ||
  mongoose.model<FooDocument>('Foo', fooSchema);

// BAD - will crash on HMR
export const FooModel = mongoose.model<FooDocument>('Foo', fooSchema);

The pattern is greppable. You can write a lint rule for it. You can check for it in CI. There is no reason for any schema file to not use it.

A Note on Next.js and Other Frameworks

This same pattern is widely used in Next.js projects with Mongoose, for the same reason. Next.js's dev server uses HMR and re-evaluates modules on changes. The Mongoose community has converged on this guard pattern regardless of framework. If you search for "Next.js Mongoose OverwriteModelError," you will find the same solution.

The difference with a backend framework like KickJS is that you have more categories of state that survive HMR (adapters, queues, cron, DI container). In a Next.js API route, you mostly just have Mongoose models. In a full backend, you have to know which things HMR updates and which things it does not.

Quick Reference: What Needs a Restart?

Change	HMR Picks Up?	Needs Restart?
Controller handler logic	Yes	No
Use case / service logic	Yes	No
DTO / Zod schema	Yes	No
Query helper functions	Yes	No
Mongoose schema fields	No*	Yes
Adapter configuration	No	Yes
New module added to array	No	Yes
Queue processor logic	No	Yes
Cron job schedule	No	Yes
DI container bindings	No	Yes

*Mongoose schema changes are tricky. The model guard prevents the crash, but the existing model instance keeps the old schema. If you add a new field to a schema, you need a restart for Mongoose to recognize it.

Takeaway

The OverwriteModelError fix is genuinely a one-liner. Write it once per schema file, and HMR works smoothly for the vast majority of your development workflow. The real lesson is broader: understand what your HMR system re-evaluates and what it does not. Mongoose models are the most visible symptom, but adapters, queues, cron jobs, and DI bindings all have the same underlying issue -- they are initialized once at boot time, and re-evaluating their source code does not re-initialize them.

For day-to-day development, the split is actually favorable. You spend most of your time writing controller logic, business rules in use cases, and validation schemas -- all of which HMR handles correctly. Schema changes, adapter config, and new modules are less frequent and worth the occasional restart.

The one-liner that matters:

export const YourModel =
  (mongoose.models.YourModel as mongoose.Model<YourDocument>) ||
  mongoose.model<YourDocument>('YourModel', yourSchema);

Put it in every schema file. Never think about OverwriteModelError again.

DEV Community: Orinda Felix Ochieng

KickJS: Decorator-Driven APIs on Express 5 — NestJS Ergonomics, Zero Overhead

TL;DR

Why Though

Show Me the Code

The CLI Is the Star

Built-in Middleware (No Extra Installs)

Vite 8 Powers Everything

836+ Real Tests

The 19 Packages

What's Coming

Get Started

forinda / kick-js

A declarative progressive backend framework

KickJS

Highlights

Install the CLI

Building a Jira Clone with KickJS and Prisma: Lessons from Supporting Prisma 5, 6, and 7

What We Built

The Adapter: Simple by Design

The Type Safety Problem

The PrismaModelDelegate Solution

The Upgrade Path

Prisma 7 Migration: What Changed

1. No more datasource.url in schema

2. Driver adapters required

3. $on removed for logging

4. Client generated to custom output

The Query Adapter: Type-Safe Search Columns

What We'd Do Differently

1. Start with the PrismaClient approach, not PrismaModelDelegate

2. Generate a db/prisma.ts barrel file

3. Type-safe DTOs from Prisma schema

4. Transaction support in the adapter

Try It

Summary of Shortcomings

Building a Jira-Like Task API with KickJS — Auth, WebSocket Chat, SSE, Queues & More

TL;DR

Why This Exists

The Stack

Getting Started

The DDD Module Pattern

Authentication — The Hard Way

Chapter 1: @public() Didn't Work

Chapter 2: The Bridge Middleware

Chapter 3: The ctx.set()/ctx.get() Fix

Real-Time Chat with WebSocket

Live Dashboard with SSE

Background Jobs That Actually Work

File Uploads → Base64 → MongoDB

10 Gotchas That'll Save You Hours

1. Mongoose HMR Guard

2. Double-Slash Routes

3. Global vs Route Middleware Signatures

4. ctx.set/get Shared Across Middleware/Handler (Fixed in v1.2.5)

5. @Inject for Constructors, @Autowired for Properties

6. QueueAdapter Wants String Names, Not Classes

7. Route-less Modules Crash Express

8. Auth defaultPolicy Blocks When resolveHandler Fails

9. ApiQueryParamsConfig Type Name

10. loadEnv() Type Erasure

The Numbers

What I'd Do Differently

What's Next

KickJS Module Generator: 4 Architecture Patterns for Every Backend Need

Pattern 1: minimal (2 files)

Pattern 2: rest (11 files)

Pattern 3: ddd (18 files)

Pattern 4: cqrs (17 files)

Auto-Wiring: The Generator Updates Your Module Registry

The import.meta.glob Pattern

Choosing a Pattern: The Decision Matrix

The --repo Flag

Wrapping Up

KickJS Query Engine Deep Dive: Filtering, Sorting, Search, and Pagination with MongoDB

KickJS Query Engine Deep Dive: Filtering, Sorting, Search, and Pagination with MongoDB

The Query Pipeline

Layer 1: Query Configs

Layer 2: The Controller

Injecting extra filters

1. No more `datasource.url` in schema

3. `$on` removed for logging

Auth (`/api/v1/auth`) — No auth required

Users (`/api/v1/users`)

Workspaces (`/api/v1/workspaces`)

Projects (`/api/v1`)

Tasks (`/api/v1`)

Comments (`/api/v1`)

Labels (`/api/v1`)

Attachments (`/api/v1`)

Channels (`/api/v1`)

Messages (`/api/v1`)

Notifications (`/api/v1/notifications`)

Activity (`/api/v1`)

Stats — SSE (`/api/v1`)

WebSocket (`/ws/chat`)