@ifecodes/backend-template 1.1.8 → 1.4.0

package/template/base/ts/src/app.ts

@@ -1,15 +1,20 @@
-import express from "express";
-import router from "./routes";
-/*__IMPORTS__*/
-
-const app = express();
-
-// Parse JSON request bodies
-app.use(express.json());
-
-/*__MIDDLEWARE__*/
-
-// Connect routes
-app.use(router);
-
-export default app;
+import express from "express";
+import router from "./routes";
+import { errorHandler, observabilityMiddleware } from "@/middlewares";
+/*__IMPORTS__*/
+
+const app = express();
+
+// Parse JSON request bodies
+app.use(express.json());
+
+app.use(observabilityMiddleware);
+
+/*__MIDDLEWARE__*/
+
+// Connect routes
+app.use(router);
+
+app.use(errorHandler);
+
+export default app;

package/template/base/ts/src/config/db.ts

@@ -1,4 +1,4 @@
-// MongoDB connection will be added here when authentication is enabled
-export const connectDB = async () => {
-  // Database connection placeholder
-};
+// MongoDB connection will be added here when authentication is enabled
+export const connectDB = async () => {
+  // Database connection placeholder
+};

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

@@ -1,10 +1,40 @@
-import dotenv from "dotenv";
-dotenv.config();
-
-export const ENV = {
-  PORT: process.env.PORT!,
-  /*__ALLOWED_ORIGIN__*/
-  NODE_ENV: process.env.NODE_ENV!,
-  /*__MONGO_URI__*/
-  /*__JWT_SECRET__*/
-};
+import dotenv from "dotenv";
+dotenv.config();
+
+const colors = {
+  reset: "\x1b[0m",
+  red: "\x1b[31m",
+  bold: "\x1b[1m",
+};
+
+function format(tag: string, color: string) {
+  return `${color}${colors.bold}[${tag}]${colors.reset}`;
+}
+
+const validateEnv = (env: Record<string, string | undefined>) => {
+  const missing = Object.entries(env)
+    .filter(([, value]) => value === undefined || value === "")
+    .map(([key]) => key);
+
+  if (missing.length > 0) {
+    console.error(
+      format("env", colors.red),
+      `Missing required environment variables: ${missing.join(", ")}`,
+    );
+    console.error(
+      format("env", colors.red),
+      "Please update your .env file and restart the server.",
+    );
+    process.exit(1);
+  }
+};
+
+export const ENV = {
+  PORT: process.env.PORT!,
+  /*__ALLOWED_ORIGIN__*/
+  NODE_ENV: process.env.NODE_ENV!,
+  /*__MONGO_URI__*/
+  /*__JWT_SECRET__*/
+};
+
+validateEnv(ENV);

package/template/base/ts/src/config/index.ts

@@ -1,2 +1,2 @@
-export { connectDB } from "./db";
-export { ENV } from "./env";
+export { connectDB } from "./db";
+export { ENV } from "./env";

package/template/base/ts/src/docs/index.ts

@@ -0,0 +1,3 @@
+import { routeRegistry } from "./route-registry";
+
+export { routeRegistry };

package/template/base/ts/src/docs/route-registry.ts

@@ -0,0 +1,98 @@
+import { RequestHandler } from "express";
+
+export interface RouteDoc {
+  tags?: string[];
+  summary: string;
+  description?: string;
+  parameters?: Array<{
+    name: string;
+    in: "query" | "path" | "header" | "cookie";
+    required?: boolean;
+    schema: Record<string, unknown>;
+    description?: string;
+  }>;
+  requestBody?: {
+    required?: boolean;
+    content: {
+      "application/json": {
+        schema: Record<string, unknown>;
+      };
+    };
+  };
+  responses: Record<
+    number | string,
+    {
+      description: string;
+      content?: {
+        "application/json": {
+          schema?: Record<string, unknown>;
+        };
+      };
+    }
+  >;
+}
+
+export interface RouteSchema {
+  method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS";
+  path: string;
+  handler: RequestHandler | RequestHandler[];
+  docs: RouteDoc;
+}
+
+class RouteRegistry {
+  private routes: RouteSchema[] = [];
+
+  register(route: RouteSchema): void {
+    this.routes.push(route);
+  }
+
+  getRoutes(): RouteSchema[] {
+    return this.routes;
+  }
+
+  generateOpenAPI(projectName: string, version = "1.0.0"): Record<string, unknown> {
+    const paths: Record<string, unknown> = {};
+    const tags = new Set<string>();
+
+    // Collect all unique tags
+    this.routes.forEach((route) => {
+      route.docs.tags?.forEach((tag) => tags.add(tag));
+    });
+
+    // Build paths from routes
+    this.routes.forEach((route) => {
+      if (!paths[route.path]) {
+        paths[route.path] = {};
+      }
+
+      const pathItem = paths[route.path] as Record<string, unknown>;
+      const method = route.method.toLowerCase();
+
+      pathItem[method] = {
+        tags: route.docs.tags || [],
+        summary: route.docs.summary,
+        description: route.docs.description,
+        parameters: route.docs.parameters || [],
+        requestBody: route.docs.requestBody,
+        responses: route.docs.responses,
+      };
+    });
+
+    return {
+      openapi: "3.0.3",
+      info: {
+        title: `${projectName} API`,
+        version,
+        description: "Auto-generated from route schemas.",
+      },
+      servers: [{ url: "http://localhost:4000" }],
+      tags: Array.from(tags).map((tag) => ({
+        name: tag,
+        description: `${tag} endpoints`,
+      })),
+      paths,
+    };
+  }
+}
+
+export const routeRegistry = new RouteRegistry();

package/template/base/ts/src/middlewares/error-handler.middleware.ts

@@ -0,0 +1,26 @@
+import { NextFunction, Request, Response } from "express";
+import { HttpError, logger } from "@/utils";
+
+// Centralized error handling middleware
+
+export const errorHandler = (
+  err: unknown,
+  _: Request,
+  res: Response,
+  __: NextFunction,
+) => {
+  if (err instanceof HttpError) {
+    logger.warn("ErrorHandler", `${err.status} ${err.message}`);
+    return res.status(err.status).json({
+      status: "error",
+      message: err.message,
+    });
+  }
+
+  logger.error("ErrorHandler", "Unhandled error", err as Error);
+
+  return res.status(500).json({
+    status: "error",
+    message: "Internal Server Error",
+  });
+};

package/template/base/ts/src/middlewares/index.ts

@@ -1,3 +1,6 @@
-export { default as methodNotAllowedHandler } from "./method-not-allowed.middleware";
-export { notFound } from "./not-found.middleware";
-export { rootHandler } from "./root.middleware";
+export { default as methodNotAllowedHandler } from "./method-not-allowed.middleware";
+export { notFound } from "./not-found.middleware";
+export { rootHandler } from "./root.middleware";
+export { errorHandler } from "./error-handler.middleware";
+export { observabilityMiddleware } from "./observability.middleware";
+export { validateRequest } from "./validation.middleware";

package/template/base/ts/src/middlewares/method-not-allowed.middleware.ts

@@ -1,16 +1,23 @@
-import { Request, Response, NextFunction } from "express";
-
-const methodNotAllowed =
-  (allowedMethods: string[]) => (req: Request, res: Response, next: NextFunction) => {
-    if (!allowedMethods.includes(req.method)) {
-      res.set("Allow", allowedMethods.join(", "));
-      return res.status(405).json({
-        status: "error",
-        message: `Method ${req.method} not allowed for ${req.originalUrl}`,
-        allowed: allowedMethods,
-      });
-    }
-    next();
-  };
-
-export default methodNotAllowed;
+import { Request, Response, NextFunction } from "express";
+import { logger } from "@/utils";
+
+// Middleware to handle 405 Method Not Allowed for unsupported HTTP methods on defined routes
+
+const methodNotAllowed =
+  (allowedMethods: string[]) => (req: Request, res: Response, next: NextFunction) => {
+    if (!allowedMethods.includes(req.method)) {
+      logger.warn(
+        "MethodNotAllowed",
+        `${req.method} ${req.originalUrl} | allowed: ${allowedMethods.join(", ")}`,
+      );
+      res.set("Allow", allowedMethods.join(", "));
+      return res.status(405).json({
+        status: "error",
+        message: `Method ${req.method} not allowed for ${req.originalUrl}`,
+        allowed: allowedMethods,
+      });
+    }
+    next();
+  };
+
+export default methodNotAllowed;

package/template/base/ts/src/middlewares/not-found.middleware.ts

@@ -1,8 +1,10 @@
-import { Request, Response } from "express";
-
-export const notFound = (req: Request, res: Response) => {
-  res.status(404).json({
-    status: "error",
-    message: `Route ${req.originalUrl} not found`,
-  });
-};
+import { Request, Response } from "express";
+import { logger } from "@/utils";
+
+export const notFound = (req: Request, res: Response) => {
+  logger.warn("NotFound", `${req.method} ${req.originalUrl}`);
+  res.status(404).json({
+    status: "error",
+    message: `Route ${req.originalUrl} not found`,
+  });
+};

package/template/base/ts/src/middlewares/observability.middleware.ts

@@ -0,0 +1,25 @@
+import { randomUUID } from "crypto";
+import { NextFunction, Request, Response } from "express";
+import { logger } from "@/utils";
+
+export const observabilityMiddleware = (
+  req: Request,
+  res: Response,
+  next: NextFunction,
+) => {
+  const requestId = req.get("X-Request-Id") || randomUUID();
+  const startedAt = Date.now();
+
+  res.locals.requestId = requestId;
+  res.setHeader("X-Request-Id", requestId);
+
+  res.on("finish", () => {
+    const duration = Date.now() - startedAt;
+    logger.info(
+      "HTTP",
+      `${requestId} ${req.method} ${req.originalUrl} -> ${res.statusCode} (${duration}ms)`,
+    );
+  });
+
+  next();
+};

package/template/base/ts/src/middlewares/root.middleware.ts

@@ -1,14 +1,16 @@
-import { Request, Response } from "express";
-
-export const rootHandler = (_req: Request, res: Response) => {
-  res.json({
-    name: "/*__PROJECT_NAME__*/",
-    type: "/*__PROJECT_TYPE__*/",
-    version: "1.0.0",
-    status: "running",
-    endpoints: {
-      health: "/api/v1/health",
-      /*__AUTH_ENDPOINT__*/
-    },
-  });
-};
+import { Request, Response } from "express";
+
+export const rootHandler = (_req: Request, res: Response) => {
+  res.json({
+    name: "/*__PROJECT_NAME__*/",
+    type: "/*__PROJECT_TYPE__*/",
+    version: "1.0.0",
+    status: "running",
+    endpoints: {
+      root: "/",
+      health: "/api/v1/health",
+      docs: "/api-docs",
+      /*__AUTH_ENDPOINT__*/
+    },
+  });
+};

package/template/base/ts/src/middlewares/validation.middleware.ts

@@ -0,0 +1,46 @@
+import { NextFunction, Request, Response } from "express";
+import { BadRequestError } from "@/utils";
+
+type RequestSchemas = {
+  body?: { parse: (value: unknown) => unknown };
+  query?: { parse: (value: unknown) => unknown };
+  params?: { parse: (value: unknown) => unknown };
+};
+
+const isValidationError = (error: unknown): error is { issues: Array<{ path?: Array<string | number>; message: string }> } => {
+  return (
+    typeof error === "object" &&
+    error !== null &&
+    "issues" in error &&
+    Array.isArray((error as { issues?: unknown }).issues)
+  );
+};
+
+export const validateRequest = (schemas: RequestSchemas) => {
+  return (req: Request, _: Response, next: NextFunction) => {
+    try {
+      if (schemas.body) {
+        req.body = schemas.body.parse(req.body);
+      }
+
+      if (schemas.query) {
+        req.query = schemas.query.parse(req.query) as Request["query"];
+      }
+
+      if (schemas.params) {
+        req.params = schemas.params.parse(req.params) as Request["params"];
+      }
+
+      next();
+    } catch (error: unknown) {
+      if (isValidationError(error)) {
+        const issues = error.issues
+          .map((issue) => `${issue.path?.join(".") || "request"}: ${issue.message}`)
+          .join("; ");
+        return next(new BadRequestError(`Request validation failed - ${issues}`));
+      }
+
+      return next(error);
+    }
+  };
+};

package/template/base/ts/src/modules/index.ts

@@ -1,8 +1,8 @@
-import { Router } from "express";
-import V1Routes from "./v1";
-
-const router = Router();
-
-router.use("/v1", V1Routes);
-
-export default router;
+import { Router } from "express";
+import V1Routes from "./v1";
+
+const router = Router();
+
+router.use("/v1", V1Routes);
+
+export default router;

package/template/base/ts/src/modules/v1/health/health.controller.auth.ts

@@ -0,0 +1,26 @@
+import { Request, Response } from "express";
+import mongoose from "mongoose";
+import { logger } from "@/utils";
+
+export const healthCheck = async (_: Request, res: Response) => {
+  const mongoState = mongoose.connection.readyState;
+
+  const healthy = mongoState === 1;
+
+  const failed: string[] = [];
+  if (mongoState !== 1) failed.push("mongodb");
+
+  return res.status(healthy ? 200 : 503).json({
+    status: healthy ? "healthy" : "unhealthy",
+    uptime: process.uptime(),
+    timestamp: new Date().toISOString(),
+    services: {
+      mongodb: mongoState === 1 ? "connected" : "disconnected",
+      memory: {
+        rss: process.memoryUsage().rss,
+        heapUsed: process.memoryUsage().heapUsed,
+      },
+    },
+    failed,
+  });
+};

package/template/base/ts/src/modules/v1/health/health.controller.ts

@@ -1,18 +1,18 @@
-import { Request, Response } from "express";
-import { logger } from "@/utils";
-
-export const healthCheck = async (_: Request, res: Response) => {
-  logger.info("Health", "healthy");
-
-  return res.status(200).json({
-    status: "healthy",
-    uptime: process.uptime(),
-    timestamp: new Date().toISOString(),
-    services: {
-      memory: {
-        rss: process.memoryUsage().rss,
-        heapUsed: process.memoryUsage().heapUsed,
-      },
-    },
-  });
-};
+import { Request, Response } from "express";
+import { logger } from "@/utils";
+
+export const healthCheck = async (_: Request, res: Response) => {
+  logger.info("Health", "healthy");
+
+  return res.status(200).json({
+    status: "healthy",
+    uptime: process.uptime(),
+    timestamp: new Date().toISOString(),
+    services: {
+      memory: {
+        rss: process.memoryUsage().rss,
+        heapUsed: process.memoryUsage().heapUsed,
+      },
+    },
+  });
+};

package/template/base/ts/src/modules/v1/health/health.route.ts

@@ -1,9 +1,68 @@
-import { Router } from "express";
-import { healthCheck } from "./health.controller";
-import { methodNotAllowedHandler } from "@/middlewares";
-
-const router = Router();
-router.use(methodNotAllowedHandler(["GET"]));
-router.get("/", healthCheck);
-
-export default router;
+import { Router } from "express";
+import { healthCheck } from "./health.controller";
+import { methodNotAllowedHandler, validateRequest } from "@/middlewares";
+import { z } from "zod";
+import { routeRegistry } from "@/docs";
+
+const router = Router();
+const healthQuerySchema = z
+  .object({
+    verbose: z.coerce.boolean().optional(),
+  })
+  .strict();
+
+// Register route schema with auto-generated docs
+routeRegistry.register({
+  method: "GET",
+  path: "/api/v1/health",
+  handler: healthCheck,
+  docs: {
+    tags: ["Health"],
+    summary: "Health check endpoint",
+    description:
+      "Returns API health status and runtime metrics including uptime and memory usage.",
+    parameters: [
+      {
+        name: "verbose",
+        in: "query",
+        required: false,
+        schema: { type: "boolean" },
+        description: "Optional verbose mode for detailed diagnostics.",
+      },
+    ],
+    responses: {
+      "200": {
+        description: "Healthy response with system metrics",
+        content: {
+          "application/json": {
+            schema: {
+              type: "object",
+              properties: {
+                status: { type: "string", example: "healthy" },
+                uptime: { type: "number", example: 123.45 },
+                timestamp: { type: "string", example: "2024-01-01T00:00:00.000Z" },
+                services: {
+                  type: "object",
+                  properties: {
+                    memory: {
+                      type: "object",
+                      properties: {
+                        rss: { type: "number" },
+                        heapUsed: { type: "number" },
+                      },
+                    },
+                  },
+                },
+              },
+            },
+          },
+        },
+      },
+    },
+  },
+});
+
+router.use(methodNotAllowedHandler(["GET"]));
+router.get("/", validateRequest({ query: healthQuerySchema }), healthCheck);
+
+export default router;

package/template/base/ts/src/modules/v1/health/index.ts

@@ -1 +1 @@
-export { default as healthRoutes } from "./health.route";
+export { default as healthRoutes } from "./health.route";

package/template/base/ts/src/modules/v1/index.ts

@@ -1,8 +1,8 @@
-import { Router } from "express";
-import { healthRoutes } from "./health";
-
-const router = Router();
-
-router.use("/health", healthRoutes);
-
-export default router;
+import { Router } from "express";
+import { healthRoutes } from "./health";
+
+const router = Router();
+
+router.use("/health", healthRoutes);
+
+export default router;

package/template/base/ts/src/routes.ts

@@ -1,15 +1,23 @@
-import { Router } from "express";
-import modulesRouter from "./modules";
-import { notFound, rootHandler } from "./middlewares";
-
-const router = Router();
-
-// Root endpoint
-router.get("/", rootHandler);
-
-router.use("/api", modulesRouter);
-
-// 404 handler - must be last
-router.use(notFound);
-
-export default router;
+import { NextFunction, Request, Response, Router } from "express";
+import modulesRouter from "./modules";
+import { notFound, rootHandler } from "./middlewares";
+import swaggerUi from "swagger-ui-express";
+import { routeRegistry } from "./docs";
+
+const router = Router();
+
+// Root endpoint
+router.get("/", rootHandler);
+
+// Swagger UI with auto-generated spec
+router.use("/api-docs", swaggerUi.serve, (_req: Request, res: Response, next: NextFunction) => {
+  const spec = routeRegistry.generateOpenAPI("/*__PROJECT_NAME__*/", "1.0.0");
+  swaggerUi.setup(spec)(_req, res, next);
+});
+
+router.use("/api", modulesRouter);
+
+// 404 handler - must be last
+router.use(notFound);
+
+export default router;

package/template/base/ts/src/server.ts

@@ -1,19 +1,19 @@
-import app from "./app";
-import { ENV } from "./config";
-import { logger } from "@/utils";
-/*__DB_IMPORT__*/
-
-const PORT = ENV.PORT || 3000;
-
-const startServer = async () => {
-  /*__DB_CONNECT__*/
-
-  app.listen(PORT, () => {
-    logger.info("Server", `Server is running on port ${PORT}`);
-  });
-};
-
-startServer().catch((error) => {
-  logger.error("Server", "Failed to start server", error as Error);
-  process.exit(1);
-});
+import app from "./app";
+import { ENV } from "./config";
+import { logger } from "@/utils";
+/*__DB_IMPORT__*/
+
+const PORT = ENV.PORT || 3000;
+
+const startServer = async () => {
+  /*__DB_CONNECT__*/
+
+  app.listen(PORT, () => {
+    logger.info("Server", `Server is running on port ${PORT}`);
+  });
+};
+
+startServer().catch((error) => {
+  logger.error("Server", "Failed to start server", error as Error);
+  process.exit(1);
+});