devdad-express-utils 1.7.0 → 1.7.1

package/README.md

@@ -54,21 +54,21 @@ throw new AppError("Validation failed", 400, ["Email is required"]);
 
 ### Response Formatting
 
-Standardize API responses with consistent JSON structure and automatic response sending.
+Standardize API responses with consistent JSON structure and intelligent auto-sending.
 
 ```typescript
-import { sendSuccess, sendError } from "devdad-express-utils";
+import { sendSuccess, sendError, send } from "devdad-express-utils";
 
-// Success response
+// Basic success response (auto-sends - no send() needed)
 sendSuccess(res, { id: 1, name: "John" }, "User fetched", 200);
 
-// Chain additional response methods
-sendSuccess(res, { id: 1, name: "John" })
+// 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");
-// Response sent automatically! 🎉
+send(res); // Send when ready
 
-// Error response
+// Error response (sends immediately)
 sendError(res, "User not found", 404);
 ```
 
@@ -99,14 +99,14 @@ All responses include a `success` field by default:
 
 #### Method Chaining
 
-`sendSuccess` returns the Express response object, allowing you to chain any Express response methods:
+`sendSuccess` returns the Express response object for native chaining:
 
 ```typescript
 sendSuccess(res, { token: "abc123" }, "Login successful", 200)
-  .cookie("authToken", "abc123", { httpOnly: true, secure: true })
+  .cookie("authToken", "abc123", { httpOnly: true })
   .header("X-Rate-Limit-Remaining", "99")
-  .status(200); // Can even override status
-// Response automatically sent after chaining completes
+  .status(201); // Can even override status
+send(res); // Send the prepared response
 ```
 
 ### Database Connection
@@ -257,18 +257,18 @@ errorHandler(err: any, req: Request, res: Response, next: NextFunction) => void
 
 ### sendSuccess
 
-Sends a standardized success response with automatic sending after method chaining. Returns the Response object for chaining Express response methods like `.cookie()`, `.header()`, etc.
+Prepares a standardized success response and returns response object for chaining.
 
 ```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
+- **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
 
 ### sendError
 
@@ -279,9 +279,27 @@ sendError(res: Response, message: string, statusCode?: number, data?: any) => vo
 ```
 
 **Features:**
-
 - Includes `success: false` field by default
 - 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/index.d.ts

@@ -2,5 +2,5 @@ export { AppError } from "./AppError.js";
 export { catchAsync } from "./catchAsync.js";
 export { errorHandler } from "./errorHandler.js";
 export { logger } from "./logger.js";
-export { sendSuccess, sendError } from "./responseFormatter.js";
+export { sendSuccess, sendError, send } from "./responseFormatter.js";
 export { default as connectDB, getDBStatus, DatabaseConnection, } from "./DatabaseConnection.js";

package/dist/index.js

@@ -2,5 +2,5 @@ export { AppError } from "./AppError.js";
 export { catchAsync } from "./catchAsync.js";
 export { errorHandler } from "./errorHandler.js";
 export { logger } from "./logger.js";
-export { sendSuccess, sendError } from "./responseFormatter.js";
+export { sendSuccess, sendError, send } from "./responseFormatter.js";
 export { default as connectDB, getDBStatus, DatabaseConnection, } from "./DatabaseConnection.js";

package/dist/responseFormatter.d.ts

@@ -1,13 +1,13 @@
 import { Response } from "express";
 /**
- * Sends a success response and returns the response object for chaining.
- * Automatically sends the response after chaining operations complete - no extra .send() needed!
+ * Sends a success response with intelligent auto-sending behavior.
  *
  * 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
+ * - **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.)
+ * - Clean and predictable approach
  *
  * @param {Response} res - Express response object.
  * @param {any} data - Response data.
@@ -16,17 +16,40 @@ import { Response } from "express";
  * @returns {Response} The Express response object for chaining.
  *
  * @example
- * // Basic usage
+ * // Basic usage (auto-sends - no send() needed)
  * sendSuccess(res, { userId: 123 }, "Login successful");
  *
  * @example
- * // Chain methods without calling .send()
+ * // Chain methods and send manually
  * sendSuccess(res, { userId: 123 }, "Login successful", 200)
  *   .cookie("authToken", "xyz789", { httpOnly: true })
  *   .header("X-Custom", "value");
- * // Response sent automatically!
+ * send(res); // Send prepared response
+ *
+ * @example
+ * // Your exact use case
+ * sendSuccess(res, { accesstoken, refreshToken, user }, "Login Successful", 200)
+ *   .cookie("accessToken", accesstoken, HTTP_OPTIONS)
+ *   .cookie("refreshToken", refreshToken, HTTP_OPTIONS);
+ * send(res); // Send when ready
  */
 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;
 /**
  * Sends an error response immediately.
  *

package/dist/responseFormatter.js

@@ -1,12 +1,12 @@
 /**
- * Sends a success response and returns the response object for chaining.
- * Automatically sends the response after chaining operations complete - no extra .send() needed!
+ * Sends a success response with intelligent auto-sending behavior.
  *
  * 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
+ * - **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.)
+ * - Clean and predictable approach
  *
  * @param {Response} res - Express response object.
  * @param {any} data - Response data.
@@ -15,15 +15,22 @@
  * @returns {Response} The Express response object for chaining.
  *
  * @example
- * // Basic usage
+ * // Basic usage (auto-sends - no send() needed)
  * sendSuccess(res, { userId: 123 }, "Login successful");
  *
  * @example
- * // Chain methods without calling .send()
+ * // Chain methods and send manually
  * sendSuccess(res, { userId: 123 }, "Login successful", 200)
  *   .cookie("authToken", "xyz789", { httpOnly: true })
  *   .header("X-Custom", "value");
- * // Response sent automatically!
+ * send(res); // Send prepared response
+ *
+ * @example
+ * // Your exact use case
+ * sendSuccess(res, { accesstoken, refreshToken, user }, "Login Successful", 200)
+ *   .cookie("accessToken", accesstoken, HTTP_OPTIONS)
+ *   .cookie("refreshToken", refreshToken, HTTP_OPTIONS);
+ * send(res); // Send when ready
  */
 export const sendSuccess = (res, data, message = "Success", statusCode = 200) => {
     const response = {
@@ -32,16 +39,36 @@ export const sendSuccess = (res, data, message = "Success", statusCode = 200) =>
         message,
         data,
     };
+    // Set status and store response for later sending
     res.status(statusCode);
-    // Use setImmediate to send response after current execution stack
+    res._responseData = response;
+    // Auto-send unless chaining is detected (using setImmediate to check)
     setImmediate(() => {
-        if (!res._responseSent) {
+        if (!res._responseSent && res._responseData) {
             res._responseSent = true;
-            res.json(response);
+            res.json(res._responseData);
         }
     });
     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);
+};
 /**
  * Sends an error response immediately.
  *

package/package.json

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