backend-starter-kit 1.0.5

package/template/src/core/middlewares/asyncHandler.middleware.js

@@ -0,0 +1,7 @@
+const asyncHandler = (fn) => {
+    return (req, res, next) => {
+        Promise.resolve(fn(req, res, next)).catch((err) => next(err));
+    };
+};
+
+export default asyncHandler;

package/template/src/core/middlewares/error.middleware.js

@@ -0,0 +1,43 @@
+import { NODE_ENV } from "../../config/env.config.js";
+import ApiError from "../http/api.error.js";
+import { logger } from "../utils/logger.utils.js";
+
+const errorHandler = (err, req, res, _next) => {
+    const error = ApiError.from(err);
+    const statusCode = error.statusCode || 500;
+
+    const isProduction = NODE_ENV === "production";
+
+    if (error.isOperational) {
+        logger.warn({
+            message: error.message,
+            statusCode,
+            method: req.method,
+            url: req.originalUrl,
+            ip: req.ip,
+        });
+    } else {
+        logger.error({
+            message: error.message,
+            stack: error.stack,
+            method: req.method,
+            url: req.originalUrl,
+            ip: req.ip,
+        });
+    }
+
+    const body =
+        isProduction && !error.isOperational
+            ? {
+                  success: false,
+                  message: "Something went wrong",
+              }
+            : {
+                  ...error.toJSON(),
+                  ...(NODE_ENV === "development" && { stack: error.stack }),
+              };
+
+    res.status(statusCode).json(body);
+};
+
+export default errorHandler;

package/template/src/core/middlewares/notFound.middleware.js

@@ -0,0 +1,8 @@
+import { API_VERSION } from "../../constants/api.constants.js";
+import ApiResponse from "../http/api.response.js";
+
+const notFound = (_, res) => {
+    return ApiResponse.redirect(res, `/api/${API_VERSION}/docs`);
+};
+
+export default notFound;

package/template/src/core/middlewares/validate.middleware.js

@@ -0,0 +1,33 @@
+import { ZodError, z } from "zod/v4";
+import ApiError from "../http/api.error.js";
+
+const validate = (schema, source = "body") => {
+    return async (req, _res, next) => {
+        try {
+            const result = await schema.safeParseAsync(req[source]);
+
+            if (!result.success) {
+                const flattenError = z.flattenError(result.error);
+
+                return next(
+                    ApiError.validationError("Validation Error", flattenError)
+                );
+            }
+
+            req[source] = result.data;
+            return next();
+        } catch (error) {
+            if (error instanceof ZodError) {
+                const flattenError = z.flattenError(error);
+
+                return next(
+                    ApiError.validationError("Validation Error", flattenError)
+                );
+            }
+
+            return next(ApiError.from(error));
+        }
+    };
+};
+
+export default validate;

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

@@ -0,0 +1,78 @@
+import fs from "fs";
+import path from "path";
+import winston from "winston";
+import { NODE_ENV } from "../../config/env.config.js";
+
+const { combine, timestamp, errors, colorize, printf, prettyPrint } =
+    winston.format;
+
+const logDir = "logs";
+if (!fs.existsSync(logDir)) {
+    fs.mkdirSync(logDir);
+}
+
+const logFormat = printf(({ timestamp, level, message, stack }) => {
+    return `\n[${timestamp}] \n ${level} :- ${stack || message}\n`;
+});
+
+export const logger = winston.createLogger({
+    level: NODE_ENV === "development" ? "debug" : "info",
+    handleExceptions: true,
+    handleRejections: true,
+    defaultMeta: { service: "backend" },
+    silent: NODE_ENV === "test",
+    format: combine(
+        timestamp({ format: "YYYY-MM-DD HH:mm:ss" }),
+        errors({ stack: true }),
+        logFormat,
+        prettyPrint()
+    ),
+    transports: [
+        new winston.transports.Console({
+            handleExceptions: true,
+            handleRejections: true,
+            format: combine(
+                colorize({
+                    all: true,
+                    message: true,
+                    colors: {
+                        info: "blue",
+                        warn: "yellow",
+                        error: "red",
+                        debug: "magenta",
+                        verbose: "cyan",
+                        silly: "green",
+                        http: "magenta",
+                        critical: "red",
+                        alert: "red",
+                        emergency: "red",
+                        notice: "blue",
+                        warning: "yellow",
+                    },
+                    level: true,
+                }),
+                logFormat
+            ),
+        }),
+        new winston.transports.File({
+            filename: path.join(logDir, "error.log"),
+            level: "error",
+            handleExceptions: true,
+            maxsize: 5 * 1024 * 1024,
+            maxFiles: 5,
+        }),
+        new winston.transports.File({
+            filename: path.join(logDir, "combined.log"),
+            handleExceptions: true,
+            maxsize: 5 * 1024 * 1024,
+            maxFiles: 5,
+        }),
+    ],
+    exitOnError: false,
+});
+
+logger.stream = {
+    write: (message) => {
+        logger.info(message.trim());
+    },
+};

package/template/src/core/utils/zod.utils.js

@@ -0,0 +1,74 @@
+import z from "zod/v4";
+
+const zString = (fieldName, minLength = 2, maxLength = 255) => {
+    return z
+        .string({ error: "Invalid string" })
+        .min(minLength, {
+            error: `${fieldName} must be at least ${minLength} characters long`,
+        })
+        .max(maxLength, {
+            error: `${fieldName} must be at most ${maxLength} characters long`,
+        });
+};
+
+const zEmail = (minLength = 2) => {
+    return z
+        .email({ pattern: z.regexes.email, error: "Invalid email address" })
+        .min(minLength, {
+            error: `Email must be at least ${minLength} characters long`,
+        })
+        .max(255, { error: "Email must be at most 255 characters long" });
+};
+
+const zNumber = (fieldName, minLength = 1, maxLength = 15) => {
+    return z
+        .number({ error: `Invalid ${fieldName}` })
+        .min(minLength, `${fieldName} must be at least ${minLength}`)
+        .max(maxLength, `${fieldName} must be at most ${maxLength}`);
+};
+
+const zUUID = (fieldName) => {
+    return z
+        .uuid({ error: `Invalid ${fieldName} format` })
+        .min(36, `${fieldName} must be at least 36 characters long`)
+        .max(36, `${fieldName} must be at most 36 characters long`);
+};
+
+const zPassword = () => {
+    return z
+        .string({ error: "Invalid password" })
+        .min(6, { error: "Password must be at least 6 characters long" })
+        .max(128, { error: "Password must be at most 128 characters long" })
+        .regex(/[a-z]/, {
+            error: "Password must contain at least one lowercase letter",
+        })
+        .regex(/[A-Z]/, {
+            error: "Password must contain at least one uppercase letter",
+        })
+        .regex(/[0-9]/, {
+            error: "Password must contain at least one number",
+        })
+        .regex(/[^a-zA-Z0-9]/, {
+            error: "Password must contain at least one special character",
+        });
+};
+
+const zArray = (
+    fieldName,
+    itemSchema = z.any(),
+    minLength = 1,
+    maxLength = 100,
+    defaultValue = []
+) => {
+    return z
+        .array(itemSchema, { error: `Invalid ${fieldName}` })
+        .min(minLength, {
+            error: `${fieldName} must contain at least ${minLength} items`,
+        })
+        .max(maxLength, {
+            error: `${fieldName} must contain at most ${maxLength} items`,
+        })
+        .default(defaultValue);
+};
+
+export { zString, zEmail, zNumber, zUUID, zPassword, zArray };

package/template/src/index.js

@@ -0,0 +1,29 @@
+import { app } from "./app";
+import { PORT } from "./config/env.config.js";
+import { logger } from "./core/utils/logger.utils.js";
+
+app.listen(PORT, async () => {
+    try {
+        app.listen(PORT, () => {
+            logger.info(`🚀 Server running on PORT: ${PORT}`);
+        });
+    } catch (error) {
+        logger.error("❌ Database connection failed:", error);
+        process.exit(1);
+    }
+});
+
+const shutdown = async (signal) => {
+    logger.info(`🛑 ${signal} received. Shutting down...`);
+
+    try {
+        logger.info("✅ Database connection closed. Server shutdown complete.");
+    } catch (err) {
+        logger.error("❌ Error during DB disconnect", err);
+    } finally {
+        process.exit(0);
+    }
+};
+
+process.on("SIGINT", () => shutdown("SIGINT"));
+process.on("SIGTERM", () => shutdown("SIGTERM"));

package/template/src/routes/createRoute.js

@@ -0,0 +1,10 @@
+import { Router } from "express";
+
+const createRouter = () =>
+    Router({
+        caseSensitive: true,
+        mergeParams: true,
+        strict: true,
+    });
+
+export default createRouter;

package/template/src/routes/health.route.js

@@ -0,0 +1,28 @@
+import ApiResponse from "../core/http/api.response.js";
+import createRouter from "./createRoute.js";
+
+const router = createRouter();
+
+/**
+ * @swagger
+ * /health:
+ *   get:
+ *     summary: Health Check
+ *     description: Check if the API is healthy and responsive
+ *     tags:
+ *       - System
+ *     responses:
+ *       200:
+ *         description: API is healthy
+ *         content:
+ *           application/json:
+ *             example:
+ *               status: success
+ *               message: API is healthy
+ *               data: null
+ */
+router.get("/", (_, res) => {
+    return ApiResponse.ok(null, "API is healthy").send(res);
+});
+
+export default router;

package/template/src/routes/index.route.js

@@ -0,0 +1,38 @@
+import { specs, swaggerUi, theme } from "../config/swagger.config.js";
+import { APP_NAME } from "../constants/app.constants.js";
+import ApiResponse from "../core/http/api.response.js";
+import createRouter from "./createRoute.js";
+import healthRoute from "./health.route.js";
+
+const router = createRouter();
+
+// Swagger UI for API documentation
+router.use("/docs", swaggerUi.serve, swaggerUi.setup(specs, theme));
+
+/**
+ * @swagger
+ * /:
+ *   get:
+ *     summary: Welcome message
+ *     description: Welcome message for the API service
+ *     tags:
+ *       - System
+ *     responses:
+ *       200:
+ *         description: Welcome message
+ *         content:
+ *           application/json:
+ *             example:
+ *               status: success
+ *               message: Welcome to the ${APP_NAME} API service
+ *               data: null
+ */
+router.get("/", (_, res) => {
+    return ApiResponse.ok(null, `Welcome to the ${APP_NAME} API Service`).send(
+        res
+    );
+});
+
+router.use("/health", healthRoute);
+
+export default router;