@stacksjs/bun-router 0.0.4 → 0.0.6

package/dist/development/hot-reload.d.ts

@@ -0,0 +1,187 @@
+/**
+ * Hot Reload Development
+ *
+ * Hot reload for development using Bun's --hot mode with state preservation
+ */
+export interface HotReloadConfig {
+    enabled?: boolean;
+    watchPaths?: string[];
+    ignorePaths?: string[];
+    extensions?: string[];
+    debounceMs?: number;
+    preserveState?: boolean;
+    onReload?: (changedFiles: string[]) => void;
+    onError?: (error: Error) => void;
+    verbose?: boolean;
+}
+export interface HotReloadState {
+    reloadCount: number;
+    lastReload: number;
+    changedFiles: string[];
+    preservedState: Record<string, any>;
+    watchers: Map<string, any>;
+}
+declare global {
+    var __HOT_RELOAD_STATE__: HotReloadState | undefined;
+    var __HOT_RELOAD_PRESERVE__: Record<string, any>;
+}
+/**
+ * Hot reload manager for development
+ */
+export declare class HotReloadManager {
+    private config;
+    private state;
+    private debounceTimer?;
+    private isReloading;
+    constructor(config?: HotReloadConfig);
+    /**
+     * Initialize or restore hot reload state
+     */
+    private initializeState;
+    /**
+     * Setup file watchers
+     */
+    private setupWatchers;
+    /**
+     * Handle file change event
+     */
+    private handleFileChange;
+    /**
+     * Check if file should be ignored
+     */
+    private shouldIgnoreFile;
+    /**
+     * Check if file should be watched
+     */
+    private shouldWatchFile;
+    /**
+     * Trigger hot reload
+     */
+    private triggerReload;
+    /**
+     * Preserve state across reloads
+     */
+    preserveState<T>(key: string, value: T): void;
+    /**
+     * Restore preserved state
+     */
+    restoreState<T>(key: string, defaultValue?: T): T | undefined;
+    /**
+     * Clear preserved state
+     */
+    clearState(key?: string): void;
+    /**
+     * Get hot reload statistics
+     */
+    getStats(): {
+        reloadCount: number;
+        lastReload: number;
+        uptime: number;
+        watchedPaths: string[];
+        preservedKeys: string[];
+    };
+    /**
+     * Stop hot reload
+     */
+    stop(): void;
+}
+/**
+ * Hot reload middleware for preserving server state
+ */
+export declare function createHotReloadMiddleware(hotReload: HotReloadManager): (request: Request, next: () => Promise<Response>) => Promise<Response>;
+/**
+ * Hot reload utilities
+ */
+export declare const HotReloadUtils: {
+    /**
+     * Check if running in hot reload mode
+     */
+    isHotReloadEnabled: () => boolean;
+    /**
+     * Get current reload count
+     */
+    getReloadCount: () => number;
+    /**
+     * Create hot-reloadable module cache
+     */
+    createModuleCache: <T>() => {
+        get: (key: string) => T | undefined;
+        set: (key: string, value: T) => void;
+        clear: () => void;
+        delete: (key: string) => boolean;
+        has: (key: string) => boolean;
+        size: () => number;
+    };
+    /**
+     * Create hot-reloadable configuration
+     */
+    createHotConfig: <T>(initialConfig: T, configPath?: string) => {
+        get: () => T;
+        reload: () => Promise<T>;
+        onChange: (callback: (config: T) => void) => void;
+    };
+};
+/**
+ * Hot reload helpers for common patterns
+ */
+export declare const HotReloadHelpers: {
+    /**
+     * Create hot-reloadable route handlers
+     */
+    createHotHandler: (handlerPath: string) => (request: Request) => Promise<Response>;
+    /**
+     * Create hot-reloadable middleware
+     */
+    createHotMiddleware: (middlewarePath: string) => (request: Request, next: () => Promise<Response>) => Promise<Response>;
+    /**
+     * Create development server with hot reload
+     */
+    createDevelopmentServer: (config?: {
+        port?: number;
+        hostname?: string;
+        hotReload?: HotReloadConfig;
+        onReload?: () => void;
+    }) => {
+        server: ReturnType<typeof Bun.serve>;
+        hotReload: HotReloadManager;
+        stop: () => void;
+    };
+};
+/**
+ * Hot reload decorators for classes and methods
+ */
+export declare const HotReloadDecorators: {
+    /**
+     * Class decorator for hot-reloadable classes
+     */
+    hotReloadable: <T extends new (...args: any[]) => any>(constructor: T) => T;
+    /**
+     * Method decorator for hot-reloadable methods
+     */
+    hotMethod: (target: any, propertyKey: string, descriptor: PropertyDescriptor) => void;
+};
+/**
+ * Initialize global hot reload
+ */
+export declare function initializeHotReload(config?: HotReloadConfig): HotReloadManager;
+/**
+ * Get global hot reload instance
+ */
+export declare function getHotReload(): HotReloadManager | null;
+/**
+ * Hot reload factory functions
+ */
+export declare const HotReloadFactory: {
+    /**
+     * Create development hot reload
+     */
+    createDevelopment: () => HotReloadManager;
+    /**
+     * Create production hot reload (disabled)
+     */
+    createProduction: () => HotReloadManager;
+    /**
+     * Create testing hot reload
+     */
+    createTesting: () => HotReloadManager;
+};

package/dist/development/index.d.ts

@@ -0,0 +1,167 @@
+/**
+ * Development Tools - Main Integration
+ *
+ * Unified development tools with router integration and middleware
+ */
+import type { EnhancedRequest } from '../types';
+import { PerformanceProfiler, PerformanceProfilingHelpers } from './performance-profiler';
+import { RouteDebugger, RouteDebugHelpers } from './route-debugger';
+import { RouteInspectionHelpers, RouteInspector } from './route-inspector';
+import { TypeScriptHelpers, TypeScriptUtilities } from './typescript-utilities';
+export interface DevelopmentConfig {
+    debug?: {
+        enabled?: boolean;
+        logLevel?: 'debug' | 'info' | 'warn' | 'error';
+        includeHeaders?: boolean;
+        includeBody?: boolean;
+        colorOutput?: boolean;
+    };
+    profiling?: {
+        enabled?: boolean;
+        sampleRate?: number;
+        includeMemory?: boolean;
+        includeCpu?: boolean;
+    };
+    inspection?: {
+        enabled?: boolean;
+        trackStats?: boolean;
+        generateReports?: boolean;
+    };
+    typescript?: {
+        generateTypes?: boolean;
+        validateTypes?: boolean;
+        generateSchemas?: boolean;
+    };
+}
+/**
+ * Development tools manager
+ */
+export declare class DevelopmentTools {
+    private debugger;
+    private inspector;
+    private profiler;
+    private tsUtils;
+    private config;
+    constructor(config?: DevelopmentConfig);
+    /**
+     * Create development middleware stack
+     */
+    createMiddleware(): Array<(req: EnhancedRequest, next: () => Promise<Response>) => Promise<Response>>;
+    /**
+     * Register route with all development tools
+     */
+    registerRoute(method: string, pattern: string, handler: (...args: any[]) => any, middleware?: ((..._args: any[]) => any)[], options?: any): string;
+    /**
+     * Get route debugging information
+     */
+    debug(): {
+        listRoutes: typeof RouteInspectionHelpers.listRoutes;
+        analyzeRoutes: typeof RouteInspectionHelpers.analyzeRoutes;
+        exportRoutes: typeof RouteInspectionHelpers.exportRoutes;
+        getDebugSession: (requestId: string) => import('./route-debugger').RouteDebugInfo | undefined;
+        clearSessions: () => void;
+    };
+    /**
+     * Get route listing and analysis
+     */
+    routes(): {
+        list: (filter?: any) => import('./route-inspector').RouteMetadata[];
+        analyze: () => import('./route-inspector').RouteAnalysis;
+        export: (format?: 'json' | 'csv' | 'markdown' | 'openapi') => string;
+        groups: () => import('./route-inspector').RouteGroup[];
+        find: (method: string, path: string) => import('./route-inspector').RouteMetadata[];
+    };
+    /**
+     * Get performance profiling information
+     */
+    profile(): {
+        getMetrics: () => import('./performance-profiler').PerformanceMetrics;
+        getProfiles: (filter?: any) => import('./performance-profiler').RouteProfile[];
+        generateReport: () => string;
+        clear: () => void;
+    };
+    /**
+     * Get TypeScript utilities
+     */
+    typescript(): {
+        generateTypes: () => string;
+        generateSchemas: () => Record<string, import('./typescript-utilities').ValidationSchema>;
+        generateOpenAPI: () => any;
+        generateRouteBuilder: () => string;
+        validateRequest: (req: EnhancedRequest, routeKey: string) => {
+            valid: boolean;
+            errors: string[];
+            warnings: string[];
+        };
+    };
+    /**
+     * Generate comprehensive development report
+     */
+    generateReport(): string;
+    /**
+     * Clear all development data
+     */
+    clear(): void;
+    /**
+     * Create inspection middleware
+     */
+    private createInspectionMiddleware;
+}
+/**
+ * Router extension for development tools
+ */
+export declare class DevelopmentRouter {
+    private devTools;
+    private routes;
+    constructor(config?: DevelopmentConfig);
+    /**
+     * Enable debugging for next route
+     */
+    debug(): {
+        get: (pattern: string, handler: (...args: any[]) => any) => any;
+        post: (pattern: string, handler: (...args: any[]) => any) => any;
+        put: (pattern: string, handler: (...args: any[]) => any) => any;
+        patch: (pattern: string, handler: (...args: any[]) => any) => any;
+        delete: (pattern: string, handler: (...args: any[]) => any) => any;
+    };
+    /**
+     * Enable profiling for route group
+     */
+    profile(): {
+        group: (callback: () => void) => void;
+    };
+    /**
+     * Get all registered routes
+     */
+    getRoutes(): import('./route-inspector').RouteMetadata[];
+    /**
+     * Register route with development tools
+     */
+    private registerRoute;
+}
+/**
+ * Development presets for common configurations
+ */
+export declare const DevelopmentPresets: {
+    /**
+     * Full development mode with all features enabled
+     */
+    development: () => DevelopmentConfig;
+    /**
+     * Production debugging with minimal overhead
+     */
+    production: () => DevelopmentConfig;
+    /**
+     * Performance testing configuration
+     */
+    performance: () => DevelopmentConfig;
+    /**
+     * TypeScript development configuration
+     */
+    typescript: () => DevelopmentConfig;
+};
+export { PerformanceProfiler, PerformanceProfilingHelpers, RouteDebugger, RouteDebugHelpers, RouteInspectionHelpers, RouteInspector, TypeScriptHelpers, TypeScriptUtilities, };
+export type { ProfileConfig as ProfilerConfig, PerformanceMetrics as ProfilerMetrics, RouteProfile as ProfilerRouteProfile, } from './performance-profiler';
+export type { RouteDebugConfig, RouteDebugInfo, } from './route-debugger';
+export type { RouteAnalysis as InspectorRouteAnalysis, RouteMetadata as InspectorRouteMetadata, RouteGroup, } from './route-inspector';
+export type { TypeScriptConfig as TSConfig, RouteTypeInfo as TSRouteTypeInfo, TypeDefinition as TSTypeDefinition, ValidationSchema as TSValidationSchema, } from './typescript-utilities';

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