kvokov/nestjs

NestJS

Follow the tier workflow below, then deepen with files under rules/ and the section map in rules/_sections.md.

Non-negotiables

1. rules/<prefix>-*.md for anything beyond this file (transactions, serialization, queues, graceful shutdown).
2. No invented Nest APIs, decorators, guards, or env keys — verify in the repo or current Nest docs.
3. Constructor injection and explicit Module wiring; DTOs + ValidationPipe on inputs unless the project documents otherwise.
4. Deliverables match the ask (checklist vs patch) and cite rules/<slug>.md.

Rules map (# = workflow priority; anchor = first file for tiers 1–4)

| # | Prefix | Focus | Anchor | | - | ------ | ----- | ------ | | 1 | arch- | Architecture | arch-avoid-circular-deps.md | | 2 | di- | Dependency injection | di-prefer-constructor-injection.md | | 3 | error- | Error handling | error-use-exception-filters.md | | 4 | security- | Security | security-validate-all-input.md, security-use-guards.md | | 5 | perf- | Performance | — | | 6 | test- | Testing | — | | 7 | db- | Database / ORM | — | | 8 | api- | API design | — | | 9 | micro- | Microservices | — | | 10 | devops- | DevOps / deploy | — |

Full list (40+ slugs) and new-rule skeleton: rules/_sections.md, rules/_template.md.

Refactoring and review workflow

Apply rules in this order; stop reranking within a tier unless a higher tier introduces new breakage. After each tier, run nest build and automated tests when the toolchain is available before moving downward.

1. CRITICAL — Architecture: resolve circular dependencies, validate feature-module boundaries, verify imports/exports/providers correctness.
2. CRITICAL — Dependency injection: enforce constructor injection, correct provider scopes, remove service-locator patterns.
3. HIGH — Error handling: consolidate exception translation; replace raw opaque errors where HTTP semantics matter.
4. HIGH — Security: global validation, authentication/authorization guards, rate limiting when exposed publicly.
5. HIGH — Performance: caching hotspots, ORM N+1 risks, lazy loading where documented in rules.
6. MEDIUM-HIGH and below: testing harnesses, migrations/transactions, API shape, microservice boundaries, deployment concerns.

Where to read next

rules/_sections.md (ordering), rules/<slug>.md (detail), rules/_template.md (blank rule).

Code snippets — common patterns

DTO with class-validator and global ValidationPipe

// create-order.dto.ts
import { IsString, IsInt, Min } from 'class-validator';

export class CreateOrderDto {
  @IsString()
  sku: string;

  @IsInt()
  @Min(1)
  qty: number;
}

// main.ts — register once globally
async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  app.useGlobalPipes(
    new ValidationPipe({ whitelist: true, forbidNonWhitelisted: true }),
  );
  await app.listen(3000);
}

Applying a JWT guard to a route

// orders.controller.ts
import { Controller, Post, Body, UseGuards } from '@nestjs/common';
import { JwtAuthGuard } from '../auth/jwt-auth.guard';
import { CreateOrderDto } from './dto/create-order.dto';
import { OrdersService } from './orders.service';

@Controller('orders')
export class OrdersController {
  constructor(private readonly ordersService: OrdersService) {}

  @Post()
  @UseGuards(JwtAuthGuard)
  create(@Body() dto: CreateOrderDto) {
    return this.ordersService.create(dto);
  }
}

Integrated example

Prompt: POST /orders body { sku, qty }, login required.

• Modules — avoid cycles (arch-feature-modules, arch-module-sharing).
• Input — CreateOrderDto + app ValidationPipe (security-validate-all-input).
• Auth / errors — JWT (security-use-guards, security-auth-jwt); HTTP errors + filters (error-throw-http-exceptions, error-use-exception-filters).
• Output — code diff vs checklist per ask; cite slugs.

Anti-patterns (reject in reviews)

• Using forwardRef as the primary fix without first extracting shared boundaries or domain events (arch-avoid-circular-deps).
• @Body() typed as any or primitives without pipes where the codebase uses DTO validation elsewhere.
• Scattered try/catch returning ad-hoc JSON instead of centralized exception mapping.
• Property injection solely to avoid constructor parameters.
• Recommending Prisma/Bull/microservice patterns without opening the relevant rules/db-*, rules/micro-* files when specifics matter.