@ifecodes/backend-template 1.1.9 → 1.4.0

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);
+});

package/template/base/ts/src/utils/http-error.ts

@@ -1,63 +1,63 @@
-export class HttpError extends Error {
-  public status: number;
-
-  constructor(status: number, message: string) {
-    super(message);
-    this.status = status;
-    Object.setPrototypeOf(this, new.target.prototype);
-  }
-}
-
-export class BadRequestError extends HttpError {
-  constructor(message = "Bad Request") {
-    super(400, message);
-  }
-}
-
-export class UnprocessableEntityError extends HttpError {
-  constructor(message = "Unprocessable Entity") {
-    super(422, message);
-  }
-}
-
-export class UnauthorizedError extends HttpError {
-  constructor(message = "Unauthorized") {
-    super(401, message);
-  }
-}
-
-export class ForbiddenError extends HttpError {
-  constructor(message = "Forbidden") {
-    super(403, message);
-  }
-}
-
-export class NotFoundError extends HttpError {
-  constructor(message = "Not Found") {
-    super(404, message);
-  }
-}
-
-export class ConflictError extends HttpError {
-  constructor(message = "Conflict") {
-    super(409, message);
-  }
-}
-
-export class TooManyRequestsError extends HttpError {
-  constructor(message = "Too Many Requests") {
-    super(429, message);
-  }
-}
-
-export class BadGatewayError extends HttpError {
-  constructor(message = "Bad Gateway") {
-    super(502, message);
-  }
-}
-
-export class InternalServerError extends HttpError {
-  constructor(message = "Internal Server Error") {
-    super(500, message);
-  }
-}
+export class HttpError extends Error {
+  public status: number;
+
+  constructor(status: number, message: string) {
+    super(message);
+    this.status = status;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+
+export class BadRequestError extends HttpError {
+  constructor(message = "Bad Request") {
+    super(400, message);
+  }
+}
+
+export class UnprocessableEntityError extends HttpError {
+  constructor(message = "Unprocessable Entity") {
+    super(422, message);
+  }
+}
+
+export class UnauthorizedError extends HttpError {
+  constructor(message = "Unauthorized") {
+    super(401, message);
+  }
+}
+
+export class ForbiddenError extends HttpError {
+  constructor(message = "Forbidden") {
+    super(403, message);
+  }
+}
+
+export class NotFoundError extends HttpError {
+  constructor(message = "Not Found") {
+    super(404, message);
+  }
+}
+
+export class ConflictError extends HttpError {
+  constructor(message = "Conflict") {
+    super(409, message);
+  }
+}
+
+export class TooManyRequestsError extends HttpError {
+  constructor(message = "Too Many Requests") {
+    super(429, message);
+  }
+}
+
+export class BadGatewayError extends HttpError {
+  constructor(message = "Bad Gateway") {
+    super(502, message);
+  }
+}
+
+export class InternalServerError extends HttpError {
+  constructor(message = "Internal Server Error") {
+    super(500, message);
+  }
+}

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

@@ -1,14 +1,14 @@
-export {
-  HttpError,
-  BadRequestError,
-  UnprocessableEntityError,
-  UnauthorizedError,
-  ForbiddenError,
-  NotFoundError,
-  ConflictError,
-  TooManyRequestsError,
-  BadGatewayError,
-  InternalServerError,
-} from "./http-error";
-
-export { default as logger } from "./logger";
+export {
+  HttpError,
+  BadRequestError,
+  UnprocessableEntityError,
+  UnauthorizedError,
+  ForbiddenError,
+  NotFoundError,
+  ConflictError,
+  TooManyRequestsError,
+  BadGatewayError,
+  InternalServerError,
+} from "./http-error";
+
+export { default as logger } from "./logger";

package/template/base/ts/src/utils/logger.ts

@@ -1,68 +1,58 @@
-import { ENV } from "@/config";
-
-// ANSI color codes for terminal output
-const colors = {
-  reset: "\x1b[0m",
-  blue: "\x1b[34m",
-  cyan: "\x1b[36m",
-  yellow: "\x1b[33m",
-  red: "\x1b[31m",
-  bold: "\x1b[1m",
-};
-
-function format(tag: string, color: string) {
-  return `${color}${colors.bold}[${tag}]${colors.reset}`;
-}
-
-function getEnvironment() {
-  return ENV.NODE_ENV === "development" || ENV.NODE_ENV === "staging"
-    ? "development"
-    : ENV.NODE_ENV;
-}
-
-console.log(
-  format("logger", colors.blue),
-  `Logger initialized for ${getEnvironment()} environment.`,
-);
-
-const requiredKeys = ENV && Object.keys(ENV).length ? Object.keys(ENV) : [];
-
-const missing = requiredKeys.filter(
-  (k) => ENV == null || (ENV as Record<string, string | undefined>)[k] === undefined || (ENV as Record<string, string | undefined>)[k] === "",
-);
-
-if (missing.length === requiredKeys.length) {
-  console.warn(
-    format("logger", colors.yellow),
-    "ENV values missing — make sure to set up your environment variables correctly.",
-  );
-} else if (missing.length > 0) {
-  console.warn(
-    format("logger", colors.yellow),
-    `Missing ENV keys: ${missing.join(", ")}`,
-  );
-}
-
-const logger = {
-  log(tag: string, ...args: unknown[]) {
-    if (getEnvironment() !== "development") return;
-    console.log(format(tag, colors.blue), ...args);
-  },
-
-  info(tag: string, ...args: unknown[]) {
-    if (getEnvironment() !== "development") return;
-    console.info(format(tag, colors.cyan), ...args);
-  },
-
-  warn(tag: string, ...args: unknown[]) {
-    if (getEnvironment() !== "development") return;
-    console.warn(format(tag, colors.yellow), ...args);
-  },
-
-  error(tag: string, ...args: unknown[]) {
-    if (getEnvironment() !== "development") return;
-    console.error(format(tag, colors.red), ...args);
-  },
-};
-
-export default logger;
+import { ENV } from "@/config";
+
+// ANSI color codes for terminal output
+const colors = {
+  reset: "\x1b[0m",
+  blue: "\x1b[34m",
+  cyan: "\x1b[36m",
+  yellow: "\x1b[33m",
+  red: "\x1b[31m",
+  bold: "\x1b[1m",
+};
+
+function format(tag: string, color: string) {
+  return `${color}${colors.bold}[${tag}]${colors.reset}`;
+}
+
+function getEnvironment() {
+  return ENV.NODE_ENV === "development" || ENV.NODE_ENV === "staging"
+    ? "development"
+    : ENV.NODE_ENV;
+}
+
+function shouldLog(level: "log" | "info" | "warn" | "error") {
+  if (level === "log") {
+    return getEnvironment() === "development";
+  }
+
+  return true;
+}
+
+console.log(
+  format("logger", colors.blue),
+  `Logger initialized for ${getEnvironment()} environment.`,
+);
+
+const logger = {
+  log(tag: string, ...args: unknown[]) {
+    if (!shouldLog("log")) return;
+    console.log(format(tag, colors.blue), ...args);
+  },
+
+  info(tag: string, ...args: unknown[]) {
+    if (!shouldLog("info")) return;
+    console.info(format(tag, colors.cyan), ...args);
+  },
+
+  warn(tag: string, ...args: unknown[]) {
+    if (!shouldLog("warn")) return;
+    console.warn(format(tag, colors.yellow), ...args);
+  },
+
+  error(tag: string, ...args: unknown[]) {
+    if (!shouldLog("error")) return;
+    console.error(format(tag, colors.red), ...args);
+  },
+};
+
+export default logger;

package/template/base/ts/tsconfig.json

@@ -1,21 +1,21 @@
-{
-  // Visit https://aka.ms/tsconfig to read more about this file
-  "compilerOptions": {
-    "target": "ES2020",
-    "module": "CommonJS",
-    "rootDir": "src",
-    "outDir": "dist",
-
-    "strict": true,
-    "noImplicitAny": true,
-    "esModuleInterop": true,
-    "skipLibCheck": true,
-
-    "paths": {
-      "@/*": ["./src/*"]
-    },
-    "types": ["node"]
-  },
-  "include": ["src"],
-  "exclude": ["node_modules", "dist"]
-}
+{
+  // Visit https://aka.ms/tsconfig to read more about this file
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "CommonJS",
+    "rootDir": "src",
+    "outDir": "dist",
+
+    "strict": true,
+    "noImplicitAny": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+
+    "paths": {
+      "@/*": ["./src/*"]
+    },
+    "types": ["node"]
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist"]
+}