@ifecodes/backend-template 1.1.9 → 1.4.0

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

@@ -1,67 +1,57 @@
-const { ENV } = require("../config/env");
-// 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, color) {
-  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[k] === undefined || ENV[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, ...args) {
-    if (getEnvironment() !== "development") return;
-    console.log(format(tag, colors.blue), ...args);
-  },
-
-  info(tag, ...args) {
-    if (getEnvironment() !== "development") return;
-    console.info(format(tag, colors.cyan), ...args);
-  },
-
-  warn(tag, ...args) {
-    if (getEnvironment() !== "development") return;
-    console.warn(format(tag, colors.yellow), ...args);
-  },
-
-  error(tag, ...args) {
-    if (getEnvironment() !== "development") return;
-    console.error(format(tag, colors.red), ...args);
-  },
-};
-
-module.exports = logger;
+const { ENV } = require('../config/env');
+// 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, color) {
+  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) {
+  if (level === 'log') {
+    return getEnvironment() === 'development';
+  }
+
+  return true;
+}
+
+console.log(
+  format('logger', colors.blue),
+  `Logger initialized for ${getEnvironment()} environment.`
+);
+
+const logger = {
+  log(tag, ...args) {
+    if (!shouldLog('log')) return;
+    console.log(format(tag, colors.blue), ...args);
+  },
+
+  info(tag, ...args) {
+    if (!shouldLog('info')) return;
+    console.info(format(tag, colors.cyan), ...args);
+  },
+
+  warn(tag, ...args) {
+    if (!shouldLog('warn')) return;
+    console.warn(format(tag, colors.yellow), ...args);
+  },
+
+  error(tag, ...args) {
+    if (!shouldLog('error')) return;
+    console.error(format(tag, colors.red), ...args);
+  },
+};
+
+module.exports = logger;

package/template/base/ts/.eslintrc.json

@@ -1,17 +1,13 @@
-{
-  "parser": "@typescript-eslint/parser",
-  "plugins": ["@typescript-eslint"],
-  "extends": [
-    "eslint:recommended",
-    "plugin:@typescript-eslint/recommended",
-    "prettier"
-  ],
-  "env": {
-    "node": true,
-    "es2021": true
-  },
-  "rules": {
-    "@typescript-eslint/no-unused-vars": ["warn"],
-    "@typescript-eslint/no-explicit-any": "error"
-  }
-}
+{
+  "parser": "@typescript-eslint/parser",
+  "plugins": ["@typescript-eslint"],
+  "extends": ["eslint:recommended", "plugin:@typescript-eslint/recommended", "prettier"],
+  "env": {
+    "node": true,
+    "es2021": true
+  },
+  "rules": {
+    "@typescript-eslint/no-unused-vars": ["warn"],
+    "@typescript-eslint/no-explicit-any": "error"
+  }
+}

package/template/base/ts/.prettierrc

@@ -1,7 +1,7 @@
-{
-  "semi": true,
-  "singleQuote": false,
-  "trailingComma": "all",
-  "printWidth": 90,
-  "tabWidth": 2
-}
+{
+  "semi": true,
+  "singleQuote": false,
+  "trailingComma": "all",
+  "printWidth": 90,
+  "tabWidth": 2
+}

package/template/base/ts/eslint.config.js

@@ -1,33 +1,33 @@
-const tsParser = require("@typescript-eslint/parser");
-const tsPlugin = require("@typescript-eslint/eslint-plugin");
-
-module.exports = [
-  // Files/paths to ignore (replaces .eslintignore usage in flat config)
-  {
-    ignores: ["node_modules/**", "dist/**"],
-  },
-
-  // TypeScript rules for source files
-  {
-    files: ["src/**/*.{ts,tsx}"],
-    languageOptions: {
-      parser: tsParser,
-      parserOptions: {
-        project: "./tsconfig.json",
-        tsconfigRootDir: __dirname,
-        ecmaVersion: 2020,
-        sourceType: "module",
-      },
-    },
-    plugins: {
-      "@typescript-eslint": tsPlugin,
-    },
-    rules: {
-      // Disallow explicit `any`
-      "@typescript-eslint/no-explicit-any": "error",
-
-      // You can add or tune more TypeScript rules here
-      "@typescript-eslint/explicit-module-boundary-types": "off",
-    },
-  },
-];
+const tsParser = require("@typescript-eslint/parser");
+const tsPlugin = require("@typescript-eslint/eslint-plugin");
+
+module.exports = [
+  // Files/paths to ignore (replaces .eslintignore usage in flat config)
+  {
+    ignores: ["node_modules/**", "dist/**"],
+  },
+
+  // TypeScript rules for source files
+  {
+    files: ["src/**/*.{ts,tsx}"],
+    languageOptions: {
+      parser: tsParser,
+      parserOptions: {
+        project: "./tsconfig.json",
+        tsconfigRootDir: __dirname,
+        ecmaVersion: 2020,
+        sourceType: "module",
+      },
+    },
+    plugins: {
+      "@typescript-eslint": tsPlugin,
+    },
+    rules: {
+      // Disallow explicit `any`
+      "@typescript-eslint/no-explicit-any": "error",
+
+      // You can add or tune more TypeScript rules here
+      "@typescript-eslint/explicit-module-boundary-types": "off",
+    },
+  },
+];

package/template/base/ts/package.json

@@ -1,39 +1,41 @@
-{
-  "version": "1.0.0",
-  "description": "",
-  "main": "index.js",
-  "scripts": {
-    "dev": "ts-node-dev --respawn --transpile-only -r tsconfig-paths/register src/server.ts",
-    "start": "node -r module-alias/register dist/server.js",
-    "build": "tsc",
-    "lint": "eslint \"src/**/*.{ts,tsx}\"",
-    "format": "prettier --write \"src/**/*.{ts,json}\"",
-    "check-format": "prettier --check \"src/**/*.{ts,json}\"",
-    "prepare": "husky"
-  },
-  "keywords": [],
-  "author": "",
-  "license": "ISC",
-  "type": "commonjs",
-  "dependencies": {
-    "dotenv": "^16.3.1",
-    "express": "^5.2.1",
-    "module-alias": "^2.2.3"
-  },
-  "devDependencies": {
-    "@types/express": "^5.0.6",
-    "@types/node": "^25.0.3",
-    "@typescript-eslint/eslint-plugin": "^8.50.1",
-    "@typescript-eslint/parser": "^8.50.1",
-    "eslint": "^9.39.2",
-    "eslint-config-prettier": "^10.1.8",
-    "husky": "^9.1.7",
-    "prettier": "^3.7.4",
-    "ts-node-dev": "^2.0.0",
-    "tsconfig-paths": "^4.2.0",
-    "typescript": "^5.9.3"
-  },
-  "_moduleAliases": {
-    "@": "dist"
-  }
-}
+{
+  "version": "1.0.0",
+  "description": "",
+  "main": "index.js",
+  "scripts": {
+    "dev": "ts-node-dev --respawn --transpile-only -r tsconfig-paths/register src/server.ts",
+    "start": "node -r module-alias/register dist/server.js",
+    "build": "tsc",
+    "lint": "eslint \"src/**/*.{ts,tsx}\"",
+    "format": "prettier --write \"src/**/*.{ts,json}\"",
+    "check-format": "prettier --check \"src/**/*.{ts,json}\"",
+    "prepare": "husky"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "type": "commonjs",
+  "dependencies": {
+    "dotenv": "^16.3.1",
+    "express": "^5.2.1",
+    "module-alias": "^2.2.3",
+    "swagger-ui-express": "^5.0.1"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.6",
+    "@types/node": "^25.0.3",
+    "@typescript-eslint/eslint-plugin": "^8.50.1",
+    "@typescript-eslint/parser": "^8.50.1",
+    "@types/swagger-ui-express": "^4.1.8",
+    "eslint": "^9.39.2",
+    "eslint-config-prettier": "^10.1.8",
+    "husky": "^9.1.7",
+    "prettier": "^3.7.4",
+    "ts-node-dev": "^2.0.0",
+    "tsconfig-paths": "^4.2.0",
+    "typescript": "^5.9.3"
+  },
+  "_moduleAliases": {
+    "@": "dist"
+  }
+}

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

@@ -1,18 +1,20 @@
-import express from "express";
-import router from "./routes";
-import { errorHandler } from "@/middlewares";
-/*__IMPORTS__*/
-
-const app = express();
-
-// Parse JSON request bodies
-app.use(express.json());
-
-/*__MIDDLEWARE__*/
-
-// Connect routes
-app.use(router);
-
-app.use(errorHandler);
-
-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

@@ -1,5 +1,5 @@
 import { NextFunction, Request, Response } from "express";
-import { HttpError } from "@/utils";
+import { HttpError, logger } from "@/utils";
 
 // Centralized error handling middleware
 
@@ -10,12 +10,15 @@ export const errorHandler = (
   __: 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,4 +1,6 @@
-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 { 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,18 +1,23 @@
-import { Request, Response, NextFunction } from "express";
-
-// 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)) {
-      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();
+};