@stacksjs/bun-router 0.0.2

package/dist/development/route-debugger.d.ts

@@ -0,0 +1,102 @@
+import type { EnhancedRequest } from '../types';
+/**
+ * Initialize global route debugger
+ */
+export declare function initializeRouteDebugger(config?: RouteDebugConfig): RouteDebugger;
+/**
+ * Get global route debugger
+ */
+export declare function getRouteDebugger(): RouteDebugger | null;
+/**
+ * Route debugging middleware factory
+ */
+export declare function createRouteDebugMiddleware(config?: RouteDebugConfig): void;
+/**
+ * Route debugging helpers
+ */
+export declare const RouteDebugHelpers: {
+  /**
+   * Record route match attempt from request context
+   */
+  recordMatch: (req: EnhancedRequest, pattern: string, method: string, matched: boolean, reason?: string, params?: Record<string, string>) => any;
+  /**
+   * Record final match from request context
+   */
+  recordFinalMatch: (req: EnhancedRequest, pattern: string, handler: (...args: any[]) => any, middleware: ((...args: any[]) => any)[], params: Record<string, string>) => any;
+  /**
+   * Record timing from request context
+   */
+  recordTiming: (req: EnhancedRequest, phase: keyof RouteDebugInfo['timings'], duration: number) => any
+};
+export declare interface RouteDebugConfig {
+  enabled?: boolean
+  logLevel?: 'debug' | 'info' | 'warn' | 'error'
+  includeHeaders?: boolean
+  includeBody?: boolean
+  includeParams?: boolean
+  includeQuery?: boolean
+  includeTimings?: boolean
+  maxBodySize?: number
+  colorOutput?: boolean
+  outputFormat?: 'console' | 'json' | 'structured'
+}
+export declare interface RouteMatchAttempt {
+  pattern: string
+  method: string
+  matched: boolean
+  reason?: string
+  params?: Record<string, string>
+  score?: number
+  timing: number
+}
+export declare interface RouteDebugInfo {
+  requestId: string
+  timestamp: number
+  method: string
+  url: string
+  path: string
+  headers?: Record<string, string>
+  query?: Record<string, string>
+  params?: Record<string, string>
+  body?: any
+  matchAttempts: RouteMatchAttempt[]
+  finalMatch?: {
+    pattern: string
+    handler: string
+    middleware: string[]
+    params: Record<string, string>
+  }
+  timings: {
+    routeMatching: number
+    middlewareExecution: number
+    handlerExecution: number
+    total: number
+  }
+  performance: {
+    memoryUsage: NodeJS.MemoryUsage
+    cpuTime: number
+  }
+}
+/**
+ * Route debugger for development
+ */
+export declare class RouteDebugger {
+  private config: RouteDebugConfig;
+  private debugSessions: any;
+  private routePatterns: any;
+  constructor(config?: RouteDebugConfig);
+  startDebugging(req: EnhancedRequest): string;
+  recordMatchAttempt(requestId: string, pattern: string, method: string, matched: boolean, reason?: string, params?: Record<string, string>): void;
+  recordFinalMatch(requestId: string, pattern: string, handler: (...args: any[]) => any, middleware: ((...args: any[]) => any)[], params: Record<string, string>): void;
+  recordTiming(requestId: string, phase: keyof RouteDebugInfo['timings'], duration: number): void;
+  finishDebugging(requestId: string, response?: Response): RouteDebugInfo | null;
+  registerRoute(method: string, pattern: string, handler: (...args: any[]) => any, middleware?: ((...args: any[]) => any)[]): void;
+  getRegisteredRoutes(): Array<{ method: string, pattern: string, handler: string, middleware: string[] }>;
+  getDebugSession(requestId: string): RouteDebugInfo | undefined;
+  clearSessions(): void;
+  private generateRequestId(): string;
+  private captureRequestBody(req: EnhancedRequest, debugInfo: RouteDebugInfo): Promise<void>;
+  private log(level: string, message: string, data?: any): void;
+  private logSummary(debugInfo: RouteDebugInfo, response?: Response): void;
+  private shouldLog(level: string): boolean;
+}

package/dist/development/route-inspector.d.ts

@@ -0,0 +1,142 @@
+/**
+ * Initialize global route inspector
+ */
+export declare function initializeRouteInspector(): RouteInspector;
+/**
+ * Get global route inspector
+ */
+export declare function getRouteInspector(): RouteInspector | null;
+/**
+ * Route inspection helpers
+ */
+export declare const RouteInspectionHelpers: {
+  /**
+   * List all routes in a formatted table
+   */
+  listRoutes: (filter?: Parameters<RouteInspector['getRoutes']>[0]) => any;
+  /**
+   * Analyze routes and show recommendations
+   */
+  analyzeRoutes: () => any;
+  /**
+   * Export routes to file
+   */
+  exportRoutes: (format: 'json' | 'csv' | 'markdown' | 'openapi' = 'json', filename?: string) => any
+};
+/**
+ * Development Tools - Route Inspector
+ *
+ * Route listing, metadata inspection, and route analysis
+ */
+export declare interface RouteMetadata {
+  id: string
+  method: string
+  pattern: string
+  originalPattern: string
+  handler: {
+    name: string
+    source?: string
+    parameters: string[]
+    isAsync: boolean
+  }
+  middleware: Array<{
+    name: string
+    source?: string
+    order: number
+  }>
+  params: Array<{
+    name: string
+    type: 'string' | 'number' | 'uuid' | 'slug'
+    optional: boolean
+    constraint?: string
+  }>
+  constraints: Record<string, any>
+  cache?: {
+    enabled: boolean
+    ttl?: number
+    tags?: string[]
+  }
+  throttling?: {
+    enabled: boolean
+    limit: number
+    window: number
+  }
+  validation?: {
+    rules: Record<string, string>
+    messages?: Record<string, string>
+  }
+  metadata: {
+    registeredAt: number
+    file?: string
+    line?: number
+    group?: string
+    name?: string
+    description?: string
+  }
+  stats: {
+    hits: number
+    averageResponseTime: number
+    lastAccessed?: number
+    errors: number
+  }
+}
+export declare interface RouteGroup {
+  name: string
+  prefix: string
+  middleware: string[]
+  routes: RouteMetadata[]
+  subgroups: RouteGroup[]
+}
+export declare interface RouteAnalysis {
+  totalRoutes: number
+  routesByMethod: Record<string, number>
+  duplicatePatterns: Array<{
+    pattern: string
+    routes: RouteMetadata[]
+  }>
+  unusedRoutes: RouteMetadata[]
+  slowRoutes: RouteMetadata[]
+  errorProneRoutes: RouteMetadata[]
+  middlewareUsage: Record<string, number>
+  parameterAnalysis: {
+    mostUsedParams: Array<{ name: string, count: number }>
+    parameterTypes: Record<string, number>
+  }
+  recommendations: string[]
+}
+/**
+ * Route inspector for development and debugging
+ */
+export declare class RouteInspector {
+  private routes: any;
+  private groups: any;
+  private routeStats: any;
+  registerRoute(method: string, pattern: string, handler: (...args: any[]) => any, middleware?: Array<(...args: any[]) => any>, options?: Partial<RouteMetadata>): string;
+  getRoutes(filter?: {
+    method?: string
+    pattern?: string
+    group?: string
+    hasMiddleware?: string
+    hasParams?: boolean
+  }): RouteMetadata[];
+  getRoute(id: string): RouteMetadata | undefined;
+  findMatchingRoutes(method: string, path: string): RouteMetadata[];
+  registerGroup(name: string, prefix: string, middleware?: Array<(...args: any[]) => any>): void;
+  getGroups(): RouteGroup[];
+  recordRouteAccess(routeId: string, responseTime: number, error?: boolean): void;
+  analyzeRoutes(): RouteAnalysis;
+  exportRoutes(format?: 'json' | 'csv' | 'markdown' | 'openapi'): string;
+  clear(): void;
+  private generateRouteId(method: string, pattern: string): string;
+  private getFunctionSource(fn: (...args: any[]) => any): string | undefined;
+  private extractFunctionParameters(fn: (...args: any[]) => any): string[];
+  private isAsyncFunction(fn: (...args: any[]) => any): boolean;
+  private extractRouteParameters(pattern: string): RouteMetadata['params'];
+  private inferParameterType(constraint?: string): 'string' | 'number' | 'uuid' | 'slug';
+  private getCallSiteInfo(): { file?: string, line?: number };
+  private patternToRegex(pattern: string): RegExp;
+  private generateRecommendations(analysis: RouteAnalysis): string[];
+  private exportToCsv(routes: RouteMetadata[]): string;
+  private exportToMarkdown(routes: RouteMetadata[]): string;
+  private exportToOpenAPI(routes: RouteMetadata[]): string;
+}

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

@@ -0,0 +1,116 @@
+import type { EnhancedRequest } from '../types';
+/**
+ * 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: () => any;
+  /**
+   * Generate validation schemas
+   */
+  generateSchemas: () => unknown;
+  /**
+   * Generate OpenAPI documentation
+   */
+  generateOpenAPI: () => any;
+  /**
+   * Validate request types
+   */
+  validateRequest: (req: EnhancedRequest, routeKey: string) => unknown
+};
+export declare interface TypeScriptConfig {
+  strictMode?: boolean
+  generateTypes?: boolean
+  validateTypes?: boolean
+  outputDir?: string
+  includeComments?: boolean
+  generateSchemas?: boolean
+}
+export declare interface RouteTypeInfo {
+  method: string
+  pattern: string
+  requestType: string
+  responseType: string
+  paramsType: string
+  queryType: string
+  bodyType: string
+  middlewareTypes: string[]
+  handlerSignature: string
+}
+export declare interface TypeDefinition {
+  name: string
+  type: 'interface' | 'type' | 'enum' | 'class'
+  definition: string
+  imports: string[]
+  exports: string[]
+  documentation?: string
+}
+export declare 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: TypeScriptConfig;
+  private routeTypes: any;
+  private typeDefinitions: any;
+  constructor(config?: TypeScriptConfig);
+  registerRouteTypes(method: string, pattern: string, options?: {
+      requestType?: string
+      responseType?: string
+      paramsType?: string
+      queryType?: string
+      bodyType?: string
+      middlewareTypes?: string[]
+      handlerSignature?: string
+    }): void;
+  generateRouteTypes(): string;
+  generateValidationSchemas(): Record<string, ValidationSchema>;
+  generateOpenAPISchema(): any;
+  validateRequest(req: EnhancedRequest, routeKey: string): {
+    valid: boolean
+    errors: string[]
+    warnings: string[]
+  };
+  generateRouteBuilder(): string;
+  generateMiddlewareTypes(): string;
+  getRouteTypes(): RouteTypeInfo[];
+  getTypeDefinition(name: string): TypeDefinition | undefined;
+  registerTypeDefinition(definition: TypeDefinition): void;
+  clear(): void;
+  private inferParamsType(pattern: string): string;
+  private extractPathParameters(pattern: string): Array<{ name: string, type: string, optional: boolean }>;
+  private inferParamType(constraint?: string): string;
+  private generateHandlerSignature(options: any): string;
+  private generateImports(): string;
+  private generateParamTypes(routes: RouteTypeInfo[]): string;
+  private generateHandlerTypes(routes: RouteTypeInfo[]): string;
+  private generateRouteRegistryType(routes: RouteTypeInfo[]): string;
+  private generateUtilityTypes(): string;
+  private pathToTypeName(path: string): string;
+  private pathToMethodName(path: string): string;
+  private pathToOperationId(path: string): string;
+  private typeToSchema(type: string): ValidationSchema;
+  private typeToOpenAPISchema(type: string): any;
+  private validateParams(_req: EnhancedRequest, _expectedType: string): string[];
+  private validateQuery(_req: EnhancedRequest, _expectedType: string): string[];
+  private validateBody(_req: EnhancedRequest, _expectedType: string): string[];
+}

package/dist/docs.d.ts

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

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

@@ -0,0 +1,138 @@
+import type { ErrorContext } from './exceptions';
+/**
+ * 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>;
+/**
+ * Middleware for circuit breaker protection
+ */
+export declare function createCircuitBreakerMiddleware(registry: CircuitBreakerRegistry): void;
+/**
+ * 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>;
+/**
+ * Factory functions for common circuit breaker configurations
+ */
+export declare const CircuitBreakerPresets: {
+  /**
+   * Fast-failing circuit breaker for critical services
+   */
+  critical: (name: string) => any;
+  /**
+   * Standard circuit breaker for regular services
+   */
+  standard: (name: string) => any;
+  /**
+   * Tolerant circuit breaker for non-critical services
+   */
+  tolerant: (name: string) => any;
+  /**
+   * Database circuit breaker with longer timeouts
+   */
+  database: (name: string) => any
+};
+/**
+ * Global circuit breaker registry instance
+ */
+export declare const globalCircuitBreakerRegistry: CircuitBreakerRegistry;
+export declare 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 declare 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 declare interface CircuitBreakerCall<T> {
+  execute: () => Promise<T>
+  fallback?: () => Promise<T>
+  timeout?: number
+  retries?: number
+  context?: ErrorContext
+}
+export type CircuitBreakerState = 'CLOSED' | 'OPEN' | 'HALF_OPEN'
+/**
+ * Circuit breaker implementation
+ */
+export declare class CircuitBreaker {
+  private config: CircuitBreakerConfig;
+  private state: CircuitBreakerState;
+  private metrics: CircuitBreakerMetrics;
+  private nextAttemptTime?: Date;
+  private halfOpenCallCount: any;
+  private recentRequests: Array<{ timestamp: Date, success: boolean, responseTime: number }>;
+  constructor(config: CircuitBreakerConfig);
+  execute<T>(call: CircuitBreakerCall<T>): Promise<T>;
+  getState(): CircuitBreakerState;
+  getMetrics(): CircuitBreakerMetrics;
+  forceOpen(): void;
+  forceClosed(): void;
+  reset(): void;
+  private onSuccess(responseTime: number): void;
+  private onFailure(error: Error, responseTime: number): void;
+  private shouldTrip(error: Error): boolean;
+  private transitionToClosed(): void;
+  private transitionToOpen(): void;
+  private transitionToHalfOpen(): void;
+  private updateAverageResponseTime(responseTime: number): void;
+  private getRecentRequests(): Array<{ timestamp: Date, success: boolean, responseTime: number }>;
+  private cleanupOldRequests(): void;
+}
+/**
+ * Circuit breaker registry for managing multiple circuit breakers
+ */
+export declare class CircuitBreakerRegistry {
+  private breakers: any;
+  private configs: any;
+  register(config: CircuitBreakerConfig): CircuitBreaker;
+  get(name: string): CircuitBreaker | undefined;
+  execute<T>(name: string, call: CircuitBreakerCall<T>): Promise<T>;
+  getAllMetrics(): Record<string, CircuitBreakerMetrics>;
+  getBreakersByState(state: CircuitBreakerState): string[];
+  forceAllClosed(): void;
+  resetAll(): void;
+  remove(name: string): boolean;
+  getNames(): string[];
+}
+/**
+ * HTTP client with circuit breaker protection
+ */
+export declare class CircuitBreakerHttpClient {
+  private registry: CircuitBreakerRegistry;
+  constructor(registry?: CircuitBreakerRegistry);
+  fetch(url: string, options?: RequestInit & {
+      circuitBreaker?: string | CircuitBreakerConfig
+      fallback?: () => Promise<Response>
+      context?: ErrorContext
+    }): Promise<Response>;
+  getRegistry(): CircuitBreakerRegistry;
+}

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

@@ -0,0 +1,57 @@
+import { CircuitBreakerRegistry } from './circuit-breaker';
+import { ErrorReportingManager } from './error-reporting';
+import { GracefulDegradationManager } from './graceful-degradation';
+import { RouterException } from './exceptions';
+import type { CircuitBreakerConfig, DegradationConfig, EnhancedRequest, ErrorReportingConfig } from '../types';
+/**
+ * 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: () => any;
+  production: (sentryDsn?: string, bugsnagApiKey?: string) => any;
+  staging: (sentryDsn?: string) => any;
+  resilient: (config: { sentryDsn?: string bugsnagApiKey?: string services?: string[] } = {}) => any
+};
+export declare 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?: ErrorReportingManager;
+  private gracefulDegradation?: GracefulDegradationManager;
+  private circuitBreakerRegistry?: CircuitBreakerRegistry;
+  private config: AdvancedErrorHandlerConfig;
+  constructor(config?: AdvancedErrorHandlerConfig);
+  private initializeComponents(): void;
+  middleware(): void;
+  handleError(error: unknown, req: EnhancedRequest): Promise<Response>;
+  private normalizeError(error: unknown, req: EnhancedRequest): RouterException;
+  private createErrorResponse(error: RouterException, _req: EnhancedRequest): Response;
+  private logError(error: RouterException, req: EnhancedRequest): void;
+  getStats(): {
+    errorReporting?: any
+    gracefulDegradation?: any
+    circuitBreakers?: any
+  };
+  cleanup(): Promise<void>;
+}