Nodejs Expert

nestjs core module guidelines

When reviewing or writing code, apply these guidelines:

• Global filters for exception handling.
• Global middlewares for request management.
• Guards for permission management.
• Interceptors for request management.

nestjs general guidelines

When reviewing or writing code, apply these guidelines:

• Use modular architecture
• Encapsulate the API in modules.
  • One module per main domain/route.
  • One controller for its route.
  • And other controllers for secondary routes.
  • A models folder with data types.
  • DTOs validated with class-validator for inputs.
  • Declare simple types for outputs.
  • A services module with business logic and persistence.
  • One service per entity.
• A core module for nest artifacts
  • Global filters for exception handling.
  • Global middlewares for request management.
  • Guards for permission management.
  • Interceptors for request management.
• A shared module for services shared between modules.
  • Utilities
  • Shared business logic
• Use the standard Jest framework for testing.
• Write tests for each controller and service.
• Write end to end tests for each api module.
• Add a admin/test method to each controller as a smoke test.

nestjs module structure guidelines

When reviewing or writing code, apply these guidelines:

• One module per main domain/route.
• One controller for its route.
• And other controllers for secondary routes.
• A models folder with data types.
• DTOs validated with class-validator for inputs.
• Declare simple types for outputs.
• A services module with business logic and persistence.
• One service per entity.

nestjs shared module guidelines

When reviewing or writing code, apply these guidelines:

• Utilities
• Shared business logic

nestjs testing guidelines

When reviewing or writing code, apply these guidelines:

• Use the standard Jest framework for testing.
• Write tests for each controller and service.
• Write end to end tests for eac

Consolidated Skills

This expert skill consolidates 1 individual skills:

• nodejs-expert

Related Skills

• typescript-expert - TypeScript type systems, patterns, and tooling for Node.js development

Iron Laws

1. ALWAYS validate DTOs at the API boundary using class-validator or zod — unvalidated inputs reach business logic, enabling injection attacks and data corruption; validation at the boundary is the last line of defense.
2. NEVER use callbacks in new Node.js code — callback hell makes error propagation non-deterministic; async/await with try/catch is the required standard for all async operations.
3. ALWAYS add a global exception filter in NestJS — without one, unhandled exceptions return raw stack traces, leaking internal implementation details to clients.
4. NEVER block the Node.js event loop with synchronous operations — CPU-bound work (file parsing, crypto, compression) blocks all concurrent requests; use worker threads, streams, or async alternatives.
5. ALWAYS implement connection pooling for database access — creating a new database connection per request exhausts the database's connection limit under load.

Anti-Patterns

Anti-Pattern	Why It Fails	Correct Approach
Missing DTO validation at API boundary	Unvalidated inputs enable injection and data corruption	Use class-validator on DTOs; reject invalid inputs at the controller boundary
Using callbacks in new code	Error propagation non-deterministic; unhandled rejections crash the process	Use async/await with try/catch for all async operations
No global exception filter in NestJS	Unhandled exceptions expose raw stack traces to clients	Add a global ExceptionFilter that logs internally and returns sanitized error responses
Synchronous operations on the event loop	Blocks all concurrent requests; latency spikes under any load	Use async alternatives (fsPromises, streams); offload CPU-bound work to worker threads
New database connection per request	Exhausts connection limit under load; adds connection overhead latency	Pool connections at startup with pg.Pool, Knex, or ORM connection pooling

Memory Protocol (MANDATORY)

Before starting:

cat .claude/context/memory/learnings.md

After completing: Record any new patterns or exceptions discovered.

ASSUME INTERRUPTION: Your context may reset. If it's not in memory, it didn't happen.