@stacksjs/bun-router 0.0.5 → 0.0.7

package/dist/development/performance-profiler.d.ts

@@ -0,0 +1,217 @@
+/**
+ * Development Tools - Performance Profiler
+ *
+ * Performance profiling, benchmarking, and optimization analysis
+ */
+import type { EnhancedRequest } from '../types';
+export interface ProfileConfig {
+    enabled?: boolean;
+    sampleRate?: number;
+    includeMemory?: boolean;
+    includeCpu?: boolean;
+    includeGc?: boolean;
+    trackSlowQueries?: boolean;
+    slowQueryThreshold?: number;
+    maxProfiles?: number;
+    outputFormat?: 'console' | 'json' | 'flamegraph';
+}
+export interface ProfilePoint {
+    name: string;
+    timestamp: number;
+    duration?: number;
+    memory?: NodeJS.MemoryUsage;
+    cpu?: NodeJS.CpuUsage;
+    metadata?: Record<string, any>;
+}
+export interface RouteProfile {
+    id: string;
+    requestId: string;
+    method: string;
+    path: string;
+    pattern: string;
+    startTime: number;
+    endTime?: number;
+    totalDuration?: number;
+    phases: {
+        routeMatching: ProfilePoint[];
+        middlewareExecution: ProfilePoint[];
+        handlerExecution: ProfilePoint[];
+        responseGeneration: ProfilePoint[];
+    };
+    memory: {
+        initial: NodeJS.MemoryUsage;
+        peak: NodeJS.MemoryUsage;
+        final?: NodeJS.MemoryUsage;
+        allocations: number;
+    };
+    cpu: {
+        initial: NodeJS.CpuUsage;
+        final?: NodeJS.CpuUsage;
+        userTime: number;
+        systemTime: number;
+    };
+    gc?: {
+        collections: number;
+        duration: number;
+        reclaimedMemory: number;
+    };
+    queries?: Array<{
+        query: string;
+        duration: number;
+        timestamp: number;
+    }>;
+    warnings: string[];
+    recommendations: string[];
+}
+export interface PerformanceMetrics {
+    averageResponseTime: number;
+    p50ResponseTime: number;
+    p95ResponseTime: number;
+    p99ResponseTime: number;
+    requestsPerSecond: number;
+    memoryUsageAverage: number;
+    memoryUsagePeak: number;
+    cpuUsageAverage: number;
+    gcPressure: number;
+    slowestRoutes: Array<{
+        pattern: string;
+        averageTime: number;
+        count: number;
+    }>;
+    memoryLeaks: Array<{
+        route: string;
+        memoryGrowth: number;
+        requests: number;
+    }>;
+}
+/**
+ * Performance profiler for route analysis
+ */
+export declare class PerformanceProfiler {
+    private config;
+    private profiles;
+    private activeProfiles;
+    private metrics;
+    private gcObserver?;
+    private memoryBaseline;
+    constructor(config?: ProfileConfig);
+    /**
+     * Start profiling a request
+     */
+    startProfiling(req: EnhancedRequest, pattern: string): string | null;
+    /**
+     * Record a profile point
+     */
+    recordPoint(profileId: string, phase: keyof RouteProfile['phases'], name: string, metadata?: Record<string, any>): void;
+    /**
+     * Start timing a specific operation
+     */
+    startTiming(profileId: string, phase: keyof RouteProfile['phases'], name: string): string;
+    /**
+     * End timing a specific operation
+     */
+    endTiming(profileId: string, phase: keyof RouteProfile['phases'], timingId: string): void;
+    /**
+     * Record database query
+     */
+    recordQuery(profileId: string, query: string, duration: number): void;
+    /**
+     * Finish profiling a request
+     */
+    finishProfiling(profileId: string, _response?: Response): RouteProfile | null;
+    /**
+     * Get profile by ID
+     */
+    getProfile(profileId: string): RouteProfile | undefined;
+    /**
+     * Get all profiles
+     */
+    getProfiles(filter?: {
+        method?: string;
+        pattern?: string;
+        minDuration?: number;
+        maxDuration?: number;
+        hasWarnings?: boolean;
+    }): RouteProfile[];
+    /**
+     * Get performance metrics
+     */
+    getMetrics(): PerformanceMetrics;
+    /**
+     * Generate performance report
+     */
+    generateReport(): string;
+    /**
+     * Clear all profiles and reset metrics
+     */
+    clear(): void;
+    /**
+     * Determine if request should be profiled
+     */
+    private shouldProfile;
+    /**
+     * Generate unique profile ID
+     */
+    private generateProfileId;
+    /**
+     * Extract request ID from request
+     */
+    private extractRequestId;
+    /**
+     * Initialize metrics structure
+     */
+    private initializeMetrics;
+    /**
+     * Setup garbage collection observer
+     */
+    private setupGcObserver;
+    /**
+     * Generate recommendations for a profile
+     */
+    private generateRecommendations;
+    /**
+     * Update performance metrics
+     */
+    private updateMetrics;
+    /**
+     * Cleanup old profiles
+     */
+    private cleanupProfiles;
+    /**
+     * Log profile information
+     */
+    private logProfile;
+}
+/**
+ * Initialize global performance profiler
+ */
+export declare function initializePerformanceProfiler(config?: ProfileConfig): PerformanceProfiler;
+/**
+ * Get global performance profiler
+ */
+export declare function getPerformanceProfiler(): PerformanceProfiler | null;
+/**
+ * Performance profiling middleware factory
+ */
+export declare function createPerformanceProfilingMiddleware(config?: ProfileConfig): (req: EnhancedRequest, next: () => Promise<Response>) => Promise<Response>;
+/**
+ * Performance profiling helpers
+ */
+export declare const PerformanceProfilingHelpers: {
+    /**
+     * Record timing from request context
+     */
+    startTiming: (req: EnhancedRequest, phase: keyof RouteProfile["phases"], name: string) => string | null;
+    /**
+     * End timing from request context
+     */
+    endTiming: (req: EnhancedRequest, phase: keyof RouteProfile["phases"], timingId: string) => void;
+    /**
+     * Record database query from request context
+     */
+    recordQuery: (req: EnhancedRequest, query: string, duration: number) => void;
+    /**
+     * Record profile point from request context
+     */
+    recordPoint: (req: EnhancedRequest, phase: keyof RouteProfile["phases"], name: string, metadata?: Record<string, any>) => void;
+};

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

@@ -0,0 +1,154 @@
+/**
+ * Development Tools - Route Debugging
+ *
+ * Comprehensive route debugging with detailed logging and inspection
+ */
+import type { EnhancedRequest } from '../types';
+export 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 interface RouteMatchAttempt {
+    pattern: string;
+    method: string;
+    matched: boolean;
+    reason?: string;
+    params?: Record<string, string>;
+    score?: number;
+    timing: number;
+}
+export 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;
+    private debugSessions;
+    private routePatterns;
+    constructor(config?: RouteDebugConfig);
+    /**
+     * Start debugging a request
+     */
+    startDebugging(req: EnhancedRequest): string;
+    /**
+     * Record route match attempt
+     */
+    recordMatchAttempt(requestId: string, pattern: string, method: string, matched: boolean, reason?: string, params?: Record<string, string>): void;
+    /**
+     * Record final route match
+     */
+    recordFinalMatch(requestId: string, pattern: string, handler: (..._args: any[]) => any, middleware: ((..._args: any[]) => any)[], params: Record<string, string>): void;
+    /**
+     * Record timing information
+     */
+    recordTiming(requestId: string, phase: keyof RouteDebugInfo['timings'], duration: number): void;
+    /**
+     * Finish debugging session
+     */
+    finishDebugging(requestId: string, response?: Response): RouteDebugInfo | null;
+    /**
+     * Register route pattern for debugging
+     */
+    registerRoute(method: string, pattern: string, handler: (...args: any[]) => any, middleware?: ((...args: any[]) => any)[]): void;
+    /**
+     * Get all registered routes
+     */
+    getRegisteredRoutes(): Array<{
+        method: string;
+        pattern: string;
+        handler: string;
+        middleware: string[];
+    }>;
+    /**
+     * Get debug session
+     */
+    getDebugSession(requestId: string): RouteDebugInfo | undefined;
+    /**
+     * Clear all debug sessions
+     */
+    clearSessions(): void;
+    /**
+     * Generate unique request ID
+     */
+    private generateRequestId;
+    /**
+     * Capture request body safely
+     */
+    private captureRequestBody;
+    /**
+     * Log debug message
+     */
+    private log;
+    /**
+     * Log debugging summary
+     */
+    private logSummary;
+    /**
+     * Check if should log at level
+     */
+    private shouldLog;
+}
+/**
+ * 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): (req: EnhancedRequest, next: () => Promise<Response>) => Promise<Response>;
+/**
+ * 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>) => void;
+    /**
+     * Record final match from request context
+     */
+    recordFinalMatch: (req: EnhancedRequest, pattern: string, handler: (...args: any[]) => any, middleware: ((...args: any[]) => any)[], params: Record<string, string>) => void;
+    /**
+     * Record timing from request context
+     */
+    recordTiming: (req: EnhancedRequest, phase: keyof RouteDebugInfo["timings"], duration: number) => void;
+};

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

@@ -0,0 +1,211 @@
+/**
+ * Development Tools - Route Inspector
+ *
+ * Route listing, metadata inspection, and route analysis
+ */
+export 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 interface RouteGroup {
+    name: string;
+    prefix: string;
+    middleware: string[];
+    routes: RouteMetadata[];
+    subgroups: RouteGroup[];
+}
+export 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;
+    private groups;
+    private routeStats;
+    /**
+     * Register a route for inspection
+     */
+    registerRoute(method: string, pattern: string, handler: (...args: any[]) => any, middleware?: Array<(...args: any[]) => any>, options?: Partial<RouteMetadata>): string;
+    /**
+     * Get all registered routes
+     */
+    getRoutes(filter?: {
+        method?: string;
+        pattern?: string;
+        group?: string;
+        hasMiddleware?: string;
+        hasParams?: boolean;
+    }): RouteMetadata[];
+    /**
+     * Get route by ID
+     */
+    getRoute(id: string): RouteMetadata | undefined;
+    /**
+     * Find routes matching a request
+     */
+    findMatchingRoutes(method: string, path: string): RouteMetadata[];
+    /**
+     * Register route group
+     */
+    registerGroup(name: string, prefix: string, middleware?: Array<(...args: any[]) => any>): void;
+    /**
+     * Get route groups
+     */
+    getGroups(): RouteGroup[];
+    /**
+     * Record route access for statistics
+     */
+    recordRouteAccess(routeId: string, responseTime: number, error?: boolean): void;
+    /**
+     * Analyze routes for insights and recommendations
+     */
+    analyzeRoutes(): RouteAnalysis;
+    /**
+     * Export routes in various formats
+     */
+    exportRoutes(format?: 'json' | 'csv' | 'markdown' | 'openapi'): string;
+    /**
+     * Clear all routes and statistics
+     */
+    clear(): void;
+    /**
+     * Generate unique route ID
+     */
+    private generateRouteId;
+    /**
+     * Extract function source code
+     */
+    private getFunctionSource;
+    /**
+     * Extract function parameters
+     */
+    private extractFunctionParameters;
+    /**
+     * Check if function is async
+     */
+    private isAsyncFunction;
+    /**
+     * Extract route parameters from pattern
+     */
+    private extractRouteParameters;
+    /**
+     * Infer parameter type from constraint
+     */
+    private inferParameterType;
+    /**
+     * Get call site information
+     */
+    private getCallSiteInfo;
+    /**
+     * Convert route pattern to regex
+     */
+    private patternToRegex;
+    /**
+     * Generate recommendations based on analysis
+     */
+    private generateRecommendations;
+    /**
+     * Export routes to CSV format
+     */
+    private exportToCsv;
+    /**
+     * Export routes to Markdown format
+     */
+    private exportToMarkdown;
+    /**
+     * Export routes to OpenAPI format
+     */
+    private exportToOpenAPI;
+}
+/**
+ * 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]) => void;
+    /**
+     * Analyze routes and show recommendations
+     */
+    analyzeRoutes: () => void;
+    /**
+     * Export routes to file
+     */
+    exportRoutes: (format?: "json" | "csv" | "markdown" | "openapi", filename?: string) => void;
+};