@ifecodes/backend-template 1.1.9 → 1.4.0

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

@@ -1,16 +1,18 @@
-const rootHandler = (_, res) => {
-  res.json({
-    name: "/*__PROJECT_NAME__*/",
-    type: "/*__PROJECT_TYPE__*/",
-    version: "1.0.0",
-    status: "running",
-    endpoints: {
-      health: "/api/v1/health",
-      /*__AUTH_ENDPOINT__*/
-    },
-  });
-};
-
-module.exports = {
-  rootHandler,
-};
+const rootHandler = (_, res) => {
+  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__*/
+    },
+  });
+};
+
+module.exports = {
+  rootHandler,
+};

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

@@ -0,0 +1,39 @@
+const { ZodError } = require('zod');
+const { BadRequestError } = require('../utils');
+
+const validateRequest = (schemas = {}) => {
+  return (req, _, next) => {
+    try {
+      if (schemas.body) {
+        req.body = schemas.body.parse(req.body);
+      }
+
+      if (schemas.query) {
+        req.query = schemas.query.parse(req.query);
+      }
+
+      if (schemas.params) {
+        req.params = schemas.params.parse(req.params);
+      }
+
+      next();
+    } catch (error) {
+      if (error instanceof ZodError) {
+        const issues = error.issues
+          .map(
+            (issue) => `${issue.path.join('.') || 'request'}: ${issue.message}`
+          )
+          .join('; ');
+        return next(
+          new BadRequestError(`Request validation failed - ${issues}`)
+        );
+      }
+
+      return next(error);
+    }
+  };
+};
+
+module.exports = {
+  validateRequest,
+};

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

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

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,21 +1,21 @@
-const { logger } = require("../../../utils");
-
-const healthCheck = async (_, res) => {
-  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,
-      },
-    },
-  });
-};
-
-module.exports = {
-  healthCheck
-};
+const { logger } = require('../../../utils');
+
+const healthCheck = async (_, res) => {
+  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,
+      },
+    },
+  });
+};
+
+module.exports = {
+  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 = Router();
-router.use(methodNotAllowedHandler(["GET"]));
-router.get("/", healthCheck);
-
-module.exports = router;
+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();
+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,5 +1,5 @@
-const healthRoutes = require("./health.route");
-
-module.exports = {
-  healthRoutes,
-};
+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 = Router();
-
-router.use("/health", healthRoutes);
-
-module.exports = router;
+const { Router } = require('express');
+const { healthRoutes } = require('./health');
+
+const router = Router();
+
+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 = Router();
-
-// Root endpoint
-router.get("/", rootHandler);
-
-router.use("/api", modulesRouter);
-
-// 404 handler - must be last
-router.use(notFound);
-
-module.exports = router;
-
+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);
+
+// 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

@@ -1,74 +1,74 @@
-class HttpError extends Error {
-  constructor(status, message) {
-    super(message);
-    this.status = status;
-    Object.setPrototypeOf(this, new.target.prototype);
-  }
-}
-
-class BadRequestError extends HttpError {
-  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") {
-    super(401, message);
-  }
-}
-
-class ForbiddenError extends HttpError {
-  constructor(message = "Forbidden") {
-    super(403, message);
-  }
-}
-
-class NotFoundError extends HttpError {
-  constructor(message = "Not Found") {
-    super(404, message);
-  }
-}
-
-class ConflictError extends HttpError {
-  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") {
-    super(500, message);
-  }
-}
-
-module.exports = {
-  HttpError,
-  BadRequestError,
-  UnprocessableEntityError,
-  UnauthorizedError,
-  ForbiddenError,
-  NotFoundError,
-  ConflictError,
-  TooManyRequestsError,
-  BadGatewayError,
-  InternalServerError,
-};
+class HttpError extends Error {
+  constructor(status, message) {
+    super(message);
+    this.status = status;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+
+class BadRequestError extends HttpError {
+  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') {
+    super(401, message);
+  }
+}
+
+class ForbiddenError extends HttpError {
+  constructor(message = 'Forbidden') {
+    super(403, message);
+  }
+}
+
+class NotFoundError extends HttpError {
+  constructor(message = 'Not Found') {
+    super(404, message);
+  }
+}
+
+class ConflictError extends HttpError {
+  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') {
+    super(500, message);
+  }
+}
+
+module.exports = {
+  HttpError,
+  BadRequestError,
+  UnprocessableEntityError,
+  UnauthorizedError,
+  ForbiddenError,
+  NotFoundError,
+  ConflictError,
+  TooManyRequestsError,
+  BadGatewayError,
+  InternalServerError,
+};

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

@@ -1,28 +1,28 @@
-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,
-};
+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,
+};