devdad-express-utils 1.1.1 → 1.2.0

package/README.md

@@ -1,6 +1,6 @@
 # Express Utils
 
-A collection of reusable utilities for Express.js applications, including error handling, async route wrapping, and custom error classes.
+A collection of reusable utilities for Express.js applications, including error handling, async route wrapping, custom error classes, and MongoDB connection management.
 
 ## Installation
 
@@ -52,6 +52,52 @@ import { AppError } from "devdad-express-utils";
 throw new AppError("Validation failed", 400, ["Email is required"]);
 ```
 
+### Response Formatting
+
+Standardize API responses with consistent JSON structure.
+
+```typescript
+import { sendSuccess, sendError, sendPaginated } from "devdad-express-utils";
+
+// Success response
+sendSuccess(res, { id: 1, name: 'John' }, 'User fetched', 200);
+
+// Error response
+sendError(res, 'User not found', 404);
+
+
+```
+
+### Authentication Middleware
+
+JWT-based authentication wrapper.
+
+```typescript
+import { requireAuth } from "devdad-express-utils";
+
+const authMiddleware = requireAuth({ secret: process.env.JWT_SECRET });
+
+app.get('/profile', authMiddleware, (req, res) => {
+  // req.user contains decoded JWT
+  res.json(req.user);
+});
+```
+
+### Database Connection
+
+MongoDB connection utility with automatic reconnection and retry logic.
+
+```typescript
+import { connectDB, getDBStatus } from "devdad-express-utils";
+
+// Connect to MongoDB (ensure MONGO_URI is set in environment)
+await connectDB();
+
+// Check connection status
+const status = getDBStatus();
+console.log(status); // { isConnected: true, readyState: 1, host: '...', name: '...' }
+```
+
 ## Error Handling Patterns
 
 ### Using AppError
@@ -133,6 +179,48 @@ Express error handling middleware with detailed logging in development.
 errorHandler(err: any, req: Request, res: Response, next: NextFunction) => void
 ```
 
+### sendSuccess
+
+Sends a standardized success response.
+
+```typescript
+sendSuccess(res: Response, data: any, message?: string, statusCode?: number) => void
+```
+
+### sendError
+
+Sends a standardized error response.
+
+```typescript
+sendError(res: Response, message: string, statusCode?: number, data?: any) => void
+```
+
+
+
+### requireAuth
+
+Middleware for JWT authentication.
+
+```typescript
+requireAuth(options: { secret: string, algorithms?: Algorithm[] }) => (req, res, next) => void
+```
+
+### connectDB
+
+Connects to MongoDB with retry logic and automatic reconnection.
+
+```typescript
+connectDB() => Promise<void>
+```
+
+### getDBStatus
+
+Gets the current MongoDB connection status.
+
+```typescript
+getDBStatus() => { isConnected: boolean; readyState: number; host: string; name: string; }
+```
+
 ## Development
 
 ```bash

package/dist/DatabaseConnection.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Database connection class for MongoDB using Mongoose.
+ * Provides automatic reconnection, retry logic, and connection status monitoring.
+ */
+declare class DatabaseConnection {
+    private retryCount;
+    private isConnected;
+    /**
+     * Creates a new DatabaseConnection instance.
+     * Sets up event listeners for connection events and application termination signals.
+     */
+    constructor();
+    /**
+     * Establishes a connection to MongoDB.
+     * @throws {Error} If MONGO_URI is not defined in environment variables.
+     */
+    connect(): Promise<void>;
+    /**
+     * Handles connection errors by retrying the connection up to MAX_RETRIES times.
+     * Exits the process if all retries fail.
+     */
+    private handleConnectionError;
+    /**
+     * Handles disconnection events by attempting to reconnect if not already connected.
+     */
+    private handleDisconnection;
+    /**
+     * Handles application termination by closing the database connection gracefully.
+     */
+    private handleAppTermination;
+    /**
+     * Gets the current connection status.
+     * @returns An object containing connection status information.
+     */
+    getConnectionStatus(): {
+        isConnected: boolean;
+        readyState: number;
+        host: string;
+        name: string;
+    };
+}
+declare const _default: () => Promise<void>;
+export default _default;
+export declare const getDBStatus: () => {
+    isConnected: boolean;
+    readyState: number;
+    host: string;
+    name: string;
+};
+export { DatabaseConnection };

package/dist/DatabaseConnection.js

@@ -0,0 +1,127 @@
+import mongoose from "mongoose";
+/**
+ * Maximum number of connection retry attempts
+ */
+const MAX_RETRIES = 3;
+/**
+ * Interval between retry attempts in milliseconds
+ */
+const RETRY_INTERVAL = 5000; // 5 seconds
+/**
+ * Database connection class for MongoDB using Mongoose.
+ * Provides automatic reconnection, retry logic, and connection status monitoring.
+ */
+class DatabaseConnection {
+    retryCount;
+    isConnected;
+    /**
+     * Creates a new DatabaseConnection instance.
+     * Sets up event listeners for connection events and application termination signals.
+     */
+    constructor() {
+        this.retryCount = 0;
+        this.isConnected = false;
+        // Configure mongoose settings
+        mongoose.set("strictQuery", true);
+        // Handle connection events
+        mongoose.connection.on("connected", () => {
+            console.log("✅ MongoDB connected successfully");
+            this.isConnected = true;
+        });
+        mongoose.connection.on("error", (err) => {
+            console.error("❌ MongoDB connection error:", err);
+            this.isConnected = false;
+        });
+        mongoose.connection.on("disconnected", () => {
+            console.log("⚠️ MongoDB disconnected");
+            this.isConnected = false;
+            this.handleDisconnection();
+        });
+        // Handle application termination
+        process.on("SIGINT", this.handleAppTermination.bind(this));
+        process.on("SIGTERM", this.handleAppTermination.bind(this));
+    }
+    /**
+     * Establishes a connection to MongoDB.
+     * @throws {Error} If MONGO_URI is not defined in environment variables.
+     */
+    async connect() {
+        try {
+            if (!process.env.MONGO_URI) {
+                throw new Error("MongoDB URI is not defined in environment variables");
+            }
+            const connectionOptions = {
+                maxPoolSize: 10,
+                serverSelectionTimeoutMS: 5000,
+                socketTimeoutMS: 45000,
+                family: 4, // Use IPv4
+            };
+            if (process.env.NODE_ENV === "development") {
+                mongoose.set("debug", true);
+            }
+            await mongoose.connect(process.env.MONGO_URI, connectionOptions);
+            this.retryCount = 0; // Reset retry count on successful connection
+        }
+        catch (error) {
+            console.error("Failed to connect to MongoDB:", error.message);
+            await this.handleConnectionError();
+        }
+    }
+    /**
+     * Handles connection errors by retrying the connection up to MAX_RETRIES times.
+     * Exits the process if all retries fail.
+     */
+    async handleConnectionError() {
+        if (this.retryCount < MAX_RETRIES) {
+            this.retryCount++;
+            console.log(`Retrying connection... Attempt ${this.retryCount} of ${MAX_RETRIES}`);
+            await new Promise((resolve) => setTimeout(resolve, RETRY_INTERVAL));
+            return this.connect();
+        }
+        else {
+            console.error(`Failed to connect to MongoDB after ${MAX_RETRIES} attempts`);
+            process.exit(1);
+        }
+    }
+    /**
+     * Handles disconnection events by attempting to reconnect if not already connected.
+     */
+    handleDisconnection() {
+        if (!this.isConnected) {
+            console.log("Attempting to reconnect to MongoDB...");
+            this.connect();
+        }
+    }
+    /**
+     * Handles application termination by closing the database connection gracefully.
+     */
+    async handleAppTermination() {
+        try {
+            await mongoose.connection.close();
+            console.log("MongoDB connection closed through app termination");
+            process.exit(0);
+        }
+        catch (err) {
+            console.error("Error during database disconnection:", err);
+            process.exit(1);
+        }
+    }
+    /**
+     * Gets the current connection status.
+     * @returns An object containing connection status information.
+     */
+    getConnectionStatus() {
+        return {
+            isConnected: this.isConnected,
+            readyState: mongoose.connection.readyState,
+            host: mongoose.connection.host,
+            name: mongoose.connection.name,
+        };
+    }
+}
+// Create a singleton instance
+const dbConnection = new DatabaseConnection();
+// Export the connect function and the instance
+export default dbConnection.connect.bind(dbConnection);
+export const getDBStatus = dbConnection.getConnectionStatus.bind(dbConnection);
+export { DatabaseConnection };

package/dist/authWrapper.d.ts

@@ -0,0 +1,17 @@
+import { JwtPayload, Algorithm } from "jsonwebtoken";
+import { Request, Response, NextFunction } from "express";
+interface AuthOptions {
+    secret: string;
+    algorithms?: Algorithm[];
+}
+interface AuthenticatedRequest extends Request {
+    user?: JwtPayload | string;
+}
+/**
+ * Middleware to require JWT authentication.
+ * Verifies the JWT token from Authorization header and attaches decoded payload to req.user.
+ * @param {AuthOptions} options - JWT verification options.
+ * @returns {(req: Request, res: Response, next: NextFunction) => void} - Middleware function.
+ */
+export declare const requireAuth: (options: AuthOptions) => (req: AuthenticatedRequest, res: Response, next: NextFunction) => void;
+export {};

package/dist/authWrapper.js

@@ -0,0 +1,48 @@
+import jwt, { JsonWebTokenError, TokenExpiredError, } from "jsonwebtoken";
+import { AppError } from "./AppError.js";
+const defaultAlgorithms = ["HS256"];
+/**
+ * Middleware to require JWT authentication.
+ * Verifies the JWT token from Authorization header and attaches decoded payload to req.user.
+ * @param {AuthOptions} options - JWT verification options.
+ * @returns {(req: Request, res: Response, next: NextFunction) => void} - Middleware function.
+ */
+export const requireAuth = (options) => {
+    return (req, res, next) => {
+        const authHeader = req.headers.authorization;
+        if (!authHeader) {
+            throw new AppError("Access denied. No token provided.", 401);
+        }
+        if (!authHeader.startsWith("Bearer ")) {
+            throw new AppError("Malformed authorization header.", 401);
+        }
+        const token = authHeader.substring(7);
+        if (!token) {
+            throw new AppError("Access denied. No token provided.", 401);
+        }
+        try {
+            let decoded;
+            if (options.algorithms) {
+                decoded = jwt.verify(token, options.secret, {
+                    algorithms: options.algorithms,
+                });
+            }
+            else {
+                decoded = jwt.verify(token, options.secret);
+            }
+            req.user = decoded;
+            next();
+        }
+        catch (error) {
+            if (error instanceof JsonWebTokenError) {
+                throw new AppError("Invalid token.", 401);
+            }
+            else if (error instanceof TokenExpiredError) {
+                throw new AppError("Token expired.", 401);
+            }
+            else {
+                throw new AppError("Authentication failed.", 401);
+            }
+        }
+    };
+};

package/dist/catchAsync.js

@@ -5,6 +5,6 @@
  * @returns {(req: Request, res: Response, next: NextFunction) => void} - The wrapped handler that catches errors.
  */
 export const catchAsync = (fn) => (req, res, next) => {
-    fn(req, res, next).catch(next);
+    Promise.resolve(fn(req, res, next)).catch(next);
 };
 //#endregion

package/dist/index.d.ts

@@ -1,3 +1,6 @@
 export { AppError } from "./AppError.js";
 export { catchAsync } from "./catchAsync.js";
 export { errorHandler } from "./errorHandler.js";
+export { sendSuccess, sendError } from "./responseFormatter.js";
+export { requireAuth } from "./authWrapper.js";
+export { default as connectDB, getDBStatus, DatabaseConnection } from "./DatabaseConnection.js";

package/dist/index.js

@@ -1,3 +1,6 @@
 export { AppError } from "./AppError.js";
 export { catchAsync } from "./catchAsync.js";
 export { errorHandler } from "./errorHandler.js";
+export { sendSuccess, sendError } from "./responseFormatter.js";
+export { requireAuth } from "./authWrapper.js";
+export { default as connectDB, getDBStatus, DatabaseConnection } from "./DatabaseConnection.js";

package/dist/responseFormatter.d.ts

@@ -0,0 +1,17 @@
+import { Response } from "express";
+/**
+ * Sends a success response.
+ * @param {Response} res - Express response object.
+ * @param {any} data - Response data.
+ * @param {string} [message='Success'] - Response message.
+ * @param {number} [statusCode=200] - HTTP status code.
+ */
+export declare const sendSuccess: (res: Response, data: any, message?: string, statusCode?: number) => void;
+/**
+ * Sends an error response.
+ * @param {Response} res - Express response object.
+ * @param {string} message - Error message.
+ * @param {number} [statusCode=400] - HTTP status code.
+ * @param {any} [data] - Additional error data.
+ */
+export declare const sendError: (res: Response, message: string, statusCode?: number, data?: any) => void;

package/dist/responseFormatter.js

@@ -0,0 +1,30 @@
+/**
+ * Sends a success response.
+ * @param {Response} res - Express response object.
+ * @param {any} data - Response data.
+ * @param {string} [message='Success'] - Response message.
+ * @param {number} [statusCode=200] - HTTP status code.
+ */
+export const sendSuccess = (res, data, message = "Success", statusCode = 200) => {
+    const response = {
+        status: "success",
+        message,
+        data,
+    };
+    res.status(statusCode).json(response);
+};
+/**
+ * Sends an error response.
+ * @param {Response} res - Express response object.
+ * @param {string} message - Error message.
+ * @param {number} [statusCode=400] - HTTP status code.
+ * @param {any} [data] - Additional error data.
+ */
+export const sendError = (res, message, statusCode = 400, data) => {
+    const response = {
+        status: "error",
+        message,
+        ...(data && { data }),
+    };
+    res.status(statusCode).json(response);
+};

package/dist/validateRequest.d.ts

@@ -0,0 +1,9 @@
+import { ValidationChain } from 'express-validator';
+import { Request, Response, NextFunction } from 'express';
+/**
+ * Middleware wrapper for express-validator validations.
+ * Runs the provided validations and throws AppError if any fail.
+ * @param {ValidationChain[]} validations - Array of express-validator validation chains.
+ * @returns {(req: Request, res: Response, next: NextFunction) => Promise<void>} - Middleware function.
+ */
+export declare const validateRequest: (validations: ValidationChain[]) => (req: Request, res: Response, next: NextFunction) => Promise<void>;

package/dist/validateRequest.js

@@ -0,0 +1,19 @@
+import { validationResult } from 'express-validator';
+import { AppError } from './AppError.js';
+/**
+ * Middleware wrapper for express-validator validations.
+ * Runs the provided validations and throws AppError if any fail.
+ * @param {ValidationChain[]} validations - Array of express-validator validation chains.
+ * @returns {(req: Request, res: Response, next: NextFunction) => Promise<void>} - Middleware function.
+ */
+export const validateRequest = (validations) => {
+    return async (req, res, next) => {
+        await Promise.all(validations.map(validation => validation.run(req)));
+        const errors = validationResult(req);
+        if (!errors.isEmpty()) {
+            const errorMessages = errors.array().map(err => err.msg);
+            throw new AppError('Validation failed', 400, errorMessages);
+        }
+        next();
+    };
+};

package/package.json

@@ -1,13 +1,15 @@
 {
   "name": "devdad-express-utils",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "description": "Reusable Express.js utilities for error handling, async wrapping, and more",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "type": "module",
   "scripts": {
     "build": "tsc",
-    "test": "echo \"Error: no test specified\" && exit 1",
+    "test": "vitest",
+    "test:ui": "vitest --ui",
+    "test:coverage": "vitest run --coverage",
     "prepublishOnly": "npm run build"
   },
   "keywords": [
@@ -24,11 +26,21 @@
   },
   "license": "ISC",
   "dependencies": {
-    "express": "^5.1.0"
+    "@types/mongoose": "^5.11.96",
+    "express": "^5.1.0",
+    "jsonwebtoken": "^9.0.2",
+    "mongoose": "^9.0.0"
   },
   "devDependencies": {
     "@types/express": "^5.0.5",
-    "typescript": "^5.9.3"
+    "@types/jsonwebtoken": "^9.0.10",
+    "@types/mongodb-memory-server": "^1.8.0",
+    "@types/supertest": "^6.0.3",
+    "@vitest/ui": "^4.0.14",
+    "mongodb-memory-server": "^10.3.0",
+    "supertest": "^7.1.4",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.14"
   },
   "files": [
     "dist"