create-charcole 1.0.0

package/template/package.json

@@ -0,0 +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"
+  }
+}

package/template/src/app.js

@@ -0,0 +1,75 @@
+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/src/config/constants.js

@@ -0,0 +1,20 @@
+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/src/config/env.js

@@ -0,0 +1,26 @@
+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/src/middlewares/errorHandler.js

@@ -0,0 +1,180 @@
+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/src/middlewares/requestLogger.js

@@ -0,0 +1,33 @@
+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/src/middlewares/validateRequest.js

@@ -0,0 +1,42 @@
+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);
+    }
+  };
+};

package/template/src/modules/health/controller.js

@@ -0,0 +1,50 @@
+import { z } from "zod";
+import { sendSuccess } from "../../utils/response.js";
+import { asyncHandler } from "../../middlewares/errorHandler.js";
+
+/**
+ * Health check endpoint
+ * Always returns healthy status (ping endpoint)
+ */
+export const getHealth = asyncHandler(async (req, res) => {
+  sendSuccess(
+    res,
+    {
+      status: "healthy",
+      uptime: process.uptime(),
+      timestamp: new Date().toISOString(),
+    },
+    200,
+    "Service is healthy",
+  );
+});
+
+/**
+ * Example POST endpoint with validation
+ * Demonstrates proper error handling with Zod validation
+ */
+export const createItemSchema = z.object({
+  body: z.object({
+    name: z.string().min(1, "Name is required").max(100),
+    description: z.string().optional(),
+  }),
+});
+
+export const createItem = asyncHandler(async (req, res) => {
+  const { name, description } = req.validatedData.body;
+
+  // Simulate some async work
+  await new Promise((resolve) => setTimeout(resolve, 10));
+
+  sendSuccess(
+    res,
+    {
+      id: Math.random().toString(36).substr(2, 9),
+      name,
+      description: description || null,
+      createdAt: new Date().toISOString(),
+    },
+    201,
+    "Item created successfully",
+  );
+});

package/template/src/routes.js

@@ -0,0 +1,17 @@
+import { Router } from "express";
+import {
+  getHealth,
+  createItem,
+  createItemSchema,
+} from "./modules/health/controller.js";
+import { validateRequest } from "./middlewares/validateRequest.js";
+
+const router = Router();
+
+// Health check
+router.get("/health", getHealth);
+
+// Example: Create item with validation
+router.post("/items", validateRequest(createItemSchema), createItem);
+
+export default router;

package/template/src/server.js

@@ -0,0 +1,38 @@
+import "dotenv/config";
+
+import { app } from "./app.js";
+import { env } from "./config/env.js";
+import { logger } from "./utils/logger.js";
+
+const PORT = env.PORT;
+
+const server = app.listen(PORT, () => {
+  logger.info(`🔥 Server running in ${env.NODE_ENV} mode`, {
+    url: `http://localhost:${PORT}`,
+    port: PORT,
+  });
+});
+
+// Graceful shutdown
+const gracefulShutdown = (signal) => {
+  logger.warn(`${signal} signal received: closing HTTP server`);
+  server.close(() => {
+    logger.info("HTTP server closed");
+    process.exit(0);
+  });
+};
+
+process.on("SIGTERM", () => gracefulShutdown("SIGTERM"));
+process.on("SIGINT", () => gracefulShutdown("SIGINT"));
+
+// Unhandled promise rejections
+process.on("unhandledRejection", (reason, promise) => {
+  logger.error("Unhandled Rejection at:", { promise, reason });
+  process.exit(1);
+});
+
+// Uncaught exceptions
+process.on("uncaughtException", (error) => {
+  logger.error("Uncaught Exception:", { error: error.message });
+  process.exit(1);
+});

package/template/src/utils/AppError.js

@@ -0,0 +1,182 @@
+/**
+ * Operational Error Class
+ *
+ * Use for expected errors that can be handled gracefully
+ * Examples: validation errors, resource not found, auth failures
+ *
+ * These errors are logged and sent back to client as JSON
+ */
+export class AppError extends Error {
+  constructor(
+    message,
+    statusCode = 500,
+    { isOperational = true, code = null, context = null, cause = null } = {},
+  ) {
+    super(message);
+
+    // Operational or Programmer error
+    this.isOperational = isOperational;
+
+    // HTTP status code
+    this.statusCode = statusCode;
+
+    // Error code for client handling (e.g., 'INVALID_EMAIL', 'USER_NOT_FOUND')
+    this.code = code;
+
+    // Additional context data
+    this.context = context || {};
+
+    // Original error that caused this
+    this.cause = cause;
+
+    // Timestamp
+    this.timestamp = new Date().toISOString();
+
+    // Preserve stack trace
+    Error.captureStackTrace(this, this.constructor);
+  }
+
+  /**
+   * Convert to JSON response format
+   */
+  toJSON() {
+    return {
+      success: false,
+      message: this.message,
+      code: this.code,
+      statusCode: this.statusCode,
+      ...(Object.keys(this.context).length > 0 && { context: this.context }),
+      timestamp: this.timestamp,
+    };
+  }
+
+  /**
+   * Get full error details for logging
+   */
+  getFullDetails() {
+    return {
+      message: this.message,
+      statusCode: this.statusCode,
+      code: this.code,
+      isOperational: this.isOperational,
+      context: this.context,
+      cause: this.cause?.message || null,
+      stack: this.stack,
+      timestamp: this.timestamp,
+    };
+  }
+}
+
+/**
+ * Validation Error - extends AppError
+ * Use for input validation failures
+ */
+export class ValidationError extends AppError {
+  constructor(message, errors = [], context = null) {
+    super(message, 422, {
+      isOperational: true,
+      code: "VALIDATION_ERROR",
+      context,
+    });
+    this.errors = errors;
+    this.name = "ValidationError";
+  }
+
+  toJSON() {
+    return {
+      ...super.toJSON(),
+      errors: this.errors,
+    };
+  }
+}
+
+/**
+ * Authentication Error
+ * Use for auth/permission failures
+ */
+export class AuthenticationError extends AppError {
+  constructor(message = "Unauthorized", context = null) {
+    super(message, 401, {
+      isOperational: true,
+      code: "AUTHENTICATION_ERROR",
+      context,
+    });
+    this.name = "AuthenticationError";
+  }
+}
+
+/**
+ * Authorization Error
+ * Use for permission denied scenarios
+ */
+export class AuthorizationError extends AppError {
+  constructor(message = "Forbidden", context = null) {
+    super(message, 403, {
+      isOperational: true,
+      code: "AUTHORIZATION_ERROR",
+      context,
+    });
+    this.name = "AuthorizationError";
+  }
+}
+
+/**
+ * Not Found Error
+ * Use when resource doesn't exist
+ */
+export class NotFoundError extends AppError {
+  constructor(resource = "Resource", context = null) {
+    super(`${resource} not found`, 404, {
+      isOperational: true,
+      code: "NOT_FOUND",
+      context,
+    });
+    this.name = "NotFoundError";
+  }
+}
+
+/**
+ * Conflict Error
+ * Use for duplicate resources, business logic conflicts
+ */
+export class ConflictError extends AppError {
+  constructor(message, context = null) {
+    super(message, 409, {
+      isOperational: true,
+      code: "CONFLICT",
+      context,
+    });
+    this.name = "ConflictError";
+  }
+}
+
+/**
+ * Bad Request Error
+ * Use for malformed requests
+ */
+export class BadRequestError extends AppError {
+  constructor(message, context = null) {
+    super(message, 400, {
+      isOperational: true,
+      code: "BAD_REQUEST",
+      context,
+    });
+    this.name = "BadRequestError";
+  }
+}
+
+/**
+ * Internal Server Error
+ * Use for unexpected server-side errors (programmer errors)
+ */
+export class InternalServerError extends AppError {
+  constructor(message = "Internal server error", cause = null, context = null) {
+    super(message, 500, {
+      isOperational: false,
+      code: "INTERNAL_SERVER_ERROR",
+      cause,
+      context,
+    });
+    this.name = "InternalServerError";
+  }
+}