devdad-express-utils 1.5.0 → 1.7.0

package/README.md

@@ -54,10 +54,10 @@ throw new AppError("Validation failed", 400, ["Email is required"]);
 
 ### Response Formatting
 
-Standardize API responses with consistent JSON structure.
+Standardize API responses with consistent JSON structure and automatic response sending.
 
 ```typescript
-import { sendSuccess, sendError, sendPaginated } from "devdad-express-utils";
+import { sendSuccess, sendError } from "devdad-express-utils";
 
 // Success response
 sendSuccess(res, { id: 1, name: "John" }, "User fetched", 200);
@@ -66,26 +66,86 @@ sendSuccess(res, { id: 1, name: "John" }, "User fetched", 200);
 sendSuccess(res, { id: 1, name: "John" })
   .cookie("session", "abc123")
   .setHeader("X-Custom", "value");
+// Response sent automatically! 🎉
 
 // Error response
 sendError(res, "User not found", 404);
 ```
 
+#### Response Format
+
+All responses include a `success` field by default:
+
+**Success Response:**
+
+```json
+{
+  "status": "success",
+  "success": true,
+  "message": "User fetched",
+  "data": { "id": 1, "name": "John" }
+}
+```
+
+**Error Response:**
+
+```json
+{
+  "status": "error",
+  "success": false,
+  "message": "User not found"
+}
+```
+
+#### Method Chaining
+
+`sendSuccess` returns the Express response object, allowing you to chain any Express response methods:
+
+```typescript
+sendSuccess(res, { token: "abc123" }, "Login successful", 200)
+  .cookie("authToken", "abc123", { httpOnly: true, secure: true })
+  .header("X-Rate-Limit-Remaining", "99")
+  .status(200); // Can even override status
+// Response automatically sent after chaining completes
+```
+
 ### Database Connection
 
-MongoDB connection utility with automatic reconnection and retry logic.
+MongoDB connection utility with automatic reconnection, exponential backoff, and configurable retry logic.
 
 ```typescript
-import { connectDB, getDBStatus } from "devdad-express-utils";
+import {
+  connectDB,
+  getDBStatus,
+  resetDBConnection,
+} 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: '...' }
+console.log(status); // { isConnected: true, readyState: 1, host: '...', name: '...', retryCount: 0 }
+
+// Manually reset and retry (useful after Docker container restarts)
+await resetDBConnection();
 ```
 
+#### Environment Variables
+
+- **MONGO_URI**: MongoDB connection string (required)
+- **DB_MAX_RETRIES**: Maximum connection retry attempts (default: 10)
+- **DB_RETRY_INTERVAL**: Initial retry interval in milliseconds (default: 3000)
+- **NODE_ENV**: Set to 'production' to exit after max retries, 'development' to keep process alive
+
+#### Retry Behavior
+
+- **Exponential backoff**: Retry intervals increase exponentially (3s → 6s → 12s → 24s → 30s max)
+- **Random jitter**: Adds up to 1 second of random delay to prevent thundering herd
+- **Docker-friendly**: Higher default retry count (10) accommodates container startup times
+- **Development mode**: Process stays alive after max retries for manual recovery
+- **Production mode**: Process exits after max retries to allow container restart
+
 ### Logging
 
 Winston-based logger with configurable service name and environment-aware transports.
@@ -197,20 +257,32 @@ errorHandler(err: any, req: Request, res: Response, next: NextFunction) => void
 
 ### sendSuccess
 
-Sends a standardized success response. Returns the Response object for method chaining.
+Sends a standardized success response with automatic sending after method chaining. Returns the Response object for chaining Express response methods like `.cookie()`, `.header()`, etc.
 
 ```typescript
 sendSuccess(res: Response, data: any, message?: string, statusCode?: number) => Response
 ```
 
+**Features:**
+
+- Includes `success: true` field by default
+- Automatically sends response after chaining completes
+- Supports all Express response method chaining
+- No extra `.send()` call needed
+
 ### sendError
 
-Sends a standardized error response.
+Sends a standardized error response immediately.
 
 ```typescript
 sendError(res: Response, message: string, statusCode?: number, data?: any) => void
 ```
 
+**Features:**
+
+- Includes `success: false` field by default
+- Sends response immediately (no chaining needed for errors)
+
 ### connectDB
 
 Connects to MongoDB with retry logic and automatic reconnection.
@@ -224,7 +296,15 @@ connectDB() => Promise<void>
 Gets the current MongoDB connection status.
 
 ```typescript
-getDBStatus() => { isConnected: boolean; readyState: number; host: string; name: string; }
+getDBStatus() => { isConnected: boolean; readyState: number; host: string; name: string; retryCount: number; }
+```
+
+### resetDBConnection
+
+Manually resets retry count and attempts reconnection. Useful for recovering from Docker container restarts.
+
+```typescript
+resetDBConnection() => Promise<void>
 ```
 
 ### logger

package/dist/DatabaseConnection.d.ts

@@ -17,11 +17,12 @@ declare class DatabaseConnection {
     connect(): Promise<void>;
     /**
      * Handles connection errors by retrying the connection up to MAX_RETRIES times.
-     * Exits the process if all retries fail.
+     * Uses exponential backoff for retry intervals.
      */
     private handleConnectionError;
     /**
      * Handles disconnection events by attempting to reconnect if not already connected.
+     * Resets retry count for fresh reconnection attempts.
      */
     private handleDisconnection;
     /**
@@ -37,7 +38,13 @@ declare class DatabaseConnection {
         readyState: number;
         host: string;
         name: string;
+        retryCount: number;
     };
+    /**
+     * Manually reset retry count and attempt reconnection
+     * Useful for recovering from Docker container restarts
+     */
+    resetAndRetry(): Promise<void>;
 }
 declare const _default: () => Promise<void>;
 export default _default;
@@ -46,5 +53,7 @@ export declare const getDBStatus: () => {
     readyState: number;
     host: string;
     name: string;
+    retryCount: number;
 };
+export declare const resetDBConnection: () => Promise<void>;
 export { DatabaseConnection };

package/dist/DatabaseConnection.js

@@ -1,12 +1,18 @@
 import mongoose from "mongoose";
 /**
  * Maximum number of connection retry attempts
+ * Can be overridden with DB_MAX_RETRIES environment variable
  */
-const MAX_RETRIES = 3;
+const MAX_RETRIES = parseInt(process.env.DB_MAX_RETRIES || '10');
 /**
- * Interval between retry attempts in milliseconds
+ * Initial interval between retry attempts in milliseconds
+ * Can be overridden with DB_RETRY_INTERVAL environment variable
  */
-const RETRY_INTERVAL = 5000; // 5 seconds
+const INITIAL_RETRY_INTERVAL = parseInt(process.env.DB_RETRY_INTERVAL || '3000'); // 3 seconds
+/**
+ * Maximum retry interval (caps exponential backoff)
+ */
+const MAX_RETRY_INTERVAL = 30000; // 30 seconds
 /**
  * Database connection class for MongoDB using Mongoose.
  * Provides automatic reconnection, retry logic, and connection status monitoring.
@@ -69,27 +75,39 @@ class DatabaseConnection {
     }
     /**
      * Handles connection errors by retrying the connection up to MAX_RETRIES times.
-     * Exits the process if all retries fail.
+     * Uses exponential backoff for retry intervals.
      */
     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));
+            // Calculate exponential backoff with jitter
+            const exponentialDelay = Math.min(INITIAL_RETRY_INTERVAL * Math.pow(2, this.retryCount - 1), MAX_RETRY_INTERVAL);
+            const jitter = Math.random() * 1000; // Add up to 1 second of random jitter
+            const delay = exponentialDelay + jitter;
+            console.log(`Retrying connection... Attempt ${this.retryCount} of ${MAX_RETRIES} (waiting ${Math.round(delay)}ms)`);
+            await new Promise((resolve) => setTimeout(resolve, delay));
             return this.connect();
         }
         else {
-            console.error(`Failed to connect to MongoDB after ${MAX_RETRIES} attempts`);
-            process.exit(1);
+            console.error(`Failed to connect to MongoDB after ${MAX_RETRIES} attempts. Please check:`, `1. Docker container is running: docker ps`, `2. MongoDB is accessible: ${process.env.MONGO_URI}`, `3. Network connectivity between containers`, `4. Environment variables are correctly set`);
+            // Only exit in production, allow recovery in development
+            if (process.env.NODE_ENV === 'production') {
+                process.exit(1);
+            }
+            else {
+                console.log('Development mode: keeping process alive for manual retry');
+            }
         }
     }
     /**
      * Handles disconnection events by attempting to reconnect if not already connected.
+     * Resets retry count for fresh reconnection attempts.
      */
-    handleDisconnection() {
+    async handleDisconnection() {
         if (!this.isConnected) {
             console.log("Attempting to reconnect to MongoDB...");
-            this.connect();
+            this.retryCount = 0; // Reset retry count for reconnection attempts
+            await this.connect();
         }
     }
     /**
@@ -116,12 +134,23 @@ class DatabaseConnection {
             readyState: mongoose.connection.readyState,
             host: mongoose.connection.host,
             name: mongoose.connection.name,
+            retryCount: this.retryCount,
         };
     }
+    /**
+     * Manually reset retry count and attempt reconnection
+     * Useful for recovering from Docker container restarts
+     */
+    async resetAndRetry() {
+        console.log('Resetting connection state and retrying...');
+        this.retryCount = 0;
+        await this.connect();
+    }
 }
 // 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 const resetDBConnection = dbConnection.resetAndRetry.bind(dbConnection);
 export { DatabaseConnection };

package/dist/responseFormatter.d.ts

@@ -1,18 +1,53 @@
 import { Response } from "express";
 /**
- * Sends a success response.
+ * Sends a success response and returns the response object for chaining.
+ * Automatically sends the response after chaining operations complete - no extra .send() needed!
+ *
+ * Features:
+ * - Includes success: true field by default
+ * - Supports method chaining (.cookie(), .header(), etc.)
+ * - Automatically sends response after chaining completes
+ * - Returns Express response object for chaining
+ *
  * @param {Response} res - Express response object.
  * @param {any} data - Response data.
  * @param {string} [message='Success'] - Response message.
  * @param {number} [statusCode=200] - HTTP status code.
  * @returns {Response} The Express response object for chaining.
+ *
+ * @example
+ * // Basic usage
+ * sendSuccess(res, { userId: 123 }, "Login successful");
+ *
+ * @example
+ * // Chain methods without calling .send()
+ * sendSuccess(res, { userId: 123 }, "Login successful", 200)
+ *   .cookie("authToken", "xyz789", { httpOnly: true })
+ *   .header("X-Custom", "value");
+ * // Response sent automatically!
  */
 export declare const sendSuccess: (res: Response, data: any, message?: string, statusCode?: number) => Response;
 /**
- * Sends an error response.
+ * Sends an error response immediately.
+ *
+ * Features:
+ * - Includes success: false field by default
+ * - Sends response immediately (no chaining needed)
+ * - Supports optional error data
+ *
  * @param {Response} res - Express response object.
  * @param {string} message - Error message.
  * @param {number} [statusCode=400] - HTTP status code.
  * @param {any} [data] - Additional error data.
+ *
+ * @example
+ * // Basic error
+ * sendError(res, "User not found", 404);
+ *
+ * @example
+ * // Error with additional data
+ * sendError(res, "Validation failed", 400, {
+ *   errors: ["Email is required", "Password too short"]
+ * });
  */
 export declare const sendError: (res: Response, message: string, statusCode?: number, data?: any) => void;

package/dist/responseFormatter.js

@@ -1,29 +1,74 @@
 /**
- * Sends a success response.
+ * Sends a success response and returns the response object for chaining.
+ * Automatically sends the response after chaining operations complete - no extra .send() needed!
+ *
+ * Features:
+ * - Includes success: true field by default
+ * - Supports method chaining (.cookie(), .header(), etc.)
+ * - Automatically sends response after chaining completes
+ * - Returns Express response object for chaining
+ *
  * @param {Response} res - Express response object.
  * @param {any} data - Response data.
  * @param {string} [message='Success'] - Response message.
  * @param {number} [statusCode=200] - HTTP status code.
  * @returns {Response} The Express response object for chaining.
+ *
+ * @example
+ * // Basic usage
+ * sendSuccess(res, { userId: 123 }, "Login successful");
+ *
+ * @example
+ * // Chain methods without calling .send()
+ * sendSuccess(res, { userId: 123 }, "Login successful", 200)
+ *   .cookie("authToken", "xyz789", { httpOnly: true })
+ *   .header("X-Custom", "value");
+ * // Response sent automatically!
  */
 export const sendSuccess = (res, data, message = "Success", statusCode = 200) => {
     const response = {
         status: "success",
+        success: true,
         message,
         data,
     };
-    return res.status(statusCode).json(response);
+    res.status(statusCode);
+    // Use setImmediate to send response after current execution stack
+    setImmediate(() => {
+        if (!res._responseSent) {
+            res._responseSent = true;
+            res.json(response);
+        }
+    });
+    return res;
 };
 /**
- * Sends an error response.
+ * Sends an error response immediately.
+ *
+ * Features:
+ * - Includes success: false field by default
+ * - Sends response immediately (no chaining needed)
+ * - Supports optional error data
+ *
  * @param {Response} res - Express response object.
  * @param {string} message - Error message.
  * @param {number} [statusCode=400] - HTTP status code.
  * @param {any} [data] - Additional error data.
+ *
+ * @example
+ * // Basic error
+ * sendError(res, "User not found", 404);
+ *
+ * @example
+ * // Error with additional data
+ * sendError(res, "Validation failed", 400, {
+ *   errors: ["Email is required", "Password too short"]
+ * });
  */
 export const sendError = (res, message, statusCode = 400, data) => {
     const response = {
         status: "error",
+        success: false,
         message,
         ...(data && { data }),
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "devdad-express-utils",
-  "version": "1.5.0",
+  "version": "1.7.0",
   "description": "Reusable Express.js utilities for error handling, async wrapping, and more",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/dist/AppError.1.js

@@ -1 +0,0 @@
-"use strict";

package/dist/AppError.2.js

@@ -1 +0,0 @@
-"use strict";

package/dist/authWrapper.d.ts

@@ -1,17 +0,0 @@
-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

@@ -1,48 +0,0 @@
-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/validateRequest.d.ts

@@ -1,9 +0,0 @@
-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

@@ -1,19 +0,0 @@
-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();
-    };
-};