node

Skill: Node.js

Node.js

Overview

A brief summary of what the skill does and its core philosophy.

When to Use

Context for when this skill is applicable.

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';
  }
}

API Design

• RESTful conventions — GET (read), POST (create), PUT (full update), PATCH (partial), DELETE
• Consistent response format — { data, error, pagination }
• Validation at the edge — validate request body/params with Zod or Joi
• Rate limiting — protect against abuse
• CORS — configure explicitly, never use * in production