qapinterface/lib/error-handling/enhanced-error-factory.js

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

/**
 * Enhanced Error Factory with qerrors Integration
 * 
 * Provides improved error creation patterns using qerrors ErrorFactory
 * while maintaining backward compatibility with existing error handling.
 */

// Direct import to avoid circular dependency
let ErrorFactory, ErrorTypes, ErrorSeverity, createTypedError;

try {
  // Import error types and factories directly from qerrors
  const qerrorsErrorTypes = require('qerrors/lib/errorTypes');
  ErrorFactory = qerrorsErrorTypes.ErrorFactory;
  ErrorTypes = qerrorsErrorTypes.ErrorTypes;
  ErrorSeverity = qerrorsErrorTypes.ErrorSeverity;
  createTypedError = qerrorsErrorTypes.createTypedError;
} catch (error) {
  // Fallback error types if qerrors not available
  ErrorFactory = { validation: (msg) => ({ message: msg, statusCode: 400 }) };
  ErrorTypes = { 
    VALIDATION: 'validation', 
    AUTHENTICATION: 'authentication',
    AUTHORIZATION: 'authorization',
    NOT_FOUND: 'not_found',
    RATE_LIMIT: 'rate_limit',
    NETWORK: 'network',
    DATABASE: 'database',
    SYSTEM: 'system',
    CONFIGURATION: 'configuration'
  };
  ErrorSeverity = { LOW: 'low', MEDIUM: 'medium', HIGH: 'high', CRITICAL: 'critical' };
  createTypedError = (msg, type, context) => ({ message: msg, type, context });
}

/**
 * Enhanced error creation with automatic classification and logging
 * @param {string} message - Error message
 * @param {string} type - Error type from ErrorTypes
 * @param {string} context - Context where error occurred
 * @param {object} metadata - Additional error metadata
 * @returns {object} Enhanced error object
 */
function createEnhancedError(message, type = ErrorTypes.SYSTEM, context = 'unknown', metadata = {}) {
  const error = createTypedError(message, type, context);
  
  // Add enhanced metadata
  error.context = context;
  error.metadata = metadata;
  error.severity = getSeverityForType(type);
  error.timestamp = new Date().toISOString();
  
  return error;
}

/**
 * Get appropriate severity level for error type
 * @param {string} type - Error type
 * @returns {string} Severity level
 */
function getSeverityForType(type) {
  const severityMap = {
    [ErrorTypes.VALIDATION]: ErrorSeverity.LOW,
    [ErrorTypes.AUTHENTICATION]: ErrorSeverity.MEDIUM,
    [ErrorTypes.AUTHORIZATION]: ErrorSeverity.MEDIUM,
    [ErrorTypes.NOT_FOUND]: ErrorSeverity.LOW,
    [ErrorTypes.RATE_LIMIT]: ErrorSeverity.MEDIUM,
    [ErrorTypes.NETWORK]: ErrorSeverity.HIGH,
    [ErrorTypes.DATABASE]: ErrorSeverity.HIGH,
    [ErrorTypes.SYSTEM]: ErrorSeverity.HIGH,
    [ErrorTypes.CONFIGURATION]: ErrorSeverity.CRITICAL
  };
  
  return severityMap[type] || ErrorSeverity.MEDIUM;
}

/**
 * Create API validation error with enhanced context
 * @param {string} field - Field that failed validation
 * @param {string} value - Invalid value
 * @param {string} reason - Validation failure reason
 * @returns {object} Enhanced validation error
 */
function createValidationError(field, value, reason) {
  return createEnhancedError(
    `Validation failed for ${field}: ${reason}`,
    ErrorTypes.VALIDATION,
    'api_validation',
    { field, value, reason }
  );
}

/**
 * Create authentication error with security context
 * @param {string} reason - Authentication failure reason
 * @param {string} source - Authentication source (header, cookie, etc.)
 * @returns {object} Enhanced authentication error
 */
function createAuthenticationError(reason, source = 'unknown') {
  return createEnhancedError(
    `Authentication failed: ${reason}`,
    ErrorTypes.AUTHENTICATION,
    'authentication',
    { source, timestamp: Date.now() }
  );
}

/**
 * Create database error with query context
 * @param {string} operation - Database operation that failed
 * @param {Error} originalError - Original database error
 * @returns {object} Enhanced database error
 */
function createDatabaseError(operation, originalError) {
  return createEnhancedError(
    `Database operation failed: ${operation}`,
    ErrorTypes.DATABASE,
    'database',
    { 
      operation, 
      originalMessage: originalError?.message,
      code: originalError?.code
    }
  );
}

/**
 * Create network error with service context
 * @param {string} service - External service name
 * @param {number} statusCode - HTTP status code
 * @param {Error} originalError - Original network error
 * @returns {object} Enhanced network error
 */
function createNetworkError(service, statusCode, originalError) {
  return createEnhancedError(
    `External service error: ${service}`,
    ErrorTypes.NETWORK,
    'external_service',
    {
      service,
      statusCode,
      originalMessage: originalError?.message,
      retryable: statusCode >= 500 || statusCode === 429
    }
  );
}

module.exports = {
  createEnhancedError,
  createValidationError,
  createAuthenticationError,
  createDatabaseError,
  createNetworkError,
  getSeverityForType,
  
  // Re-export qerrors functionality
  ErrorFactory,
  ErrorTypes,
  ErrorSeverity
};