npm package: @onlineapps/error-handler-core
Description: Core error handling functionality for OA Drive microservices - classification, retry, circuit breaker, DLQ routing
Author: OnlineApps
Latest version: 1.1.10

# @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

```bash
npm install @onlineapps/error-handler-core
```

## Usage

### Basic Setup

```javascript
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

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

### Handle Error

```javascript
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

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

### Execute with Circuit Breaker

```javascript
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](/docs/standards/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](/docs/standards/UNIFIED_ERROR_HANDLING.md)
- [Error Handling Architecture](/docs/standards/ERROR_HANDLING_ARCHITECTURE.md)
- [Error Handling Standard](/docs/standards/ERROR_HANDLING.md)

---

*Version: 1.0.0 | License: MIT*