create-charcole 1.1.0 → 2.0.1

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

@@ -0,0 +1,38 @@
+import { Request, Response, NextFunction } from "express";
+import { logger } from "../utils/logger.js";
+
+/**
+ * Request logging middleware
+ * Logs all HTTP requests with method, path, status, duration, and IP
+ */
+export const requestLogger = (
+  req: Request,
+  res: Response,
+  next: NextFunction,
+): void => {
+  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") || undefined,
+      ...(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

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

@@ -0,0 +1,46 @@
+import { Request, Response, NextFunction } from "express";
+import { z, ZodError } from "zod";
+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: z.AnyZodObject) => {
+  return async (
+    req: Request,
+    res: Response,
+    next: NextFunction,
+  ): Promise<void> => {
+    try {
+      const validated = await schema.parseAsync({
+        body: req.body,
+        query: req.query,
+        params: req.params,
+      });
+
+      req.validatedData = validated;
+      next();
+    } catch (error) {
+      if (error instanceof 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/ts/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/ts/src/modules/health/controller.ts

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

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

@@ -0,0 +1,16 @@
+import { Router } from "express";
+
+import {
+  getHealth,
+  createItem,
+  createItemSchema,
+} from "./modules/health/controller.js";
+import { validateRequest } from "./middlewares/validateRequest.js";
+
+const router = Router();
+
+router.get("/health", getHealth);
+
+router.post("/items", validateRequest(createItemSchema), createItem);
+
+export default router;

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

@@ -0,0 +1,42 @@
+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,
+  });
+});
+
+const gracefulShutdown = (signal: string): void => {
+  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"));
+
+process.on(
+  "unhandledRejection",
+  (reason: unknown, promise: Promise<unknown>) => {
+    logger.error("Unhandled Rejection at:", { promise, reason });
+    process.exit(1);
+  },
+);
+
+process.on("uncaughtException", (error: Error) => {
+  logger.error("Uncaught Exception:", {
+    message: error.message,
+    stack: error.stack,
+  });
+  process.exit(1);
+});

package/template/ts/src/types/express.d.ts

@@ -0,0 +1,9 @@
+import { Request } from "express";
+
+declare global {
+  namespace Express {
+    interface Request {
+      validatedData?: Record<string, any>;
+    }
+  }
+}

package/template/ts/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";
+  }
+}