@onlineapps/conn-infra-error-handler 1.0.0

package/src/index.js

@@ -0,0 +1,822 @@
+/**
+ * @module @onlineapps/conn-infra-error-handler
+ * @description Unified error handling connector providing retry strategies, circuit breaker pattern,
+ * and compensation mechanisms for OA Drive microservices.
+ *
+ * @see {@link https://github.com/onlineapps/oa-drive/tree/main/shared/connector/conn-infra-error-handler|GitHub Repository}
+ * @author OA Drive Team
+ * @license MIT
+ * @since 1.0.0
+ */
+
+const CircuitBreaker = require('opossum');
+
+// Error types enum
+const ErrorTypes = {
+  TRANSIENT: 'TRANSIENT',      // Retry with backoff
+  BUSINESS: 'BUSINESS',        // Don't retry, return error
+  FATAL: 'FATAL',              // Stop workflow
+  VALIDATION: 'VALIDATION',    // Input validation error
+  TIMEOUT: 'TIMEOUT',          // Operation timeout
+  RATE_LIMIT: 'RATE_LIMIT',    // Rate limiting
+  UNKNOWN: 'UNKNOWN'           // Unclassified error
+};
+
+// Standard error codes
+const ErrorCodes = {
+  // Network errors
+  ECONNREFUSED: ErrorTypes.TRANSIENT,
+  ENOTFOUND: ErrorTypes.TRANSIENT,
+  ETIMEDOUT: ErrorTypes.TRANSIENT,
+  ECONNRESET: ErrorTypes.TRANSIENT,
+  EPIPE: ErrorTypes.TRANSIENT,
+
+  // HTTP status codes
+  408: ErrorTypes.TIMEOUT,
+  429: ErrorTypes.RATE_LIMIT,
+  500: ErrorTypes.TRANSIENT,
+  502: ErrorTypes.TRANSIENT,
+  503: ErrorTypes.TRANSIENT,
+  504: ErrorTypes.TIMEOUT,
+
+  // Business errors
+  400: ErrorTypes.VALIDATION,
+  401: ErrorTypes.BUSINESS,
+  403: ErrorTypes.BUSINESS,
+  404: ErrorTypes.BUSINESS,
+  409: ErrorTypes.BUSINESS,
+  422: ErrorTypes.VALIDATION
+};
+
+/**
+ * Error handling connector with retry, circuit breaker, and compensation
+ *
+ * @class ErrorHandlerConnector
+ *
+ * @example <caption>Basic Usage</caption>
+ * const errorHandler = new ErrorHandlerConnector({
+ *   maxRetries: 3,
+ *   retryDelay: 1000
+ * });
+ *
+ * const result = await errorHandler.executeWithRetry(async () => {
+ *   return await riskyOperation();
+ * });
+ *
+ * @example <caption>With Circuit Breaker</caption>
+ * const errorHandler = new ErrorHandlerConnector({
+ *   circuitBreakerEnabled: true,
+ *   errorThreshold: 50
+ * });
+ *
+ * await errorHandler.executeWithCircuitBreaker('api-call', async () => {
+ *   return await apiClient.call();
+ * });
+ */
+class ErrorHandlerConnector {
+  /**
+   * Creates a new ErrorHandlerConnector instance
+   *
+   * @constructor
+   * @param {Object} [config={}] - Configuration options
+   * @param {number} [config.maxRetries=3] - Maximum retry attempts
+   * @param {number} [config.retryDelay=1000] - Initial retry delay in ms
+   * @param {number} [config.retryMultiplier=2] - Backoff multiplier
+   * @param {number} [config.maxRetryDelay=30000] - Maximum retry delay
+   * @param {boolean} [config.circuitBreakerEnabled=true] - Enable circuit breaker
+   * @param {number} [config.circuitTimeout=10000] - Circuit breaker timeout
+   * @param {number} [config.errorThreshold=50] - Error threshold percentage
+   * @param {number} [config.resetTimeout=30000] - Circuit reset timeout
+   * @param {boolean} [config.compensationEnabled=true] - Enable compensation
+   * @param {Object} [config.circuitBreakerOptions] - Additional circuit breaker options
+   *
+   * @example <caption>Full Configuration</caption>
+   * const errorHandler = new ErrorHandlerConnector({
+   *   maxRetries: 5,
+   *   retryDelay: 500,
+   *   retryMultiplier: 1.5,
+   *   maxRetryDelay: 20000,
+   *   circuitBreakerEnabled: true,
+   *   errorThreshold: 60,
+   *   compensationEnabled: true
+   * });
+   */
+  constructor(config = {}) {
+    // Retry configuration
+    this.maxRetries = config.maxRetries || 3;
+    this.retryDelay = config.retryDelay || 1000;
+    this.retryMultiplier = config.retryMultiplier || 2;
+    this.maxRetryDelay = config.maxRetryDelay || 30000;
+
+    // Circuit breaker configuration
+    this.circuitBreakerEnabled = config.circuitBreakerEnabled !== false;
+    this.circuitBreakerOptions = {
+      timeout: config.circuitTimeout || 10000,
+      errorThresholdPercentage: config.errorThreshold || 50,
+      resetTimeout: config.resetTimeout || 30000,
+      rollingCountTimeout: config.rollingCountTimeout || 10000,
+      rollingCountBuckets: config.rollingCountBuckets || 10,
+      ...config.circuitBreakerOptions
+    };
+
+    // Compensation configuration
+    this.compensationEnabled = config.compensationEnabled !== false;
+    this.compensationHandlers = new Map();
+
+    // Circuit breakers registry
+    this.circuitBreakers = new Map();
+
+    // Error statistics
+    this.stats = {
+      errors: 0,
+      retries: 0,
+      compensations: 0,
+      circuitBreaks: 0,
+      byType: {}
+    };
+
+    // Initialize error type stats
+    Object.values(ErrorTypes).forEach(type => {
+      this.stats.byType[type] = 0;
+    });
+  }
+
+  /**
+   * Classify error into type for appropriate handling
+   *
+   * @method classifyError
+   * @param {Error} error - Error to classify
+   * @param {string} [error.code] - Error code (e.g., ECONNREFUSED)
+   * @param {number} [error.statusCode] - HTTP status code
+   * @param {string} [error.type] - Explicit error type
+   * @returns {string} Error type from ErrorTypes enum
+   *
+   * @example <caption>Network Error</caption>
+   * const type = errorHandler.classifyError(new Error('ECONNREFUSED'));
+   * // Returns: 'TRANSIENT'
+   *
+   * @example <caption>HTTP Error</caption>
+   * const error = new Error('Not Found');
+   * error.statusCode = 404;
+   * const type = errorHandler.classifyError(error);
+   * // Returns: 'BUSINESS'
+   *
+   * @example <caption>Timeout Error</caption>
+   * const type = errorHandler.classifyError(new Error('Operation timeout'));
+   * // Returns: 'TIMEOUT'
+   */
+  classifyError(error) {
+    // Check by error code
+    if (error.code && ErrorCodes[error.code]) {
+      return ErrorCodes[error.code];
+    }
+
+    // Check by HTTP status
+    if (error.statusCode && ErrorCodes[error.statusCode]) {
+      return ErrorCodes[error.statusCode];
+    }
+
+    // Check by error message patterns
+    const message = error.message?.toLowerCase() || '';
+
+    if (message.includes('timeout')) return ErrorTypes.TIMEOUT;
+    if (message.includes('rate limit')) return ErrorTypes.RATE_LIMIT;
+    if (message.includes('validation')) return ErrorTypes.VALIDATION;
+    if (message.includes('unauthorized') || message.includes('forbidden')) {
+      return ErrorTypes.BUSINESS;
+    }
+    if (message.includes('connection') || message.includes('network')) {
+      return ErrorTypes.TRANSIENT;
+    }
+
+    // Check if error has explicit type
+    if (error.type && ErrorTypes[error.type]) {
+      return error.type;
+    }
+
+    return ErrorTypes.UNKNOWN;
+  }
+
+  /**
+   * Determine if error should be retried
+   *
+   * @method shouldRetry
+   * @param {Error} error - Error to check
+   * @param {number} [attempts=0] - Current attempt count
+   * @returns {boolean} True if should retry
+   *
+   * @example
+   * const error = new Error('Connection refused');
+   * if (errorHandler.shouldRetry(error, 1)) {
+   *   // Retry the operation
+   * }
+   */
+  shouldRetry(error, attempts = 0) {
+    if (attempts >= this.maxRetries) {
+      return false;
+    }
+
+    const errorType = this.classifyError(error);
+
+    // Only retry transient and timeout errors
+    return [
+      ErrorTypes.TRANSIENT,
+      ErrorTypes.TIMEOUT,
+      ErrorTypes.RATE_LIMIT
+    ].includes(errorType);
+  }
+
+  /**
+   * Calculate exponential backoff delay
+   *
+   * @method calculateBackoff
+   * @param {number} attempts - Current attempt number (1-based)
+   * @returns {number} Delay in milliseconds
+   *
+   * @example
+   * const delay = errorHandler.calculateBackoff(3);
+   * // With default config: 1000 * 2^2 = 4000ms
+   */
+  calculateBackoff(attempts) {
+    const delay = this.retryDelay * Math.pow(this.retryMultiplier, attempts - 1);
+    return Math.min(delay, this.maxRetryDelay);
+  }
+
+  /**
+   * Execute function with automatic retry on failure
+   *
+   * @async
+   * @method executeWithRetry
+   * @param {Function} fn - Async function to execute
+   * @param {Object} [options={}] - Retry options
+   * @param {number} [options.maxRetries] - Override max retries
+   * @param {Array<string>} [options.retryOn=[]] - Additional error codes to retry
+   * @param {Function} [options.onRetry] - Callback on retry (error, attempt, delay)
+   * @returns {Promise<*>} Function result
+   *
+   * @throws {Error} Last error if all retries fail
+   *
+   * @example <caption>Simple Retry</caption>
+   * const result = await errorHandler.executeWithRetry(async () => {
+   *   return await apiClient.fetchData();
+   * });
+   *
+   * @example <caption>With Options</caption>
+   * const result = await errorHandler.executeWithRetry(
+   *   async () => await riskyOperation(),
+   *   {
+   *     maxRetries: 5,
+   *     retryOn: ['CUSTOM_ERROR'],
+   *     onRetry: (error, attempt, delay) => {
+   *       console.log(`Retry ${attempt} after ${delay}ms`);
+   *     }
+   *   }
+   * );
+   *
+   * @example <caption>Database Operation</caption>
+   * const data = await errorHandler.executeWithRetry(async () => {
+   *   const conn = await db.connect();
+   *   try {
+   *     return await conn.query('SELECT * FROM users');
+   *   } finally {
+   *     conn.close();
+   *   }
+   * });
+   */
+  async executeWithRetry(fn, options = {}) {
+    const maxAttempts = options.maxRetries || this.maxRetries;
+    const retryOn = options.retryOn || [];
+
+    let lastError;
+
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+      try {
+        return await fn();
+      } catch (error) {
+        lastError = error;
+        this.stats.errors++;
+        this.stats.byType[this.classifyError(error)]++;
+
+        // Check if should retry
+        const shouldRetry = this.shouldRetry(error, attempt) ||
+                           retryOn.includes(error.code);
+
+        if (!shouldRetry || attempt === maxAttempts) {
+          throw error;
+        }
+
+        // Calculate and wait backoff
+        const delay = this.calculateBackoff(attempt);
+        this.stats.retries++;
+
+        if (options.onRetry) {
+          options.onRetry(error, attempt, delay);
+        }
+
+        await this.sleep(delay);
+      }
+    }
+
+    throw lastError;
+  }
+
+  /**
+   * Get or create circuit breaker for operation
+   * @param {string} name - Operation name
+   * @param {Function} fn - Function to protect
+   * @param {object} options - Circuit breaker options
+   * @returns {CircuitBreaker} Circuit breaker instance
+   */
+  getCircuitBreaker(name, fn, options = {}) {
+    if (!this.circuitBreakerEnabled) {
+      // Return pass-through if disabled
+      return { fire: () => fn() };
+    }
+
+    if (!this.circuitBreakers.has(name)) {
+      const breaker = new CircuitBreaker(fn, {
+        ...this.circuitBreakerOptions,
+        ...options
+      });
+
+      // Track circuit breaker events
+      breaker.on('open', () => {
+        this.stats.circuitBreaks++;
+        console.warn(`Circuit breaker opened: ${name}`);
+      });
+
+      breaker.on('halfOpen', () => {
+        console.info(`Circuit breaker half-open: ${name}`);
+      });
+
+      this.circuitBreakers.set(name, breaker);
+    }
+
+    return this.circuitBreakers.get(name);
+  }
+
+  /**
+   * Execute function with circuit breaker protection
+   *
+   * @async
+   * @method executeWithCircuitBreaker
+   * @param {string} name - Operation name for circuit breaker
+   * @param {Function} fn - Async function to execute
+   * @param {Object} [options={}] - Circuit breaker options
+   * @param {number} [options.timeout] - Operation timeout
+   * @param {number} [options.errorThresholdPercentage] - Error threshold
+   * @returns {Promise<*>} Function result
+   *
+   * @throws {Error} If circuit is open or operation fails
+   *
+   * @fires CircuitBreaker#open - When circuit opens
+   * @fires CircuitBreaker#halfOpen - When circuit enters half-open state
+   *
+   * @example <caption>API Call Protection</caption>
+   * try {
+   *   const data = await errorHandler.executeWithCircuitBreaker(
+   *     'user-api',
+   *     async () => await userAPI.getUser(id)
+   *   );
+   * } catch (error) {
+   *   if (error.message.includes('circuit is open')) {
+   *     // Service is down, use fallback
+   *   }
+   * }
+   *
+   * @example <caption>With Custom Options</caption>
+   * const result = await errorHandler.executeWithCircuitBreaker(
+   *   'payment-gateway',
+   *   async () => await processPayment(order),
+   *   {
+   *     timeout: 5000,
+   *     errorThresholdPercentage: 30
+   *   }
+   * );
+   */
+  async executeWithCircuitBreaker(name, fn, options = {}) {
+    const breaker = this.getCircuitBreaker(name, fn, options);
+
+    try {
+      return await breaker.fire();
+    } catch (error) {
+      this.stats.errors++;
+      this.stats.byType[this.classifyError(error)]++;
+
+      if (error.code === 'EOPENBREAKER') {
+        throw new Error(`Service unavailable: ${name} circuit is open`);
+      }
+
+      throw error;
+    }
+  }
+
+  /**
+   * Register compensation handler for an operation
+   *
+   * @method registerCompensation
+   * @param {string} operation - Operation name
+   * @param {Function} handler - Compensation handler function
+   * @returns {void}
+   *
+   * @example
+   * errorHandler.registerCompensation('create-order', async (context) => {
+   *   // Rollback order creation
+   *   await orderService.cancel(context.orderId);
+   * });
+   *
+   * errorHandler.registerCompensation('charge-payment', async (context) => {
+   *   // Refund payment
+   *   await paymentService.refund(context.chargeId);
+   * });
+   */
+  registerCompensation(operation, handler) {
+    this.compensationHandlers.set(operation, handler);
+  }
+
+  /**
+   * Execute compensation for failed operation
+   *
+   * @async
+   * @method executeCompensation
+   * @param {string} operation - Operation that failed
+   * @param {Object} context - Operation context for compensation
+   * @returns {Promise<*>} Compensation result or null if no handler
+   *
+   * @throws {Error} If compensation fails
+   *
+   * @example
+   * try {
+   *   await createOrder(data);
+   * } catch (error) {
+   *   await errorHandler.executeCompensation('create-order', {
+   *     orderId: data.orderId,
+   *     userId: data.userId
+   *   });
+   * }
+   */
+  async executeCompensation(operation, context) {
+    if (!this.compensationEnabled) {
+      return null;
+    }
+
+    const handler = this.compensationHandlers.get(operation);
+
+    if (!handler) {
+      console.warn(`No compensation handler for: ${operation}`);
+      return null;
+    }
+
+    try {
+      this.stats.compensations++;
+      const result = await handler(context);
+      console.info(`Compensation executed for: ${operation}`);
+      return result;
+    } catch (error) {
+      console.error(`Compensation failed for ${operation}:`, error);
+      throw error;
+    }
+  }
+
+  /**
+   * Route failed message to dead letter queue
+   *
+   * @async
+   * @method routeToDLQ
+   * @param {Object} mqClient - Message queue client
+   * @param {Object} message - Original message that failed
+   * @param {Error} error - Error that occurred
+   * @returns {Promise<void>}
+   *
+   * @example
+   * try {
+   *   await processMessage(message);
+   * } catch (error) {
+   *   if (!errorHandler.shouldRetry(error)) {
+   *     await errorHandler.routeToDLQ(mqClient, message, error);
+   *   }
+   * }
+   */
+  async routeToDLQ(mqClient, message, error) {
+    const dlqMessage = {
+      ...message,
+      error: {
+        message: error.message,
+        stack: error.stack,
+        code: error.code,
+        type: this.classifyError(error),
+        timestamp: new Date().toISOString()
+      },
+      originalQueue: message.queue || 'unknown',
+      retryCount: message.retryCount || 0
+    };
+
+    const dlqName = `${message.queue || 'unknown'}.dlq`;
+
+    await mqClient.publish(dlqName, dlqMessage, {
+      persistent: true
+    });
+
+    console.info(`Message routed to DLQ: ${dlqName}`);
+  }
+
+  /**
+   * Create standardized error response
+   *
+   * @method createErrorResponse
+   * @param {Error} error - Original error
+   * @param {Object} [context={}] - Additional context
+   * @returns {ErrorResponse} Formatted error response
+   *
+   * @example
+   * const response = errorHandler.createErrorResponse(
+   *   new Error('Database connection failed'),
+   *   { operation: 'user-fetch', userId: 123 }
+   * );
+   * // Returns standardized error object
+   */
+  createErrorResponse(error, context = {}) {
+    const errorType = this.classifyError(error);
+
+    return {
+      success: false,
+      error: {
+        message: error.message,
+        code: error.code || 'UNKNOWN_ERROR',
+        type: errorType,
+        retryable: this.shouldRetry(error),
+        timestamp: new Date().toISOString(),
+        ...context
+      }
+    };
+  }
+
+  /**
+   * Wrap function with error handling capabilities
+   *
+   * @method wrap
+   * @param {Function} fn - Function to wrap
+   * @param {Object} [options={}] - Wrapping options
+   * @param {string} [options.name] - Operation name
+   * @param {boolean} [options.circuitBreaker=true] - Use circuit breaker
+   * @param {boolean} [options.retry=true] - Use retry logic
+   * @param {number} [options.maxRetries] - Max retry attempts
+   * @returns {Function} Wrapped function
+   *
+   * @example <caption>Wrap API Function</caption>
+   * const safeApiCall = errorHandler.wrap(
+   *   async (id) => await api.getUser(id),
+   *   { name: 'get-user', maxRetries: 3 }
+   * );
+   *
+   * const user = await safeApiCall(123);
+   *
+   * @example <caption>Wrap Database Function</caption>
+   * const safeQuery = errorHandler.wrap(
+   *   async (sql, params) => await db.query(sql, params),
+   *   { circuitBreaker: false, retry: true }
+   * );
+   */
+  wrap(fn, options = {}) {
+    const name = options.name || fn.name || 'wrapped';
+    const useCircuitBreaker = options.circuitBreaker !== false;
+    const useRetry = options.retry !== false;
+
+    return async (...args) => {
+      const execute = async () => {
+        if (useRetry) {
+          return await this.executeWithRetry(() => fn(...args), options);
+        }
+        return await fn(...args);
+      };
+
+      if (useCircuitBreaker) {
+        return await this.executeWithCircuitBreaker(name, execute, options);
+      }
+
+      return await execute();
+    };
+  }
+
+  /**
+   * Handle workflow error with compensation support
+   *
+   * @async
+   * @method handleWorkflowError
+   * @param {Object} workflow - Workflow context
+   * @param {Error} error - Error that occurred
+   * @param {string} failedStep - Step that failed
+   * @returns {Promise<WorkflowErrorResult>} Error handling result
+   *
+   * @example
+   * const result = await errorHandler.handleWorkflowError(
+   *   workflowContext,
+   *   error,
+   *   'payment-processing'
+   * );
+   *
+   * if (result.shouldRetry) {
+   *   // Retry the step
+   * } else if (result.compensated) {
+   *   // Compensation was executed
+   * }
+   */
+  async handleWorkflowError(workflow, error, failedStep) {
+    const errorType = this.classifyError(error);
+
+    const result = {
+      handled: false,
+      compensated: false,
+      shouldContinue: false,
+      shouldRetry: false,
+      error: this.createErrorResponse(error, { step: failedStep })
+    };
+
+    // Determine action based on error type
+    switch (errorType) {
+      case ErrorTypes.TRANSIENT:
+      case ErrorTypes.TIMEOUT:
+        result.shouldRetry = true;
+        result.handled = true;
+        break;
+
+      case ErrorTypes.BUSINESS:
+      case ErrorTypes.VALIDATION:
+        // Try compensation
+        if (this.compensationEnabled && workflow.compensationSteps) {
+          try {
+            await this.executeCompensation(failedStep, workflow);
+            result.compensated = true;
+            result.handled = true;
+          } catch (compError) {
+            console.error('Compensation failed:', compError);
+          }
+        }
+        break;
+
+      case ErrorTypes.FATAL:
+        // Stop workflow immediately
+        result.shouldContinue = false;
+        result.handled = true;
+        break;
+
+      default:
+        // Unknown error, let it propagate
+        break;
+    }
+
+    return result;
+  }
+
+  /**
+   * Get error handler statistics
+   *
+   * @method getStats
+   * @returns {ErrorStats} Current statistics
+   *
+   * @example
+   * const stats = errorHandler.getStats();
+   * console.log(`Total errors: ${stats.errors}`);
+   * console.log(`Retry success rate: ${stats.retries / stats.errors * 100}%`);
+   * console.log(`Circuit breakers:`, stats.circuitBreakers);
+   */
+  getStats() {
+    const circuitBreakerStats = {};
+
+    this.circuitBreakers.forEach((breaker, name) => {
+      circuitBreakerStats[name] = {
+        state: breaker.opened ? 'open' : breaker.halfOpen ? 'half-open' : 'closed',
+        stats: breaker.stats
+      };
+    });
+
+    return {
+      ...this.stats,
+      circuitBreakers: circuitBreakerStats
+    };
+  }
+
+  /**
+   * Reset all statistics
+   *
+   * @method resetStats
+   * @returns {void}
+   *
+   * @example
+   * errorHandler.resetStats();
+   * // All counters reset to 0
+   */
+  resetStats() {
+    this.stats = {
+      errors: 0,
+      retries: 0,
+      compensations: 0,
+      circuitBreaks: 0,
+      byType: {}
+    };
+
+    Object.values(ErrorTypes).forEach(type => {
+      this.stats.byType[type] = 0;
+    });
+  }
+
+  /**
+   * Sleep utility
+   * @private
+   */
+  async sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+  }
+}
+
+/**
+ * @typedef {Object} ErrorResponse
+ * @property {boolean} success - Always false for errors
+ * @property {Object} error - Error details
+ * @property {string} error.message - Error message
+ * @property {string} error.code - Error code
+ * @property {string} error.type - Error type from ErrorTypes
+ * @property {boolean} error.retryable - Whether error is retryable
+ * @property {string} error.timestamp - ISO timestamp
+ */
+
+/**
+ * @typedef {Object} WorkflowErrorResult
+ * @property {boolean} handled - Whether error was handled
+ * @property {boolean} compensated - Whether compensation was executed
+ * @property {boolean} shouldContinue - Whether workflow should continue
+ * @property {boolean} shouldRetry - Whether step should be retried
+ * @property {ErrorResponse} error - Error response
+ */
+
+/**
+ * @typedef {Object} ErrorStats
+ * @property {number} errors - Total errors
+ * @property {number} retries - Total retries
+ * @property {number} compensations - Total compensations
+ * @property {number} circuitBreaks - Circuit breaker trips
+ * @property {Object} byType - Errors by type
+ * @property {Object} circuitBreakers - Circuit breaker states
+ */
+
+// Export main class as default
+module.exports = ErrorHandlerConnector;
+
+/**
+ * Error type enumeration
+ * @enum {string}
+ */
+module.exports.ErrorTypes = ErrorTypes;
+
+/**
+ * Standard error code mappings
+ * @enum {string}
+ */
+module.exports.ErrorCodes = ErrorCodes;
+
+/**
+ * Factory function to create error handler instance
+ *
+ * @function create
+ * @param {Object} config - Configuration object
+ * @returns {ErrorHandlerConnector} New error handler instance
+ *
+ * @example
+ * const errorHandler = ErrorHandlerConnector.create({
+ *   maxRetries: 5,
+ *   circuitBreakerEnabled: true
+ * });
+ */
+module.exports.create = (config) => new ErrorHandlerConnector(config);
+
+/**
+ * Current version
+ * @constant {string}
+ */
+module.exports.VERSION = '1.0.0';
+
+// Export mock for testing
+module.exports.MockErrorHandler = class MockErrorHandler {
+  constructor() {
+    this.stats = { errors: 0, retries: 0, compensations: 0 };
+  }
+
+  classifyError(error) {
+    return error.type || ErrorTypes.UNKNOWN;
+  }
+
+  shouldRetry(error) {
+    return error.retryable !== false;
+  }
+
+  async executeWithRetry(fn) {
+    try {
+      return await fn();
+    } catch (error) {
+      this.stats.errors++;
+      throw error;
+    }
+  }
+
+  getStats() { return this.stats; }
+};