create-charcole 1.0.0 → 2.0.1

package/template/ts/package.json

@@ -0,0 +1,32 @@
+{
+  "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": {
+    "@types/express": "^5.0.6",
+    "@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

@@ -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/ts/src/app.ts

@@ -0,0 +1,66 @@
+import express, { Request, Response, NextFunction } from "express";
+import cors from "cors";
+
+import { env } from "./config/env.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();
+
+app.set("trust proxy", 1);
+
+app.use(
+  cors({
+    origin: env.CORS_ORIGIN,
+    credentials: true,
+    methods: ["GET", "POST", "PUT", "DELETE", "PATCH", "OPTIONS"],
+    allowedHeaders: ["Content-Type", "Authorization"],
+  }),
+);
+
+app.use(express.json({ limit: "10mb" }));
+app.use(express.urlencoded({ extended: true, limit: "10mb" }));
+
+app.use((req: Request, res: Response, next: NextFunction) => {
+  req.setTimeout(env.REQUEST_TIMEOUT);
+  res.setTimeout(env.REQUEST_TIMEOUT);
+  next();
+});
+
+app.use(requestLogger);
+
+app.use("/api", routes);
+
+app.get(
+  "/",
+  asyncHandler(async (_req: Request, res: Response) => {
+    sendSuccess(
+      res,
+      {
+        message: "Welcome to Charcole API",
+        version: "2.0.0",
+        environment: env.NODE_ENV,
+      },
+      200,
+      "API is online",
+    );
+  }),
+);
+
+app.use((req: Request) => {
+  throw new NotFoundError(`${req.method} ${req.path}`, {
+    method: req.method,
+    path: req.path,
+  });
+});
+
+app.use(errorHandler);
+
+logger.info("Express app configured successfully");

package/template/ts/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/ts/src/config/constants.ts

@@ -0,0 +1,27 @@
+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,
+} as const;
+
+export type HttpStatus = typeof HTTP_STATUS;
+
+export const ERROR_MESSAGES = {
+  VALIDATION_ERROR: "Validation failed",
+  NOT_FOUND: "Resource not found",
+  UNAUTHORIZED: "Unauthorized",
+  SERVER_ERROR: "Internal server error",
+  BAD_REQUEST: "Bad request",
+} as const;
+
+export type ErrorMessages = typeof ERROR_MESSAGES;
+
+export type HttpStatusCode = (typeof HTTP_STATUS)[keyof typeof HTTP_STATUS];
+export type ErrorMessage = (typeof ERROR_MESSAGES)[keyof typeof ERROR_MESSAGES];

package/template/ts/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/ts/src/config/env.ts

@@ -0,0 +1,40 @@
+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),
+});
+
+type EnvSchema = z.infer<typeof envSchema>;
+
+const parseEnv = (): EnvSchema => {
+  try {
+    return envSchema.parse(process.env);
+  } catch (error) {
+    if (error instanceof z.ZodError) {
+      console.error("❌ Invalid environment variables:");
+      error.errors.forEach((err) => {
+        console.error(`  - ${err.path.join(".")}: ${err.message}`);
+      });
+    } else {
+      console.error("❌ Failed to parse environment variables:", error);
+    }
+    process.exit(1);
+  }
+};
+
+const parsedEnv = parseEnv();
+
+export const env = {
+  ...parsedEnv,
+  isDevelopment: parsedEnv.NODE_ENV === "development",
+  isProduction: parsedEnv.NODE_ENV === "production",
+  isTest: parsedEnv.NODE_ENV === "test",
+} as const;
+
+export type Env = typeof env;

package/template/ts/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/ts/src/middlewares/errorHandler.ts

@@ -0,0 +1,209 @@
+import { ZodError } from "zod";
+import { HTTP_STATUS, ERROR_MESSAGES } from "../config/constants.js";
+import { logger } from "../utils/logger.js";
+import {
+  AppError,
+  ValidationError,
+  InternalServerError,
+  AuthenticationError,
+  AuthorizationError,
+  NotFoundError,
+  ConflictError,
+  BadRequestError,
+} from "../utils/AppError.js";
+import { env } from "../config/env.js";
+import { Request, Response, NextFunction, RequestHandler } from "express";
+
+const normalizeError = (err: unknown): AppError => {
+  if (err instanceof AppError) {
+    return err;
+  }
+
+  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);
+  }
+
+  if (err instanceof Error) {
+    if (err instanceof SyntaxError) {
+      return new InternalServerError("Syntax error in application code", err, {
+        type: "SyntaxError",
+      });
+    }
+
+    if (err instanceof TypeError) {
+      return new InternalServerError("Type error in application", err, {
+        type: "TypeError",
+      });
+    }
+
+    if (err instanceof ReferenceError) {
+      return new InternalServerError("Reference error in application", err, {
+        type: "ReferenceError",
+      });
+    }
+
+    if (err instanceof RangeError) {
+      return new InternalServerError("Range error in application", err, {
+        type: "RangeError",
+      });
+    }
+
+    return new InternalServerError(
+      err.message || ERROR_MESSAGES.SERVER_ERROR,
+      err,
+      { type: "UnknownError" },
+    );
+  }
+
+  const errorMessage =
+    typeof err === "string"
+      ? err
+      : err &&
+          typeof err === "object" &&
+          "message" in err &&
+          typeof err.message === "string"
+        ? err.message
+        : ERROR_MESSAGES.SERVER_ERROR;
+
+  return new InternalServerError(
+    errorMessage,
+    err instanceof Error ? err : new Error(String(err)),
+    { type: "UnknownError" },
+  );
+};
+
+const logError = (appError: AppError, req: Request): void => {
+  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"),
+  };
+
+  if (appError.isOperational) {
+    logger.warn(`Operational Error: ${appError.code}`, errorDetails);
+  } else {
+    logger.error(
+      `Programmer Error: ${appError.code}`,
+      errorDetails,
+      appError.stack,
+    );
+  }
+
+  if (
+    appError instanceof ValidationError &&
+    (appError as ValidationError).errors
+  ) {
+    const validationError = appError as ValidationError;
+    logger.debug("Validation errors", { errors: validationError.errors });
+  }
+
+  if (appError.cause) {
+    const causeMessage =
+      appError.cause instanceof Error
+        ? appError.cause.message
+        : String(appError.cause);
+    logger.debug("Error cause", { cause: causeMessage });
+  }
+};
+
+const sendErrorResponse = (res: Response, appError: AppError): void => {
+  const statusCode = appError.statusCode || HTTP_STATUS.INTERNAL_SERVER_ERROR;
+
+  if (!appError.isOperational && env.isProduction) {
+    res.status(statusCode).json({
+      success: false,
+      message: ERROR_MESSAGES.SERVER_ERROR,
+      code: "INTERNAL_SERVER_ERROR",
+      timestamp: new Date().toISOString(),
+    });
+    return;
+  }
+
+  const response =
+    (appError as any).toJSON && typeof (appError as any).toJSON === "function"
+      ? (appError as any).toJSON()
+      : {
+          success: false,
+          message: appError.message,
+          code: appError.code,
+          statusCode,
+          timestamp: new Date().toISOString(),
+        };
+
+  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: unknown,
+  req: Request,
+  res: Response,
+  next: NextFunction,
+): void => {
+  const appError = normalizeError(err);
+
+  logError(appError, req);
+
+  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: RequestHandler): RequestHandler => {
+  return (req: Request, res: Response, next: NextFunction): any => {
+    try {
+      const result = fn(req, res, next);
+
+      if (
+        result &&
+        typeof result === "object" &&
+        "then" in result &&
+        typeof result.then === "function"
+      ) {
+        return (result as Promise<any>).catch(next);
+      }
+
+      return result;
+    } catch (err) {
+      return next(err);
+    }
+  };
+};
+
+export {
+  AppError,
+  ValidationError,
+  InternalServerError,
+  AuthenticationError,
+  AuthorizationError,
+  NotFoundError,
+  ConflictError,
+  BadRequestError,
+};