@arcadialdev/arcality 2.2.0

package/.agents/skills/nodejs-backend-patterns/SKILL.md

@@ -0,0 +1,639 @@
+---
+name: nodejs-backend-patterns
+description: Build production-ready Node.js backend services with Express/Fastify, implementing middleware patterns, error handling, authentication, database integration, and API design best practices. Use when creating Node.js servers, REST APIs, GraphQL backends, or microservices architectures.
+---
+
+# Node.js Backend Patterns
+
+Comprehensive guidance for building scalable, maintainable, and production-ready Node.js backend applications with modern frameworks, architectural patterns, and best practices.
+
+## When to Use This Skill
+
+- Building REST APIs or GraphQL servers
+- Creating microservices with Node.js
+- Implementing authentication and authorization
+- Designing scalable backend architectures
+- Setting up middleware and error handling
+- Integrating databases (SQL and NoSQL)
+- Building real-time applications with WebSockets
+- Implementing background job processing
+
+## Core Frameworks
+
+### Express.js - Minimalist Framework
+
+**Basic Setup:**
+
+```typescript
+import express, { Request, Response, NextFunction } from "express";
+import helmet from "helmet";
+import cors from "cors";
+import compression from "compression";
+
+const app = express();
+
+// Security middleware
+app.use(helmet());
+app.use(cors({ origin: process.env.ALLOWED_ORIGINS?.split(",") }));
+app.use(compression());
+
+// Body parsing
+app.use(express.json({ limit: "10mb" }));
+app.use(express.urlencoded({ extended: true, limit: "10mb" }));
+
+// Request logging
+app.use((req: Request, res: Response, next: NextFunction) => {
+  console.log(`${req.method} ${req.path}`);
+  next();
+});
+
+const PORT = process.env.PORT || 3000;
+app.listen(PORT, () => {
+  console.log(`Server running on port ${PORT}`);
+});
+```
+
+### Fastify - High Performance Framework
+
+**Basic Setup:**
+
+```typescript
+import Fastify from "fastify";
+import helmet from "@fastify/helmet";
+import cors from "@fastify/cors";
+import compress from "@fastify/compress";
+
+const fastify = Fastify({
+  logger: {
+    level: process.env.LOG_LEVEL || "info",
+    transport: {
+      target: "pino-pretty",
+      options: { colorize: true },
+    },
+  },
+});
+
+// Plugins
+await fastify.register(helmet);
+await fastify.register(cors, { origin: true });
+await fastify.register(compress);
+
+// Type-safe routes with schema validation
+fastify.post<{
+  Body: { name: string; email: string };
+  Reply: { id: string; name: string };
+}>(
+  "/users",
+  {
+    schema: {
+      body: {
+        type: "object",
+        required: ["name", "email"],
+        properties: {
+          name: { type: "string", minLength: 1 },
+          email: { type: "string", format: "email" },
+        },
+      },
+    },
+  },
+  async (request, reply) => {
+    const { name, email } = request.body;
+    return { id: "123", name };
+  },
+);
+
+await fastify.listen({ port: 3000, host: "0.0.0.0" });
+```
+
+## Architectural Patterns
+
+### Pattern 1: Layered Architecture
+
+**Structure:**
+
+```
+src/
+├── controllers/     # Handle HTTP requests/responses
+├── services/        # Business logic
+├── repositories/    # Data access layer
+├── models/          # Data models
+├── middleware/      # Express/Fastify middleware
+├── routes/          # Route definitions
+├── utils/           # Helper functions
+├── config/          # Configuration
+└── types/           # TypeScript types
+```
+
+**Controller Layer:**
+
+```typescript
+// controllers/user.controller.ts
+import { Request, Response, NextFunction } from "express";
+import { UserService } from "../services/user.service";
+import { CreateUserDTO, UpdateUserDTO } from "../types/user.types";
+
+export class UserController {
+  constructor(private userService: UserService) {}
+
+  async createUser(req: Request, res: Response, next: NextFunction) {
+    try {
+      const userData: CreateUserDTO = req.body;
+      const user = await this.userService.createUser(userData);
+      res.status(201).json(user);
+    } catch (error) {
+      next(error);
+    }
+  }
+
+  async getUser(req: Request, res: Response, next: NextFunction) {
+    try {
+      const { id } = req.params;
+      const user = await this.userService.getUserById(id);
+      res.json(user);
+    } catch (error) {
+      next(error);
+    }
+  }
+
+  async updateUser(req: Request, res: Response, next: NextFunction) {
+    try {
+      const { id } = req.params;
+      const updates: UpdateUserDTO = req.body;
+      const user = await this.userService.updateUser(id, updates);
+      res.json(user);
+    } catch (error) {
+      next(error);
+    }
+  }
+
+  async deleteUser(req: Request, res: Response, next: NextFunction) {
+    try {
+      const { id } = req.params;
+      await this.userService.deleteUser(id);
+      res.status(204).send();
+    } catch (error) {
+      next(error);
+    }
+  }
+}
+```
+
+**Service Layer:**
+
+```typescript
+// services/user.service.ts
+import { UserRepository } from "../repositories/user.repository";
+import { CreateUserDTO, UpdateUserDTO, User } from "../types/user.types";
+import { NotFoundError, ValidationError } from "../utils/errors";
+import bcrypt from "bcrypt";
+
+export class UserService {
+  constructor(private userRepository: UserRepository) {}
+
+  async createUser(userData: CreateUserDTO): Promise<User> {
+    // Validation
+    const existingUser = await this.userRepository.findByEmail(userData.email);
+    if (existingUser) {
+      throw new ValidationError("Email already exists");
+    }
+
+    // Hash password
+    const hashedPassword = await bcrypt.hash(userData.password, 10);
+
+    // Create user
+    const user = await this.userRepository.create({
+      ...userData,
+      password: hashedPassword,
+    });
+
+    // Remove password from response
+    const { password, ...userWithoutPassword } = user;
+    return userWithoutPassword as User;
+  }
+
+  async getUserById(id: string): Promise<User> {
+    const user = await this.userRepository.findById(id);
+    if (!user) {
+      throw new NotFoundError("User not found");
+    }
+    const { password, ...userWithoutPassword } = user;
+    return userWithoutPassword as User;
+  }
+
+  async updateUser(id: string, updates: UpdateUserDTO): Promise<User> {
+    const user = await this.userRepository.update(id, updates);
+    if (!user) {
+      throw new NotFoundError("User not found");
+    }
+    const { password, ...userWithoutPassword } = user;
+    return userWithoutPassword as User;
+  }
+
+  async deleteUser(id: string): Promise<void> {
+    const deleted = await this.userRepository.delete(id);
+    if (!deleted) {
+      throw new NotFoundError("User not found");
+    }
+  }
+}
+```
+
+**Repository Layer:**
+
+```typescript
+// repositories/user.repository.ts
+import { Pool } from "pg";
+import { CreateUserDTO, UpdateUserDTO, UserEntity } from "../types/user.types";
+
+export class UserRepository {
+  constructor(private db: Pool) {}
+
+  async create(
+    userData: CreateUserDTO & { password: string },
+  ): Promise<UserEntity> {
+    const query = `
+      INSERT INTO users (name, email, password)
+      VALUES ($1, $2, $3)
+      RETURNING id, name, email, password, created_at, updated_at
+    `;
+    const { rows } = await this.db.query(query, [
+      userData.name,
+      userData.email,
+      userData.password,
+    ]);
+    return rows[0];
+  }
+
+  async findById(id: string): Promise<UserEntity | null> {
+    const query = "SELECT * FROM users WHERE id = $1";
+    const { rows } = await this.db.query(query, [id]);
+    return rows[0] || null;
+  }
+
+  async findByEmail(email: string): Promise<UserEntity | null> {
+    const query = "SELECT * FROM users WHERE email = $1";
+    const { rows } = await this.db.query(query, [email]);
+    return rows[0] || null;
+  }
+
+  async update(id: string, updates: UpdateUserDTO): Promise<UserEntity | null> {
+    const fields = Object.keys(updates);
+    const values = Object.values(updates);
+
+    const setClause = fields
+      .map((field, idx) => `${field} = $${idx + 2}`)
+      .join(", ");
+
+    const query = `
+      UPDATE users
+      SET ${setClause}, updated_at = CURRENT_TIMESTAMP
+      WHERE id = $1
+      RETURNING *
+    `;
+
+    const { rows } = await this.db.query(query, [id, ...values]);
+    return rows[0] || null;
+  }
+
+  async delete(id: string): Promise<boolean> {
+    const query = "DELETE FROM users WHERE id = $1";
+    const { rowCount } = await this.db.query(query, [id]);
+    return rowCount > 0;
+  }
+}
+```
+
+### Pattern 2: Dependency Injection
+
+Use a DI container to wire up repositories, services, and controllers. For a full container implementation, see [references/advanced-patterns.md](references/advanced-patterns.md).
+
+## Middleware Patterns
+
+### Authentication Middleware
+
+```typescript
+// middleware/auth.middleware.ts
+import { Request, Response, NextFunction } from "express";
+import jwt from "jsonwebtoken";
+import { UnauthorizedError } from "../utils/errors";
+
+interface JWTPayload {
+  userId: string;
+  email: string;
+}
+
+declare global {
+  namespace Express {
+    interface Request {
+      user?: JWTPayload;
+    }
+  }
+}
+
+export const authenticate = async (
+  req: Request,
+  res: Response,
+  next: NextFunction,
+) => {
+  try {
+    const token = req.headers.authorization?.replace("Bearer ", "");
+
+    if (!token) {
+      throw new UnauthorizedError("No token provided");
+    }
+
+    const payload = jwt.verify(token, process.env.JWT_SECRET!) as JWTPayload;
+
+    req.user = payload;
+    next();
+  } catch (error) {
+    next(new UnauthorizedError("Invalid token"));
+  }
+};
+
+export const authorize = (...roles: string[]) => {
+  return async (req: Request, res: Response, next: NextFunction) => {
+    if (!req.user) {
+      return next(new UnauthorizedError("Not authenticated"));
+    }
+
+    // Check if user has required role
+    const hasRole = roles.some((role) => req.user?.roles?.includes(role));
+
+    if (!hasRole) {
+      return next(new UnauthorizedError("Insufficient permissions"));
+    }
+
+    next();
+  };
+};
+```
+
+### Validation Middleware
+
+```typescript
+// middleware/validation.middleware.ts
+import { Request, Response, NextFunction } from "express";
+import { AnyZodObject, ZodError } from "zod";
+import { ValidationError } from "../utils/errors";
+
+export const validate = (schema: AnyZodObject) => {
+  return async (req: Request, res: Response, next: NextFunction) => {
+    try {
+      await schema.parseAsync({
+        body: req.body,
+        query: req.query,
+        params: req.params,
+      });
+      next();
+    } catch (error) {
+      if (error instanceof ZodError) {
+        const errors = error.errors.map((err) => ({
+          field: err.path.join("."),
+          message: err.message,
+        }));
+        next(new ValidationError("Validation failed", errors));
+      } else {
+        next(error);
+      }
+    }
+  };
+};
+
+// Usage with Zod
+import { z } from "zod";
+
+const createUserSchema = z.object({
+  body: z.object({
+    name: z.string().min(1),
+    email: z.string().email(),
+    password: z.string().min(8),
+  }),
+});
+
+router.post("/users", validate(createUserSchema), userController.createUser);
+```
+
+### Rate Limiting Middleware
+
+```typescript
+// middleware/rate-limit.middleware.ts
+import rateLimit from "express-rate-limit";
+import RedisStore from "rate-limit-redis";
+import Redis from "ioredis";
+
+const redis = new Redis({
+  host: process.env.REDIS_HOST,
+  port: parseInt(process.env.REDIS_PORT || "6379"),
+});
+
+export const apiLimiter = rateLimit({
+  store: new RedisStore({
+    client: redis,
+    prefix: "rl:",
+  }),
+  windowMs: 15 * 60 * 1000, // 15 minutes
+  max: 100, // Limit each IP to 100 requests per windowMs
+  message: "Too many requests from this IP, please try again later",
+  standardHeaders: true,
+  legacyHeaders: false,
+});
+
+export const authLimiter = rateLimit({
+  store: new RedisStore({
+    client: redis,
+    prefix: "rl:auth:",
+  }),
+  windowMs: 15 * 60 * 1000,
+  max: 5, // Stricter limit for auth endpoints
+  skipSuccessfulRequests: true,
+});
+```
+
+### Request Logging Middleware
+
+```typescript
+// middleware/logger.middleware.ts
+import { Request, Response, NextFunction } from "express";
+import pino from "pino";
+
+const logger = pino({
+  level: process.env.LOG_LEVEL || "info",
+  transport: {
+    target: "pino-pretty",
+    options: { colorize: true },
+  },
+});
+
+export const requestLogger = (
+  req: Request,
+  res: Response,
+  next: NextFunction,
+) => {
+  const start = Date.now();
+
+  // Log response when finished
+  res.on("finish", () => {
+    const duration = Date.now() - start;
+    logger.info({
+      method: req.method,
+      url: req.url,
+      status: res.statusCode,
+      duration: `${duration}ms`,
+      userAgent: req.headers["user-agent"],
+      ip: req.ip,
+    });
+  });
+
+  next();
+};
+
+export { logger };
+```
+
+## Error Handling
+
+### Custom Error Classes
+
+```typescript
+// utils/errors.ts
+export class AppError extends Error {
+  constructor(
+    public message: string,
+    public statusCode: number = 500,
+    public isOperational: boolean = true,
+  ) {
+    super(message);
+    Object.setPrototypeOf(this, AppError.prototype);
+    Error.captureStackTrace(this, this.constructor);
+  }
+}
+
+export class ValidationError extends AppError {
+  constructor(
+    message: string,
+    public errors?: any[],
+  ) {
+    super(message, 400);
+  }
+}
+
+export class NotFoundError extends AppError {
+  constructor(message: string = "Resource not found") {
+    super(message, 404);
+  }
+}
+
+export class UnauthorizedError extends AppError {
+  constructor(message: string = "Unauthorized") {
+    super(message, 401);
+  }
+}
+
+export class ForbiddenError extends AppError {
+  constructor(message: string = "Forbidden") {
+    super(message, 403);
+  }
+}
+
+export class ConflictError extends AppError {
+  constructor(message: string) {
+    super(message, 409);
+  }
+}
+```
+
+### Global Error Handler
+
+```typescript
+// middleware/error-handler.ts
+import { Request, Response, NextFunction } from "express";
+import { AppError } from "../utils/errors";
+import { logger } from "./logger.middleware";
+
+export const errorHandler = (
+  err: Error,
+  req: Request,
+  res: Response,
+  next: NextFunction,
+) => {
+  if (err instanceof AppError) {
+    return res.status(err.statusCode).json({
+      status: "error",
+      message: err.message,
+      ...(err instanceof ValidationError && { errors: err.errors }),
+    });
+  }
+
+  // Log unexpected errors
+  logger.error({
+    error: err.message,
+    stack: err.stack,
+    url: req.url,
+    method: req.method,
+  });
+
+  // Don't leak error details in production
+  const message =
+    process.env.NODE_ENV === "production"
+      ? "Internal server error"
+      : err.message;
+
+  res.status(500).json({
+    status: "error",
+    message,
+  });
+};
+
+// Async error wrapper
+export const asyncHandler = (
+  fn: (req: Request, res: Response, next: NextFunction) => Promise<any>,
+) => {
+  return (req: Request, res: Response, next: NextFunction) => {
+    Promise.resolve(fn(req, res, next)).catch(next);
+  };
+};
+```
+
+## Database Patterns
+
+Node.js supports both SQL and NoSQL databases. Use connection pooling for all production databases.
+
+Key patterns covered in [references/advanced-patterns.md](references/advanced-patterns.md):
+- **PostgreSQL with connection pool** — `pg` Pool configuration and graceful shutdown
+- **MongoDB with Mongoose** — connection management and schema definition
+- **Transaction pattern** — `BEGIN`/`COMMIT`/`ROLLBACK` with `pg` client
+
+## Authentication & Authorization
+
+JWT-based auth with access tokens (short-lived, 15m) and refresh tokens (7d). Full `AuthService` implementation with `bcrypt` password comparison in [references/advanced-patterns.md](references/advanced-patterns.md).
+
+## Caching Strategies
+
+Redis-backed `CacheService` with get/set/delete/invalidatePattern, plus a `@Cacheable` decorator for method-level caching. See [references/advanced-patterns.md](references/advanced-patterns.md).
+
+## API Response Format
+
+Standardized `ApiResponse` helper with `success`, `error`, and `paginated` static methods. See [references/advanced-patterns.md](references/advanced-patterns.md).
+
+## Best Practices
+
+1. **Use TypeScript**: Type safety prevents runtime errors
+2. **Implement proper error handling**: Use custom error classes
+3. **Validate input**: Use libraries like Zod or Joi
+4. **Use environment variables**: Never hardcode secrets
+5. **Implement logging**: Use structured logging (Pino, Winston)
+6. **Add rate limiting**: Prevent abuse
+7. **Use HTTPS**: Always in production
+8. **Implement CORS properly**: Don't use `*` in production
+9. **Use dependency injection**: Easier testing and maintenance
+10. **Write tests**: Unit, integration, and E2E tests
+11. **Handle graceful shutdown**: Clean up resources
+12. **Use connection pooling**: For databases
+13. **Implement health checks**: For monitoring
+14. **Use compression**: Reduce response size
+15. **Monitor performance**: Use APM tools
+
+## Testing Patterns
+
+See `javascript-testing-patterns` skill for comprehensive testing guidance.