@stacksjs/bun-router 0.0.14 → 0.0.15

package/dist/development/typescript-utilities.d.ts

@@ -0,0 +1,209 @@
+/**
+ * Development Tools - TypeScript Utilities
+ *
+ * TypeScript development utilities, type checking, and code generation
+ */
+import type { EnhancedRequest } from '../types';
+export interface TypeScriptConfig {
+    strictMode?: boolean;
+    generateTypes?: boolean;
+    validateTypes?: boolean;
+    outputDir?: string;
+    includeComments?: boolean;
+    generateSchemas?: boolean;
+}
+export interface RouteTypeInfo {
+    method: string;
+    pattern: string;
+    requestType: string;
+    responseType: string;
+    paramsType: string;
+    queryType: string;
+    bodyType: string;
+    middlewareTypes: string[];
+    handlerSignature: string;
+}
+export interface TypeDefinition {
+    name: string;
+    type: 'interface' | 'type' | 'enum' | 'class';
+    definition: string;
+    imports: string[];
+    exports: string[];
+    documentation?: string;
+}
+export interface ValidationSchema {
+    type: 'object' | 'array' | 'string' | 'number' | 'boolean';
+    properties?: Record<string, ValidationSchema>;
+    items?: ValidationSchema;
+    required?: string[];
+    pattern?: string;
+    minimum?: number;
+    maximum?: number;
+    enum?: any[];
+}
+/**
+ * TypeScript utilities for development
+ */
+export declare class TypeScriptUtilities {
+    private config;
+    private routeTypes;
+    private typeDefinitions;
+    constructor(config?: TypeScriptConfig);
+    /**
+     * Register route type information
+     */
+    registerRouteTypes(method: string, pattern: string, options?: {
+        requestType?: string;
+        responseType?: string;
+        paramsType?: string;
+        queryType?: string;
+        bodyType?: string;
+        middlewareTypes?: string[];
+        handlerSignature?: string;
+    }): void;
+    /**
+     * Generate TypeScript definitions for all routes
+     */
+    generateRouteTypes(): string;
+    /**
+     * Generate validation schemas from TypeScript types
+     */
+    generateValidationSchemas(): Record<string, ValidationSchema>;
+    /**
+     * Generate OpenAPI schema from route types
+     */
+    generateOpenAPISchema(): any;
+    /**
+     * Validate request against TypeScript types
+     */
+    validateRequest(req: EnhancedRequest, routeKey: string): {
+        valid: boolean;
+        errors: string[];
+        warnings: string[];
+    };
+    /**
+     * Generate type-safe route builder
+     */
+    generateRouteBuilder(): string;
+    /**
+     * Generate middleware type definitions
+     */
+    generateMiddlewareTypes(): string;
+    /**
+     * Get route type information
+     */
+    getRouteTypes(): RouteTypeInfo[];
+    /**
+     * Get type definition
+     */
+    getTypeDefinition(name: string): TypeDefinition | undefined;
+    /**
+     * Register custom type definition
+     */
+    registerTypeDefinition(definition: TypeDefinition): void;
+    /**
+     * Clear all type information
+     */
+    clear(): void;
+    /**
+     * Infer parameter types from route pattern
+     */
+    private inferParamsType;
+    /**
+     * Extract path parameters from pattern
+     */
+    private extractPathParameters;
+    /**
+     * Infer parameter type from constraint
+     */
+    private inferParamType;
+    /**
+     * Generate handler signature
+     */
+    private generateHandlerSignature;
+    /**
+     * Generate imports section
+     */
+    private generateImports;
+    /**
+     * Generate parameter types
+     */
+    private generateParamTypes;
+    /**
+     * Generate handler types
+     */
+    private generateHandlerTypes;
+    /**
+     * Generate route registry type
+     */
+    private generateRouteRegistryType;
+    /**
+     * Generate utility types
+     */
+    private generateUtilityTypes;
+    /**
+     * Convert path to type name
+     */
+    private pathToTypeName;
+    /**
+     * Convert path to method name
+     */
+    private pathToMethodName;
+    /**
+     * Convert path to operation ID
+     */
+    private pathToOperationId;
+    /**
+     * Convert TypeScript type to validation schema
+     */
+    private typeToSchema;
+    /**
+     * Convert TypeScript type to OpenAPI schema
+     */
+    private typeToOpenAPISchema;
+    /**
+     * Validate request parameters
+     */
+    private validateParams;
+    /**
+     * Validate query parameters
+     */
+    private validateQuery;
+    /**
+     * Validate request body
+     */
+    private validateBody;
+}
+/**
+ * Initialize global TypeScript utilities
+ */
+export declare function initializeTypeScriptUtilities(config?: TypeScriptConfig): TypeScriptUtilities;
+/**
+ * Get global TypeScript utilities
+ */
+export declare function getTypeScriptUtilities(): TypeScriptUtilities | null;
+/**
+ * TypeScript development helpers
+ */
+export declare const TypeScriptHelpers: {
+    /**
+     * Generate types for current routes
+     */
+    generateTypes: () => string;
+    /**
+     * Generate validation schemas
+     */
+    generateSchemas: () => Record<string, ValidationSchema>;
+    /**
+     * Generate OpenAPI documentation
+     */
+    generateOpenAPI: () => any;
+    /**
+     * Validate request types
+     */
+    validateRequest: (req: EnhancedRequest, routeKey: string) => {
+        valid: boolean;
+        errors: string[];
+        warnings: string[];
+    };
+};

package/dist/docs.d.ts

@@ -0,0 +1,11 @@
+interface DocsOptions {
+    verbose?: boolean;
+    output?: string;
+    groupBy?: 'path' | 'method' | 'tag';
+    includeExamples?: boolean;
+}
+/**
+ * Generates API documentation from route definitions
+ */
+export declare function generateApiDocs(options?: DocsOptions): Promise<void>;
+export {};

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;
+};