@stacksjs/bun-router 0.0.2

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

@@ -0,0 +1,135 @@
+import type { ErrorContext, RouterException } from './exceptions';
+/**
+ * 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?) => any;
+  bugsnag: (apiKey: string, environment?) => any;
+  development: () => any
+};
+export declare 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 declare 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 declare 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: ErrorReportingConfig;
+  private sentry: any;
+  constructor(config: ErrorReportingConfig);
+  private initializeSentry(): Promise<void>;
+  report(error: RouterException, context?: ErrorContext): Promise<string | null>;
+  addBreadcrumb(message: string, category?: any, level?: any, 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?: any): Promise<boolean>;
+  private shouldIgnoreError(error: RouterException): boolean;
+  private mapSeverityToLevel(severity: string): string;
+  private generateFingerprint(error: RouterException): string[];
+}
+/**
+ * Bugsnag error reporter implementation
+ */
+export declare class BugsnagReporter implements ErrorReporter {
+  private config: ErrorReportingConfig;
+  private bugsnag: any;
+  constructor(config: ErrorReportingConfig);
+  private initializeBugsnag(): Promise<void>;
+  report(error: RouterException, context?: ErrorContext): Promise<string | null>;
+  addBreadcrumb(message: string, category?: any, _level?: any, 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(error: RouterException): boolean;
+  private mapSeverityToBugsnag(severity: string): string;
+  private generateGroupingHash(error: RouterException): string;
+}
+/**
+ * Custom error reporter for custom implementations
+ */
+export declare class CustomReporter implements ErrorReporter {
+  private config: ErrorReportingConfig;
+  private reportHandler: (report: ErrorReport) => Promise<string | null>;
+  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(severity: string): 'debug' | 'info' | 'warning' | 'error' | 'fatal';
+}
+/**
+ * Error reporting manager
+ */
+export declare class ErrorReportingManager {
+  private reporters: ErrorReporter[];
+  private breadcrumbs: Array<{ message: string, timestamp: Date, data?: any }>;
+  private maxBreadcrumbs: any;
+  constructor(configs: ErrorReportingConfig[]);
+  private initializeReporters(configs: ErrorReportingConfig[]): void;
+  addReporter(reporter: ErrorReporter): void;
+  report(error: RouterException, context?: ErrorContext): Promise<string[]>;
+  addBreadcrumb(message: string, category?: any, 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?: any): Promise<boolean>;
+  getBreadcrumbs(): Array<{ message: string, timestamp: Date, data?: any }>;
+}

package/dist/errors/exceptions.d.ts

@@ -0,0 +1,178 @@
+/**
+ * Factory functions for common errors
+ */
+export declare const ErrorFactory: {
+  validation: (message: string, fields?: Record<string, string[]>, context?: ErrorContext) => any;
+  authentication: (message?: string, context?: ErrorContext) => any;
+  authorization: (message?: string, requiredPermissions?: string[], context?: ErrorContext) => any;
+  notFound: (resource?: string, resourceId?: string, context?: ErrorContext) => any;
+  methodNotAllowed: (method: string, allowedMethods: string[], context?: ErrorContext) => any;
+  timeout: (timeoutMs: number, message?: string, context?: ErrorContext) => any;
+  rateLimit: (retryAfter: number, limit: number, remaining?: number, context?: ErrorContext) => any;
+  internalServer: (message?: string, cause?: Error, context?: ErrorContext) => any;
+  serviceUnavailable: (message?: string, retryAfter?: number, context?: ErrorContext) => any;
+  database: (message: string, operation?: string, query?: string, cause?: Error, context?: ErrorContext) => any;
+  externalService: ( message: string, service: string, endpoint?: string, statusCode?: number, cause?: Error, context?: ErrorContext, ) => any;
+  circuitBreakerOpen: (service: string, nextAttemptAt: Date, context?: ErrorContext) => any;
+  businessLogic: (message: string, businessRule: string, context?: ErrorContext) => any;
+  configuration: (message: string, configKey: string, context?: ErrorContext) => any;
+  fileSystem: (message: string, path: string, operation: string, cause?: Error, context?: ErrorContext) => any
+};
+/**
+ * Advanced Error Handling - Exception Hierarchy
+ *
+ * Comprehensive exception types with metadata, stack traces, and context information
+ */
+export declare 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 declare 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);
+  toJSON(): Record<string, any>;
+  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, 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, 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);
+}

package/dist/errors/graceful-degradation.d.ts

@@ -0,0 +1,130 @@
+import type { EnhancedRequest } from '../types';
+import type { ErrorContext, RouterException } from './exceptions';
+/**
+ * Middleware for graceful degradation
+ */
+export declare function createGracefulDegradationMiddleware(config: DegradationConfig): void;
+/**
+ * Factory functions for common degradation strategies
+ */
+export declare const DegradationStrategies: {
+  cacheFirst: (ttl: number?, staleWhileRevalidate?) => any;
+  staticFallback: (body: any, status?) => any;
+  simplifiedView: () => any;
+  redirectToMaintenance: (url: string) => any
+};
+export declare interface DegradationConfig {
+  enabled: boolean
+  fallbackStrategies: {
+    [serviceName: string]: FallbackStrategy
+  }
+  healthChecks: {
+    [serviceName: string]: HealthCheckConfig
+  }
+  monitoring: {
+    enabled: boolean
+    alertThresholds: {
+      errorRate: number
+      responseTime: number
+      availability: number
+    }
+  }
+}
+export declare interface FallbackStrategy {
+  type: 'cache' | 'static' | 'simplified' | 'redirect' | 'custom'
+  priority: number
+  timeout: number
+  retries: number
+  backoff: {
+    type: 'fixed' | 'exponential'
+    delay: number
+    maxDelay?: number
+  }
+  fallbackHandler?: (error: RouterException, context: ErrorContext) => Promise<Response>
+  cacheConfig?: {
+    key: string
+    ttl: number
+    staleWhileRevalidate: boolean
+  }
+  staticResponse?: {
+    status: number
+    body: any
+    headers?: Record<string, string>
+  }
+  redirectConfig?: {
+    url: string
+    permanent: boolean
+  }
+}
+export declare interface HealthCheckConfig {
+  enabled: boolean
+  endpoint: string
+  interval: number
+  timeout: number
+  retries: number
+  expectedStatus: number[]
+  expectedBody?: string | RegExp
+  headers?: Record<string, string>
+  onHealthy?: () => void
+  onUnhealthy?: (error: Error) => void
+}
+export declare interface ServiceHealth {
+  name: string
+  status: 'healthy' | 'degraded' | 'unhealthy'
+  lastCheck: Date
+  responseTime: number
+  errorRate: number
+  availability: number
+  consecutiveFailures: number
+  metadata?: Record<string, any>
+}
+export declare interface DegradationContext {
+  request: EnhancedRequest
+  serviceName: string
+  error: RouterException
+  attemptCount: number
+  startTime: Date
+  metadata?: Record<string, any>
+}
+/**
+ * Service health monitor
+ */
+export declare class ServiceHealthMonitor {
+  private healthStatus: any;
+  private healthCheckIntervals: any;
+  private config: DegradationConfig;
+  constructor(config: DegradationConfig);
+  private initializeHealthChecks(): void;
+  private performHealthCheck(serviceName: string, config: HealthCheckConfig): Promise<void>;
+  private updateHealthStatus(serviceName: string, isHealthy: boolean, responseTime: number): void;
+  getServiceHealth(serviceName: string): ServiceHealth | undefined;
+  getAllServiceHealth(): ServiceHealth[];
+  isServiceHealthy(serviceName: string): boolean;
+  isServiceDegraded(serviceName: string): boolean;
+  stop(): void;
+}
+/**
+ * Graceful degradation manager
+ */
+export declare class GracefulDegradationManager {
+  private config: DegradationConfig;
+  private healthMonitor: ServiceHealthMonitor;
+  private cache: any;
+  private metrics: any;
+  constructor(config: DegradationConfig);
+  handleFailure(serviceName: string, error: RouterException, request: EnhancedRequest, originalHandler: () => Promise<Response>): Promise<Response>;
+  private executeFallbackStrategy(strategy: FallbackStrategy, context: DegradationContext, originalHandler: () => Promise<Response>): Promise<Response>;
+  private handleCacheFallback(strategy: FallbackStrategy, context: DegradationContext): Promise<Response>;
+  private handleStaticFallback(strategy: FallbackStrategy, context: DegradationContext): Promise<Response>;
+  private handleSimplifiedFallback(strategy: FallbackStrategy, context: DegradationContext): Promise<Response>;
+  private handleRedirectFallback(strategy: FallbackStrategy, context: DegradationContext): Promise<Response>;
+  private handleCustomFallback(strategy: FallbackStrategy, context: DegradationContext): Promise<Response>;
+  cacheResponse(serviceName: string, key: string, data: any, ttl: number): void;
+  getServiceMetrics(serviceName: string): { errorRate: number, avgResponseTime: number, totalRequests: number };
+  getSystemHealth(): { status: 'healthy' | 'degraded' | 'unhealthy', services: ServiceHealth[] };
+  private calculateBackoffDelay(backoff: FallbackStrategy['backoff'], attempt: number): number;
+  private generateCacheKey(template: string, context: DegradationContext): string;
+  private updateMetrics(serviceName: string, success: boolean, responseTime: number): void;
+  private sleep(ms: number): Promise<void>;
+  stop(): void;
+}

package/dist/errors/index.d.ts

@@ -0,0 +1,6 @@
+export * from './circuit-breaker';
+export { createAdvancedErrorHandler } from './error-handler';
+export * from './error-reporting';
+export * from './exceptions';
+export * from './graceful-degradation';
+export * from './router-errors';

package/dist/errors/router-errors.d.ts

@@ -0,0 +1,97 @@
+import { RouterException } from './exceptions';
+import type { ErrorContext } from './exceptions';
+/**
+ * Utility to find similar routes using Levenshtein distance
+ */
+export declare function findSimilarRoutes(requestedPath: string, availableRoutes: Array<{ method: string, path: string }>, maxResults?: number): SimilarRoute[];
+/**
+ * Detect route conflicts in a list of routes
+ */
+export declare function detectRouteConflicts(routes: Array<{ method: string, path: string, name?: string }>): RouteConflictInfo[][];
+/**
+ * Factory for creating router-specific errors
+ */
+export declare const RouterErrorFactory: {
+  routeConflict: (routes: RouteConflictInfo[], context?: ErrorContext) => any;
+  circularDependency: (chain: string[], context?: ErrorContext) => any;
+  middlewareConfig: (name: string, errors: string[], context?: ErrorContext) => any;
+  routeNotFound: (method: string, path: string, similarRoutes?: SimilarRoute[], context?: ErrorContext) => any;
+  handlerResolution: (ref: string, reason: string, context?: ErrorContext) => any;
+  modelBinding: (model: string, param: string, value: string, reason: string, context?: ErrorContext) => any
+};
+export declare interface RouteConflictInfo {
+  method: string
+  path: string
+  name?: string
+  definedAt?: string
+  pattern?: string
+}
+export declare interface SimilarRoute {
+  method: string
+  path: string
+  similarity?: number
+}
+/**
+ * Route conflict error with detailed information about conflicting routes
+ */
+export declare class RouteConflictException extends RouterException {
+  readonly conflictingRoutes: RouteConflictInfo[];
+  readonly suggestion: string;
+  constructor(conflictingRoutes: RouteConflictInfo[], context?: ErrorContext);
+  static private buildMessage(routes: RouteConflictInfo[]): string;
+  static private buildSuggestion(routes: RouteConflictInfo[]): string;
+  toJSON(): Record<string, unknown>;
+}
+/**
+ * Circular dependency error with dependency chain visualization
+ */
+export declare class CircularDependencyException extends RouterException {
+  readonly dependencyChain: string[];
+  readonly suggestion: string;
+  constructor(dependencyChain: string[], context?: ErrorContext);
+  static private buildMessage(chain: string[]): string;
+  static private buildSuggestion(chain: string[]): string;
+  toJSON(): Record<string, unknown>;
+}
+/**
+ * Middleware configuration error
+ */
+export declare class MiddlewareConfigurationException extends RouterException {
+  readonly middlewareName: string;
+  readonly configErrors: string[];
+  readonly suggestion: string;
+  constructor(middlewareName: string, configErrors: string[], context?: ErrorContext);
+  private buildSuggestion(): string;
+}
+/**
+ * Route not found error with helpful suggestions
+ */
+export declare class RouteNotFoundException extends RouterException {
+  readonly requestedPath: string;
+  readonly requestedMethod: string;
+  readonly similarRoutes: SimilarRoute[];
+  readonly suggestion: string;
+  constructor(requestedMethod: string, requestedPath: string, similarRoutes?: SimilarRoute[], context?: ErrorContext);
+  static private buildMessage(method: string, path: string, similarRoutes: SimilarRoute[]): string;
+  private buildSuggestion(): string;
+}
+/**
+ * Handler resolution error
+ */
+export declare class HandlerResolutionException extends RouterException {
+  readonly handlerRef: string;
+  readonly suggestion: string;
+  constructor(handlerRef: string, reason: string, context?: ErrorContext);
+  private buildSuggestion(handlerRef: string): string;
+}
+/**
+ * Model binding error
+ */
+export declare class ModelBindingException extends RouterException {
+  readonly modelName: string;
+  readonly paramName: string;
+  readonly paramValue: string;
+  readonly suggestion: string;
+  constructor(modelName: string, paramName: string, paramValue: string, reason: string, context?: ErrorContext);
+  private buildSuggestion(): string;
+}

package/dist/file-serving/static-files.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Static file middleware factory
+ */
+export declare function createStaticFileMiddleware(config: StaticFileConfig): void;
+/**
+ * Static file serving helpers
+ */
+export declare const StaticFileHelpers: {
+  /**
+   * Create development server with hot reload
+   */
+  createDevelopmentServer: (config: StaticFileConfig) => any;
+  /**
+   * Create production server with aggressive caching
+   */
+  createProductionServer: (config: StaticFileConfig) => any;
+  /**
+   * Create SPA server with fallback to index.html
+   */
+  createSPAServer: (config: StaticFileConfig) => any
+};
+/**
+ * File serving utilities
+ */
+export declare const FileServingUtils: {
+  /**
+   * Calculate optimal cache settings based on file type
+   */
+  getOptimalCacheSettings: (filePath: string) => any;
+  /**
+   * Generate security headers for static files
+   */
+  generateSecurityHeaders: () => unknown;
+  /**
+   * Create file watcher for cache invalidation
+   */
+  createFileWatcher: (server: StaticFileServer, watchPath: string) => Promise<{ close: ()
+};
+/**
+ * Static File Serving
+ *
+ * Efficient file serving using Bun.file() with advanced caching and optimization
+ */
+export declare interface StaticFileConfig {
+  root: string
+  maxAge?: number
+  immutable?: boolean
+  etag?: boolean
+  lastModified?: boolean
+  index?: string[]
+  extensions?: string[]
+  fallthrough?: boolean
+  setHeaders?: (res: Response, path: string, stat: any) => void
+  compression?: boolean
+  compressionThreshold?: number
+  cacheControl?: string
+  dotfiles?: 'allow' | 'deny' | 'ignore'
+}
+export declare interface FileCache {
+  content: ArrayBuffer
+  etag: string
+  lastModified: string
+  mimeType: string
+  size: number
+  compressed?: ArrayBuffer
+  compressedEtag?: string
+}
+export declare interface FileStats {
+  hits: number
+  misses: number
+  bytesServed: number
+  compressionRatio: number
+  averageResponseTime: number
+  lastAccessed: number
+}
+/**
+ * High-performance static file server using Bun.file()
+ */
+export declare class StaticFileServer {
+  private config: Required<StaticFileConfig>;
+  private cache: any;
+  private stats: any;
+  private compressionCache: any;
+  constructor(config: StaticFileConfig);
+  serve(request: Request): Promise<Response | null>;
+  serveFile(request: Request, filePath: string, requestPath: string): Promise<Response>;
+  private serveCachedFile(request: Request, cached: FileCache, requestPath: string, startTime: number): Response;
+  private resolveFile(pathname: string): Promise<string | null>;
+  private joinPath(parts: string[]): string;
+  private generateEtag(content: ArrayBuffer, lastModified: string): string;
+  private compressContent(content: ArrayBuffer): Promise<ArrayBuffer | null>;
+  private getMimeType(filePath: string): string;
+  private updateStats(path: string, bytes: number, startTime: number, cached: boolean): void;
+  getStats(): Record<string, FileStats>;
+  clearCache(): void;
+  getCacheSize(): number;
+  preloadFiles(paths: string[]): Promise<void>;
+}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export { default as Auth } from './auth';
+export * from './auth';
+export * from './config';
+export * as Errors from './errors';
+export * from './middleware';
+export * from './response/response-factory';
+export * from './router';
+export * from './testing';
+export * from './types';
+export * from './utils';