@onlineapps/error-handler-core

Core error handling functionality for OA Drive microservices. Used by both business services (via conn-infra-error-handler wrapper) and infrastructure services (directly).

Features

• Error Classification - Automatic error type detection (TRANSIENT, BUSINESS, FATAL, etc.)
• Retry Logic - Exponential backoff for transient errors
• Circuit Breaker - Protection against cascading failures
• DLQ Routing - Dead letter queue routing for permanent errors
• Compensation - Rollback operations for failed workflows
• Unified Logging - Structured error logging via monitoring-core

Installation

npm install @onlineapps/error-handler-core

Usage

Basic Setup

const { init: initMonitoring } = require('@onlineapps/monitoring-core');
const { ErrorHandlerCore } = require('@onlineapps/error-handler-core');

// Initialize monitoring-core
const monitoring = await initMonitoring({
  serviceName: 'my-service',
  mode: 'light'
});

// Initialize error handler
const errorHandler = new ErrorHandlerCore({
  serviceName: 'my-service',
  serviceVersion: '1.0.0',
  environment: process.env.NODE_ENV,
  monitoring: monitoring,  // monitoring-core instance (required)
  handling: {
    maxRetries: 3,
    retryDelay: 1000,
    retryMultiplier: 2,
    circuitBreakerEnabled: true,
    dlqEnabled: true,
    mqClient: mqClient  // Optional, for DLQ routing
  }
});

Log Error

await errorHandler.logError({
  moduleName: 'MyModule',
  operation: 'myOperation',
  error: new Error('Something failed'),
  context: { userId: 123 }
});

Handle Error

try {
  await criticalOperation();
} catch (error) {
  const result = await errorHandler.handleError({
    moduleName: 'MyModule',
    operation: 'criticalOperation',
    error: error,
    context: { operationId: 'op-123' }
  });
  
  // result.action: 'retry' | 'dlq' | 'throw' | 'continue' | 'compensate'
  if (result.action === 'retry') {
    await sleep(result.retryDelay);
    // Retry operation
  }
}

Execute with Retry

const result = await errorHandler.executeWithRetry({
  moduleName: 'MQClient',
  operation: 'publish',
  fn: async () => await mqClient.publish(queue, message),
  context: { queue, messageId }
});

Execute with Circuit Breaker

const result = await errorHandler.executeWithCircuitBreaker({
  moduleName: 'ExternalAPI',
  operation: 'getUser',
  circuitName: 'user-api',
  fn: async () => await userAPI.getUser(id),
  context: { userId: id }
});

API Reference

See UNIFIED_ERROR_HANDLING.md for complete API documentation.

Architecture

• Core Library - Used directly by infrastructure services
• Wrapper - conn-infra-error-handler wraps this for business services
• Dependencies - Uses monitoring-core for logging

Related Documentation

• Unified Error Handling Standard
• Error Handling Architecture
• Error Handling Standard

Version: 1.0.0 | License: MIT