@stacksjs/bun-router 0.0.4 → 0.0.6

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

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

@@ -0,0 +1,209 @@
+/**
+ * Development Tools - TypeScript Utilities
+ *
+ * TypeScript development utilities, type checking, and code generation
+ */
+import type { EnhancedRequest } from '../types';
+export interface TypeScriptConfig {
+    strictMode?: boolean;
+    generateTypes?: boolean;
+    validateTypes?: boolean;
+    outputDir?: string;
+    includeComments?: boolean;
+    generateSchemas?: boolean;
+}
+export interface RouteTypeInfo {
+    method: string;
+    pattern: string;
+    requestType: string;
+    responseType: string;
+    paramsType: string;
+    queryType: string;
+    bodyType: string;
+    middlewareTypes: string[];
+    handlerSignature: string;
+}
+export interface TypeDefinition {
+    name: string;
+    type: 'interface' | 'type' | 'enum' | 'class';
+    definition: string;
+    imports: string[];
+    exports: string[];
+    documentation?: string;
+}
+export 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;
+    private routeTypes;
+    private typeDefinitions;
+    constructor(config?: TypeScriptConfig);
+    /**
+     * Register route type information
+     */
+    registerRouteTypes(method: string, pattern: string, options?: {
+        requestType?: string;
+        responseType?: string;
+        paramsType?: string;
+        queryType?: string;
+        bodyType?: string;
+        middlewareTypes?: string[];
+        handlerSignature?: string;
+    }): void;
+    /**
+     * Generate TypeScript definitions for all routes
+     */
+    generateRouteTypes(): string;
+    /**
+     * Generate validation schemas from TypeScript types
+     */
+    generateValidationSchemas(): Record<string, ValidationSchema>;
+    /**
+     * Generate OpenAPI schema from route types
+     */
+    generateOpenAPISchema(): any;
+    /**
+     * Validate request against TypeScript types
+     */
+    validateRequest(req: EnhancedRequest, routeKey: string): {
+        valid: boolean;
+        errors: string[];
+        warnings: string[];
+    };
+    /**
+     * Generate type-safe route builder
+     */
+    generateRouteBuilder(): string;
+    /**
+     * Generate middleware type definitions
+     */
+    generateMiddlewareTypes(): string;
+    /**
+     * Get route type information
+     */
+    getRouteTypes(): RouteTypeInfo[];
+    /**
+     * Get type definition
+     */
+    getTypeDefinition(name: string): TypeDefinition | undefined;
+    /**
+     * Register custom type definition
+     */
+    registerTypeDefinition(definition: TypeDefinition): void;
+    /**
+     * Clear all type information
+     */
+    clear(): void;
+    /**
+     * Infer parameter types from route pattern
+     */
+    private inferParamsType;
+    /**
+     * Extract path parameters from pattern
+     */
+    private extractPathParameters;
+    /**
+     * Infer parameter type from constraint
+     */
+    private inferParamType;
+    /**
+     * Generate handler signature
+     */
+    private generateHandlerSignature;
+    /**
+     * Generate imports section
+     */
+    private generateImports;
+    /**
+     * Generate parameter types
+     */
+    private generateParamTypes;
+    /**
+     * Generate handler types
+     */
+    private generateHandlerTypes;
+    /**
+     * Generate route registry type
+     */
+    private generateRouteRegistryType;
+    /**
+     * Generate utility types
+     */
+    private generateUtilityTypes;
+    /**
+     * Convert path to type name
+     */
+    private pathToTypeName;
+    /**
+     * Convert path to method name
+     */
+    private pathToMethodName;
+    /**
+     * Convert path to operation ID
+     */
+    private pathToOperationId;
+    /**
+     * Convert TypeScript type to validation schema
+     */
+    private typeToSchema;
+    /**
+     * Convert TypeScript type to OpenAPI schema
+     */
+    private typeToOpenAPISchema;
+    /**
+     * Validate request parameters
+     */
+    private validateParams;
+    /**
+     * Validate query parameters
+     */
+    private validateQuery;
+    /**
+     * Validate request body
+     */
+    private validateBody;
+}
+/**
+ * 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: () => string;
+    /**
+     * Generate validation schemas
+     */
+    generateSchemas: () => Record<string, ValidationSchema>;
+    /**
+     * Generate OpenAPI documentation
+     */
+    generateOpenAPI: () => any;
+    /**
+     * Validate request types
+     */
+    validateRequest: (req: EnhancedRequest, routeKey: string) => {
+        valid: boolean;
+        errors: string[];
+        warnings: string[];
+    };
+};

package/dist/docs.d.ts

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