devdad-express-utils 1.6.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,17 +66,59 @@ 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, exponential backoff, and configurable retry logic.
 
 ```typescript
-import { connectDB, getDBStatus, resetDBConnection } from "devdad-express-utils";
+import {
+  connectDB,
+  getDBStatus,
+  resetDBConnection,
+} from "devdad-express-utils";
 
 // Connect to MongoDB (ensure MONGO_URI is set in environment)
 await connectDB();
@@ -215,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.

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.6.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",