@revealui/core 0.0.1-pre.4 → 0.2.1

package/dist/error-handling/circuit-breaker.js

@@ -0,0 +1,542 @@
+/**
+ * Circuit Breaker Pattern
+ *
+ * Prevents cascading failures by stopping requests to failing services
+ */
+import { logger } from '../observability/logger.js';
+const DEFAULT_CONFIG = {
+    failureThreshold: 5,
+    successThreshold: 2,
+    timeout: 60000,
+    resetTimeout: 30000,
+    volumeThreshold: 10,
+    errorFilter: () => true,
+    onStateChange: () => { },
+    onTrip: () => { },
+    onReset: () => { },
+};
+/**
+ * Circuit Breaker implementation
+ */
+export class CircuitBreaker {
+    state = 'closed';
+    failures = 0;
+    successes = 0;
+    consecutiveFailures = 0;
+    consecutiveSuccesses = 0;
+    totalCalls = 0;
+    totalFailures = 0;
+    totalSuccesses = 0;
+    lastFailureTime;
+    lastSuccessTime;
+    stateChangedAt = Date.now();
+    resetTimer;
+    config;
+    constructor(config = {}) {
+        this.config = { ...DEFAULT_CONFIG, ...config };
+    }
+    /**
+     * Execute function with circuit breaker
+     */
+    async execute(fn) {
+        // Check if circuit is open
+        if (this.state === 'open') {
+            // Check if reset timeout has passed
+            if (Date.now() - this.stateChangedAt >= this.config.resetTimeout) {
+                this.transitionTo('half-open');
+            }
+            else {
+                throw new CircuitBreakerOpenError('Circuit breaker is open');
+            }
+        }
+        this.totalCalls++;
+        try {
+            const result = await fn();
+            this.onSuccess();
+            return result;
+        }
+        catch (error) {
+            const err = error instanceof Error ? error : new Error(String(error));
+            this.onFailure(err);
+            throw error;
+        }
+    }
+    /**
+     * Handle successful execution
+     */
+    onSuccess() {
+        this.successes++;
+        this.consecutiveSuccesses++;
+        this.totalSuccesses++;
+        this.consecutiveFailures = 0;
+        this.lastSuccessTime = Date.now();
+        if (this.state === 'half-open') {
+            // Check if we can close the circuit
+            if (this.consecutiveSuccesses >= this.config.successThreshold) {
+                this.transitionTo('closed');
+            }
+        }
+        // Reset failure count in closed state
+        if (this.state === 'closed') {
+            this.failures = 0;
+        }
+    }
+    /**
+     * Handle failed execution
+     */
+    onFailure(error) {
+        // Check if error should count
+        if (!this.config.errorFilter(error)) {
+            return;
+        }
+        this.failures++;
+        this.consecutiveFailures++;
+        this.totalFailures++;
+        this.consecutiveSuccesses = 0;
+        this.lastFailureTime = Date.now();
+        if (this.state === 'half-open') {
+            // Immediately open circuit on failure in half-open state
+            this.transitionTo('open');
+        }
+        else if (this.state === 'closed') {
+            // Check if we should open the circuit
+            if (this.consecutiveFailures >= this.config.failureThreshold &&
+                this.totalCalls >= this.config.volumeThreshold) {
+                this.transitionTo('open');
+            }
+        }
+    }
+    /**
+     * Transition to new state
+     */
+    transitionTo(newState) {
+        if (this.state === newState)
+            return;
+        const oldState = this.state;
+        this.state = newState;
+        this.stateChangedAt = Date.now();
+        // Reset counters
+        if (newState === 'half-open' || newState === 'closed') {
+            this.consecutiveFailures = 0;
+            this.consecutiveSuccesses = 0;
+        }
+        // Clear reset timer
+        if (this.resetTimer) {
+            clearTimeout(this.resetTimer);
+            this.resetTimer = undefined;
+        }
+        // Set reset timer for open state
+        if (newState === 'open') {
+            this.resetTimer = setTimeout(() => {
+                this.transitionTo('half-open');
+            }, this.config.resetTimeout);
+            this.config.onTrip();
+        }
+        // Circuit reset
+        if (newState === 'closed' && oldState === 'half-open') {
+            this.failures = 0;
+            this.config.onReset();
+        }
+        this.config.onStateChange(newState);
+        logger.info(`Circuit breaker state changed: ${oldState} -> ${newState}`, this.getStats());
+    }
+    /**
+     * Get current state
+     */
+    getState() {
+        return this.state;
+    }
+    /**
+     * Get statistics
+     */
+    getStats() {
+        return {
+            state: this.state,
+            failures: this.failures,
+            successes: this.successes,
+            consecutiveFailures: this.consecutiveFailures,
+            consecutiveSuccesses: this.consecutiveSuccesses,
+            totalCalls: this.totalCalls,
+            totalFailures: this.totalFailures,
+            totalSuccesses: this.totalSuccesses,
+            lastFailureTime: this.lastFailureTime,
+            lastSuccessTime: this.lastSuccessTime,
+            stateChangedAt: this.stateChangedAt,
+        };
+    }
+    /**
+     * Manually open circuit
+     */
+    trip() {
+        this.transitionTo('open');
+    }
+    /**
+     * Manually close circuit
+     */
+    reset() {
+        this.failures = 0;
+        this.successes = 0;
+        this.consecutiveFailures = 0;
+        this.consecutiveSuccesses = 0;
+        this.transitionTo('closed');
+    }
+    /**
+     * Force state to half-open
+     */
+    halfOpen() {
+        this.transitionTo('half-open');
+    }
+    /**
+     * Check if circuit is open
+     */
+    isOpen() {
+        return this.state === 'open';
+    }
+    /**
+     * Check if circuit is closed
+     */
+    isClosed() {
+        return this.state === 'closed';
+    }
+    /**
+     * Check if circuit is half-open
+     */
+    isHalfOpen() {
+        return this.state === 'half-open';
+    }
+    /**
+     * Get failure rate
+     */
+    getFailureRate() {
+        if (this.totalCalls === 0)
+            return 0;
+        return this.totalFailures / this.totalCalls;
+    }
+    /**
+     * Get success rate
+     */
+    getSuccessRate() {
+        if (this.totalCalls === 0)
+            return 0;
+        return this.totalSuccesses / this.totalCalls;
+    }
+    /**
+     * Cleanup
+     */
+    destroy() {
+        if (this.resetTimer) {
+            clearTimeout(this.resetTimer);
+        }
+    }
+}
+/**
+ * Circuit breaker open error
+ */
+export class CircuitBreakerOpenError extends Error {
+    constructor(message = 'Circuit breaker is open') {
+        super(message);
+        this.name = 'CircuitBreakerOpenError';
+    }
+}
+/**
+ * Circuit breaker registry
+ */
+export class CircuitBreakerRegistry {
+    breakers = new Map();
+    /**
+     * Get or create circuit breaker
+     */
+    get(name, config) {
+        let breaker = this.breakers.get(name);
+        if (!breaker) {
+            breaker = new CircuitBreaker(config);
+            this.breakers.set(name, breaker);
+        }
+        return breaker;
+    }
+    /**
+     * Check if breaker exists
+     */
+    has(name) {
+        return this.breakers.has(name);
+    }
+    /**
+     * Remove circuit breaker
+     */
+    remove(name) {
+        const breaker = this.breakers.get(name);
+        if (breaker) {
+            breaker.destroy();
+            return this.breakers.delete(name);
+        }
+        return false;
+    }
+    /**
+     * Get all breakers
+     */
+    getAll() {
+        return new Map(this.breakers);
+    }
+    /**
+     * Get all statistics
+     */
+    getAllStats() {
+        const stats = {};
+        for (const [name, breaker] of this.breakers) {
+            stats[name] = breaker.getStats();
+        }
+        return stats;
+    }
+    /**
+     * Reset all breakers
+     */
+    resetAll() {
+        for (const breaker of this.breakers.values()) {
+            breaker.reset();
+        }
+    }
+    /**
+     * Clear all breakers
+     */
+    clear() {
+        for (const breaker of this.breakers.values()) {
+            breaker.destroy();
+        }
+        this.breakers.clear();
+    }
+}
+/**
+ * Global circuit breaker registry
+ */
+export const circuitBreakerRegistry = new CircuitBreakerRegistry();
+/**
+ * Create circuit breaker decorator
+ */
+export function CircuitBreak(nameOrConfig = {}) {
+    return (target, propertyKey, descriptor) => {
+        const originalMethod = descriptor.value;
+        const name = typeof nameOrConfig === 'string'
+            ? nameOrConfig
+            : `${target.constructor.name}.${propertyKey}`;
+        const config = typeof nameOrConfig === 'object' ? nameOrConfig : undefined;
+        descriptor.value = async function (...args) {
+            const breaker = circuitBreakerRegistry.get(name, config);
+            return breaker.execute(() => originalMethod.apply(this, args));
+        };
+        return descriptor;
+    };
+}
+/**
+ * Execute with circuit breaker
+ */
+export async function withCircuitBreaker(name, fn, config) {
+    const breaker = circuitBreakerRegistry.get(name, config);
+    return breaker.execute(fn);
+}
+/**
+ * Create circuit breaker middleware
+ */
+export function createCircuitBreakerMiddleware(name, config) {
+    const breaker = circuitBreakerRegistry.get(name, config);
+    return async (_request, next) => {
+        return breaker.execute(next);
+    };
+}
+/**
+ * Circuit breaker for fetch
+ */
+export async function fetchWithCircuitBreaker(name, url, init, config) {
+    const breaker = circuitBreakerRegistry.get(name, config);
+    return breaker.execute(async () => {
+        const response = await fetch(url, init);
+        // Treat 5xx errors as failures
+        if (response.status >= 500) {
+            const error = new Error(`HTTP ${response.status}: ${response.statusText}`);
+            error.statusCode = response.status;
+            throw error;
+        }
+        return response;
+    });
+}
+/**
+ * Adaptive circuit breaker with dynamic thresholds
+ */
+export class AdaptiveCircuitBreaker extends CircuitBreaker {
+    errorRateWindow = [];
+    windowSize = 100;
+    adaptiveThreshold;
+    constructor(config = {}) {
+        super(config);
+        this.adaptiveThreshold = config.failureThreshold || 5;
+    }
+    /**
+     * Execute with adaptive thresholds
+     */
+    async execute(fn) {
+        try {
+            const result = await super.execute(fn);
+            this.recordSuccess();
+            return result;
+        }
+        catch (error) {
+            this.recordFailure();
+            throw error;
+        }
+    }
+    /**
+     * Record success in window
+     */
+    recordSuccess() {
+        this.errorRateWindow.push(0);
+        this.trimWindow();
+        this.adjustThreshold();
+    }
+    /**
+     * Record failure in window
+     */
+    recordFailure() {
+        this.errorRateWindow.push(1);
+        this.trimWindow();
+        this.adjustThreshold();
+    }
+    /**
+     * Trim window to size
+     */
+    trimWindow() {
+        if (this.errorRateWindow.length > this.windowSize) {
+            this.errorRateWindow.shift();
+        }
+    }
+    /**
+     * Adjust threshold based on error rate
+     */
+    adjustThreshold() {
+        const errorRate = this.getWindowErrorRate();
+        // Increase threshold if error rate is low
+        if (errorRate < 0.1) {
+            this.adaptiveThreshold = Math.min(this.adaptiveThreshold + 1, 20);
+        }
+        // Decrease threshold if error rate is high
+        else if (errorRate > 0.5) {
+            this.adaptiveThreshold = Math.max(this.adaptiveThreshold - 1, 2);
+        }
+    }
+    /**
+     * Get error rate in window
+     */
+    getWindowErrorRate() {
+        if (this.errorRateWindow.length === 0)
+            return 0;
+        const errors = this.errorRateWindow.reduce((sum, val) => sum + val, 0);
+        return errors / this.errorRateWindow.length;
+    }
+    /**
+     * Get adaptive threshold
+     */
+    getAdaptiveThreshold() {
+        return this.adaptiveThreshold;
+    }
+}
+/**
+ * Bulkhead pattern - limit concurrent executions
+ */
+export class Bulkhead {
+    activeRequests = 0;
+    queue = [];
+    maxConcurrent;
+    maxQueue;
+    constructor(maxConcurrent = 10, maxQueue = 100) {
+        this.maxConcurrent = maxConcurrent;
+        this.maxQueue = maxQueue;
+    }
+    /**
+     * Execute with bulkhead
+     */
+    async execute(fn) {
+        // Check if at capacity
+        if (this.activeRequests >= this.maxConcurrent) {
+            // Check queue capacity
+            if (this.queue.length >= this.maxQueue) {
+                throw new Error('Bulkhead queue is full');
+            }
+            // Wait for slot
+            await new Promise((resolve) => {
+                this.queue.push(resolve);
+            });
+        }
+        this.activeRequests++;
+        try {
+            return await fn();
+        }
+        finally {
+            this.activeRequests--;
+            // Process queue
+            const next = this.queue.shift();
+            if (next) {
+                next();
+            }
+        }
+    }
+    /**
+     * Get active requests
+     */
+    getActiveRequests() {
+        return this.activeRequests;
+    }
+    /**
+     * Get queue size
+     */
+    getQueueSize() {
+        return this.queue.length;
+    }
+    /**
+     * Get statistics
+     */
+    getStats() {
+        return {
+            activeRequests: this.activeRequests,
+            queueSize: this.queue.length,
+            maxConcurrent: this.maxConcurrent,
+            maxQueue: this.maxQueue,
+        };
+    }
+}
+/**
+ * Combined resilience wrapper
+ */
+export class ResilientOperation {
+    fn;
+    circuitBreaker;
+    bulkhead;
+    constructor(fn, circuitBreaker, bulkhead) {
+        this.fn = fn;
+        this.circuitBreaker = circuitBreaker;
+        this.bulkhead = bulkhead;
+    }
+    /**
+     * Execute with all resilience patterns
+     */
+    async execute() {
+        const executeFn = async () => {
+            if (this.bulkhead) {
+                return this.bulkhead.execute(this.fn);
+            }
+            return this.fn();
+        };
+        if (this.circuitBreaker) {
+            return this.circuitBreaker.execute(executeFn);
+        }
+        return executeFn();
+    }
+}
+/**
+ * Create resilient function
+ */
+export function createResilientFunction(fn, options = {}) {
+    const breaker = options.circuitBreaker ? new CircuitBreaker(options.circuitBreaker) : undefined;
+    const bulkhead = options.bulkhead
+        ? new Bulkhead(options.bulkhead.maxConcurrent, options.bulkhead.maxQueue)
+        : undefined;
+    const operation = new ResilientOperation(fn, breaker, bulkhead);
+    return () => operation.execute();
+}

package/dist/error-handling/error-boundary.d.ts

@@ -0,0 +1,94 @@
+/**
+ * React Error Boundary Components
+ *
+ * Catch and handle React component errors gracefully
+ */
+import React, { Component, type ReactNode } from 'react';
+export interface ErrorInfo {
+    componentStack: string;
+}
+export interface ErrorBoundaryProps {
+    children: ReactNode;
+    fallback?: ReactNode | ((error: Error, errorInfo?: ErrorInfo) => ReactNode);
+    onError?: (error: Error, errorInfo?: ErrorInfo) => void;
+    onReset?: () => void;
+    resetKeys?: unknown[];
+    isolate?: boolean;
+}
+export interface ErrorBoundaryState {
+    hasError: boolean;
+    error: Error | null;
+    errorInfo: ErrorInfo | null;
+}
+/**
+ * Error Boundary Component
+ */
+export declare class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundaryState> {
+    constructor(props: ErrorBoundaryProps);
+    static getDerivedStateFromError(error: Error): Partial<ErrorBoundaryState>;
+    componentDidCatch(error: Error, errorInfo: ErrorInfo): void;
+    componentDidUpdate(prevProps: ErrorBoundaryProps): void;
+    reset: () => void;
+    render(): ReactNode;
+}
+/**
+ * Error Boundary with retry
+ */
+export interface ErrorBoundaryWithRetryProps extends ErrorBoundaryProps {
+    maxRetries?: number;
+    retryDelay?: number;
+}
+export declare class ErrorBoundaryWithRetry extends Component<ErrorBoundaryWithRetryProps, ErrorBoundaryState & {
+    retryCount: number;
+}> {
+    private retryTimeout?;
+    constructor(props: ErrorBoundaryWithRetryProps);
+    static getDerivedStateFromError(error: Error): Partial<ErrorBoundaryState>;
+    componentDidCatch(error: Error, errorInfo: ErrorInfo): void;
+    componentWillUnmount(): void;
+    reset: () => void;
+    render(): ReactNode;
+}
+/**
+ * withErrorBoundary HOC
+ */
+export declare function withErrorBoundary<P extends object>(Component: React.ComponentType<P>, errorBoundaryProps?: Omit<ErrorBoundaryProps, 'children'>): React.ComponentType<P>;
+/**
+ * useErrorHandler hook
+ */
+export declare function useErrorHandler(error?: Error | null): (error: Error) => void;
+/**
+ * Error types
+ */
+export declare class NetworkError extends Error {
+    statusCode?: number | undefined;
+    constructor(message: string, statusCode?: number | undefined);
+}
+export declare class ValidationError extends Error {
+    fields?: Record<string, string> | undefined;
+    constructor(message: string, fields?: Record<string, string> | undefined);
+}
+export declare class AuthenticationError extends Error {
+    constructor(message: string);
+}
+export declare class NotFoundError extends Error {
+    resource?: string | undefined;
+    constructor(message: string, resource?: string | undefined);
+}
+/**
+ * Error classification
+ */
+export declare function isNetworkError(error: unknown): error is NetworkError;
+export declare function isValidationError(error: unknown): error is ValidationError;
+export declare function isAuthenticationError(error: unknown): error is AuthenticationError;
+export declare function isNotFoundError(error: unknown): error is NotFoundError;
+/**
+ * Error severity
+ */
+export type ErrorSeverity = 'low' | 'medium' | 'high' | 'critical';
+export declare function getErrorSeverity(error: Error): ErrorSeverity;
+/**
+ * Should retry error
+ */
+export declare function shouldRetryError(error: Error): boolean;
+//# sourceMappingURL=error-boundary.d.ts.map

package/dist/error-handling/error-boundary.d.ts.map

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