create-charcole 1.1.0 → 2.0.1

package/template/{package.json → js/package.json}

@@ -1,28 +1,28 @@
-{
-  "name": "charcole",
-  "version": "1.0.0",
-  "description": "Production-grade Node.js Express API",
-  "main": "src/server.js",
-  "scripts": {
-    "start": "node src/server.js",
-    "dev": "nodemon src/server.js",
-    "lint": "echo 'Add linting here'",
-    "test": "echo 'Add tests here'"
-  },
-  "engines": {
-    "node": ">=18.0.0"
-  },
-  "keywords": [],
-  "author": "",
-  "license": "ISC",
-  "type": "module",
-  "dependencies": {
-    "cors": "^2.8.5",
-    "dotenv": "^16.3.1",
-    "express": "^4.18.2",
-    "zod": "^3.22.4"
-  },
-  "devDependencies": {
-    "nodemon": "^3.0.2"
-  }
-}
+{
+  "name": "charcole",
+  "version": "2.0.0",
+  "description": "Production-grade Node.js Express API",
+  "main": "src/server.js",
+  "scripts": {
+    "start": "node src/server.js",
+    "dev": "nodemon src/server.js",
+    "lint": "echo 'Add linting here'",
+    "test": "echo 'Add tests here'"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "type": "module",
+  "dependencies": {
+    "cors": "^2.8.5",
+    "dotenv": "^16.3.1",
+    "express": "^4.18.2",
+    "zod": "^3.22.4"
+  },
+  "devDependencies": {
+    "nodemon": "^3.0.2"
+  }
+}

package/template/ts/.env.example

@@ -0,0 +1,8 @@
+NODE_ENV=development
+PORT=3000
+
+LOG_LEVEL=info
+
+CORS_ORIGIN=*
+
+REQUEST_TIMEOUT=30000

package/template/ts/ARCHITECTURE_DIAGRAMS.md

@@ -0,0 +1,283 @@
+# Error Handling Architecture Diagram
+
+## Complete Error Flow
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│                         HTTP REQUEST                                │
+└──────────────────────────────────────┬──────────────────────────────┘
+                                       │
+                                       ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│                    CORS & BODY PARSING MIDDLEWARE                   │
+└──────────────────────────────────────┬──────────────────────────────┘
+                                       │
+                                       ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│                       REQUEST LOGGER MIDDLEWARE                      │
+│  (Logs: method, path, query, IP, user-agent)                        │
+└──────────────────────────────────────┬──────────────────────────────┘
+                                       │
+                                       ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│                    VALIDATION MIDDLEWARE (optional)                  │
+│                                                                      │
+│  Validates with Zod schema → throws ValidationError if fails       │
+└──────────────────────────────────────┬──────────────────────────────┘
+                                       │
+                                       ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│              ROUTE HANDLER (wrapped with asyncHandler)              │
+│                                                                      │
+│  ┌────────────────────────────────────────────────────────────────┐ │
+│  │ asyncHandler(async (req, res) => {                             │ │
+│  │   // Your handler code                                         │ │
+│  │   const user = await User.findById(req.params.id);            │ │
+│  │                                                                │ │
+│  │   if (!user) {                                                │ │
+│  │     throw new NotFoundError("User", { id: req.params.id });   │ │
+│  │   }                                                            │ │
+│  │                                                                │ │
+│  │   sendSuccess(res, user);                                     │ │
+│  │ })                                                             │ │
+│  └────────────────────────────────────────────────────────────────┘ │
+└────────┬────────────────────────────────────────────────────────────┘
+         │
+         ├──→ Success? ──→ sendSuccess() ──→ [END: Response sent]
+         │
+         └──→ Error thrown ✘ ──→ [Continue below]
+                                 │
+                                 ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│              GLOBAL ERROR HANDLER MIDDLEWARE                         │
+│  (This is where ALL errors flow!)                                   │
+└────┬────────────────────────────────────────────────────────────────┘
+     │
+     ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│                    ERROR NORMALIZATION                               │
+│                                                                      │
+│  if (err instanceof AppError)     → Use as is                       │
+│  if (err instanceof ZodError)     → Convert to ValidationError      │
+│  if (err instanceof TypeError)    → Convert to InternalServerError  │
+│  if (err instanceof ReferenceError)→ Convert to InternalServerError │
+│  if (err instanceof SyntaxError)  → Convert to InternalServerError  │
+│  if (err instanceof RangeError)   → Convert to InternalServerError  │
+│  else                             → Wrap in InternalServerError     │
+└────┬────────────────────────────────────────────────────────────────┘
+     │
+     ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│                    ERROR CLASSIFICATION                              │
+│                                                                      │
+│  ┌─ Operational Error (isOperational: true)                        │
+│  │  ├─ ValidationError (422)                                       │
+│  │  ├─ NotFoundError (404)                                         │
+│  │  ├─ AuthenticationError (401)                                   │
+│  │  ├─ AuthorizationError (403)                                    │
+│  │  ├─ ConflictError (409)                                         │
+│  │  └─ BadRequestError (400)                                       │
+│  │                                                                  │
+│  └─ Programmer Error (isOperational: false)                        │
+│     └─ TypeError, ReferenceError, SyntaxError, etc.                │
+└────┬────────────────────────────────────────────────────────────────┘
+     │
+     ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│                      ERROR LOGGING                                   │
+│                                                                      │
+│  If Operational Error:                                              │
+│  ├─ Log as WARN level                                              │
+│  ├─ Include: code, message, statusCode, method, path, IP           │
+│  └─ NO stack trace (expected error)                                │
+│                                                                      │
+│  If Programmer Error:                                               │
+│  ├─ Log as ERROR level                                             │
+│  ├─ Include: code, message, statusCode, method, path, IP, stack    │
+│  └─ YES full stack trace (for debugging)                           │
+└────┬────────────────────────────────────────────────────────────────┘
+     │
+     ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│                  SEND ERROR RESPONSE                                 │
+│                                                                      │
+│  If Production & Programmer Error:                                  │
+│  ├─ {                                                               │
+│  │   success: false,                                               │
+│  │   message: "Internal server error",                             │
+│  │   code: "INTERNAL_SERVER_ERROR",                                │
+│  │   timestamp: "..."                                              │
+│  │ }                                                                │
+│  │                                                                  │
+│  └─ (Details hidden from client)                                   │
+│                                                                      │
+│  If Development OR Operational Error:                               │
+│  ├─ {                                                               │
+│  │   success: false,                                               │
+│  │   message: "Full error message",                                │
+│  │   code: "ERROR_CODE",                                           │
+│  │   statusCode: 422,                                              │
+│  │   context: { ... },                                             │
+│  │   errors: [ ... ],  // for validation errors                    │
+│  │   timestamp: "..."                                              │
+│  │ }                                                                │
+│  │                                                                  │
+│  └─ (Full details sent)                                            │
+└────┬────────────────────────────────────────────────────────────────┘
+     │
+     ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│                  HTTP RESPONSE SENT TO CLIENT                        │
+│                                                                      │
+│  Status Code: 400, 401, 403, 404, 409, 422, 500, etc.              │
+│  Body: Consistent JSON error format                                 │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+## Error Class Hierarchy
+
+```
+Error (JavaScript)
+  │
+  └── AppError (Base class)
+      │
+      ├── ValidationError         (422 - Input validation failed)
+      ├── BadRequestError         (400 - Malformed request)
+      ├── AuthenticationError     (401 - Auth failed)
+      ├── AuthorizationError      (403 - Permission denied)
+      ├── NotFoundError           (404 - Resource not found)
+      ├── ConflictError           (409 - Duplicate/conflict)
+      └── InternalServerError     (500 - Unexpected error)
+```
+
+## Middleware Stack Order
+
+```
+Express App
+│
+├─ Trust Proxy
+├─ CORS
+├─ JSON Body Parser
+├─ URL Encoded Parser
+├─ Request Timeout Handler
+│
+├─ requestLogger (logs all requests)
+│
+├─ Routes:
+│  │
+│  ├─ validateRequest (optional, per route)
+│  │
+│  └─ Route Handler (MUST wrap with asyncHandler)
+│
+└─ errorHandler (MUST BE LAST)
+   └─ Catches all errors and sends JSON response
+```
+
+## Error Classification Decision Tree
+
+```
+                           Error Thrown
+                                │
+                    ┌───────────┴───────────┐
+                    │                       │
+               Is AppError?            Is ZodError?
+                    │                       │
+                   YES                     YES
+                    │                       │
+            ┌───────▼────────┐      ┌──────▼──────────┐
+            │ Use as is      │      │ Convert to      │
+            │ (already has   │      │ ValidationError │
+            │  isOperational)│      │ (422)           │
+            └─────────────────┘      └─────────────────┘
+                                            │
+                    ┌───────────────────────┴───────────────────────┐
+                    │                                               │
+              Is Operational?                              Is Programmer Error?
+              (isOperational: true)                        (Syntax, Type, Ref, Range)
+                    │                                               │
+                   YES                                             YES
+                    │                                               │
+         ┌──────────▼──────────┐                        ┌──────────▼──────────┐
+         │ Send full error     │                        │ Convert to          │
+         │ details to client   │                        │ InternalServerError │
+         │ with code & context │                        │ (500)               │
+         │                     │                        │ isOperational: false│
+         │ Log as WARN         │                        │                     │
+         │ (no stack)          │                        │ Log as ERROR        │
+         │                     │                        │ WITH FULL STACK     │
+         └─────────────────────┘                        │                     │
+                                                        │ Hide details in     │
+                                                        │ production          │
+                                                        └─────────────────────┘
+```
+
+## Request-to-Response Timeline
+
+```
+TIME  LAYER                  ACTION
+════  ═════════════════════  ════════════════════════════════════════
+
+T0    Network               Request arrives at server
+
+T1    Express Middleware    CORS, Body Parser, Request Logger
+
+T2    Route Handler         validateRequest() - validates input
+
+T3    Route Handler         Handler executes (wrapped with asyncHandler)
+                            ├─ Success: sendSuccess() → Response sent → T6
+                            └─ Error: Thrown → T4
+
+T4    asyncHandler          Catches error, passes to next(error)
+
+T5    Error Handler Mw      Normalizes error
+                            Classifies (operational vs programmer)
+                            Logs error with context
+                            Sanitizes response (production)
+                            Sends JSON response
+
+T6    Network               Response sent to client
+```
+
+## Environment Behavior
+
+```
+┌──────────────────────┐           ┌──────────────────────┐
+│    DEVELOPMENT       │           │    PRODUCTION        │
+│  NODE_ENV=development│           │  NODE_ENV=production │
+└──────────┬───────────┘           └──────────┬───────────┘
+           │                                  │
+           │ Programmer Error:                │ Programmer Error:
+           │ ┌────────────────────────┐       │ ┌────────────────────────┐
+           │ │ {                      │       │ │ {                      │
+           │ │   success: false,      │       │ │   success: false,      │
+           │ │   message: "TypeError: │       │ │   message: "Internal   │
+           │ │   x is undefined",     │       │ │   server error",       │
+           │ │   code: "INTERNAL...", │       │ │   code: "INTERNAL...", │
+           │ │   stack: "TypeError... │       │ │   timestamp: "..."     │
+           │ │   at handler.js:15..." │       │ │ }                      │
+           │ │ }                      │       │ │                        │
+           │ └────────────────────────┘       │ └────────────────────────┘
+           │                                  │
+           │ Operational Error:               │ Operational Error:
+           │ (sent fully in both)             │ (sent fully in both)
+           │ ┌────────────────────────┐       │ ┌────────────────────────┐
+           │ │ {                      │       │ │ {                      │
+           │ │   success: false,      │       │ │   success: false,      │
+           │ │   message: "User not   │       │ │   message: "User not   │
+           │ │   found",              │       │ │   found",              │
+           │ │   code: "NOT_FOUND",   │       │ │   code: "NOT_FOUND",   │
+           │ │   context: {...}       │       │ │   context: {...}       │
+           │ │ }                      │       │ │ }                      │
+           │ └────────────────────────┘       │ └────────────────────────┘
+           │                                  │
+           │ Logging:                         │ Logging:
+           │ Full details + stack             │ Full details + stack
+           │ (for development)                │ (server-side only)
+           │                                  │
+```
+
+---
+
+This architecture ensures that **every single error in your application flows through one place, gets properly classified, logged with full context, and returns a consistent JSON response to the client.**
+
+That's production-grade error handling. 🎯

package/template/ts/CHECKLIST.md

@@ -0,0 +1,279 @@
+# Implementation Checklist - Production Error Handling System
+
+## ✅ Files Created
+
+- [x] `src/utils/AppError.js` - Error class hierarchy (8 error types)
+- [x] `ERROR_HANDLING.md` - Comprehensive documentation
+- [x] `QUICK_REFERENCE.md` - Quick start guide
+- [x] `ARCHITECTURE_DIAGRAMS.md` - Visual architecture diagrams
+- [x] `IMPLEMENTATION_COMPLETE.md` - Implementation details & examples
+- [x] `COMPLETE.md` - Final summary document
+- [x] `test-api.js` - API testing script
+
+## ✅ Files Updated
+
+### Core System
+
+- [x] `src/utils/logger.js` - Added stack trace support + fatal() method
+- [x] `src/utils/response.js` - Added documentation, kept for backward compatibility
+- [x] `src/middlewares/errorHandler.js` - **Complete rewrite**
+  - Global error handler with normalization
+  - asyncHandler wrapper for async routes
+  - Error classification (operational vs programmer)
+  - Intelligent logging based on error type
+  - Production-safe responses
+- [x] `src/middlewares/validateRequest.js` - Updated to throw ValidationError
+- [x] `src/middlewares/requestLogger.js` - Enhanced with error detection
+- [x] `src/app.js` - Updated to use new error system
+- [x] `src/server.js` - Enhanced with graceful shutdown
+- [x] `src/routes.js` - Updated with example routes
+- [x] `src/modules/health/controller.js` - Updated with asyncHandler & new error classes
+- [x] `package.json` - Already had Zod, no changes needed
+- [x] `.env` - Already configured
+- [x] `.env.example` - Already configured
+- [x] `README.md` - Already configured
+
+---
+
+## 🎯 Core Components
+
+### 1. AppError Class Hierarchy
+
+```
+AppError (base) - isOperational, code, context, cause, timestamp
+├── ValidationError (422)
+├── BadRequestError (400)
+├── AuthenticationError (401)
+├── AuthorizationError (403)
+├── NotFoundError (404)
+├── ConflictError (409)
+└── InternalServerError (500)
+```
+
+**Methods:**
+
+- `toJSON()` - Convert to response format
+- `getFullDetails()` - Get full error info for logging
+
+### 2. Global Error Handler
+
+```
+errorHandler(err, req, res, next)
+├── normalizeError() - Convert any error type to AppError
+├── logError() - Log with appropriate level + context
+└── sendErrorResponse() - Send client response
+```
+
+### 3. Async Error Wrapper
+
+```
+asyncHandler(fn) - Wraps async handlers to catch errors
+```
+
+**Usage:**
+
+```javascript
+router.get(
+  "/endpoint",
+  asyncHandler(async (req, res) => {
+    // Error thrown here is caught and passed to global handler
+  }),
+);
+```
+
+### 4. Validation Middleware
+
+```
+validateRequest(schema) - Validates body, query, params
+├── Throws ValidationError if fails
+└── Attaches req.validatedData if succeeds
+```
+
+### 5. Enhanced Logger
+
+```
+logger.debug(msg, data)
+logger.info(msg, data)
+logger.warn(msg, data)
+logger.error(msg, data, stack)
+logger.fatal(msg, data, stack)
+```
+
+**Features:**
+
+- Color-coded output
+- Configurable levels
+- Stack trace support
+
+---
+
+## 🔄 Error Flow Summary
+
+1. **Request arrives**
+2. **Middleware chain** (CORS, body parser, request logger)
+3. **Validation middleware** (optional, throws ValidationError)
+4. **Route handler** (wrapped with asyncHandler)
+   - Success → `sendSuccess(res, data)` → Response sent
+   - Error → `throw new ErrorType(...)` → Step 5
+5. **asyncHandler catches** error → passes to next(error)
+6. **Global error handler** catches error
+   - Normalizes: ZodError → ValidationError, TypeError → InternalServerError, etc.
+   - Classifies: operational vs programmer
+   - Logs: WARN for operational, ERROR with stack for programmer
+   - Sanitizes: hides details in production
+   - Sends: consistent JSON response
+7. **Client receives** structured error response
+
+---
+
+## 📊 Error Classification
+
+### Operational Errors (isOperational: true)
+
+**Expected errors that can be handled gracefully**
+
+- ValidationError (422) - Input validation failed
+- BadRequestError (400) - Malformed request
+- AuthenticationError (401) - Invalid credentials
+- AuthorizationError (403) - Permission denied
+- NotFoundError (404) - Resource doesn't exist
+- ConflictError (409) - Duplicate/conflict
+
+**Behavior:**
+
+- ✅ Logged as WARN
+- ✅ Full details sent to client
+- ✅ NO stack trace logged
+- ✅ Code included for client handling
+
+### Programmer Errors (isOperational: false)
+
+**Unexpected errors that indicate bugs**
+
+- TypeError
+- ReferenceError
+- SyntaxError
+- RangeError
+- Unhandled exceptions
+- Any error not explicitly thrown as AppError
+
+**Behavior:**
+
+- ✅ Logged as ERROR
+- ✅ FULL stack trace logged
+- ✅ Generic message sent to client in production
+- ✅ Full details shown in development
+
+---
+
+## 🎓 Golden Rules
+
+1. ✅ **Always wrap async handlers** with asyncHandler
+2. ✅ **Always throw AppError** (not res.status().json())
+3. ✅ **Always validate** with validateRequest middleware
+4. ✅ **Always include context** when throwing errors
+5. ✅ **Always use sendSuccess()** for success responses
+6. ❌ **Never use res.status().json()** for errors
+7. ❌ **Never catch errors silently**
+8. ❌ **Never mix error handling styles**
+
+---
+
+## 🔍 Testing the System
+
+### Manual Test Cases
+
+1. **Valid request** → 200 with data
+2. **Invalid input** → 422 with field errors
+3. **Not found** → 404 with context
+4. **Duplicate** → 409 with message
+5. **Unauthorized** → 401 with message
+6. **Forbidden** → 403 with message
+7. **Programmer error** → 500 (generic in prod, detailed in dev)
+8. **Unhandled error** → Caught and logged
+
+### Run API Tests
+
+```bash
+node test-api.js
+```
+
+---
+
+## 📈 Production Readiness
+
+### Before Deploying
+
+- [ ] Set `NODE_ENV=production` in .env
+- [ ] Configure `CORS_ORIGIN` for your domain
+- [ ] Set `LOG_LEVEL` appropriately
+- [ ] Test all endpoints with error cases
+- [ ] Verify error responses don't leak secrets
+- [ ] Set up error monitoring (e.g., Sentry)
+- [ ] Configure structured logging sink
+- [ ] Test graceful shutdown behavior
+
+### Error Monitoring
+
+Monitor these metrics:
+
+- 4xx error rate (client errors)
+- 5xx error rate (server errors)
+- Error rate by endpoint
+- Error rate by error code
+- Response time percentiles
+- Unhandled exception rate
+
+---
+
+## 📚 Documentation Files
+
+| File                                                     | Purpose        | Audience   |
+| -------------------------------------------------------- | -------------- | ---------- |
+| [COMPLETE.md](COMPLETE.md)                               | Final summary  | Everyone   |
+| [QUICK_REFERENCE.md](QUICK_REFERENCE.md)                 | Quick start    | Developers |
+| [ERROR_HANDLING.md](ERROR_HANDLING.md)                   | Full guide     | Architects |
+| [ARCHITECTURE_DIAGRAMS.md](ARCHITECTURE_DIAGRAMS.md)     | Visual arch    | Architects |
+| [IMPLEMENTATION_COMPLETE.md](IMPLEMENTATION_COMPLETE.md) | Implementation | DevOps     |
+
+---
+
+## 🚀 Starting the Server
+
+```bash
+# Development
+npm run dev
+
+# Production
+npm start
+
+# Testing
+node test-api.js
+```
+
+---
+
+## ✨ What You Get
+
+✅ Centralized error handling  
+✅ Proper error classification  
+✅ Comprehensive logging  
+✅ Secure error responses  
+✅ Development-friendly output  
+✅ Production-safe responses  
+✅ Consistent JSON format  
+✅ Full stack traces (in dev)  
+✅ Error context tracking  
+✅ Request logging  
+✅ Async error catching  
+✅ Graceful shutdown
+
+---
+
+## 🎯 Status: COMPLETE ✅
+
+All components implemented. All files created. All documentation written.
+
+**Your production-grade error handling system is ready to deploy.** 🚀
+
+Every error flows through one place. Every response is consistent. This is where engineering starts. 🎓