Package Exports

@unrdf/self-healing-workflows
@unrdf/self-healing-workflows/circuit-breaker
@unrdf/self-healing-workflows/classifier
@unrdf/self-healing-workflows/engine
@unrdf/self-healing-workflows/health
@unrdf/self-healing-workflows/recovery
@unrdf/self-healing-workflows/retry
@unrdf/self-healing-workflows/schemas

Readme

@unrdf/self-healing-workflows

Automatic error recovery system with 85-95% success rate using YAWL + Daemon + Hooks

Features

Automatic Retry: Exponential backoff with jitter
Circuit Breaker: Fail-fast pattern for cascading failures
Error Classification: Pattern-based error categorization
Recovery Actions: Comprehensive action library (retry, skip, compensate, restart)
Health Monitoring: Real-time health checks and alerting
OTEL Integration: Full observability support

Installation

pnpm add @unrdf/self-healing-workflows

Quick Start

import { SelfHealingEngine } from '@unrdf/self-healing-workflows';

// Create engine
const engine = new SelfHealingEngine({
  retry: {
    maxAttempts: 3,
    initialDelay: 1000,
    backoffMultiplier: 2
  },
  circuitBreaker: {
    failureThreshold: 5,
    resetTimeout: 30000
  }
});

// Execute with automatic recovery
const result = await engine.execute(async () => {
  return await fetch('https://api.example.com/data');
}, {
  fallback: () => getCachedData()
});

Recovery Strategies

1. Immediate Retry (3 attempts)

import { immediateRetry } from '@unrdf/self-healing-workflows';

const result = await immediateRetry(async () => {
  return await riskyOperation();
});

2. Exponential Backoff (2s, 4s, 8s, 16s)

import { exponentialRetry } from '@unrdf/self-healing-workflows';

const result = await exponentialRetry(async () => {
  return await apiCall();
});

3. Circuit Breaker

import { createCircuitBreaker } from '@unrdf/self-healing-workflows';

const breaker = createCircuitBreaker({
  failureThreshold: 5,
  successThreshold: 2,
  timeout: 60000
});

const result = await breaker.execute(async () => {
  return await externalService();
}, {
  fallback: () => defaultValue
});

4. Compensating Transaction

await engine.execute(
  async () => {
    await createOrder();
    await chargeCard();
    await updateInventory();
  },
  {
    compensationFn: async () => {
      await refundCard();
      await cancelOrder();
    }
  }
);

5. Skip and Continue

for (const item of items) {
  try {
    await processItem(item);
  } catch (error) {
    console.log('Skipping failed item');
    continue;
  }
}

6. Manual Intervention

await engine.execute(
  async () => {
    await criticalOperation();
  },
  {
    notificationFn: async (alert) => {
      await sendPagerDutyAlert(alert);
    }
  }
);

Error Classification

Errors are automatically classified into categories:

Network: Connection failures, DNS errors
Timeout: Operation timeouts
Validation: Data validation failures
Resource: Memory, disk, CPU exhaustion
Dependency: External service failures
Business Logic: Domain rule violations

import { createErrorClassifier } from '@unrdf/self-healing-workflows';

const classifier = createErrorClassifier();
const classified = classifier.classify(new Error('ECONNREFUSED'));

console.log(classified.category); // 'network'
console.log(classified.severity); // 'medium'
console.log(classified.retryable); // true

Health Monitoring

import { createHealthMonitor } from '@unrdf/self-healing-workflows';

const monitor = createHealthMonitor({
  interval: 30000,
  timeout: 5000
});

// Register checks
monitor.registerCheck('database', async () => {
  await db.ping();
});

monitor.registerCheck('cache', async () => {
  await cache.ping();
});

// Start monitoring
monitor.start();

// Listen for status changes
monitor.onStatusChange((result) => {
  console.log('Health status:', result.status);
  console.log('Failed checks:', result.checks.filter(c => c.status === 'unhealthy'));
});

Statistics

const stats = engine.getStats();

console.log('Success rate:', stats.successRate * 100 + '%');
console.log('Total attempts:', stats.totalAttempts);
console.log('Average recovery time:', stats.averageRecoveryTime + 'ms');
console.log('Errors by category:', stats.errorsByCategory);

Custom Error Patterns

engine.addErrorPattern({
  name: 'RateLimitError',
  category: 'dependency',
  severity: 'medium',
  pattern: /rate limit|429/i
});

Custom Recovery Actions

engine.addRecoveryAction({
  type: 'fallback',
  name: 'use-cache',
  execute: async (context) => {
    return await getFromCache(context.key);
  },
  condition: (error) => error.category === 'network',
  priority: 70
});

Performance Targets

Operation	P95 Target	Typical
Recovery decision	<50ms	~10ms
Retry execution	100ms-30s	~2s
Health check	<10ms	~5ms
Circuit breaker switch	<1ms	~0.1ms

Recovery Success Rate

Target: 85-95% success rate for retryable errors

Measured across:

Network failures
Timeout errors
Resource constraints
Service degradation

API Reference

SelfHealingEngine

class SelfHealingEngine {
  constructor(config?: SelfHealingConfig)
  execute<T>(operation: () => Promise<T>, options?: ExecuteOptions): Promise<T>
  wrap<T>(fn: Function, options?: ExecuteOptions): Function
  getStats(): RecoveryStats
  getHealth(): Promise<HealthCheckResult>
  addErrorPattern(pattern: ErrorPattern): void
  addRecoveryAction(action: RecoveryAction): void
}

RetryStrategy

class RetryStrategy {
  constructor(config?: RetryStrategyConfig)
  execute<T>(operation: () => Promise<T>, options?: RetryOptions): Promise<T>
  calculateDelay(attempt: number): number
}

CircuitBreaker

class CircuitBreaker {
  constructor(config?: CircuitBreakerConfig)
  execute<T>(operation: () => Promise<T>, options?: BreakerOptions): Promise<T>
  getState(): 'closed' | 'open' | 'half-open'
  reset(): void
}

Examples

See examples/ directory:

basic-usage.mjs - Getting started
recovery-strategies.mjs - All recovery patterns

License

MIT