@revealui/resilience 0.2.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025-2026 RevealUI Studio
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/LICENSE.commercial

@@ -0,0 +1,112 @@
+RevealUI Commercial License
+Version 1.0, February 2026
+
+Copyright (c) 2025-2026 RevealUI Studio (founder@revealui.com)
+
+TERMS AND CONDITIONS
+
+1. DEFINITIONS
+
+"Software" means the RevealUI source code, documentation, and associated
+files contained in directories and packages designated as commercial,
+including but not limited to: packages/ai, packages/mcp, packages/editors,
+packages/services, packages/harnesses, and any directory named "ee" within
+the repository.
+
+"License Key" means a valid RevealUI license key obtained through an active
+paid subscription at https://revealui.com.
+
+"Licensee" means the individual or organization that holds a valid License
+Key through an active subscription.
+
+"Production Use" means any use of the Software beyond local development and
+evaluation, including but not limited to: deploying the Software to serve
+end users, integrating the Software into a product or service, or using the
+Software in a revenue-generating capacity.
+
+2. GRANT OF RIGHTS
+
+Subject to the terms of this License and a valid License Key, the Licensee
+is granted a non-exclusive, non-transferable, revocable license to:
+
+  (a) Use the Software for internal development and Production Use.
+  (b) Modify the Software for internal use.
+  (c) Deploy the Software on infrastructure controlled by the Licensee.
+
+Enterprise License holders are additionally granted the right to:
+
+  (d) Deploy the Software in a self-hosted environment.
+  (e) Remove or replace RevealUI branding (white-label).
+  (f) Use the Software for multiple tenants within the Licensee's
+      organization or customer base.
+
+3. RESTRICTIONS
+
+The Licensee SHALL NOT:
+
+  (a) Provide the Software, or any portion of it, to third parties as a
+      hosted or managed service that competes with RevealUI.
+  (b) Redistribute, sublicense, sell, or otherwise transfer the Software
+      or any portion of it to third parties.
+  (c) Remove, alter, or circumvent the license key verification
+      functionality of the Software.
+  (d) Use the Software in Production without a valid License Key.
+  (e) Share, publish, or make the License Key available to unauthorized
+      parties.
+
+4. EVALUATION
+
+The Software may be used for evaluation and local development purposes
+without a License Key. Evaluation use does not grant any rights to
+Production Use.
+
+5. SUBSCRIPTION AND PAYMENT
+
+This License is valid only during the term of an active paid subscription.
+Upon cancellation or expiration of the subscription:
+
+  (a) The License terminates automatically.
+  (b) A grace period of fourteen (14) days is provided for the Licensee
+      to transition away from Production Use.
+  (c) After the grace period, the Licensee must cease all Production Use
+      of the Software.
+
+6. INTELLECTUAL PROPERTY
+
+The Software is and remains the intellectual property of RevealUI Studio.
+This License does not grant any ownership rights. Contributions to
+commercial portions of the Software require a Contributor License Agreement.
+
+7. OPEN SOURCE COMPONENTS
+
+This License applies only to files and directories designated as commercial.
+Files under the MIT License (as indicated in the root LICENSE file) are not
+subject to this commercial license and may be used freely under MIT terms.
+
+8. DISCLAIMER OF WARRANTY
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+
+9. LIMITATION OF LIABILITY
+
+IN NO EVENT SHALL REVEALUI STUDIO BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE, EXCEEDING THE AMOUNT PAID BY THE LICENSEE IN
+THE TWELVE (12) MONTHS PRECEDING THE CLAIM.
+
+10. GOVERNING LAW
+
+This License shall be governed by the laws of the State of California,
+United States of America, without regard to its conflict of law provisions.
+
+11. ENTIRE AGREEMENT
+
+This License constitutes the entire agreement between the parties with
+respect to the commercial portions of the Software and supersedes all
+prior agreements, understandings, and communications.
+
+For licensing inquiries: founder@revealui.com
+For pricing and subscriptions: https://revealui.com/pricing

package/dist/index.d.ts

@@ -0,0 +1,477 @@
+/**
+ * Circuit Breaker Pattern
+ *
+ * Prevents cascading failures by stopping requests to failing services
+ */
+type CircuitState = 'closed' | 'open' | 'half-open';
+interface CircuitBreakerConfig {
+    failureThreshold?: number;
+    successThreshold?: number;
+    timeout?: number;
+    resetTimeout?: number;
+    volumeThreshold?: number;
+    errorFilter?: (error: Error) => boolean;
+    onStateChange?: (state: CircuitState) => void;
+    onTrip?: () => void;
+    onReset?: () => void;
+}
+interface CircuitBreakerStats {
+    [key: string]: unknown;
+    state: CircuitState;
+    failures: number;
+    successes: number;
+    consecutiveFailures: number;
+    consecutiveSuccesses: number;
+    totalCalls: number;
+    totalFailures: number;
+    totalSuccesses: number;
+    lastFailureTime?: number;
+    lastSuccessTime?: number;
+    stateChangedAt: number;
+}
+/**
+ * Circuit Breaker implementation
+ */
+declare class CircuitBreaker {
+    private state;
+    private failures;
+    private successes;
+    private consecutiveFailures;
+    private consecutiveSuccesses;
+    private totalCalls;
+    private totalFailures;
+    private totalSuccesses;
+    private lastFailureTime?;
+    private lastSuccessTime?;
+    private stateChangedAt;
+    private resetTimer?;
+    protected config: Required<CircuitBreakerConfig>;
+    constructor(config?: CircuitBreakerConfig);
+    /**
+     * Execute function with circuit breaker
+     */
+    execute<T>(fn: () => Promise<T>): Promise<T>;
+    /**
+     * Handle successful execution
+     */
+    private onSuccess;
+    /**
+     * Handle failed execution
+     */
+    private onFailure;
+    /**
+     * Transition to new state
+     */
+    private transitionTo;
+    /**
+     * Get current state
+     */
+    getState(): CircuitState;
+    /**
+     * Get statistics
+     */
+    getStats(): CircuitBreakerStats;
+    /**
+     * Manually open circuit
+     */
+    trip(): void;
+    /**
+     * Manually close circuit
+     */
+    reset(): void;
+    /**
+     * Force state to half-open
+     */
+    halfOpen(): void;
+    /**
+     * Check if circuit is open
+     */
+    isOpen(): boolean;
+    /**
+     * Check if circuit is closed
+     */
+    isClosed(): boolean;
+    /**
+     * Check if circuit is half-open
+     */
+    isHalfOpen(): boolean;
+    /**
+     * Get failure rate
+     */
+    getFailureRate(): number;
+    /**
+     * Get success rate
+     */
+    getSuccessRate(): number;
+    /**
+     * Cleanup
+     */
+    destroy(): void;
+}
+/**
+ * Circuit breaker open error
+ */
+declare class CircuitBreakerOpenError extends Error {
+    constructor(message?: string);
+}
+/**
+ * Circuit breaker registry
+ */
+declare class CircuitBreakerRegistry {
+    private breakers;
+    /**
+     * Get or create circuit breaker
+     */
+    get(name: string, config?: CircuitBreakerConfig): CircuitBreaker;
+    /**
+     * Check if breaker exists
+     */
+    has(name: string): boolean;
+    /**
+     * Remove circuit breaker
+     */
+    remove(name: string): boolean;
+    /**
+     * Get all breakers
+     */
+    getAll(): Map<string, CircuitBreaker>;
+    /**
+     * Get all statistics
+     */
+    getAllStats(): Record<string, CircuitBreakerStats>;
+    /**
+     * Reset all breakers
+     */
+    resetAll(): void;
+    /**
+     * Clear all breakers
+     */
+    clear(): void;
+}
+/**
+ * Global circuit breaker registry
+ */
+declare const circuitBreakerRegistry: CircuitBreakerRegistry;
+/**
+ * Create circuit breaker decorator
+ */
+declare function CircuitBreak(nameOrConfig?: string | CircuitBreakerConfig): (target: object, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
+/**
+ * Execute with circuit breaker
+ */
+declare function withCircuitBreaker<T>(name: string, fn: () => Promise<T>, config?: CircuitBreakerConfig): Promise<T>;
+/**
+ * Create circuit breaker middleware
+ */
+declare function createCircuitBreakerMiddleware<TRequest = unknown, TResponse = unknown>(name: string, config?: CircuitBreakerConfig): (_request: TRequest, next: () => Promise<TResponse>) => Promise<TResponse>;
+/**
+ * Circuit breaker for fetch
+ */
+declare function fetchWithCircuitBreaker(name: string, url: string, init?: RequestInit, config?: CircuitBreakerConfig): Promise<Response>;
+/**
+ * Adaptive circuit breaker with dynamic thresholds
+ */
+declare class AdaptiveCircuitBreaker extends CircuitBreaker {
+    private errorRateWindow;
+    private windowSize;
+    private adaptiveThreshold;
+    constructor(config?: CircuitBreakerConfig);
+    /**
+     * Execute with adaptive thresholds
+     */
+    execute<T>(fn: () => Promise<T>): Promise<T>;
+    /**
+     * Record success in window
+     */
+    private recordSuccess;
+    /**
+     * Record failure in window
+     */
+    private recordFailure;
+    /**
+     * Trim window to size
+     */
+    private trimWindow;
+    /**
+     * Adjust threshold based on error rate
+     */
+    private adjustThreshold;
+    /**
+     * Get error rate in window
+     */
+    private getWindowErrorRate;
+    /**
+     * Get adaptive threshold
+     */
+    getAdaptiveThreshold(): number;
+}
+/**
+ * Bulkhead pattern - limit concurrent executions
+ */
+declare class Bulkhead {
+    private activeRequests;
+    private queue;
+    private maxConcurrent;
+    private maxQueue;
+    constructor(maxConcurrent?: number, maxQueue?: number);
+    /**
+     * Execute with bulkhead
+     */
+    execute<T>(fn: () => Promise<T>): Promise<T>;
+    /**
+     * Get active requests
+     */
+    getActiveRequests(): number;
+    /**
+     * Get queue size
+     */
+    getQueueSize(): number;
+    /**
+     * Get statistics
+     */
+    getStats(): {
+        activeRequests: number;
+        queueSize: number;
+        maxConcurrent: number;
+        maxQueue: number;
+    };
+}
+/**
+ * Combined resilience wrapper
+ */
+declare class ResilientOperation<T> {
+    private fn;
+    private circuitBreaker?;
+    private bulkhead?;
+    constructor(fn: () => Promise<T>, circuitBreaker?: CircuitBreaker | undefined, bulkhead?: Bulkhead | undefined);
+    /**
+     * Execute with all resilience patterns
+     */
+    execute(): Promise<T>;
+}
+/**
+ * Create resilient function
+ */
+declare function createResilientFunction<T>(fn: () => Promise<T>, options?: {
+    circuitBreaker?: CircuitBreakerConfig;
+    bulkhead?: {
+        maxConcurrent: number;
+        maxQueue: number;
+    };
+}): () => Promise<T>;
+
+/**
+ * Internal logger for @revealui/resilience.
+ *
+ * Defaults to `console`. Consumers should call `configureResilienceLogger()`
+ * to supply a structured logger (e.g. from `@revealui/utils/logger`).
+ */
+interface ResilienceLogger {
+    warn(message: string, ...args: unknown[]): void;
+    error(message: string, ...args: unknown[]): void;
+    info(message: string, ...args: unknown[]): void;
+    debug(message: string, ...args: unknown[]): void;
+}
+/**
+ * Replace the default console logger with a structured logger.
+ */
+declare function configureResilienceLogger(logger: ResilienceLogger): void;
+/**
+ * Get the current resilience logger instance.
+ */
+declare function getResilienceLogger(): ResilienceLogger;
+
+/**
+ * Retry Logic for API Calls
+ *
+ * Implements exponential backoff and retry strategies
+ */
+interface HttpError extends Error {
+    statusCode?: number;
+    response?: Response;
+}
+interface RetryConfig {
+    maxRetries?: number;
+    baseDelay?: number;
+    maxDelay?: number;
+    exponentialBackoff?: boolean;
+    jitter?: boolean;
+    retryableErrors?: (error: Error) => boolean;
+    onRetry?: (error: Error, attempt: number) => void;
+}
+interface RetryOptions {
+    signal?: AbortSignal;
+}
+/**
+ * Retry a function with exponential backoff
+ */
+declare function retry<T>(fn: () => Promise<T>, config?: RetryConfig, options?: RetryOptions): Promise<T>;
+/**
+ * Calculate retry delay with exponential backoff
+ */
+declare function calculateDelay(attempt: number, baseDelay: number, maxDelay: number, exponentialBackoff: boolean, jitter: boolean): number;
+/**
+ * Sleep with abort support
+ */
+declare function sleep(ms: number, signal?: AbortSignal): Promise<void>;
+/**
+ * Retry wrapper for fetch
+ */
+declare function fetchWithRetry(url: string, init?: RequestInit, config?: RetryConfig): Promise<Response>;
+/**
+ * Retry wrapper class
+ */
+declare class RetryableOperation<T> {
+    private fn;
+    private config;
+    private abortController;
+    private attempts;
+    private lastError?;
+    constructor(fn: () => Promise<T>, config?: RetryConfig);
+    /**
+     * Execute with retry
+     */
+    execute(): Promise<T>;
+    /**
+     * Abort operation
+     */
+    abort(): void;
+    /**
+     * Get retry statistics
+     */
+    getStats(): {
+        attempts: number;
+        lastError?: Error;
+    };
+}
+/**
+ * Retry decorator
+ */
+declare function Retryable(config?: RetryConfig): (_target: object, _propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
+/**
+ * Create retry middleware for API client
+ */
+declare function createRetryMiddleware<TRequest = unknown, TResponse = unknown>(config?: RetryConfig): (_request: TRequest, next: () => Promise<TResponse>) => Promise<TResponse>;
+/**
+ * Batch retry - retry multiple operations
+ */
+declare function retryBatch<T>(operations: Array<() => Promise<T>>, config?: RetryConfig): Promise<Array<T | Error>>;
+/**
+ * Retry with fallback
+ */
+declare function retryWithFallback<T>(primary: () => Promise<T>, fallback: () => Promise<T>, config?: RetryConfig): Promise<T>;
+/**
+ * Conditional retry - only retry if condition is met
+ */
+declare function retryIf<T>(fn: () => Promise<T>, condition: (error: Error, attempt: number) => boolean, config?: RetryConfig): Promise<T>;
+/**
+ * Retry until condition is met
+ */
+declare function retryUntil<T>(fn: () => Promise<T>, predicate: (result: T) => boolean, config?: RetryConfig, maxAttempts?: number): Promise<T>;
+/**
+ * Exponential backoff iterator
+ */
+declare class ExponentialBackoff implements AsyncIterable<number> {
+    private baseDelay;
+    private maxDelay;
+    private maxAttempts;
+    private jitter;
+    constructor(baseDelay?: number, maxDelay?: number, maxAttempts?: number, jitter?: boolean);
+    [Symbol.asyncIterator](): AsyncIterator<number>;
+}
+/**
+ * Retry policy builder
+ */
+declare class RetryPolicyBuilder {
+    private config;
+    /**
+     * Set max retries
+     */
+    maxRetries(count: number): this;
+    /**
+     * Set base delay
+     */
+    baseDelay(ms: number): this;
+    /**
+     * Set max delay
+     */
+    maxDelay(ms: number): this;
+    /**
+     * Enable/disable exponential backoff
+     */
+    exponentialBackoff(enabled?: boolean): this;
+    /**
+     * Enable/disable jitter
+     */
+    jitter(enabled?: boolean): this;
+    /**
+     * Set custom retryable errors function
+     */
+    retryOn(fn: (error: Error) => boolean): this;
+    /**
+     * Set retry callback
+     */
+    onRetry(fn: (error: Error, attempt: number) => void): this;
+    /**
+     * Build retry config
+     */
+    build(): RetryConfig;
+    /**
+     * Execute function with built policy
+     */
+    execute<T>(fn: () => Promise<T>): Promise<T>;
+}
+/**
+ * Common retry policies
+ */
+declare const RetryPolicies: {
+    /**
+     * Default policy - 3 retries with exponential backoff
+     */
+    default: () => RetryConfig;
+    /**
+     * Aggressive policy - more retries, faster backoff
+     */
+    aggressive: () => RetryConfig;
+    /**
+     * Conservative policy - fewer retries, longer backoff
+     */
+    conservative: () => RetryConfig;
+    /**
+     * Linear backoff policy
+     */
+    linear: () => RetryConfig;
+    /**
+     * Immediate retry policy - no delay
+     */
+    immediate: () => RetryConfig;
+    /**
+     * Network error only policy
+     */
+    networkOnly: () => RetryConfig;
+    /**
+     * Idempotent operations policy (safe to retry)
+     */
+    idempotent: () => RetryConfig;
+};
+/**
+ * Global retry configuration
+ */
+declare class GlobalRetryConfig {
+    private config;
+    /**
+     * Set global retry config
+     */
+    setConfig(config: RetryConfig): void;
+    /**
+     * Get global retry config
+     */
+    getConfig(): RetryConfig;
+    /**
+     * Reset to default config
+     */
+    reset(): void;
+}
+declare const globalRetryConfig: GlobalRetryConfig;
+
+export { AdaptiveCircuitBreaker, Bulkhead, CircuitBreak, CircuitBreaker, type CircuitBreakerConfig, CircuitBreakerOpenError, CircuitBreakerRegistry, type CircuitBreakerStats, type CircuitState, ExponentialBackoff, type HttpError, type ResilienceLogger, ResilientOperation, type RetryConfig, type RetryOptions, RetryPolicies, RetryPolicyBuilder, Retryable, RetryableOperation, calculateDelay, circuitBreakerRegistry, configureResilienceLogger, createCircuitBreakerMiddleware, createResilientFunction, createRetryMiddleware, fetchWithCircuitBreaker, fetchWithRetry, getResilienceLogger, globalRetryConfig, retry, retryBatch, retryIf, retryUntil, retryWithFallback, sleep, withCircuitBreaker };