kumaran-is Iron Law: Always load the nestjs-api skill before writing NestJS code; never generate Prisma or Fastify patterns without consulting current documentation.
NestJS + TypeScript Coding Standards
Standards for readable, maintainable TypeScript code in NestJS 11.x + Fastify services.
Core Principles
- Prefer clarity over cleverness
- Immutable by default; minimize shared mutable state
- Fail fast with meaningful exceptions
- Consistent naming and module structure
Key Rules
| Rule | Standard |
|---|---|
| Naming | Classes: PascalCase, files: kebab-case, constants: UPPER_SNAKE_CASE |
| TypeScript Strictness | strict: true always; no any, use unknown with type guards |
| Immutability | readonly on injected dependencies; spread for updates, never mutate |
| Error Handling | Custom exceptions extend BaseException; log + rethrow, never swallow |
| DTOs | class-validator on every field; separate Create/Update/Response DTOs |
| Modules | Feature-first modules; explicit imports/exports, no implicit dependencies |
| Logging | Logger per class with structured key-value pairs; never log PII |
| Testing | AAA pattern (Arrange-Act-Assert); one assertion focus per test |
| Null Handling | Use null over undefined for explicit absence; validate with DTOs |
| Generics | Explicit return types on public methods; use type inference for locals |
| Environment | All required env vars in .env with working defaults; no ?? fallbacks in config code; .env written via Bash (hooks block Write/Edit) |
| Prisma 7.x | provider = "prisma-client" with output path; no url in schema; use prisma.config.ts; PrismaService via composition (not inheritance) with @prisma/adapter-pg |
Project Structure
src/
main.ts → app.module.ts
config/ → common/ → core/ → features/
features/<entity>/
<entity>.module.ts
<entity>.controller.ts
<entity>.service.ts
dto/
repository/
Code Examples & Detailed Patterns
For naming examples, TypeScript strictness, immutability patterns, DTO validation, module organization, error handling, service patterns, controller patterns, logging, formatting, code smells, and testing expectations, Read reference/nestjs-standards-examples.md.
Remember: Keep code intentional, typed, and observable. Optimize for maintainability over micro-optimizations unless proven necessary.
TypeScript Immutability Rules
CRITICAL — Never mutate objects or arrays directly in NestJS services/controllers.
// ✅ ALWAYS: Spread operator for object updates
const updatedUser = { ...user, name: 'New Name', updatedAt: new Date() }
const updatedItems = [...items, newItem]
// ❌ NEVER: Direct mutation
user.name = 'New Name' // BAD — breaks immutability, causes subtle bugs
items.push(newItem) // BAD — mutates in place, unpredictable in reactive chains
Why: Prisma entities and DTOs passed between layers can be shared references. Mutating them corrupts upstream state silently.
No Magic Numbers
// ✅ GOOD: Named constants
const MAX_RETRY_ATTEMPTS = 3
const DEBOUNCE_DELAY_MS = 500
const DEFAULT_PAGE_SIZE = 20
// ❌ BAD: Magic literals
if (retryCount > 3) { }
setTimeout(fn, 500)
.limit(20)
Early Returns Over Deep Nesting
// ✅ GOOD: Guard clauses, max 2 levels nesting
if (!user) throw new NotFoundException('User not found')
if (!user.isActive) throw new ForbiddenException('Account suspended')
return this.userRepo.findOrders(user.id)
// ❌ BAD: 4+ levels of nesting
if (user) {
if (user.isActive) {
if (order) {
if (order.isPaid) { ... }
}
}
}
Parallel Async (use Promise.all)
// ✅ GOOD: Parallel when operations are independent
const [user, orders, stats] = await Promise.all([
this.userService.findById(userId),
this.orderService.findByUser(userId),
this.statsService.forUser(userId),
])
// ❌ BAD: Sequential when not needed
const user = await this.userService.findById(userId)
const orders = await this.orderService.findByUser(userId)
const stats = await this.statsService.forUser(userId)
Error Handling
Exception hierarchy: Use HttpException subclasses (NotFoundException, BadRequestException). Global exception filter returns RFC 9457 ProblemDetail.
Validation failures: Use class-validator decorators on DTOs. Global ValidationPipe auto-returns 422 with field-level details.