Node.js

Node.js

Overview

Production-grade Node.js runtime and server standard. Enforces async event loop non-blocking hygiene, graceful shutdown, structured JSON logging with correlation IDs, and unhandled rejection guards.

When to Use

Activate when developing Node.js HTTP servers, Express/Fastify APIs, background workers, CLI tools, or stream-based data pipelines.

Negative Constraints (What NOT to Do)

1. NEVER execute synchronous filesystem/crypto calls in request handlers (fs.readFileSync): Always use async promises (fs.promises.*) to avoid blocking the event loop.
2. NEVER leave uncaught promise rejections: Every async route must use express-async-errors or wrap operations in try/catch calling next(err).
3. NEVER buffer large files/payloads entirely in memory (fs.readFile): Always use Streams or Pipelines (stream.pipeline) for processing large files.
4. NEVER store in-memory session or user state on a single process instance: Use Redis or an external state store to allow multi-instance scaling.
5. NEVER ignore SIGTERM / SIGINT shutdown signals: Always implement graceful shutdown to close open DB pools and drain active HTTP connections.

Rules & Patterns

Architecture

• Layered architecture: Routes → Controllers → Services → Repositories
• Dependency injection - don't import dependencies directly in services
• Config from environment - never hardcode secrets, use env variables
• Graceful shutdown - handle SIGTERM, close connections, drain requests

Error Handling

• Never swallow errors - always handle or re-throw
• Custom error classes - extend Error with HTTP status codes
• Global error handler - catch unhandled rejections and uncaught exceptions
• Structured logging - JSON logs with request ID, timestamp, level

class AppError extends Error {
  constructor(
    public message: string,
    public statusCode: number = 500,
    public code: string = 'INTERNAL_ERROR'
  ) {
    super(message);
    this.name = 'AppError';
  }
}