@nahisaho/musubix-core 1.0.0

package/dist/error/graceful-degradation.d.ts

@@ -0,0 +1,309 @@
+/**
+ * Graceful Degradation
+ *
+ * Handles errors gracefully with fallback strategies
+ *
+ * @packageDocumentation
+ * @module error/graceful-degradation
+ *
+ * @see REQ-ERR-001 - Graceful Degradation
+ * @see Article V - Safety Assurance
+ */
+/**
+ * Degradation level
+ */
+export type DegradationLevel = 'full' | 'reduced' | 'minimal' | 'offline' | 'emergency';
+/**
+ * Service status
+ */
+export type ServiceStatus = 'healthy' | 'degraded' | 'unavailable' | 'unknown';
+/**
+ * Fallback strategy
+ */
+export type FallbackStrategy = 'cache' | 'default' | 'retry' | 'alternative' | 'skip' | 'queue' | 'manual';
+/**
+ * Service health check result
+ */
+export interface HealthCheckResult {
+    /** Service name */
+    service: string;
+    /** Status */
+    status: ServiceStatus;
+    /** Response time (ms) */
+    responseTime?: number;
+    /** Last successful check */
+    lastSuccess?: Date;
+    /** Error message if any */
+    error?: string;
+    /** Additional details */
+    details?: Record<string, unknown>;
+}
+/**
+ * Service configuration
+ */
+export interface ServiceConfig {
+    /** Service name */
+    name: string;
+    /** Health check function */
+    healthCheck: () => Promise<boolean>;
+    /** Fallback strategies in order of preference */
+    fallbackStrategies: FallbackStrategy[];
+    /** Cache TTL (ms) */
+    cacheTtl?: number;
+    /** Retry attempts */
+    retryAttempts?: number;
+    /** Retry delay (ms) */
+    retryDelay?: number;
+    /** Alternative service */
+    alternative?: string;
+    /** Priority (higher = more important) */
+    priority: number;
+    /** Required for minimal operation */
+    required: boolean;
+}
+/**
+ * Fallback action
+ */
+export interface FallbackAction<T = unknown> {
+    /** Strategy used */
+    strategy: FallbackStrategy;
+    /** Execute fallback */
+    execute: () => Promise<T>;
+    /** Description */
+    description: string;
+}
+/**
+ * Degradation event
+ */
+export interface DegradationEvent {
+    /** Event ID */
+    id: string;
+    /** Timestamp */
+    timestamp: Date;
+    /** Service affected */
+    service: string;
+    /** Previous level */
+    previousLevel: DegradationLevel;
+    /** New level */
+    newLevel: DegradationLevel;
+    /** Reason */
+    reason: string;
+    /** Fallback used */
+    fallbackUsed?: FallbackStrategy;
+    /** Recovery time estimate */
+    estimatedRecovery?: Date;
+}
+/**
+ * Operation result with degradation info
+ */
+export interface DegradedResult<T> {
+    /** Result value */
+    value: T;
+    /** Was degraded */
+    degraded: boolean;
+    /** Degradation level */
+    level: DegradationLevel;
+    /** Strategy used */
+    strategy?: FallbackStrategy;
+    /** Original error */
+    originalError?: Error;
+    /** Warnings */
+    warnings: string[];
+}
+/**
+ * Graceful degradation config
+ */
+export interface GracefulDegradationConfig {
+    /** Services configuration */
+    services: ServiceConfig[];
+    /** Health check interval (ms) */
+    healthCheckInterval: number;
+    /** Cache provider */
+    cacheProvider?: CacheProvider;
+    /** Queue provider */
+    queueProvider?: QueueProvider;
+    /** Event handler */
+    onDegradation?: (event: DegradationEvent) => void;
+    /** Recovery handler */
+    onRecovery?: (service: string, level: DegradationLevel) => void;
+    /** Auto-recovery enabled */
+    autoRecovery: boolean;
+    /** Max queue size */
+    maxQueueSize: number;
+}
+/**
+ * Cache provider interface
+ */
+export interface CacheProvider {
+    get<T>(key: string): Promise<T | null>;
+    set<T>(key: string, value: T, ttl?: number): Promise<void>;
+    delete(key: string): Promise<void>;
+    clear(): Promise<void>;
+}
+/**
+ * Queue provider interface
+ */
+export interface QueueProvider {
+    enqueue<T>(item: T): Promise<string>;
+    dequeue<T>(): Promise<T | null>;
+    size(): Promise<number>;
+    clear(): Promise<void>;
+}
+/**
+ * In-memory cache provider
+ */
+export declare class MemoryCacheProvider implements CacheProvider {
+    private cache;
+    get<T>(key: string): Promise<T | null>;
+    set<T>(key: string, value: T, ttl?: number): Promise<void>;
+    delete(key: string): Promise<void>;
+    clear(): Promise<void>;
+}
+/**
+ * In-memory queue provider
+ */
+export declare class MemoryQueueProvider implements QueueProvider {
+    private queue;
+    private counter;
+    enqueue<T>(item: T): Promise<string>;
+    dequeue<T>(): Promise<T | null>;
+    size(): Promise<number>;
+    clear(): Promise<void>;
+}
+/**
+ * Default configuration
+ */
+export declare const DEFAULT_DEGRADATION_CONFIG: GracefulDegradationConfig;
+/**
+ * Graceful Degradation Manager
+ */
+export declare class GracefulDegradation {
+    private config;
+    private serviceStatus;
+    private currentLevel;
+    private events;
+    private eventCounter;
+    private healthCheckTimer?;
+    private cache;
+    private queue;
+    constructor(config?: Partial<GracefulDegradationConfig>);
+    /**
+     * Start health monitoring
+     */
+    start(): void;
+    /**
+     * Stop health monitoring
+     */
+    stop(): void;
+    /**
+     * Register a service
+     */
+    registerService(service: ServiceConfig): void;
+    /**
+     * Execute operation with graceful degradation
+     */
+    execute<T>(serviceName: string, operation: () => Promise<T>, options?: {
+        cacheKey?: string;
+        defaultValue?: T;
+        timeout?: number;
+    }): Promise<DegradedResult<T>>;
+    /**
+     * Execute fallback strategy
+     */
+    private executeFallback;
+    /**
+     * Execute a specific strategy
+     */
+    private executeStrategy;
+    /**
+     * Run health checks on all services
+     */
+    runHealthChecks(): Promise<Map<string, HealthCheckResult>>;
+    /**
+     * Check health of a single service
+     */
+    private checkServiceHealth;
+    /**
+     * Handle service degradation
+     */
+    private handleServiceDegradation;
+    /**
+     * Handle service recovery
+     */
+    private handleServiceRecovery;
+    /**
+     * Process queued items
+     */
+    private processQueue;
+    /**
+     * Recalculate overall degradation level
+     */
+    private recalculateLevel;
+    /**
+     * Get current degradation level
+     */
+    getLevel(): DegradationLevel;
+    /**
+     * Get service status
+     */
+    getServiceStatus(serviceName: string): HealthCheckResult | undefined;
+    /**
+     * Get all service statuses
+     */
+    getAllStatuses(): Map<string, HealthCheckResult>;
+    /**
+     * Get degradation events
+     */
+    getEvents(limit?: number): DegradationEvent[];
+    /**
+     * Check if a feature is available at current level
+     */
+    isFeatureAvailable(requiredLevel: DegradationLevel): boolean;
+    /**
+     * Cache a value
+     */
+    cacheValue<T>(key: string, value: T, ttl?: number): Promise<void>;
+    /**
+     * Get cached value
+     */
+    getCachedValue<T>(key: string): Promise<T | null>;
+    /**
+     * Clear cache
+     */
+    clearCache(): Promise<void>;
+    /**
+     * Execute with timeout
+     */
+    private withTimeout;
+}
+/**
+ * Create graceful degradation instance
+ */
+export declare function createGracefulDegradation(config?: Partial<GracefulDegradationConfig>): GracefulDegradation;
+/**
+ * Retry with exponential backoff
+ */
+export declare function retryWithBackoff<T>(operation: () => Promise<T>, options?: {
+    maxAttempts?: number;
+    initialDelay?: number;
+    maxDelay?: number;
+    backoffFactor?: number;
+}): Promise<T>;
+/**
+ * Circuit breaker
+ */
+export declare class CircuitBreaker {
+    private readonly threshold;
+    private readonly resetTimeout;
+    private failures;
+    private lastFailure?;
+    private state;
+    constructor(threshold?: number, resetTimeout?: number);
+    execute<T>(operation: () => Promise<T>): Promise<T>;
+    private shouldAttemptReset;
+    private onSuccess;
+    private onFailure;
+    getState(): 'closed' | 'open' | 'half-open';
+    reset(): void;
+}
+//# sourceMappingURL=graceful-degradation.d.ts.map

package/dist/error/graceful-degradation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graceful-degradation.d.ts","sourceRoot":"","sources":["../../src/error/graceful-degradation.ts"],"names":[],"mappings":"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"}