@stacksjs/bun-router 0.0.5 → 0.0.7

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

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

@@ -0,0 +1,154 @@
+/**
+ * Advanced Error Handling - Graceful Degradation
+ *
+ * Handles partial failures with fallback mechanisms and service degradation
+ */
+import type { EnhancedRequest } from '../types';
+import type { ErrorContext, RouterException } from './exceptions';
+export interface DegradationConfig {
+    enabled: boolean;
+    fallbackStrategies: {
+        [serviceName: string]: FallbackStrategy;
+    };
+    healthChecks: {
+        [serviceName: string]: HealthCheckConfig;
+    };
+    monitoring: {
+        enabled: boolean;
+        alertThresholds: {
+            errorRate: number;
+            responseTime: number;
+            availability: number;
+        };
+    };
+}
+export 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 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 interface ServiceHealth {
+    name: string;
+    status: 'healthy' | 'degraded' | 'unhealthy';
+    lastCheck: Date;
+    responseTime: number;
+    errorRate: number;
+    availability: number;
+    consecutiveFailures: number;
+    metadata?: Record<string, any>;
+}
+export 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;
+    private healthCheckIntervals;
+    private config;
+    constructor(config: DegradationConfig);
+    private initializeHealthChecks;
+    private performHealthCheck;
+    private updateHealthStatus;
+    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;
+    private healthMonitor;
+    private cache;
+    private metrics;
+    constructor(config: DegradationConfig);
+    /**
+     * Handle service failure with graceful degradation
+     */
+    handleFailure(serviceName: string, error: RouterException, request: EnhancedRequest, originalHandler: () => Promise<Response>): Promise<Response>;
+    private executeFallbackStrategy;
+    private handleCacheFallback;
+    private handleStaticFallback;
+    private handleSimplifiedFallback;
+    private handleRedirectFallback;
+    private handleCustomFallback;
+    /**
+     * Cache successful responses for fallback use
+     */
+    cacheResponse(serviceName: string, key: string, data: any, ttl: number): void;
+    /**
+     * Get service metrics
+     */
+    getServiceMetrics(serviceName: string): {
+        errorRate: number;
+        avgResponseTime: number;
+        totalRequests: number;
+    };
+    /**
+     * Get overall system health
+     */
+    getSystemHealth(): {
+        status: 'healthy' | 'degraded' | 'unhealthy';
+        services: ServiceHealth[];
+    };
+    private calculateBackoffDelay;
+    private generateCacheKey;
+    private updateMetrics;
+    private sleep;
+    stop(): void;
+}
+/**
+ * Middleware for graceful degradation
+ */
+export declare function createGracefulDegradationMiddleware(config: DegradationConfig): (req: EnhancedRequest, next: () => Promise<Response>) => Promise<Response>;
+/**
+ * Factory functions for common degradation strategies
+ */
+export declare const DegradationStrategies: {
+    cacheFirst: (ttl?: number, staleWhileRevalidate?: boolean) => FallbackStrategy;
+    staticFallback: (body: any, status?: number) => FallbackStrategy;
+    simplifiedView: () => FallbackStrategy;
+    redirectToMaintenance: (url: string) => FallbackStrategy;
+};

package/dist/errors/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Advanced Error Handling - Main Export File
+ */
+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,110 @@
+/**
+ * Enhanced Router Error Messages
+ *
+ * Provides detailed, actionable error messages for common router issues
+ * including route conflicts, circular dependencies, and configuration errors.
+ */
+import type { ErrorContext } from './exceptions';
+import { RouterException } from './exceptions';
+/**
+ * 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);
+    private static buildMessage;
+    private static buildSuggestion;
+    toJSON(): Record<string, unknown>;
+}
+export interface RouteConflictInfo {
+    method: string;
+    path: string;
+    name?: string;
+    definedAt?: string;
+    pattern?: string;
+}
+/**
+ * Circular dependency error with dependency chain visualization
+ */
+export declare class CircularDependencyException extends RouterException {
+    readonly dependencyChain: string[];
+    readonly suggestion: string;
+    constructor(dependencyChain: string[], context?: ErrorContext);
+    private static buildMessage;
+    private static buildSuggestion;
+    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;
+}
+/**
+ * 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);
+    private static buildMessage;
+    private buildSuggestion;
+}
+export interface SimilarRoute {
+    method: string;
+    path: string;
+    similarity?: number;
+}
+/**
+ * Handler resolution error
+ */
+export declare class HandlerResolutionException extends RouterException {
+    readonly handlerRef: string;
+    readonly suggestion: string;
+    constructor(handlerRef: string, reason: string, context?: ErrorContext);
+    private buildSuggestion;
+}
+/**
+ * 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;
+}
+/**
+ * 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) => RouteConflictException;
+    circularDependency: (chain: string[], context?: ErrorContext) => CircularDependencyException;
+    middlewareConfig: (name: string, errors: string[], context?: ErrorContext) => MiddlewareConfigurationException;
+    routeNotFound: (method: string, path: string, similarRoutes?: SimilarRoute[], context?: ErrorContext) => RouteNotFoundException;
+    handlerResolution: (ref: string, reason: string, context?: ErrorContext) => HandlerResolutionException;
+    modelBinding: (model: string, param: string, value: string, reason: string, context?: ErrorContext) => ModelBindingException;
+};

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

@@ -0,0 +1,143 @@
+/**
+ * Static File Serving
+ *
+ * Efficient file serving using Bun.file() with advanced caching and optimization
+ */
+export 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 interface FileCache {
+    content: ArrayBuffer;
+    etag: string;
+    lastModified: string;
+    mimeType: string;
+    size: number;
+    compressed?: ArrayBuffer;
+    compressedEtag?: string;
+}
+export 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;
+    private cache;
+    private stats;
+    private compressionCache;
+    constructor(config: StaticFileConfig);
+    /**
+     * Serve static file
+     */
+    serve(request: Request): Promise<Response | null>;
+    /**
+     * Serve specific file
+     */
+    serveFile(request: Request, filePath: string, requestPath: string): Promise<Response>;
+    /**
+     * Serve cached file with proper headers
+     */
+    private serveCachedFile;
+    /**
+     * Resolve file path, handling index files and extensions
+     */
+    private resolveFile;
+    /**
+     * Join paths safely
+     */
+    private joinPath;
+    /**
+     * Generate ETag for content
+     */
+    private generateEtag;
+    /**
+     * Compress content using gzip
+     */
+    private compressContent;
+    /**
+     * Get MIME type for file
+     */
+    private getMimeType;
+    /**
+     * Update file serving statistics
+     */
+    private updateStats;
+    /**
+     * Get serving statistics
+     */
+    getStats(): Record<string, FileStats>;
+    /**
+     * Clear cache
+     */
+    clearCache(): void;
+    /**
+     * Get cache size
+     */
+    getCacheSize(): number;
+    /**
+     * Preload files into cache
+     */
+    preloadFiles(paths: string[]): Promise<void>;
+}
+/**
+ * Static file middleware factory
+ */
+export declare function createStaticFileMiddleware(config: StaticFileConfig): (request: Request, next: () => Promise<Response>) => Promise<Response>;
+/**
+ * Static file serving helpers
+ */
+export declare const StaticFileHelpers: {
+    /**
+     * Create development server with hot reload
+     */
+    createDevelopmentServer: (config: StaticFileConfig) => StaticFileServer;
+    /**
+     * Create production server with aggressive caching
+     */
+    createProductionServer: (config: StaticFileConfig) => StaticFileServer;
+    /**
+     * Create SPA server with fallback to index.html
+     */
+    createSPAServer: (config: StaticFileConfig) => StaticFileServer;
+    /**
+     * Create CDN-optimized server
+     */
+    createCDNServer: (config: StaticFileConfig) => StaticFileServer;
+};
+/**
+ * File serving utilities
+ */
+export declare const FileServingUtils: {
+    /**
+     * Calculate optimal cache settings based on file type
+     */
+    getOptimalCacheSettings: (filePath: string) => Partial<StaticFileConfig>;
+    /**
+     * Generate security headers for static files
+     */
+    generateSecurityHeaders: () => Record<string, string>;
+    /**
+     * Create file watcher for cache invalidation
+     */
+    createFileWatcher: (server: StaticFileServer, watchPath: string) => Promise<{
+        close: () => void;
+    }>;
+};

package/dist/index.d.ts

@@ -3,10 +3,12 @@ export * from './auth';
 export * from './config';
 export * as Errors from './errors';
 export * from './middleware';
+export { getCurrentRequest, request, runWithRequest, setCurrentRequest } from './request/context';
 export * from './session';
 export * from './response/response-factory';
 export * from './router';
 export { MiddlewareGroupRegistry, middlewareGroups } from './router/middleware-groups';
 export * from './testing';
 export * from './types';
+export { clearNamedRoutes, getNamedRoutePath, getNamedRoutes, registerNamedRoute, url, type UrlOptions } from './url';
 export * from './utils';