@orchestrator-claude/definitions 3.5.0

package/kb/error-handling.md

@@ -0,0 +1,555 @@
+---
+title: "Error Handling Patterns"
+category: "patterns"
+tier: "foundational"
+tags: ["api", "errors", "express", "middleware"]
+template: "api"
+---
+
+# Error Handling Patterns
+
+## Overview
+
+This document defines error handling patterns and strategies for building robust, maintainable REST APIs with consistent error responses.
+
+**Project**: my-project
+**Template**: api
+
+---
+
+## 1. Error Response Format
+
+### Standard Error Structure
+
+All API errors MUST follow this consistent format:
+
+```typescript
+interface ErrorResponse {
+  error: string;           // Error type/name
+  message: string;         // Human-readable message
+  details?: unknown;       // Optional additional context
+  timestamp: string;       // ISO 8601 timestamp
+  path: string;           // Request path
+  requestId?: string;     // Request ID for tracing
+}
+```
+
+### Example
+
+```json
+{
+  "error": "ValidationError",
+  "message": "Invalid email format",
+  "details": {
+    "field": "email",
+    "value": "invalid-email",
+    "constraint": "Must be a valid email address"
+  },
+  "timestamp": "2025-01-06T12:00:00Z",
+  "path": "/api/v1/users",
+  "requestId": "550e8400-e29b-41d4-a716-446655440000"
+}
+```
+
+---
+
+## 2. Error Types
+
+### Domain Errors
+
+Errors from business logic (domain layer).
+
+```typescript
+// src/domain/errors/UserNotFoundError.ts
+export class UserNotFoundError extends Error {
+  constructor(userId: string) {
+    super(`User not found: ${userId}`);
+    this.name = 'UserNotFoundError';
+  }
+}
+
+// src/domain/errors/DuplicateEmailError.ts
+export class DuplicateEmailError extends Error {
+  constructor(email: string) {
+    super(`Email already exists: ${email}`);
+    this.name = 'DuplicateEmailError';
+  }
+}
+```
+
+### Validation Errors
+
+Errors from input validation (using Zod).
+
+```typescript
+import { z } from 'zod';
+
+const CreateUserSchema = z.object({
+  name: z.string().min(1).max(100),
+  email: z.string().email(),
+  age: z.number().int().positive().optional(),
+});
+
+// Validation error example
+const result = CreateUserSchema.safeParse(input);
+if (!result.success) {
+  // result.error.issues contains detailed validation errors
+}
+```
+
+### Infrastructure Errors
+
+Errors from external systems (database, APIs).
+
+```typescript
+export class DatabaseError extends Error {
+  constructor(message: string, public readonly cause?: Error) {
+    super(message);
+    this.name = 'DatabaseError';
+  }
+}
+
+export class ExternalAPIError extends Error {
+  constructor(
+    service: string,
+    message: string,
+    public readonly statusCode?: number
+  ) {
+    super(`${service}: ${message}`);
+    this.name = 'ExternalAPIError';
+  }
+}
+```
+
+---
+
+## 3. Error Middleware
+
+### Global Error Handler
+
+```typescript
+// src/presentation/middleware/errorHandler.ts
+import type { Request, Response, NextFunction } from 'express';
+
+export function errorHandler(
+  err: Error,
+  req: Request,
+  res: Response,
+  next: NextFunction
+): void {
+  // Log error
+  console.error('API Error:', {
+    error: err.name,
+    message: err.message,
+    stack: process.env.NODE_ENV === 'development' ? err.stack : undefined,
+    path: req.path,
+    method: req.method,
+    requestId: req.id,
+  });
+
+  // Map error to HTTP status
+  const statusCode = getStatusCode(err);
+  const errorResponse = createErrorResponse(err, req);
+
+  res.status(statusCode).json(errorResponse);
+}
+
+function getStatusCode(err: Error): number {
+  // Domain errors
+  if (err.name === 'UserNotFoundError') return 404;
+  if (err.name === 'DuplicateEmailError') return 409;
+  if (err.name === 'UnauthorizedError') return 401;
+  if (err.name === 'ForbiddenError') return 403;
+
+  // Validation errors
+  if (err.name === 'ZodError') return 400;
+
+  // Default to 500
+  return 500;
+}
+
+function createErrorResponse(err: Error, req: Request): ErrorResponse {
+  const isProduction = process.env.NODE_ENV === 'production';
+
+  return {
+    error: err.name,
+    message: isProduction && err.name === 'Error'
+      ? 'An unexpected error occurred'
+      : err.message,
+    details: getErrorDetails(err),
+    timestamp: new Date().toISOString(),
+    path: req.path,
+    requestId: req.id,
+  };
+}
+
+function getErrorDetails(err: Error): unknown {
+  // For Zod validation errors
+  if (err.name === 'ZodError') {
+    const zodError = err as z.ZodError;
+    return zodError.issues.map(issue => ({
+      path: issue.path.join('.'),
+      message: issue.message,
+      code: issue.code,
+    }));
+  }
+
+  // For other errors, return nothing in production
+  if (process.env.NODE_ENV === 'production') {
+    return undefined;
+  }
+
+  return { stack: err.stack };
+}
+```
+
+### Register Error Handler
+
+```typescript
+// src/server.ts
+import express from 'express';
+import { errorHandler } from './presentation/middleware/errorHandler';
+
+const app = express();
+
+// ... routes ...
+
+// Error handler MUST be last middleware
+app.use(errorHandler);
+
+export default app;
+```
+
+---
+
+## 4. Validation Error Handling
+
+### Request Validation Middleware
+
+```typescript
+// src/presentation/middleware/validateRequest.ts
+import type { Request, Response, NextFunction } from 'express';
+import type { z } from 'zod';
+
+export function validateRequest<T extends z.ZodSchema>(schema: T) {
+  return (req: Request, res: Response, next: NextFunction) => {
+    const result = schema.safeParse(req.body);
+
+    if (!result.success) {
+      const errorResponse: ErrorResponse = {
+        error: 'ValidationError',
+        message: 'Request validation failed',
+        details: result.error.issues.map(issue => ({
+          path: issue.path.join('.'),
+          message: issue.message,
+          code: issue.code,
+        })),
+        timestamp: new Date().toISOString(),
+        path: req.path,
+        requestId: req.id,
+      };
+
+      return res.status(400).json(errorResponse);
+    }
+
+    // Attach validated data to request
+    req.body = result.data;
+    next();
+  };
+}
+```
+
+### Usage in Routes
+
+```typescript
+import { validateRequest } from '../middleware/validateRequest';
+import { CreateUserSchema } from '../schemas/user';
+
+router.post(
+  '/api/v1/users',
+  validateRequest(CreateUserSchema),
+  async (req, res, next) => {
+    try {
+      // req.body is now type-safe and validated
+      const result = await createUserUseCase.execute(req.body);
+
+      if (result.isErr()) {
+        // Convert domain error to HTTP error
+        return next(new DuplicateEmailError(req.body.email));
+      }
+
+      res.status(201).json(result.value);
+    } catch (err) {
+      next(err); // Pass to error handler
+    }
+  }
+);
+```
+
+---
+
+## 5. Async Error Handling
+
+### Async Route Handler Wrapper
+
+```typescript
+// src/presentation/middleware/asyncHandler.ts
+import type { Request, Response, NextFunction } from 'express';
+
+type AsyncRouteHandler = (
+  req: Request,
+  res: Response,
+  next: NextFunction
+) => Promise<void>;
+
+export function asyncHandler(fn: AsyncRouteHandler) {
+  return (req: Request, res: Response, next: NextFunction) => {
+    Promise.resolve(fn(req, res, next)).catch(next);
+  };
+}
+```
+
+### Usage
+
+```typescript
+import { asyncHandler } from '../middleware/asyncHandler';
+
+router.get(
+  '/api/v1/users/:id',
+  asyncHandler(async (req, res) => {
+    const result = await getUserUseCase.execute({ userId: req.params.id });
+
+    if (result.isErr()) {
+      throw new UserNotFoundError(req.params.id);
+    }
+
+    res.json(result.value);
+  })
+);
+```
+
+---
+
+## 6. Result Pattern
+
+### Use Result<T, E> for Use Cases
+
+```typescript
+// src/shared/types/Result.ts
+export type Result<T, E> =
+  | { isOk: true; value: T }
+  | { isOk: false; error: E };
+
+export function ok<T>(value: T): Result<T, never> {
+  return { isOk: true, value };
+}
+
+export function err<E>(error: E): Result<never, E> {
+  return { isOk: false, error };
+}
+
+// Usage in Use Case
+export class GetUserUseCase {
+  async execute(input: { userId: string }): Promise<Result<User, string>> {
+    const user = await this.userRepository.findById(input.userId);
+
+    if (!user) {
+      return err('User not found');
+    }
+
+    return ok(user);
+  }
+}
+
+// Usage in Route
+router.get('/api/v1/users/:id', async (req, res, next) => {
+  const result = await getUserUseCase.execute({ userId: req.params.id });
+
+  if (!result.isOk) {
+    return next(new UserNotFoundError(req.params.id));
+  }
+
+  res.json(result.value);
+});
+```
+
+---
+
+## 7. Not Found Handler
+
+### 404 Handler
+
+```typescript
+// src/presentation/middleware/notFoundHandler.ts
+import type { Request, Response } from 'express';
+
+export function notFoundHandler(req: Request, res: Response): void {
+  const errorResponse: ErrorResponse = {
+    error: 'NotFound',
+    message: `Route not found: ${req.method} ${req.path}`,
+    timestamp: new Date().toISOString(),
+    path: req.path,
+    requestId: req.id,
+  };
+
+  res.status(404).json(errorResponse);
+}
+```
+
+### Register Before Error Handler
+
+```typescript
+// src/server.ts
+import { notFoundHandler } from './presentation/middleware/notFoundHandler';
+import { errorHandler } from './presentation/middleware/errorHandler';
+
+// ... routes ...
+
+// 404 handler
+app.use(notFoundHandler);
+
+// Error handler
+app.use(errorHandler);
+```
+
+---
+
+## 8. Error Logging
+
+### Structured Logging
+
+```typescript
+interface ErrorLog {
+  level: 'error';
+  error: string;
+  message: string;
+  stack?: string;
+  context: {
+    requestId?: string;
+    path: string;
+    method: string;
+    userId?: string;
+  };
+  timestamp: string;
+}
+
+function logError(err: Error, req: Request): void {
+  const log: ErrorLog = {
+    level: 'error',
+    error: err.name,
+    message: err.message,
+    stack: err.stack,
+    context: {
+      requestId: req.id,
+      path: req.path,
+      method: req.method,
+      userId: req.user?.id, // If authenticated
+    },
+    timestamp: new Date().toISOString(),
+  };
+
+  // Log as JSON for parsing by log aggregators
+  console.error(JSON.stringify(log));
+}
+```
+
+---
+
+## 9. Rate Limit Errors
+
+### Rate Limit Handler
+
+```typescript
+import rateLimit from 'express-rate-limit';
+
+const limiter = rateLimit({
+  windowMs: 15 * 60 * 1000, // 15 minutes
+  max: 100,
+  handler: (req, res) => {
+    const errorResponse: ErrorResponse = {
+      error: 'TooManyRequests',
+      message: 'Too many requests from this IP, please try again later',
+      timestamp: new Date().toISOString(),
+      path: req.path,
+      requestId: req.id,
+    };
+
+    res.status(429).json(errorResponse);
+  },
+  standardHeaders: true,
+  legacyHeaders: false,
+});
+
+app.use('/api/', limiter);
+```
+
+---
+
+## 10. Testing Error Handling
+
+### Test Error Responses
+
+```typescript
+import request from 'supertest';
+import { app } from '../src/server';
+
+describe('Error Handling', () => {
+  it('should return 404 for non-existent route', async () => {
+    const response = await request(app)
+      .get('/api/v1/nonexistent')
+      .expect(404);
+
+    expect(response.body).toHaveProperty('error', 'NotFound');
+    expect(response.body).toHaveProperty('message');
+    expect(response.body).toHaveProperty('timestamp');
+    expect(response.body).toHaveProperty('path', '/api/v1/nonexistent');
+  });
+
+  it('should return 400 for validation errors', async () => {
+    const response = await request(app)
+      .post('/api/v1/users')
+      .send({ name: '', email: 'invalid' })
+      .expect(400);
+
+    expect(response.body.error).toBe('ValidationError');
+    expect(response.body.details).toBeInstanceOf(Array);
+  });
+
+  it('should return 500 for unexpected errors', async () => {
+    // Mock repository to throw error
+    jest.spyOn(userRepository, 'findById').mockRejectedValue(new Error('DB Error'));
+
+    const response = await request(app)
+      .get('/api/v1/users/123')
+      .expect(500);
+
+    expect(response.body.error).toBe('Error');
+    expect(response.body.message).toBeTruthy();
+  });
+});
+```
+
+---
+
+## Best Practices
+
+1. **Always use middleware for error handling** - Don't handle errors in routes
+2. **Log all errors** - Include request context for debugging
+3. **Use Result pattern** - Avoid throwing errors in use cases
+4. **Consistent error format** - All errors follow same structure
+5. **Sanitize in production** - Don't expose stack traces or sensitive data
+6. **Test error scenarios** - Test all error cases (4xx, 5xx)
+
+---
+
+## References
+
+- [Express Error Handling](https://expressjs.com/en/guide/error-handling.html)
+- [HTTP Status Codes](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status)
+- [Zod Validation](https://zod.dev/)
+
+---
+
+**Generated for**: my-project
+**Template**: api
+**Constitution Preset**: orchestrator