@stacksjs/bun-router 0.0.4 → 0.0.6

package/dist/errors/circuit-breaker.d.ts

@@ -0,0 +1,195 @@
+/**
+ * Advanced Error Handling - Circuit Breaker Pattern
+ *
+ * Prevents cascading failures by monitoring external service health
+ * and temporarily blocking requests when services are failing
+ */
+import type { ErrorContext } from './exceptions';
+export interface CircuitBreakerConfig {
+    name: string;
+    failureThreshold: number;
+    recoveryTimeout: number;
+    timeout: number;
+    monitoringPeriod: number;
+    minimumRequests: number;
+    errorThresholdPercentage: number;
+    halfOpenMaxCalls: number;
+    resetTimeout: number;
+    onStateChange?: (state: CircuitBreakerState, name: string) => void;
+    onFailure?: (error: Error, name: string) => void;
+    onSuccess?: (name: string) => void;
+    shouldTripOnError?: (error: Error) => boolean;
+}
+export type CircuitBreakerState = 'CLOSED' | 'OPEN' | 'HALF_OPEN';
+export interface CircuitBreakerMetrics {
+    totalRequests: number;
+    successfulRequests: number;
+    failedRequests: number;
+    timeouts: number;
+    averageResponseTime: number;
+    lastFailureTime?: Date;
+    lastSuccessTime?: Date;
+    state: CircuitBreakerState;
+    nextAttemptTime?: Date;
+    consecutiveFailures: number;
+    consecutiveSuccesses: number;
+}
+export interface CircuitBreakerCall<T> {
+    execute: () => Promise<T>;
+    fallback?: () => Promise<T>;
+    timeout?: number;
+    retries?: number;
+    context?: ErrorContext;
+}
+/**
+ * Circuit breaker implementation
+ */
+export declare class CircuitBreaker {
+    private config;
+    private state;
+    private metrics;
+    private nextAttemptTime?;
+    private halfOpenCallCount;
+    private recentRequests;
+    constructor(config: CircuitBreakerConfig);
+    /**
+     * Execute a function with circuit breaker protection
+     */
+    execute<T>(call: CircuitBreakerCall<T>): Promise<T>;
+    /**
+     * Get current circuit breaker state
+     */
+    getState(): CircuitBreakerState;
+    /**
+     * Get circuit breaker metrics
+     */
+    getMetrics(): CircuitBreakerMetrics;
+    /**
+     * Force circuit breaker to open state
+     */
+    forceOpen(): void;
+    /**
+     * Force circuit breaker to closed state
+     */
+    forceClosed(): void;
+    /**
+     * Reset circuit breaker metrics
+     */
+    reset(): void;
+    private onSuccess;
+    private onFailure;
+    private shouldTrip;
+    private transitionToClosed;
+    private transitionToOpen;
+    private transitionToHalfOpen;
+    private updateAverageResponseTime;
+    private getRecentRequests;
+    private cleanupOldRequests;
+}
+/**
+ * Circuit breaker registry for managing multiple circuit breakers
+ */
+export declare class CircuitBreakerRegistry {
+    private breakers;
+    private configs;
+    /**
+     * Register a new circuit breaker
+     */
+    register(config: CircuitBreakerConfig): CircuitBreaker;
+    /**
+     * Get circuit breaker by name
+     */
+    get(name: string): CircuitBreaker | undefined;
+    /**
+     * Execute function with circuit breaker protection
+     */
+    execute<T>(name: string, call: CircuitBreakerCall<T>): Promise<T>;
+    /**
+     * Get all circuit breaker metrics
+     */
+    getAllMetrics(): Record<string, CircuitBreakerMetrics>;
+    /**
+     * Get circuit breakers by state
+     */
+    getBreakersByState(state: CircuitBreakerState): string[];
+    /**
+     * Force all circuit breakers to closed state
+     */
+    forceAllClosed(): void;
+    /**
+     * Reset all circuit breaker metrics
+     */
+    resetAll(): void;
+    /**
+     * Remove circuit breaker
+     */
+    remove(name: string): boolean;
+    /**
+     * Get all registered circuit breaker names
+     */
+    getNames(): string[];
+}
+/**
+ * Decorator for circuit breaker protection
+ */
+export declare function circuitBreaker(config: CircuitBreakerConfig): <T extends (...args: any[]) => Promise<any>>(target: any, propertyName: string, descriptor: TypedPropertyDescriptor<T>) => TypedPropertyDescriptor<T>;
+/**
+ * HTTP client with circuit breaker protection
+ */
+export declare class CircuitBreakerHttpClient {
+    private registry;
+    constructor(registry?: CircuitBreakerRegistry);
+    /**
+     * Make HTTP request with circuit breaker protection
+     */
+    fetch(url: string, options?: RequestInit & {
+        circuitBreaker?: string | CircuitBreakerConfig;
+        fallback?: () => Promise<Response>;
+        context?: ErrorContext;
+    }): Promise<Response>;
+    /**
+     * Get circuit breaker registry
+     */
+    getRegistry(): CircuitBreakerRegistry;
+}
+/**
+ * Middleware for circuit breaker protection
+ */
+export declare function createCircuitBreakerMiddleware(registry: CircuitBreakerRegistry): (req: any, next: () => Promise<Response>) => Promise<Response>;
+/**
+ * Factory functions for common circuit breaker configurations
+ */
+export declare const CircuitBreakerPresets: {
+    /**
+     * Fast-failing circuit breaker for critical services
+     */
+    critical: (name: string) => CircuitBreakerConfig;
+    /**
+     * Standard circuit breaker for regular services
+     */
+    standard: (name: string) => CircuitBreakerConfig;
+    /**
+     * Tolerant circuit breaker for non-critical services
+     */
+    tolerant: (name: string) => CircuitBreakerConfig;
+    /**
+     * Database circuit breaker with longer timeouts
+     */
+    database: (name: string) => CircuitBreakerConfig;
+    /**
+     * External API circuit breaker
+     */
+    externalApi: (name: string) => CircuitBreakerConfig;
+};
+/**
+ * Global circuit breaker registry instance
+ */
+export declare const globalCircuitBreakerRegistry: CircuitBreakerRegistry;
+/**
+ * Convenience function to create and register a circuit breaker
+ */
+export declare function createCircuitBreaker(config: CircuitBreakerConfig): CircuitBreaker;
+/**
+ * Convenience function to execute with circuit breaker protection
+ */
+export declare function withCircuitBreaker<T>(name: string, call: CircuitBreakerCall<T>): Promise<T>;

package/dist/errors/error-handler.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Advanced Error Handling - Main Error Handler Middleware
+ *
+ * Unified error handling middleware that integrates all error handling components
+ */
+import type { CircuitBreakerConfig, DegradationConfig, EnhancedRequest, ErrorReportingConfig } from '../types';
+import { RouterException } from './exceptions';
+export interface AdvancedErrorHandlerConfig {
+    errorReporting?: ErrorReportingConfig[];
+    gracefulDegradation?: DegradationConfig;
+    circuitBreakers?: CircuitBreakerConfig[];
+    globalErrorHandler?: (error: RouterException, req: EnhancedRequest) => Promise<Response>;
+    development?: boolean;
+    includeStackTrace?: boolean;
+    sanitizeErrors?: boolean;
+    logErrors?: boolean;
+    customErrorPages?: {
+        [statusCode: number]: string | ((_error: RouterException, _req: EnhancedRequest) => Promise<Response>);
+    };
+}
+/**
+ * Advanced error handler middleware
+ */
+export declare class AdvancedErrorHandler {
+    private errorReporting?;
+    private gracefulDegradation?;
+    private circuitBreakerRegistry?;
+    private config;
+    constructor(config?: AdvancedErrorHandlerConfig);
+    private initializeComponents;
+    /**
+     * Main error handling middleware
+     */
+    middleware(): (req: EnhancedRequest, next: () => Promise<Response>) => Promise<Response>;
+    /**
+     * Handle errors with full advanced error handling pipeline
+     */
+    handleError(error: unknown, req: EnhancedRequest): Promise<Response>;
+    /**
+     * Convert any error to RouterException
+     */
+    private normalizeError;
+    /**
+     * Create standardized error response
+     */
+    private createErrorResponse;
+    /**
+     * Log error with appropriate level
+     */
+    private logError;
+    /**
+     * Get error handler statistics
+     */
+    getStats(): {
+        errorReporting?: any;
+        gracefulDegradation?: any;
+        circuitBreakers?: any;
+    };
+    /**
+     * Cleanup resources
+     */
+    cleanup(): Promise<void>;
+}
+/**
+ * Factory function to create advanced error handler middleware
+ */
+export declare function createAdvancedErrorHandler(config?: AdvancedErrorHandlerConfig): {
+    middleware: (req: EnhancedRequest, next: () => Promise<Response>) => Promise<Response>;
+    getStats: () => {
+        errorReporting?: any;
+        gracefulDegradation?: any;
+        circuitBreakers?: any;
+    };
+    cleanup: () => Promise<void>;
+};
+/**
+ * Preset configurations for different environments
+ */
+export declare const ErrorHandlerPresets: {
+    development: () => AdvancedErrorHandlerConfig;
+    production: (sentryDsn?: string, bugsnagApiKey?: string) => AdvancedErrorHandlerConfig;
+    staging: (sentryDsn?: string) => AdvancedErrorHandlerConfig;
+    resilient: (config?: {
+        sentryDsn?: string;
+        bugsnagApiKey?: string;
+        services?: string[];
+    }) => AdvancedErrorHandlerConfig;
+};

package/dist/errors/error-reporting.d.ts

@@ -0,0 +1,144 @@
+/**
+ * Advanced Error Handling - Error Reporting Integration
+ *
+ * Integration with external error reporting services (Sentry, Bugsnag, etc.)
+ */
+import type { ErrorContext, RouterException } from './exceptions';
+export interface ErrorReportingConfig {
+    enabled: boolean;
+    service: 'sentry' | 'bugsnag' | 'custom';
+    dsn?: string;
+    apiKey?: string;
+    environment?: string;
+    release?: string;
+    sampleRate?: number;
+    beforeSend?: (error: Error, context: ErrorContext) => Error | null;
+    filters?: {
+        ignoreErrors?: (string | RegExp)[];
+        ignoreCodes?: string[];
+        ignoreUrls?: (string | RegExp)[];
+        allowUrls?: (string | RegExp)[];
+    };
+    tags?: Record<string, string>;
+    user?: {
+        id?: string;
+        email?: string;
+        username?: string;
+    };
+    extra?: Record<string, any>;
+    breadcrumbs?: {
+        enabled: boolean;
+        maxBreadcrumbs: number;
+    };
+    performance?: {
+        enabled: boolean;
+        tracesSampleRate: number;
+    };
+}
+export interface ErrorReport {
+    error: RouterException;
+    context: ErrorContext;
+    fingerprint?: string[];
+    tags?: Record<string, string>;
+    extra?: Record<string, any>;
+    user?: Record<string, any>;
+    level?: 'debug' | 'info' | 'warning' | 'error' | 'fatal';
+}
+export interface ErrorReporter {
+    report: (error: RouterException, context?: ErrorContext) => Promise<string | null>;
+    addBreadcrumb: (message: string, category?: string, level?: string, data?: Record<string, any>) => void;
+    setUser: (user: Record<string, any>) => void;
+    setTag: (key: string, value: string) => void;
+    setExtra: (key: string, value: any) => void;
+    setContext: (key: string, context: Record<string, any>) => void;
+    close: (timeout?: number) => Promise<boolean>;
+}
+/**
+ * Sentry error reporter implementation
+ */
+export declare class SentryReporter implements ErrorReporter {
+    private config;
+    private sentry;
+    constructor(config: ErrorReportingConfig);
+    private initializeSentry;
+    report(error: RouterException, context?: ErrorContext): Promise<string | null>;
+    addBreadcrumb(message: string, category?: string, level?: string, data?: Record<string, any>): void;
+    setUser(user: Record<string, any>): void;
+    setTag(key: string, value: string): void;
+    setExtra(key: string, value: any): void;
+    setContext(key: string, context: Record<string, any>): void;
+    close(timeout?: number): Promise<boolean>;
+    private shouldIgnoreError;
+    private mapSeverityToLevel;
+    private generateFingerprint;
+}
+/**
+ * Bugsnag error reporter implementation
+ */
+export declare class BugsnagReporter implements ErrorReporter {
+    private config;
+    private bugsnag;
+    constructor(config: ErrorReportingConfig);
+    private initializeBugsnag;
+    report(error: RouterException, context?: ErrorContext): Promise<string | null>;
+    addBreadcrumb(message: string, category?: string, _level?: string, data?: Record<string, any>): void;
+    setUser(user: Record<string, any>): void;
+    setTag(key: string, value: string): void;
+    setExtra(key: string, value: any): void;
+    setContext(key: string, context: Record<string, any>): void;
+    close(): Promise<boolean>;
+    private shouldIgnoreError;
+    private mapSeverityToBugsnag;
+    private generateGroupingHash;
+}
+/**
+ * Custom error reporter for custom implementations
+ */
+export declare class CustomReporter implements ErrorReporter {
+    private config;
+    private reportHandler;
+    constructor(config: ErrorReportingConfig, reportHandler: (report: ErrorReport) => Promise<string | null>);
+    report(error: RouterException, context?: ErrorContext): Promise<string | null>;
+    addBreadcrumb(): void;
+    setUser(): void;
+    setTag(): void;
+    setExtra(): void;
+    setContext(): void;
+    close(): Promise<boolean>;
+    private mapSeverityToLevel;
+}
+/**
+ * Error reporting manager
+ */
+export declare class ErrorReportingManager {
+    private reporters;
+    private breadcrumbs;
+    private maxBreadcrumbs;
+    constructor(configs: ErrorReportingConfig[]);
+    private initializeReporters;
+    addReporter(reporter: ErrorReporter): void;
+    report(error: RouterException, context?: ErrorContext): Promise<string[]>;
+    addBreadcrumb(message: string, category?: string, data?: any): void;
+    setUser(user: Record<string, any>): void;
+    setTag(key: string, value: string): void;
+    setExtra(key: string, value: any): void;
+    setContext(key: string, context: Record<string, any>): void;
+    close(timeout?: number): Promise<boolean>;
+    getBreadcrumbs(): Array<{
+        message: string;
+        timestamp: Date;
+        data?: any;
+    }>;
+}
+/**
+ * Factory function to create error reporting manager
+ */
+export declare function createErrorReporting(configs: ErrorReportingConfig[]): ErrorReportingManager;
+/**
+ * Default configuration presets
+ */
+export declare const ErrorReportingPresets: {
+    sentry: (dsn: string, environment?: string) => ErrorReportingConfig;
+    bugsnag: (apiKey: string, environment?: string) => ErrorReportingConfig;
+    development: () => ErrorReportingConfig;
+};

package/dist/errors/exceptions.d.ts

@@ -0,0 +1,184 @@
+/**
+ * Advanced Error Handling - Exception Hierarchy
+ *
+ * Comprehensive exception types with metadata, stack traces, and context information
+ */
+export interface ErrorContext {
+    requestId?: string;
+    userId?: string | number;
+    traceId?: string;
+    spanId?: string;
+    route?: string;
+    method?: string;
+    url?: string;
+    userAgent?: string;
+    ip?: string;
+    timestamp?: Date;
+    metadata?: Record<string, unknown>;
+}
+export interface ErrorDetails {
+    code: string;
+    message: string;
+    context?: ErrorContext;
+    cause?: Error;
+    statusCode?: number;
+    retryable?: boolean;
+    severity?: 'low' | 'medium' | 'high' | 'critical';
+    category?: 'validation' | 'authentication' | 'authorization' | 'network' | 'database' | 'external' | 'system' | 'business';
+}
+/**
+ * Base exception class for all router errors
+ */
+export declare abstract class RouterException extends Error {
+    readonly code: string;
+    readonly statusCode: number;
+    readonly context: ErrorContext;
+    readonly retryable: boolean;
+    readonly severity: 'low' | 'medium' | 'high' | 'critical';
+    readonly category: string;
+    readonly timestamp: Date;
+    readonly cause?: Error;
+    constructor(details: ErrorDetails);
+    /**
+     * Convert error to JSON for logging/reporting
+     */
+    toJSON(): Record<string, any>;
+    /**
+     * Create HTTP response for this error
+     */
+    toResponse(): Response;
+}
+/**
+ * Validation errors (400)
+ */
+export declare class ValidationException extends RouterException {
+    readonly fields: Record<string, string[]>;
+    constructor(message: string, fields?: Record<string, string[]>, context?: ErrorContext);
+    toResponse(): Response;
+}
+/**
+ * Authentication errors (401)
+ */
+export declare class AuthenticationException extends RouterException {
+    constructor(message?: string, context?: ErrorContext);
+}
+/**
+ * Authorization errors (403)
+ */
+export declare class AuthorizationException extends RouterException {
+    readonly requiredPermissions?: string[];
+    constructor(message?: string, requiredPermissions?: string[], context?: ErrorContext);
+}
+/**
+ * Resource not found errors (404)
+ */
+export declare class NotFoundException extends RouterException {
+    readonly resource?: string;
+    readonly resourceId?: string;
+    constructor(message?: string, resource?: string, resourceId?: string, context?: ErrorContext);
+}
+/**
+ * Method not allowed errors (405)
+ */
+export declare class MethodNotAllowedException extends RouterException {
+    readonly allowedMethods: string[];
+    constructor(method: string, allowedMethods: string[], context?: ErrorContext);
+    toResponse(): Response;
+}
+/**
+ * Request timeout errors (408)
+ */
+export declare class TimeoutException extends RouterException {
+    readonly timeoutMs: number;
+    constructor(message: string | undefined, timeoutMs: number, context?: ErrorContext);
+}
+/**
+ * Rate limit exceeded errors (429)
+ */
+export declare class RateLimitException extends RouterException {
+    readonly retryAfter: number;
+    readonly limit: number;
+    readonly remaining: number;
+    constructor(message: string | undefined, retryAfter: number, limit: number, remaining?: number, context?: ErrorContext);
+    toResponse(): Response;
+}
+/**
+ * Internal server errors (500)
+ */
+export declare class InternalServerException extends RouterException {
+    constructor(message?: string, cause?: Error, context?: ErrorContext);
+}
+/**
+ * Service unavailable errors (503)
+ */
+export declare class ServiceUnavailableException extends RouterException {
+    readonly retryAfter?: number;
+    constructor(message?: string, retryAfter?: number, context?: ErrorContext);
+    toResponse(): Response;
+}
+/**
+ * Database errors
+ */
+export declare class DatabaseException extends RouterException {
+    readonly query?: string;
+    readonly operation?: string;
+    constructor(message: string, operation?: string, query?: string, cause?: Error, context?: ErrorContext);
+}
+/**
+ * External service errors
+ */
+export declare class ExternalServiceException extends RouterException {
+    readonly service: string;
+    readonly endpoint?: string;
+    constructor(message: string, service: string, endpoint?: string, statusCode?: number, cause?: Error, context?: ErrorContext);
+}
+/**
+ * Circuit breaker open errors
+ */
+export declare class CircuitBreakerOpenException extends RouterException {
+    readonly service: string;
+    readonly nextAttemptAt: Date;
+    constructor(service: string, nextAttemptAt: Date, context?: ErrorContext);
+}
+/**
+ * Business logic errors
+ */
+export declare class BusinessLogicException extends RouterException {
+    readonly businessRule: string;
+    constructor(message: string, businessRule: string, context?: ErrorContext);
+}
+/**
+ * Configuration errors
+ */
+export declare class ConfigurationException extends RouterException {
+    readonly configKey: string;
+    constructor(message: string, configKey: string, context?: ErrorContext);
+}
+/**
+ * File system errors
+ */
+export declare class FileSystemException extends RouterException {
+    readonly path: string;
+    readonly operation: string;
+    constructor(message: string, path: string, operation: string, cause?: Error, context?: ErrorContext);
+}
+/**
+ * Factory functions for common errors
+ */
+export declare const ErrorFactory: {
+    validation: (message: string, fields?: Record<string, string[]>, context?: ErrorContext) => ValidationException;
+    authentication: (message?: string, context?: ErrorContext) => AuthenticationException;
+    authorization: (message?: string, requiredPermissions?: string[], context?: ErrorContext) => AuthorizationException;
+    notFound: (resource?: string, resourceId?: string, context?: ErrorContext) => NotFoundException;
+    methodNotAllowed: (method: string, allowedMethods: string[], context?: ErrorContext) => MethodNotAllowedException;
+    timeout: (timeoutMs: number, message?: string, context?: ErrorContext) => TimeoutException;
+    rateLimit: (retryAfter: number, limit: number, remaining?: number, context?: ErrorContext) => RateLimitException;
+    internalServer: (message?: string, cause?: Error, context?: ErrorContext) => InternalServerException;
+    serviceUnavailable: (message?: string, retryAfter?: number, context?: ErrorContext) => ServiceUnavailableException;
+    database: (message: string, operation?: string, query?: string, cause?: Error, context?: ErrorContext) => DatabaseException;
+    externalService: (message: string, service: string, endpoint?: string, statusCode?: number, cause?: Error, context?: ErrorContext) => ExternalServiceException;
+    circuitBreakerOpen: (service: string, nextAttemptAt: Date, context?: ErrorContext) => CircuitBreakerOpenException;
+    businessLogic: (message: string, businessRule: string, context?: ErrorContext) => BusinessLogicException;
+    configuration: (message: string, configKey: string, context?: ErrorContext) => ConfigurationException;
+    fileSystem: (message: string, path: string, operation: string, cause?: Error, context?: ErrorContext) => FileSystemException;
+};