devdad-express-utils 1.8.0 → 1.8.1

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";
+/**
+ * Response formatting utilities with callback-based method chaining
+ */
 export { sendSuccess, sendError } from "./responseFormatter.js";
-export { default as connectDB, getDBStatus, DatabaseConnection, } from "./DatabaseConnection.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";
+/**
+ * Response formatting utilities with callback-based method chaining
+ */
 export { sendSuccess, sendError } from "./responseFormatter.js";
-export { default as connectDB, getDBStatus, DatabaseConnection, } from "./DatabaseConnection.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,34 +4,34 @@ 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, callbacks?: ((res: Response) => Response)[]) => Response;
 /**

package/dist/responseFormatter.js

@@ -3,34 +3,34 @@
  *
  * 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, callbacks) => {
     const response = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "devdad-express-utils",
-  "version": "1.8.0",
+  "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",