@ifecodes/backend-template 1.1.8 → 1.4.0

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

@@ -0,0 +1,29 @@
+const mongoose = require('mongoose');
+const { logger } = require('../../../utils');
+
+const healthCheck = async (_, res) => {
+  const mongoState = mongoose.connection.readyState;
+
+  const healthy = mongoState === 1;
+
+  const failed = [];
+  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,
+  });
+};
+
+module.exports = {
+  healthCheck,
+};

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

@@ -1,10 +1,10 @@
-const { logger } = require("../../../utils");
+const { logger } = require('../../../utils');
 
 const healthCheck = async (_, res) => {
-  logger.info("Health", "healthy");
+  logger.info('Health', 'healthy');
 
   return res.status(200).json({
-    status: "healthy",
+    status: 'healthy',
     uptime: process.uptime(),
     timestamp: new Date().toISOString(),
     services: {
@@ -17,5 +17,5 @@ const healthCheck = async (_, res) => {
 };
 
 module.exports = {
-  healthCheck
+  healthCheck,
 };

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

@@ -1,9 +1,74 @@
-const { Router } = require("express");
-const { healthCheck } = require("./health.controller");
-const { methodNotAllowedHandler } = require("../../../middlewares");
+const { Router } = require('express');
+const { healthCheck } = require('./health.controller');
+const { z } = require('zod');
+const {
+  methodNotAllowedHandler,
+  validateRequest,
+} = require('../../../middlewares');
+const { routeRegistry } = require('../../../docs');
 
 const router = Router();
-router.use(methodNotAllowedHandler(["GET"]));
-router.get("/", healthCheck);
+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('/', healthCheck);
 
 module.exports = router;

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

@@ -1,4 +1,4 @@
-const healthRoutes = require("./health.route");
+const healthRoutes = require('./health.route');
 
 module.exports = {
   healthRoutes,

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

@@ -1,8 +1,8 @@
-const { Router } = require("express");
-const { healthRoutes } = require("./health");
+const { Router } = require('express');
+const { healthRoutes } = require('./health');
 
 const router = Router();
 
-router.use("/health", healthRoutes);
+router.use('/health', healthRoutes);
 
 module.exports = router;

package/template/base/js/src/routes.js

@@ -1,16 +1,23 @@
-const { Router } = require("express");
-const modulesRouter = require("./modules");
-const { notFound, rootHandler } = require("./middlewares");
+const { Router } = require('express');
+const modulesRouter = require('./modules');
+const { notFound, rootHandler } = require('./middlewares');
+const swaggerUi = require('swagger-ui-express');
+const { routeRegistry } = require('./docs');
 
 const router = Router();
 
 // Root endpoint
-router.get("/", rootHandler);
+router.get('/', rootHandler);
 
-router.use("/api", modulesRouter);
+// Swagger UI with auto-generated spec
+router.use('/api-docs', swaggerUi.serve, (_, res, next) => {
+  const spec = routeRegistry.generateOpenAPI('/*__PROJECT_NAME__*/', '1.0.0');
+  swaggerUi.setup(spec)(_, res, next);
+});
+
+router.use('/api', modulesRouter);
 
 // 404 handler - must be last
 router.use(notFound);
 
 module.exports = router;
-

package/template/base/js/src/server.js

@@ -1,18 +1,18 @@
-const app = require("./app");
-const { ENV/*__DB_IMPORT__*/ } = require("./config");
-const { logger } = require("./utils");
-
-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);
-  process.exit(1);
-});
+const app = require('./app');
+const { ENV /*__DB_IMPORT__*/ } = require('./config');
+const { logger } = require('./utils');
+
+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);
+  process.exit(1);
+});

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

@@ -7,37 +7,55 @@ class HttpError extends Error {
 }
 
 class BadRequestError extends HttpError {
-  constructor(message = "Bad Request") {
+  constructor(message = 'Bad Request') {
     super(400, message);
   }
 }
 
+class UnprocessableEntityError extends HttpError {
+  constructor(message = 'Unprocessable Entity') {
+    super(422, message);
+  }
+}
+
 class UnauthorizedError extends HttpError {
-  constructor(message = "Unauthorized") {
+  constructor(message = 'Unauthorized') {
     super(401, message);
   }
 }
 
 class ForbiddenError extends HttpError {
-  constructor(message = "Forbidden") {
+  constructor(message = 'Forbidden') {
     super(403, message);
   }
 }
 
 class NotFoundError extends HttpError {
-  constructor(message = "Not Found") {
+  constructor(message = 'Not Found') {
     super(404, message);
   }
 }
 
 class ConflictError extends HttpError {
-  constructor(message = "Conflict") {
+  constructor(message = 'Conflict') {
     super(409, message);
   }
 }
 
+class TooManyRequestsError extends HttpError {
+  constructor(message = 'Too Many Requests') {
+    super(429, message);
+  }
+}
+
+class BadGatewayError extends HttpError {
+  constructor(message = 'Bad Gateway') {
+    super(502, message);
+  }
+}
+
 class InternalServerError extends HttpError {
-  constructor(message = "Internal Server Error") {
+  constructor(message = 'Internal Server Error') {
     super(500, message);
   }
 }
@@ -45,9 +63,12 @@ class InternalServerError extends HttpError {
 module.exports = {
   HttpError,
   BadRequestError,
+  UnprocessableEntityError,
   UnauthorizedError,
   ForbiddenError,
   NotFoundError,
   ConflictError,
+  TooManyRequestsError,
+  BadGatewayError,
   InternalServerError,
 };

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

@@ -1,22 +1,28 @@
-const {
-  HttpError,
-  BadRequestError,
-  UnauthorizedError,
-  ForbiddenError,
-  NotFoundError,
-  ConflictError,
-  InternalServerError,
-} = require("./http-error");
-
-const logger = require("./logger");
-
-module.exports = {
-  HttpError,
-  BadRequestError,
-  UnauthorizedError,
-  ForbiddenError,
-  NotFoundError,
-  ConflictError,
-  InternalServerError,
-  logger,
-};
+const {
+  HttpError,
+  BadRequestError,
+  UnprocessableEntityError,
+  UnauthorizedError,
+  ForbiddenError,
+  NotFoundError,
+  ConflictError,
+  TooManyRequestsError,
+  BadGatewayError,
+  InternalServerError,
+} = require('./http-error');
+
+const logger = require('./logger');
+
+module.exports = {
+  HttpError,
+  BadRequestError,
+  UnprocessableEntityError,
+  UnauthorizedError,
+  ForbiddenError,
+  NotFoundError,
+  ConflictError,
+  TooManyRequestsError,
+  BadGatewayError,
+  InternalServerError,
+  logger,
+};

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 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"
+  }
+}