create-charcole 1.0.0 → 2.0.1

package/template/ts/COMPLETE.md

@@ -0,0 +1,405 @@
+# ✅ PRODUCTION-LEVEL ERROR HANDLING - COMPLETE
+
+## 🎯 Mission Accomplished
+
+**No more random `res.status(500).json(...)`**
+
+Your Express backend now has an **enterprise-grade, centralized error handling system** that distinguishes between operational and programmer errors, with comprehensive logging and consistent JSON responses.
+
+---
+
+## 📂 What Was Built
+
+### Core Error System
+
+```
+src/
+├── utils/
+│   ├── AppError.js                    [NEW] Error class hierarchy
+│   │   ├── AppError (base)
+│   │   ├── ValidationError (422)
+│   │   ├── AuthenticationError (401)
+│   │   ├── AuthorizationError (403)
+│   │   ├── NotFoundError (404)
+│   │   ├── ConflictError (409)
+│   │   ├── BadRequestError (400)
+│   │   └── InternalServerError (500)
+│   │
+│   ├── logger.js                      [ENHANCED] Color-coded logging with stacks
+│   │   ├── debug(), info(), warn(), error()
+│   │   └── fatal() for unhandled errors
+│   │
+│   └── response.js                    [MAINTAINED] Success response helpers
+│
+├── middlewares/
+│   ├── errorHandler.js                [REWRITTEN] Global error handler
+│   │   ├── errorHandler() - Global middleware (MUST BE LAST)
+│   │   ├── asyncHandler() - Wrapper for async routes
+│   │   ├── normalizeError() - Error type conversion
+│   │   ├── logError() - Contextual logging
+│   │   └── sendErrorResponse() - Client response
+│   │
+│   ├── validateRequest.js             [UPDATED] Validation middleware
+│   │   └── Throws ValidationError on failure
+│   │
+│   └── requestLogger.js               [IMPROVED] Request logging
+│       └── Logs all requests with context
+│
+├── config/
+│   ├── env.js                         [MAINTAINED] Environment validation
+│   └── constants.js                   [MAINTAINED] Status codes & messages
+│
+├── app.js                             [UPDATED] Express setup
+│   └── errorHandler as last middleware
+│
+├── server.js                          [UPDATED] Graceful shutdown
+│   └── Proper cleanup on SIGTERM/SIGINT
+│
+├── routes.js                          [UPDATED] Example routes
+│   └── Using new error classes
+│
+└── modules/health/controller.js       [UPDATED] Example handlers
+    └── Using asyncHandler & errors
+```
+
+---
+
+## 🎓 How to Use
+
+### 1️⃣ Throw Errors (Never use res.status().json!)
+
+```javascript
+// ✅ Correct - Throw AppError
+throw new NotFoundError("User", { id: userId });
+throw new ValidationError("Invalid email", errors);
+throw new AuthenticationError("Invalid credentials");
+throw new ConflictError("Email already exists");
+
+// ❌ Wrong - Never use res.status()
+res.status(404).json({ error: "User not found" });
+res.status(500).json({ error: "Something went wrong" });
+```
+
+### 2️⃣ Wrap Async Handlers
+
+```javascript
+// ✅ Correct
+import { asyncHandler } from "./middlewares/errorHandler.js";
+
+router.get(
+  "/users/:id",
+  asyncHandler(async (req, res) => {
+    const user = await User.findById(req.params.id);
+    if (!user) throw new NotFoundError("User");
+    sendSuccess(res, user);
+  }),
+);
+
+// ❌ Wrong
+router.get("/users/:id", async (req, res) => {
+  const user = await User.findById(req.params.id); // Error leaks!
+  sendSuccess(res, user);
+});
+```
+
+### 3️⃣ Validate Requests
+
+```javascript
+import { validateRequest } from "./middlewares/validateRequest.js";
+import { z } from "zod";
+
+const schema = z.object({
+  body: z.object({
+    email: z.string().email(),
+    name: z.string().min(1),
+  }),
+});
+
+router.post(
+  "/users",
+  validateRequest(schema),
+  asyncHandler(async (req, res) => {
+    // req.validatedData.body is already validated
+    const user = await User.create(req.validatedData.body);
+    sendSuccess(res, user, 201, "User created");
+  }),
+);
+```
+
+### 4️⃣ Always Send Success Responses Using Helper
+
+```javascript
+import { sendSuccess } from "./utils/response.js";
+
+// ✅ Correct
+router.get(
+  "/users",
+  asyncHandler(async (req, res) => {
+    const users = await User.find();
+    sendSuccess(res, users, 200, "Users fetched successfully");
+  }),
+);
+
+// ❌ Wrong
+router.get("/users", async (req, res) => {
+  const users = await User.find();
+  res.json(users); // Inconsistent format
+});
+```
+
+---
+
+## 🔍 What Happens When An Error Occurs
+
+```
+Request comes in
+       ↓
+Route Handler throws error (intentional or accidental)
+       ↓
+asyncHandler catches it
+       ↓
+Global errorHandler middleware (last in chain)
+       ↓
+Error normalized to AppError
+       ↓
+Error classified:
+   ├─ Operational? (expected error)
+   │  └─ Log as WARN, send full details to client
+   │
+   └─ Programmer? (unexpected bug)
+      ├─ Log as ERROR with full stack trace
+      └─ Send generic message in production
+       ↓
+Consistent JSON response sent to client
+```
+
+---
+
+## 📊 Logging Examples
+
+### Operational Error (WARN)
+
+```
+[2024-01-19T15:55:30.000Z] WARN: Operational Error: NOT_FOUND
+{
+  "type": "OPERATIONAL",
+  "code": "NOT_FOUND",
+  "message": "User not found",
+  "statusCode": 404,
+  "method": "GET",
+  "path": "/api/users/999"
+}
+```
+
+### Programmer Error (ERROR with stack)
+
+```
+[2024-01-19T15:55:30.000Z] ERROR: Programmer Error: REFERENCE_ERROR
+{
+  "type": "PROGRAMMER",
+  "code": "REFERENCE_ERROR",
+  "message": "user is not defined",
+  "statusCode": 500,
+  "method": "GET",
+  "path": "/api/users/123"
+}
+ReferenceError: user is not defined
+    at getUserHandler (/app/src/modules/users/controller.js:15:3)
+    at processRequest (/app/src/middlewares/errorHandler.js:42:5)
+    ...
+```
+
+---
+
+## 📝 Response Formats
+
+### ✅ Success (200, 201, etc.)
+
+```json
+{
+  "success": true,
+  "message": "User created successfully",
+  "data": { "id": "123", "name": "John" },
+  "timestamp": "2024-01-19T15:55:30.000Z"
+}
+```
+
+### ❌ Validation Error (422)
+
+```json
+{
+  "success": false,
+  "message": "Validation failed",
+  "code": "VALIDATION_ERROR",
+  "statusCode": 422,
+  "errors": [
+    { "field": "email", "message": "Invalid email", "code": "invalid_email" }
+  ],
+  "timestamp": "2024-01-19T15:55:30.000Z"
+}
+```
+
+### ❌ Not Found (404)
+
+```json
+{
+  "success": false,
+  "message": "User not found",
+  "code": "NOT_FOUND",
+  "statusCode": 404,
+  "context": { "id": "999" },
+  "timestamp": "2024-01-19T15:55:30.000Z"
+}
+```
+
+### ❌ Programmer Error (Production)
+
+```json
+{
+  "success": false,
+  "message": "Internal server error",
+  "code": "INTERNAL_SERVER_ERROR",
+  "timestamp": "2024-01-19T15:55:30.000Z"
+}
+```
+
+---
+
+## 📚 Documentation Files
+
+| File                                                     | Purpose                                                                 |
+| -------------------------------------------------------- | ----------------------------------------------------------------------- |
+| [ERROR_HANDLING.md](ERROR_HANDLING.md)                   | **Comprehensive guide** - Architecture, usage, best practices, examples |
+| [QUICK_REFERENCE.md](QUICK_REFERENCE.md)                 | **Quick start** - Error classes, usage patterns, golden rules           |
+| [ARCHITECTURE_DIAGRAMS.md](ARCHITECTURE_DIAGRAMS.md)     | **Visual diagrams** - Error flow, middleware stack, decision trees      |
+| [IMPLEMENTATION_COMPLETE.md](IMPLEMENTATION_COMPLETE.md) | **Implementation details** - Full API response examples                 |
+
+---
+
+## ✨ Key Features Implemented
+
+| Feature                   | Status | Details                               |
+| ------------------------- | ------ | ------------------------------------- |
+| Centralized Error Handler | ✅     | All errors flow through one place     |
+| Error Classification      | ✅     | Operational vs Programmer errors      |
+| Error Classes             | ✅     | 8 specialized error types             |
+| Async Error Wrapping      | ✅     | asyncHandler prevents promise leaks   |
+| Zod Integration           | ✅     | Automatic validation error formatting |
+| Request Validation Mw     | ✅     | Validates body, query, params         |
+| Structured Logging        | ✅     | Color-coded with levels & context     |
+| Stack Trace Logging       | ✅     | Full traces for programmer errors     |
+| Production Sanitization   | ✅     | Hides details in production           |
+| Graceful Shutdown         | ✅     | Proper cleanup on signals             |
+| Consistent JSON Format    | ✅     | All responses standardized            |
+| Request Logging           | ✅     | Logs method, path, status, duration   |
+| Unhandled Exceptions      | ✅     | Caught and logged at exit             |
+
+---
+
+## 🚀 Running Your API
+
+```bash
+# Development (with auto-reload)
+npm run dev
+
+# Production
+npm start
+```
+
+Output:
+
+```
+[2024-01-19T15:55:01.329Z] INFO: Express app configured successfully
+[2024-01-19T15:55:01.329Z] INFO: 🔥 Server running in development mode {
+  "url": "http://localhost:3000",
+  "port": 3000
+}
+```
+
+---
+
+## 🎯 Next Steps
+
+1. **Read [QUICK_REFERENCE.md](QUICK_REFERENCE.md)** for quick start patterns
+2. **Check [ERROR_HANDLING.md](ERROR_HANDLING.md)** for comprehensive guide
+3. **Start building endpoints** using the patterns shown
+4. **Deploy with confidence** - your error handling is production-ready
+
+---
+
+## 💡 Example: Creating a User Endpoint
+
+```javascript
+import {
+  asyncHandler,
+  ConflictError,
+  ValidationError,
+} from "./middlewares/errorHandler.js";
+import { validateRequest } from "./middlewares/validateRequest.js";
+import { sendSuccess } from "./utils/response.js";
+import { z } from "zod";
+
+// 1. Define validation schema
+const createUserSchema = z.object({
+  body: z.object({
+    email: z.string().email("Invalid email"),
+    name: z.string().min(1, "Name required").max(100),
+    password: z.string().min(8, "Min 8 chars"),
+  }),
+});
+
+// 2. Export handler wrapped with asyncHandler
+export const createUser = asyncHandler(async (req, res) => {
+  const { email, name, password } = req.validatedData.body;
+
+  // Check for duplicate (operational error)
+  const exists = await User.findOne({ email });
+  if (exists) {
+    throw new ConflictError("User with this email already exists", { email });
+  }
+
+  // Create user
+  const user = await User.create({ email, name, password });
+
+  // Send success response
+  sendSuccess(res, user, 201, "User created successfully");
+});
+
+// 3. Use in routes
+router.post("/users", validateRequest(createUserSchema), createUser);
+
+// That's it! Errors are automatically caught and handled:
+// ✅ Validation errors → 422 with field details
+// ✅ Duplicate email → 409 Conflict
+// ✅ Database error → 500 with stack trace (dev only)
+// ✅ Any unexpected error → 500 with full logging
+```
+
+---
+
+## 🏆 You Now Have
+
+✅ **A complete, production-grade error handling system**  
+✅ **Every error flows through one centralized handler**  
+✅ **Operational vs Programmer errors are distinguished**  
+✅ **Comprehensive logging with context**  
+✅ **Consistent JSON response format**  
+✅ **Security: Production sanitization of errors**  
+✅ **Development debugging: Full stack traces**  
+✅ **Enterprise-ready error management**
+
+---
+
+## 📞 Support
+
+For detailed examples and patterns, see:
+
+- **[ERROR_HANDLING.md](ERROR_HANDLING.md)** - Full documentation with examples
+- **[QUICK_REFERENCE.md](QUICK_REFERENCE.md)** - Quick patterns and golden rules
+- **[ARCHITECTURE_DIAGRAMS.md](ARCHITECTURE_DIAGRAMS.md)** - Visual architecture
+
+---
+
+**Your API is now ready for production.** 🚀
+
+Every error goes through one place. Every response is consistent. Every issue is properly logged. That's what engineering looks like. 🎯