devdad-express-utils 1.7.2 → 1.8.1

package/README.md

@@ -54,19 +54,19 @@ throw new AppError("Validation failed", 400, ["Email is required"]);
 
 ### Response Formatting
 
-Standardize API responses with consistent JSON structure and intelligent auto-sending.
+Standardize API responses with consistent JSON structure and callback-based chaining.
 
 ```typescript
-import { sendSuccess, sendError, send } from "devdad-express-utils";
+import { sendSuccess, sendError } from "devdad-express-utils";
 
-// Basic success response (auto-sends - no send() needed)
+// Basic success response
 sendSuccess(res, { id: 1, name: "John" }, "User fetched", 200);
 
-// Chain native Express methods (use send() when done chaining)
-sendSuccess(res, { id: 1, name: "John" }, "User fetched", 200)
-  .cookie("session", "abc123")
-  .setHeader("X-Custom", "value");
-send(res); // Send when ready
+// Chain methods using callbacks
+sendSuccess(res, { id: 1, name: "John" }, "User fetched", 200, [
+  (res) => res.cookie("session", "abc123"),
+  (res) => res.setHeader("X-Custom", "value")
+]);
 
 // Error response (sends immediately)
 sendError(res, "User not found", 404);
@@ -257,18 +257,18 @@ errorHandler(err: any, req: Request, res: Response, next: NextFunction) => void
 
 ### sendSuccess
 
-Prepares a standardized success response and returns response object for chaining.
+Sends a standardized success response with optional callbacks for chaining response methods.
 
 ```typescript
-sendSuccess(res: Response, data: any, message?: string, statusCode?: number) => Response
+sendSuccess(res: Response, data: any, message?: string, statusCode?: number, callbacks?: Array<(res: Response) => Response>) => Response
 ```
 
 **Features:**
 - Includes `success: true` field by default
-- **Auto-sends** when no chaining detected (no `send()` needed)
-- Returns Express response object for native method chaining
-- Use `send()` when chaining methods (explicit control)
-- No magic - intelligent and predictable
+- Supports chaining via callbacks array
+- Executes callbacks before sending response
+- No timing issues - predictable order
+- Clean and explicit approach
 
 ### sendError
 
@@ -283,23 +283,7 @@ sendError(res: Response, message: string, statusCode?: number, data?: any) => vo
 - Sends response immediately (no chaining needed for errors)
 - Supports optional error data
 
-### send
 
-Sends the prepared success response from `sendSuccess`. Only needed when chaining methods.
-
-```typescript
-send(res: Response) => void
-```
-
-**Features:**
-- Sends the response prepared by `sendSuccess`
-- **Only needed when chaining** (.cookie(), .header(), etc.)
-- Basic usage: sendSuccess() auto-sends, no send() needed
-- Explicit control over when response is sent
-
-**When to Use:**
-- ❌ Basic: `sendSuccess(res, data)` → NO send() needed
-- ✅ Chaining: `sendSuccess(res, data).cookie(...)` → send() needed
 
 ### connectDB
 

package/dist/DatabaseConnection.d.ts

@@ -46,8 +46,31 @@ declare class DatabaseConnection {
      */
     resetAndRetry(): Promise<void>;
 }
+/**
+ * Default export function to connect to MongoDB.
+ * Establishes a connection with automatic retry logic and reconnection handling.
+ *
+ * @example
+ * import connectDB from './DatabaseConnection';
+ * await connectDB(); // Connects using MONGO_URI from environment
+ */
 declare const _default: () => Promise<void>;
 export default _default;
+/**
+ * Gets the current database connection status.
+ *
+ * @returns {Object} Connection status information including:
+ * - isConnected: boolean - whether the database is connected
+ * - readyState: number - mongoose connection ready state
+ * - host: string - database host
+ * - name: string - database name
+ * - retryCount: number - current retry attempt count
+ *
+ * @example
+ * import { getDBStatus } from './DatabaseConnection';
+ * const status = getDBStatus();
+ * console.log('DB connected:', status.isConnected);
+ */
 export declare const getDBStatus: () => {
     isConnected: boolean;
     readyState: number;
@@ -55,5 +78,13 @@ export declare const getDBStatus: () => {
     name: string;
     retryCount: number;
 };
+/**
+ * Resets the connection state and attempts to reconnect.
+ * Useful for recovering from Docker container restarts or network issues.
+ *
+ * @example
+ * import { resetDBConnection } from './DatabaseConnection';
+ * await resetDBConnection(); // Reset retry count and reconnect
+ */
 export declare const resetDBConnection: () => Promise<void>;
 export { DatabaseConnection };

package/dist/DatabaseConnection.js

@@ -149,8 +149,38 @@ class DatabaseConnection {
 }
 // Create a singleton instance
 const dbConnection = new DatabaseConnection();
-// Export the connect function and the instance
+/**
+ * Default export function to connect to MongoDB.
+ * Establishes a connection with automatic retry logic and reconnection handling.
+ *
+ * @example
+ * import connectDB from './DatabaseConnection';
+ * await connectDB(); // Connects using MONGO_URI from environment
+ */
 export default dbConnection.connect.bind(dbConnection);
+/**
+ * Gets the current database connection status.
+ *
+ * @returns {Object} Connection status information including:
+ * - isConnected: boolean - whether the database is connected
+ * - readyState: number - mongoose connection ready state
+ * - host: string - database host
+ * - name: string - database name
+ * - retryCount: number - current retry attempt count
+ *
+ * @example
+ * import { getDBStatus } from './DatabaseConnection';
+ * const status = getDBStatus();
+ * console.log('DB connected:', status.isConnected);
+ */
 export const getDBStatus = dbConnection.getConnectionStatus.bind(dbConnection);
+/**
+ * Resets the connection state and attempts to reconnect.
+ * Useful for recovering from Docker container restarts or network issues.
+ *
+ * @example
+ * import { resetDBConnection } from './DatabaseConnection';
+ * await resetDBConnection(); // Reset retry count and reconnect
+ */
 export const resetDBConnection = dbConnection.resetAndRetry.bind(dbConnection);
 export { DatabaseConnection };

package/dist/index.d.ts

@@ -1,6 +1,34 @@
+/**
+ * Express Utils - A comprehensive utility library for Express.js applications
+ *
+ * This library provides essential utilities for building robust Express applications:
+ * - Error handling with custom AppError class and global error handler
+ * - Async error catching middleware
+ * - Response formatting with callback-based chaining
+ * - Database connection management with retry logic
+ * - Structured logging with Winston
+ */
+/**
+ * Custom error class for application errors with status codes and operational flags
+ */
 export { AppError } from "./AppError.js";
+/**
+ * Higher-order function to catch asynchronous errors in Express route handlers
+ */
 export { catchAsync } from "./catchAsync.js";
+/**
+ * Global error handler middleware for Express applications
+ */
 export { errorHandler } from "./errorHandler.js";
+/**
+ * Winston logger instance for structured application logging
+ */
 export { logger } from "./logger.js";
-export { sendSuccess, sendError, send } from "./responseFormatter.js";
-export { default as connectDB, getDBStatus, DatabaseConnection, } from "./DatabaseConnection.js";
+/**
+ * Response formatting utilities with callback-based method chaining
+ */
+export { sendSuccess, sendError } from "./responseFormatter.js";
+/**
+ * Database connection utilities for MongoDB with automatic retry logic
+ */
+export { default as connectDB, getDBStatus, resetDBConnection, DatabaseConnection, } from "./DatabaseConnection.js";

package/dist/index.js

@@ -1,6 +1,34 @@
+/**
+ * Express Utils - A comprehensive utility library for Express.js applications
+ *
+ * This library provides essential utilities for building robust Express applications:
+ * - Error handling with custom AppError class and global error handler
+ * - Async error catching middleware
+ * - Response formatting with callback-based chaining
+ * - Database connection management with retry logic
+ * - Structured logging with Winston
+ */
+/**
+ * Custom error class for application errors with status codes and operational flags
+ */
 export { AppError } from "./AppError.js";
+/**
+ * Higher-order function to catch asynchronous errors in Express route handlers
+ */
 export { catchAsync } from "./catchAsync.js";
+/**
+ * Global error handler middleware for Express applications
+ */
 export { errorHandler } from "./errorHandler.js";
+/**
+ * Winston logger instance for structured application logging
+ */
 export { logger } from "./logger.js";
-export { sendSuccess, sendError, send } from "./responseFormatter.js";
-export { default as connectDB, getDBStatus, DatabaseConnection, } from "./DatabaseConnection.js";
+/**
+ * Response formatting utilities with callback-based method chaining
+ */
+export { sendSuccess, sendError } from "./responseFormatter.js";
+/**
+ * Database connection utilities for MongoDB with automatic retry logic
+ */
+export { default as connectDB, getDBStatus, resetDBConnection, DatabaseConnection, } from "./DatabaseConnection.js";

package/dist/logger.d.ts

@@ -1,2 +1,18 @@
 import winston from "winston";
+/**
+ * Winston logger instance for application logging.
+ *
+ * Features:
+ * - Different log levels for production vs development
+ * - Console and file logging (in development)
+ * - JSON format for structured logging
+ * - Error stack trace capture
+ * - Custom service name via SERVICE_NAME environment variable
+ *
+ * @example
+ * // Basic logging
+ * logger.info("User logged in", { userId: 123 });
+ * logger.error("Database connection failed", { error: err });
+ * logger.debug("Processing request", { method: "POST", url: "/api/users" });
+ */
 export declare const logger: winston.Logger;

package/dist/logger.js

@@ -1,4 +1,20 @@
 import winston from "winston";
+/**
+ * Winston logger instance for application logging.
+ *
+ * Features:
+ * - Different log levels for production vs development
+ * - Console and file logging (in development)
+ * - JSON format for structured logging
+ * - Error stack trace capture
+ * - Custom service name via SERVICE_NAME environment variable
+ *
+ * @example
+ * // Basic logging
+ * logger.info("User logged in", { userId: 123 });
+ * logger.error("Database connection failed", { error: err });
+ * logger.debug("Processing request", { method: "POST", url: "/api/users" });
+ */
 export const logger = winston.createLogger({
     level: process.env.NODE_ENV === "production" ? "info" : "debug",
     format: winston.format.combine(winston.format.timestamp(), winston.format.errors({ stack: true }), winston.format.splat(), winston.format.json()),

package/dist/responseFormatter.d.ts

@@ -4,52 +4,36 @@ import { Response } from "express";
  *
  * Features:
  * - Includes success: true field by default
- * - **Auto-sends** when no chaining detected (no send() needed)
- * - Returns Express response object for native method chaining
- * - Use send() only when chaining methods (.cookie(), .header(), etc.)
+ * - **Auto-sends** when no callbacks provided
+ * - Supports method chaining through callback functions
  * - Clean and predictable approach
  *
  * @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.
+ * @param {((res: Response) => Response)[]} [callbacks] - Optional array of callback functions for chaining response methods.
+ * @returns {Response} The Express response object.
  *
  * @example
- * // Basic usage (auto-sends - no send() needed)
+ * // Basic usage (auto-sends - no callbacks needed)
  * sendSuccess(res, { userId: 123 }, "Login successful");
  *
  * @example
- * // Chain methods and send manually
- * sendSuccess(res, { userId: 123 }, "Login successful", 200)
- *   .cookie("authToken", "xyz789", { httpOnly: true })
- *   .header("X-Custom", "value");
- * send(res); // Send prepared response
+ * // Chain methods using callbacks
+ * sendSuccess(res, { userId: 123 }, "Login successful", 200, [
+ *   (res) => res.cookie("authToken", "xyz789", { httpOnly: true }),
+ *   (res) => res.header("X-Custom", "value")
+ * ]);
  *
  * @example
- * // Example Login Response
- * sendSuccess(res, { accesstoken, refreshToken, user }, "Login Successful", 200)
- *   .cookie("accessToken", accesstoken, HTTP_OPTIONS)
- *   .cookie("refreshToken", refreshToken, HTTP_OPTIONS);
- * send(res); // Send when ready
+ * // Example Login Response with multiple callbacks
+ * sendSuccess(res, { accesstoken, refreshToken, user }, "Login Successful", 200, [
+ *   (res) => res.cookie("accessToken", accesstoken, HTTP_OPTIONS),
+ *   (res) => res.cookie("refreshToken", refreshToken, HTTP_OPTIONS)
+ * ]);
  */
-export declare const sendSuccess: (res: Response, data: any, message?: string, statusCode?: number) => Response;
-/**
- * Sends the prepared success response.
- * Use this only when chaining methods (.cookie(), .header(), etc.).
- * For basic usage, sendSuccess() auto-sends and you don't need this.
- *
- * @param {Response} res - Express response object.
- * @returns {void}
- *
- * @example
- * // Only needed when chaining methods
- * sendSuccess(res, data, "Success", 200)
- *   .cookie("session", "abc123")
- *   .header("X-Custom", "value");
- * send(res); // Send when ready
- */
-export declare const send: (res: Response) => void;
+export declare const sendSuccess: (res: Response, data: any, message?: string, statusCode?: number, callbacks?: ((res: Response) => Response)[]) => Response;
 /**
  * Sends an error response immediately.
  *

package/dist/responseFormatter.js

@@ -3,71 +3,54 @@
  *
  * Features:
  * - Includes success: true field by default
- * - **Auto-sends** when no chaining detected (no send() needed)
- * - Returns Express response object for native method chaining
- * - Use send() only when chaining methods (.cookie(), .header(), etc.)
+ * - **Auto-sends** when no callbacks provided
+ * - Supports method chaining through callback functions
  * - Clean and predictable approach
  *
  * @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.
+ * @param {((res: Response) => Response)[]} [callbacks] - Optional array of callback functions for chaining response methods.
+ * @returns {Response} The Express response object.
  *
  * @example
- * // Basic usage (auto-sends - no send() needed)
+ * // Basic usage (auto-sends - no callbacks needed)
  * sendSuccess(res, { userId: 123 }, "Login successful");
  *
  * @example
- * // Chain methods and send manually
- * sendSuccess(res, { userId: 123 }, "Login successful", 200)
- *   .cookie("authToken", "xyz789", { httpOnly: true })
- *   .header("X-Custom", "value");
- * send(res); // Send prepared response
+ * // Chain methods using callbacks
+ * sendSuccess(res, { userId: 123 }, "Login successful", 200, [
+ *   (res) => res.cookie("authToken", "xyz789", { httpOnly: true }),
+ *   (res) => res.header("X-Custom", "value")
+ * ]);
  *
  * @example
- * // Example Login Response
- * sendSuccess(res, { accesstoken, refreshToken, user }, "Login Successful", 200)
- *   .cookie("accessToken", accesstoken, HTTP_OPTIONS)
- *   .cookie("refreshToken", refreshToken, HTTP_OPTIONS);
- * send(res); // Send when ready
+ * // Example Login Response with multiple callbacks
+ * sendSuccess(res, { accesstoken, refreshToken, user }, "Login Successful", 200, [
+ *   (res) => res.cookie("accessToken", accesstoken, HTTP_OPTIONS),
+ *   (res) => res.cookie("refreshToken", refreshToken, HTTP_OPTIONS)
+ * ]);
  */
-export const sendSuccess = (res, data, message = "Success", statusCode = 200) => {
+export const sendSuccess = (res, data, message = "Success", statusCode = 200, callbacks) => {
     const response = {
         status: "success",
         success: true,
         message,
         data,
     };
-    // Set status and store response for later sending
     res.status(statusCode);
-    res._responseData = response;
-    // Auto-send unless chaining is detected (using setImmediate to check)
-    setImmediate(() => {
-        if (!res._responseSent && res._responseData) {
-            res._responseSent = true;
-            res.json(res._responseData);
+    // Execute callbacks for chaining if provided
+    if (callbacks && callbacks.length > 0) {
+        let currentRes = res;
+        for (const callback of callbacks) {
+            if (typeof callback === 'function') {
+                currentRes = callback(currentRes);
+            }
         }
-    });
-    return res;
-};
-/**
- * Sends the prepared success response.
- * Use this only when chaining methods (.cookie(), .header(), etc.).
- * For basic usage, sendSuccess() auto-sends and you don't need this.
- *
- * @param {Response} res - Express response object.
- * @returns {void}
- *
- * @example
- * // Only needed when chaining methods
- * sendSuccess(res, data, "Success", 200)
- *   .cookie("session", "abc123")
- *   .header("X-Custom", "value");
- * send(res); // Send when ready
- */
-export const send = (res) => {
-    res.json(res._responseData);
+    }
+    // Send response
+    return res.json(response);
 };
 /**
  * Sends an error response immediately.

package/package.json

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