create-charcole 2.0.4 → 2.1.0

package/template/ts/QUICK_REFERENCE.md

@@ -1,270 +0,0 @@
-# Production-Level Error Handling System - Quick Reference
-
-## 🎯 Problem Solved
-
-❌ **Before:** Random `res.status(500).json(...)` scattered throughout code  
-✅ **After:** Single centralized error handler with distinguished error types
-
-## 🏗️ System Architecture
-
-```
-Every Request
-    ↓
-Route Handler (wrapped with asyncHandler)
-    ↓
-    ├─→ Success? → sendSuccess(res, data)
-    │
-    └─→ Error thrown ✘
-        ↓
-    Global Error Handler
-        ↓
-    Normalize Error
-    ├─→ Is it AppError? Use it
-    ├─→ Is it ZodError? Convert to ValidationError
-    ├─→ Is it TypeError/ReferenceError/etc? Convert to InternalServerError
-        ↓
-    Classify Error
-    ├─→ Operational? (isOperational: true)
-    │   ├─ Log as WARN with context
-    │   └─ Send full details to client
-    │
-    └─→ Programmer Error? (isOperational: false)
-        ├─ Log as ERROR with stack trace
-        └─ Send generic message in production
-        ↓
-    Send Consistent JSON Response
-```
-
-## 📦 Error Classes (Use These!)
-
-```javascript
-import {
-  AppError, // Base class
-  ValidationError, // Input validation failed
-  AuthenticationError, // Auth failed (401)
-  AuthorizationError, // Permission denied (403)
-  NotFoundError, // Resource not found (404)
-  ConflictError, // Duplicate/conflict (409)
-  BadRequestError, // Malformed request (400)
-  InternalServerError, // Unexpected error (500)
-} from "./middlewares/errorHandler.js";
-```
-
-## 🎬 Quick Start
-
-### 1. Throw Operational Errors
-
-```javascript
-// Validation
-throw new ValidationError("Invalid input", [
-  { field: "email", message: "Invalid email", code: "invalid_email" },
-]);
-
-// Not found
-throw new NotFoundError("User", { id: userId });
-
-// Duplicate
-throw new ConflictError("Email already exists", { email });
-
-// Auth
-throw new AuthenticationError("Invalid credentials");
-
-// Permission
-throw new AuthorizationError("Access denied");
-
-// Generic operational error
-throw new AppError("Request failed", 400, {
-  isOperational: true,
-  code: "CUSTOM_ERROR",
-  context: { details: "..." },
-});
-```
-
-### 2. Wrap All Async Handlers
-
-```javascript
-import { asyncHandler } from "./middlewares/errorHandler.js";
-
-// ✅ Correct
-router.post(
-  "/users",
-  asyncHandler(async (req, res) => {
-    const user = await User.create(req.body);
-    sendSuccess(res, user, 201);
-  }),
-);
-
-// ❌ Wrong - errors leak!
-router.post("/users", async (req, res) => {
-  const user = await User.create(req.body); // Error not caught!
-  sendSuccess(res, user, 201);
-});
-```
-
-### 3. Use Validation Middleware
-
-```javascript
-import { validateRequest } from "./middlewares/validateRequest.js";
-import { z } from "zod";
-
-const createUserSchema = z.object({
-  body: z.object({
-    email: z.string().email("Invalid email"),
-    name: z.string().min(1, "Name required"),
-  }),
-});
-
-router.post(
-  "/users",
-  validateRequest(createUserSchema),
-  asyncHandler(async (req, res) => {
-    // req.validatedData.body has been validated
-    const user = await User.create(req.validatedData.body);
-    sendSuccess(res, user, 201, "User created");
-  }),
-);
-```
-
-## 📊 Logging Behavior
-
-| Error Type             | Level | Includes Stack | Info Sent to Client    |
-| ---------------------- | ----- | -------------- | ---------------------- |
-| ValidationError        | WARN  | ❌             | ✅ All details         |
-| NotFoundError          | WARN  | ❌             | ✅ All details         |
-| AuthenticationError    | WARN  | ❌             | ✅ All details         |
-| TypeError (programmer) | ERROR | ✅             | ❌ Generic only (prod) |
-| Unhandled (programmer) | FATAL | ✅             | ❌ Generic only (prod) |
-
-## 📋 Response Format
-
-All responses are consistent JSON:
-
-### Success
-
-```json
-{
-  "success": true,
-  "message": "User created successfully",
-  "data": { "id": "123", "name": "John" },
-  "timestamp": "2024-01-19T15:55:30.000Z"
-}
-```
-
-### Operational Error
-
-```json
-{
-  "success": false,
-  "message": "User not found",
-  "code": "NOT_FOUND",
-  "statusCode": 404,
-  "context": { "id": "999" },
-  "timestamp": "2024-01-19T15:55:30.000Z"
-}
-```
-
-### Validation Error
-
-```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"
-}
-```
-
-### Programmer Error (Production)
-
-```json
-{
-  "success": false,
-  "message": "Internal server error",
-  "code": "INTERNAL_SERVER_ERROR",
-  "timestamp": "2024-01-19T15:55:30.000Z"
-}
-```
-
-## 🛡️ Golden Rules
-
-1. **Always use asyncHandler** for async route handlers
-
-   ```javascript
-   router.get("/endpoint", asyncHandler(async (req, res) => { ... }))
-   ```
-
-2. **Never use res.status().json()** for errors - throw AppError instead
-
-   ```javascript
-   // ❌ Wrong
-   res.status(400).json({ error: "..." });
-
-   // ✅ Correct
-   throw new BadRequestError("Invalid input");
-   ```
-
-3. **Validate request early** with validateRequest middleware
-
-   ```javascript
-   router.post("/endpoint", validateRequest(schema), handler);
-   ```
-
-4. **Throw, don't catch** - let global handler catch
-
-   ```javascript
-   // ❌ Wrong
-   try {
-     await someTask();
-   } catch (err) {
-     res.status(500).json(err);
-   }
-
-   // ✅ Correct
-   await someTask(); // Error bubbles up to global handler
-   ```
-
-5. **Include context** when throwing errors
-   ```javascript
-   throw new NotFoundError("User", { id: userId, email: userEmail });
-   ```
-
-## 🚀 Features at a Glance
-
-| Feature                                          | Status |
-| ------------------------------------------------ | ------ |
-| Centralized error handler                        | ✅     |
-| Error classification (operational vs programmer) | ✅     |
-| Validation error formatting                      | ✅     |
-| Async error wrapping                             | ✅     |
-| Stack trace logging                              | ✅     |
-| Production sanitization                          | ✅     |
-| Request logging                                  | ✅     |
-| Graceful shutdown                                | ✅     |
-| Unhandled exception catching                     | ✅     |
-| Consistent JSON responses                        | ✅     |
-
-## 📚 Full Documentation
-
-- **[ERROR_HANDLING.md](ERROR_HANDLING.md)** - Comprehensive guide with examples
-- **[IMPLEMENTATION_COMPLETE.md](IMPLEMENTATION_COMPLETE.md)** - Full implementation details
-
-## 🎓 Key Files
-
-| File                                 | Purpose                             |
-| ------------------------------------ | ----------------------------------- |
-| `src/utils/AppError.js`              | Error class hierarchy               |
-| `src/middlewares/errorHandler.js`    | Global error handler + asyncHandler |
-| `src/middlewares/validateRequest.js` | Zod validation middleware           |
-| `src/middlewares/requestLogger.js`   | Request logging                     |
-| `src/utils/logger.js`                | Structured logging with colors      |
-| `src/utils/response.js`              | Success response helpers            |
-
----
-
-**That's it! Your API now has enterprise-grade error handling.** 🎯
-
-Every error flows through one place. Every response is consistent. Errors are properly classified and logged. You're ready for production. 🚀

package/template/ts/package.json

@@ -1,32 +0,0 @@
-{
-  "name": "charcole",
-  "version": "2.0.4",
-  "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": {
-    "@types/express": "^4.17.21",
-    "@types/node": "^25.0.10",
-    "nodemon": "^3.0.2",
-    "ts-node-dev": "^2.0.0",
-    "typescript": "^5.9.3"
-  }
-}

package/template/ts/src/app.js

@@ -1,75 +0,0 @@
-import express from "express";
-import cors from "cors";
-import { env } from "./config/env.js";
-import { HTTP_STATUS, ERROR_MESSAGES } from "./config/constants.js";
-import { requestLogger } from "./middlewares/requestLogger.js";
-import {
-  errorHandler,
-  asyncHandler,
-  NotFoundError,
-} from "./middlewares/errorHandler.js";
-import { sendSuccess } from "./utils/response.js";
-import { logger } from "./utils/logger.js";
-import routes from "./routes.js";
-
-export const app = express();
-
-// Trust proxy
-app.set("trust proxy", 1);
-
-// CORS Configuration
-app.use(
-  cors({
-    origin: env.CORS_ORIGIN,
-    credentials: true,
-    methods: ["GET", "POST", "PUT", "DELETE", "PATCH", "OPTIONS"],
-    allowedHeaders: ["Content-Type", "Authorization"],
-  }),
-);
-
-// Body parsing middleware
-app.use(express.json({ limit: "10mb" }));
-app.use(express.urlencoded({ extended: true, limit: "10mb" }));
-
-// Request timeout
-app.use((req, res, next) => {
-  req.setTimeout(env.REQUEST_TIMEOUT);
-  res.setTimeout(env.REQUEST_TIMEOUT);
-  next();
-});
-
-// Request logging
-app.use(requestLogger);
-
-// API Routes
-app.use("/api", routes);
-
-// Root health endpoint
-app.get(
-  "/",
-  asyncHandler(async (req, res) => {
-    sendSuccess(
-      res,
-      {
-        message: "Welcome to Charcole API",
-        version: "1.0.0",
-        environment: env.NODE_ENV,
-      },
-      200,
-      "API is online",
-    );
-  }),
-);
-
-// 404 handler
-app.use((req, res, next) => {
-  throw new NotFoundError(`${req.method} ${req.path}`, {
-    method: req.method,
-    path: req.path,
-  });
-});
-
-// Global error handler (MUST be last)
-app.use(errorHandler);
-
-logger.info("Express app configured successfully");

package/template/ts/src/config/constants.js

@@ -1,20 +0,0 @@
-export const HTTP_STATUS = {
-  OK: 200,
-  CREATED: 201,
-  BAD_REQUEST: 400,
-  UNAUTHORIZED: 401,
-  FORBIDDEN: 403,
-  NOT_FOUND: 404,
-  CONFLICT: 409,
-  UNPROCESSABLE_ENTITY: 422,
-  INTERNAL_SERVER_ERROR: 500,
-  SERVICE_UNAVAILABLE: 503,
-};
-
-export const ERROR_MESSAGES = {
-  VALIDATION_ERROR: "Validation failed",
-  NOT_FOUND: "Resource not found",
-  UNAUTHORIZED: "Unauthorized",
-  SERVER_ERROR: "Internal server error",
-  BAD_REQUEST: "Bad request",
-};

package/template/ts/src/config/env.js

@@ -1,26 +0,0 @@
-import { z } from "zod";
-
-const envSchema = z.object({
-  NODE_ENV: z
-    .enum(["development", "production", "test"])
-    .default("development"),
-  PORT: z.coerce.number().default(3000),
-  LOG_LEVEL: z.enum(["debug", "info", "warn", "error"]).default("info"),
-  CORS_ORIGIN: z.string().default("*"),
-  REQUEST_TIMEOUT: z.coerce.number().default(30000),
-});
-
-const parseEnv = () => {
-  try {
-    return envSchema.parse(process.env);
-  } catch (error) {
-    console.error("❌ Invalid environment variables:", error.errors);
-    process.exit(1);
-  }
-};
-
-export const env = parseEnv();
-
-export const isDevelopment = env.NODE_ENV === "development";
-export const isProduction = env.NODE_ENV === "production";
-export const isTest = env.NODE_ENV === "test";

package/template/ts/src/middlewares/errorHandler.js

@@ -1,180 +0,0 @@
-import { ZodError } from "zod";
-import { HTTP_STATUS, ERROR_MESSAGES } from "../config/constants.js";
-import { logger } from "../utils/logger.js";
-import {
-  AppError,
-  ValidationError,
-  InternalServerError,
-} from "../utils/AppError.js";
-import { env } from "../config/env.js";
-
-/**
- * Normalize different error types to AppError
- */
-const normalizeError = (err) => {
-  // Already an AppError
-  if (err instanceof AppError) {
-    return err;
-  }
-
-  // Zod validation error
-  if (err instanceof ZodError) {
-    const errors = err.errors.map((e) => ({
-      field: e.path.join("."),
-      message: e.message,
-      code: e.code,
-    }));
-    return new ValidationError(ERROR_MESSAGES.VALIDATION_ERROR, errors);
-  }
-
-  // Syntax errors (programmer error)
-  if (err instanceof SyntaxError) {
-    return new InternalServerError("Syntax error in application code", err, {
-      type: "SyntaxError",
-    });
-  }
-
-  // Type errors (programmer error)
-  if (err instanceof TypeError) {
-    return new InternalServerError("Type error in application", err, {
-      type: "TypeError",
-    });
-  }
-
-  // Reference errors (programmer error)
-  if (err instanceof ReferenceError) {
-    return new InternalServerError("Reference error in application", err, {
-      type: "ReferenceError",
-    });
-  }
-
-  // Range errors
-  if (err instanceof RangeError) {
-    return new InternalServerError("Range error in application", err, {
-      type: "RangeError",
-    });
-  }
-
-  // Generic error (unknown)
-  return new InternalServerError(
-    err.message || ERROR_MESSAGES.SERVER_ERROR,
-    err,
-    { type: "UnknownError" },
-  );
-};
-
-/**
- * Log error based on type (operational vs programmer)
- */
-const logError = (appError, req) => {
-  const errorDetails = {
-    type: appError.isOperational ? "OPERATIONAL" : "PROGRAMMER",
-    code: appError.code,
-    message: appError.message,
-    statusCode: appError.statusCode,
-    method: req.method,
-    path: req.path,
-    query: req.query,
-    ip: req.ip,
-    userAgent: req.get("user-agent"),
-  };
-
-  // Operational errors: normal logging
-  if (appError.isOperational) {
-    logger.warn(`Operational Error: ${appError.code}`, errorDetails);
-  } else {
-    // Programmer errors: detailed logging with stack
-    logger.error(
-      `Programmer Error: ${appError.code}`,
-      errorDetails,
-      appError.stack,
-    );
-  }
-
-  // Log validation errors separately
-  if (appError instanceof ValidationError && appError.errors) {
-    logger.debug("Validation errors", { errors: appError.errors });
-  }
-
-  // Log cause if present
-  if (appError.cause) {
-    logger.debug("Error cause", { cause: appError.cause.message });
-  }
-};
-
-/**
- * Send error response
- */
-const sendErrorResponse = (res, appError) => {
-  const statusCode = appError.statusCode || HTTP_STATUS.INTERNAL_SERVER_ERROR;
-
-  // In production, hide internal details for programmer errors
-  if (!appError.isOperational && env.isProduction) {
-    return res.status(statusCode).json({
-      success: false,
-      message: ERROR_MESSAGES.SERVER_ERROR,
-      code: "INTERNAL_SERVER_ERROR",
-      timestamp: new Date().toISOString(),
-    });
-  }
-
-  // Return detailed error in development
-  const response = appError.toJSON
-    ? appError.toJSON()
-    : {
-        success: false,
-        message: appError.message,
-        code: appError.code,
-        statusCode,
-        timestamp: new Date().toISOString(),
-      };
-
-  return res.status(statusCode).json(response);
-};
-
-/**
- * Global Error Handler Middleware
- *
- * This middleware catches all errors and provides a unified way to handle them.
- * MUST be the last middleware in the app.
- *
- * Features:
- * - Distinguishes between operational and programmer errors
- * - Logs errors with full context
- * - Hides sensitive info in production
- * - Formats JSON responses consistently
- */
-export const errorHandler = (err, req, res, next) => {
-  // Normalize the error
-  const appError = normalizeError(err);
-
-  // Log the error
-  logError(appError, req);
-
-  // Send response
-  sendErrorResponse(res, appError);
-};
-
-/**
- * Async error wrapper
- * Wrap async route handlers to catch errors and pass to middleware
- *
- * Example:
- * router.get('/users/:id', asyncHandler(getUserHandler))
- */
-export const asyncHandler = (fn) => {
-  return (req, res, next) => {
-    return Promise.resolve(fn(req, res, next)).catch(next);
-  };
-};
-
-export {
-  AppError,
-  ValidationError,
-  InternalServerError,
-  AuthenticationError,
-  AuthorizationError,
-  NotFoundError,
-  ConflictError,
-  BadRequestError,
-} from "../utils/AppError.js";

package/template/ts/src/middlewares/requestLogger.js

@@ -1,33 +0,0 @@
-import { logger } from "../utils/logger.js";
-
-/**
- * Request logging middleware
- * Logs all HTTP requests with method, path, status, duration, and IP
- */
-export const requestLogger = (req, res, next) => {
-  const start = Date.now();
-
-  res.on("finish", () => {
-    const duration = Date.now() - start;
-    const statusCode = res.statusCode;
-    const isError = statusCode >= 400;
-
-    const logData = {
-      method: req.method,
-      path: req.path,
-      statusCode,
-      durationMs: duration,
-      ip: req.ip,
-      userAgent: req.get("user-agent"),
-      ...(isError && { error: true }),
-    };
-
-    if (isError) {
-      logger.warn(`${req.method} ${req.path}`, logData);
-    } else {
-      logger.debug(`${req.method} ${req.path}`, logData);
-    }
-  });
-
-  next();
-};

package/template/ts/src/middlewares/validateRequest.js

@@ -1,42 +0,0 @@
-import { ValidationError } from "../utils/AppError.js";
-
-/**
- * Request validation middleware
- *
- * Validates request body, query, and params against a Zod schema
- * Throws ValidationError if validation fails
- *
- * Example:
- * const schema = z.object({
- *   body: z.object({ name: z.string() }),
- *   query: z.object({ page: z.coerce.number().optional() }),
- * });
- *
- * router.post('/items', validateRequest(schema), handler)
- */
-export const validateRequest = (schema) => {
-  return async (req, res, next) => {
-    try {
-      // Validate request
-      const validated = await schema.parseAsync({
-        body: req.body,
-        query: req.query,
-        params: req.params,
-      });
-
-      // Attach validated data
-      req.validatedData = validated;
-      next();
-    } catch (error) {
-      if (error.name === "ZodError") {
-        const errors = error.errors.map((e) => ({
-          field: e.path.join("."),
-          message: e.message,
-          code: e.code,
-        }));
-        throw new ValidationError("Request validation failed", errors);
-      }
-      next(error);
-    }
-  };
-};