qapinterface/lib/http/error-response-creator.js

Comprehensive API utilities for Node.js applications including authentication, security, request processing, and response handling with zero external dependencies

/**
 * Standardized API Error Response Factory
 * 
 * SINGLE RESPONSIBILITY: Create consistent error response objects for all API endpoints ONLY
 * 
 * ERROR HANDLING PHILOSOPHY:
 * Consistent error responses are critical for robust client applications. This module
 * ensures that all API errors follow the same structure, enabling predictable error
 * handling patterns and improved debugging capabilities.
 * 
 * SECURITY CONSIDERATIONS:
 * Error responses must balance helpful debugging information with security concerns:
 * - Never expose internal system details or stack traces
 * - Provide enough context for legitimate debugging
 * - Use consistent error codes for automated error handling
 * - Include validation details to help correct malformed requests
 * 
 * DESIGN DECISIONS:
 * - Nested error object separates error details from response metadata
 * - Optional issues array supports detailed validation error reporting
 * - Consistent timestamp format matches success responses
 * - Status code inclusion enables proper HTTP response handling
 * 
 * ERROR STRUCTURE RATIONALE:
 * The nested error object prevents confusion between response metadata
 * and error details, making it clear what data represents the actual error
 * versus response processing information.
 */

/**
 * Creates a standardized error response with consistent structure and security-conscious design.
 * 
 * RESPONSE STRUCTURE:
 * {
 *   success: false,                    // Boolean flag for programmatic error checking
 *   error: {                          // Nested error details object
 *     message: string,                 // Human-readable error description
 *     statusCode: number,              // HTTP status code for proper response handling
 *     issues?: Array                   // Optional detailed validation issues
 *   },
 *   timestamp: string                  // ISO timestamp for audit trails
 * }
 * 
 * MESSAGE GUIDELINES:
 * - Should be descriptive but not expose internal system details
 * - Safe for client display and logging
 * - Specific enough for debugging but generic enough for security
 * 
 * STATUS CODE USAGE:
 * - 400-499: Client errors (malformed requests, authentication, etc.)
 * - 500-599: Server errors (internal failures, service unavailable, etc.)
 * - Default 500 assumes internal server error when not specified
 * 
 * @param {string} message - Descriptive error message safe for client consumption
 * @param {number} [statusCode=500] - HTTP status code appropriate for the error type
 * @param {Array<object>} [issues=null] - Optional detailed validation or processing issues
 * @returns {object} Standardized error response object with nested error details
 */
function createErrorResponse(message, statusCode = 500, issues = null) {
  // Base response structure: Consistent with success responses but success=false
  const response = {
    // Success indicator: Always false for error responses
    // Provides immediate programmatic error detection for clients
    success: false,
    
    // Error details: Nested object containing all error-specific information
    error: {
      // Message: Human-readable error description
      // Should be safe for client display and logging
      message,
      
      // Status code: HTTP status code for proper response handling
      // Enables correct client-side error categorization and retry logic
      statusCode,
    },
    
    // Timestamp: ISO 8601 formatted creation time for audit trails
    // Generated at response creation for accurate error timing
    timestamp: new Date().toISOString(),
  };
  
  // Issues injection: Add detailed validation errors only when provided
  // Conditional to avoid empty issues arrays in the response
  if (issues) {
    // Issues array: Detailed breakdown of validation or processing problems
    // Helps clients identify specific fields or values that need correction
    response.error.issues = issues;
  }
  
  return response;
}

module.exports = {
  createErrorResponse
};