@stacksjs/bun-router 0.0.5 → 0.0.7

package/dist/router/index.d.ts

@@ -0,0 +1,113 @@
+import type { ActionHandler, Route } from '../types';
+import { Dependencies, globalMiddlewarePipeline, MiddlewareFactory, MiddlewarePipeline, SkipConditions } from '../middleware/pipeline';
+import { FluentRouteBuilder, FluentRouter, RouteFactory, router, RouterUtils } from './fluent-routing';
+import { Router } from './router';
+import '../types';
+export { Router };
+declare module './router' {
+    interface Router {
+        stream: (callback: () => Generator<string | Uint8Array, void, unknown> | AsyncGenerator<string | Uint8Array, void, unknown>, status?: number, headers?: Record<string, string>) => Response;
+        streamJson: <T>(data: Record<string, Iterable<T> | AsyncIterable<T>>, status?: number, headers?: Record<string, string>) => Response;
+        eventStream: <_T = any>(callback: () => Generator<{
+            data: any;
+            event?: string;
+            id?: string;
+            retry?: number;
+        }, void, unknown> | AsyncGenerator<{
+            data: any;
+            event?: string;
+            id?: string;
+            retry?: number;
+        }, void, unknown>, headers?: Record<string, string>) => Response;
+        streamDownload: (callback: () => Generator<string | Uint8Array, void, unknown> | AsyncGenerator<string | Uint8Array, void, unknown>, filename: string, headers?: Record<string, string>) => Response;
+        streamFile: (filePath: string, request: any, options?: {
+            contentType?: string;
+            enableRanges?: boolean;
+            chunkSize?: number;
+        }) => Promise<Response>;
+        streamFileWithRanges: (filePath: string, req: any) => Promise<Response>;
+        streamResponse: (generator: () => AsyncGenerator<string | Uint8Array, void, unknown>, options?: {
+            headers?: Record<string, string>;
+            status?: number;
+        }) => Response;
+        transformStream: (transformer: (chunk: string | Uint8Array) => string | Uint8Array | Promise<string | Uint8Array>, options?: {
+            headers?: Record<string, string>;
+            status?: number;
+        }) => (req: Request) => Response;
+        model: <T>(key: string, modelClass: string | ((_value: string) => Promise<T | null>), callback?: (model: T | null) => Response | null) => Router;
+        implicitBinding: () => any;
+        missing: (callback: (req: any) => Response) => any;
+        scopedBindings: (bindings: Record<string, string>) => any;
+        clearModelCache: (modelName?: string) => Router;
+        getModelStats: () => {
+            totalEntries: number;
+            validEntries: number;
+            expiredEntries: number;
+            models: number;
+        };
+        readonly modelRegistry: {
+            has: (name: string) => boolean;
+            register: <_T>(name: string, config: any) => void;
+            resolve: <_T>(modelName: string, params: Record<string, string>, req?: any) => Promise<any>;
+            createErrorResponse: (modelName: string, result: any, params: Record<string, string>) => Response;
+            clearCache: (modelName: string, params?: Record<string, string>) => void;
+            clearAllCache: () => void;
+            getCacheStats: () => any;
+        };
+        matchRoute: (path: string, method: string, domain?: string) => {
+            route: Route;
+            params: Record<string, string>;
+        } | undefined;
+        getAllowedMethods: (path: string, domain?: string) => string[];
+        clearRouteCache: () => void;
+        getCacheStats: () => any;
+        getRouteStats: () => any;
+        warmRouteCache: (commonPaths: Array<{
+            path: string;
+            method: string;
+        }>) => void;
+        getRoutesByMethod: () => any;
+        getRouteConflicts: () => any;
+        rebuildRouteCompiler: () => void;
+        optimizeRoutes: (usageStats?: Record<string, number>) => void;
+        addRouteToCompiler: (route: Route) => void;
+        initializeRouteCompiler: () => void;
+        health: () => Router;
+        renderView: (view: string, data?: Record<string, any>, options?: {
+            layout?: string;
+        }) => Promise<string>;
+        view: (path: string, view: string, data?: Record<string, any>, options?: {
+            layout?: string;
+            status?: number;
+            headers?: Record<string, string>;
+        }) => Router;
+        where: ((_param: string, _pattern: string | RegExp) => Router) & ((constraints: Record<string, string | RegExp>) => Router);
+        whereNumber: (param: string) => Router;
+        whereAlpha: (param: string) => Router;
+        whereAlphaNumeric: (param: string) => Router;
+        whereUuid: (param: string) => Router;
+        whereIn: (param: string, values: string[]) => Router;
+        domain: (domain: string, callback: () => void) => Router;
+        resource: (name: string, handlers: {
+            index?: ActionHandler;
+            show?: ActionHandler;
+            store?: ActionHandler;
+            update?: ActionHandler;
+            destroy?: ActionHandler;
+            create?: ActionHandler;
+            edit?: ActionHandler;
+        }) => Router;
+        onError: (handler: (error: Error) => Response | Promise<Response>) => Router;
+        redirect: (url: string, status?: 301 | 302 | 303 | 307 | 308) => Response;
+        permanentRedirect: (url: string) => Response;
+        fallback: (handler: ActionHandler) => Router;
+        route: (name: string, params?: Record<string, string>) => string;
+    }
+}
+export { Dependencies, FluentRouteBuilder, FluentRouter, globalMiddlewarePipeline, MiddlewareFactory, MiddlewarePipeline, RouteFactory, router, RouterUtils, SkipConditions };
+export * from '../routing/route-caching';
+export * from '../routing/route-throttling';
+export * from '../routing/subdomain-routing';
+export { createHandlerResolver, resolveHandler, wrapResponse } from './handler-resolver';
+export * from './validation-integration';
+export type { DiscoveredRoute, FileBasedRoutingConfig } from './file-based-routing';

package/dist/router/middleware-groups.d.ts

@@ -0,0 +1,94 @@
+import type { MiddlewareHandler } from '../types';
+/**
+ * Middleware Group Registry
+ *
+ * Allows defining named groups of middleware that can be applied to routes.
+ * Similar to Laravel's middleware groups (web, api).
+ *
+ * @example
+ * // Define groups
+ * groups.define('web', ['session', 'csrf', 'cors'])
+ * groups.define('api', ['throttle:60,1', 'cors'])
+ *
+ * // Use on routes
+ * router.group({ middleware: 'web' }, () => { ... })
+ */
+export declare class MiddlewareGroupRegistry {
+    private groups;
+    private globalMiddleware;
+    private middlewarePriority;
+    /**
+     * Define a middleware group
+     */
+    define(name: string, middleware: (string | MiddlewareHandler)[]): this;
+    /**
+     * Extend an existing group with additional middleware
+     */
+    extend(name: string, middleware: (string | MiddlewareHandler)[]): this;
+    /**
+     * Prepend middleware to an existing group
+     */
+    prepend(name: string, middleware: (string | MiddlewareHandler)[]): this;
+    /**
+     * Get middleware for a group
+     */
+    get(name: string): (string | MiddlewareHandler)[];
+    /**
+     * Check if a group exists
+     */
+    has(name: string): boolean;
+    /**
+     * Remove a group
+     */
+    remove(name: string): this;
+    /**
+     * Resolve a middleware reference, expanding group names into their middleware
+     */
+    resolve(middleware: string | MiddlewareHandler): (string | MiddlewareHandler)[];
+    /**
+     * Resolve multiple middleware references, expanding groups
+     */
+    resolveAll(middleware: (string | MiddlewareHandler)[]): (string | MiddlewareHandler)[];
+    /**
+     * Add middleware to the global stack (runs on every request)
+     */
+    pushGlobal(...middleware: (string | MiddlewareHandler)[]): this;
+    /**
+     * Prepend middleware to the global stack
+     */
+    prependGlobal(...middleware: (string | MiddlewareHandler)[]): this;
+    /**
+     * Remove middleware from the global stack
+     */
+    removeGlobal(middleware: string): this;
+    /**
+     * Get the global middleware stack
+     */
+    getGlobal(): (string | MiddlewareHandler)[];
+    /**
+     * Set execution priority for a middleware (lower = runs first)
+     */
+    setPriority(name: string, priority: number): this;
+    /**
+     * Sort middleware by priority
+     */
+    sortByPriority(middleware: (string | MiddlewareHandler)[]): (string | MiddlewareHandler)[];
+    /**
+     * Filter middleware by applying except/only rules.
+     *
+     * @param middleware - Full middleware list
+     * @param options - except or only filter
+     */
+    filter(middleware: (string | MiddlewareHandler)[], options: {
+        except?: string[];
+        only?: string[];
+    }): (string | MiddlewareHandler)[];
+    /**
+     * Clear all groups and global middleware
+     */
+    flush(): void;
+}
+/**
+ * Default middleware group registry instance
+ */
+export declare const middlewareGroups: MiddlewareGroupRegistry;

package/dist/router/middleware-integration.d.ts

@@ -0,0 +1,112 @@
+import type { EnhancedRequest, MiddlewareHandler } from '../types';
+import type { Router } from './router';
+export type SkipConditionFn = (_req: EnhancedRequest) => boolean;
+export type SkipConditionsList = SkipConditionFn[];
+/**
+ * Skip condition helpers
+ */
+export declare const SkipConditions: {
+    skipForPaths: (paths: string[]) => SkipConditionFn;
+    skipForMethods: (methods: string[]) => SkipConditionFn;
+};
+/**
+ * Dependency helpers
+ */
+export declare const Dependencies: {
+    cache: (config: {
+        type: string;
+        ttl: number;
+    }) => {
+        type: string;
+        config: {
+            type: string;
+            ttl: number;
+        };
+    };
+    logger: (level: string) => {
+        type: string;
+        config: {
+            level: string;
+        };
+    };
+};
+declare class MiddlewarePipeline {
+    registerDependency(_key: string, _dependency: any): this;
+    registerSkipConditions(_middleware: MiddlewareHandler, _conditions: SkipConditionsList): void;
+    getStats(): any;
+    getCacheInfo(): any;
+    clearCache(): this;
+    compilePipeline(_key: string, _middleware: MiddlewareHandler[], _options?: any): void;
+    execute(_key: string, _req: EnhancedRequest, _handler: () => Promise<Response>): Promise<Response>;
+}
+/**
+ * Integration layer for middleware pipeline with the router
+ */
+export declare function registerMiddlewarePipeline(RouterClass: typeof Router): void;
+/**
+ * Middleware factory for common use cases
+ */
+export declare class MiddlewareFactory {
+    private pipeline;
+    constructor(pipeline: MiddlewarePipeline);
+    /**
+     * Create authentication middleware with conditional execution
+     */
+    createAuthMiddleware(options?: {
+        skipPaths?: string[];
+        skipMethods?: string[];
+        requireRoles?: string[];
+        jwtSecret?: string;
+    }): MiddlewareHandler;
+    /**
+     * Create rate limiting middleware with dependency injection
+     */
+    createRateLimitMiddleware(options: {
+        maxRequests: number;
+        windowMs: number;
+        skipPaths?: string[];
+    }): MiddlewareHandler;
+    /**
+     * Create logging middleware with dependency injection
+     */
+    createLoggingMiddleware(options?: {
+        level?: string;
+        skipPaths?: string[];
+        includeBody?: boolean;
+    }): MiddlewareHandler;
+    /**
+     * Create CORS middleware with conditional execution
+     */
+    createCorsMiddleware(options?: {
+        origin?: string | string[];
+        methods?: string[];
+        allowedHeaders?: string[];
+        credentials?: boolean;
+    }): MiddlewareHandler;
+}
+/**
+ * Helper function to setup common middleware stack
+ */
+export declare function setupMiddlewareStack(router: any, options?: {
+    auth?: {
+        jwtSecret: string;
+        skipPaths?: string[];
+        requireRoles?: string[];
+    };
+    rateLimit?: {
+        maxRequests: number;
+        windowMs: number;
+        skipPaths?: string[];
+    };
+    cors?: {
+        origin?: string | string[];
+        methods?: string[];
+        allowedHeaders?: string[];
+        credentials?: boolean;
+    };
+    logging?: {
+        level?: string;
+        skipPaths?: string[];
+    };
+}): MiddlewareHandler[];
+export {};

package/dist/router/middleware.d.ts

@@ -0,0 +1,5 @@
+import type { Router } from './router';
+/**
+ * Middleware handling extension for Router class
+ */
+export declare function registerMiddlewareHandling(RouterClass: typeof Router): void;

package/dist/router/model-binding.d.ts

@@ -0,0 +1,5 @@
+import type { Router } from './router';
+/**
+ * Model binding extension for Router class
+ */
+export declare function registerModelBinding(RouterClass: typeof Router): void;

package/dist/router/optimized-route-matching.d.ts

@@ -0,0 +1,6 @@
+import type { Router } from './router';
+/**
+ * Optimized route matching extension for Router class
+ * Replaces the original route matching with high-performance trie-based matching
+ */
+export declare function registerOptimizedRouteMatching(RouterClass: typeof Router): void;

package/dist/router/route-building.d.ts

@@ -0,0 +1,5 @@
+import type { Router } from './router';
+/**
+ * Route building extension for Router class
+ */
+export declare function registerRouteBuilding(RouterClass: typeof Router): void;

package/dist/router/route-compiler.d.ts

@@ -0,0 +1,153 @@
+import type { HTTPMethod, MatchResult, Route } from '../types';
+import type { CompiledRoute } from './route-trie';
+/**
+ * Route compilation options
+ */
+export interface RouteCompilerOptions {
+    enableCaching: boolean;
+    enableMethodGrouping: boolean;
+    enablePriorityOptimization: boolean;
+    cacheSize: number;
+    precompilePatterns: boolean;
+}
+/**
+ * Route matching statistics for performance monitoring
+ */
+export interface RouteMatchStats {
+    totalMatches: number;
+    cacheHits: number;
+    cacheMisses: number;
+    averageMatchTime: number;
+    trieDepth: number;
+    methodDistribution: Record<string, number>;
+}
+/**
+ * High-performance route compiler with pre-compilation and optimization
+ */
+export declare class RouteCompiler {
+    private trie;
+    private matchCache;
+    private cacheKeys;
+    private stats;
+    private options;
+    constructor(options?: Partial<RouteCompilerOptions>);
+    /**
+     * Add a route to the compiler
+     * @returns true if route was added, false if it's a duplicate
+     */
+    addRoute(route: Route): boolean;
+    /**
+     * Check if a route is an exact duplicate of an existing route
+     */
+    private checkForDuplicateRoute;
+    /**
+     * Pre-compile route patterns for faster matching
+     */
+    private patternCache;
+    /**
+     * Extract parameter names from a route path
+     */
+    private extractParamNames;
+    /**
+     * Pre-compile route patterns for faster matching
+     */
+    private precompileRoutePattern;
+    /**
+     * Convert Laravel-style route to a simple regex pattern
+     * @param path The route path with Laravel-style parameters
+     * @param constraints Optional constraints for route parameters
+     */
+    private convertToURLPattern;
+    /**
+     * Match a request path and method to a route
+     */
+    match(path: string, method: HTTPMethod): MatchResult | null;
+    /**
+     * Add an entry to the cache with LRU eviction if needed
+     */
+    private addToCache;
+    /**
+     * Update LRU tracking for a cache key
+     */
+    private updateCacheLRU;
+    /**
+     * Update average match time statistics
+     */
+    private updateMatchTime;
+    /**
+     * Get all compiled routes sorted by priority
+     */
+    getCompiledRoutes(): CompiledRoute[];
+    /**
+     * Get routes grouped by HTTP method
+     */
+    getRoutesByMethod(): Map<HTTPMethod, CompiledRoute[]>;
+    /**
+     * Warm up the cache with common routes
+     * @param commonPaths Array of paths and methods to pre-cache
+     * @param options Optional warming options
+     * @param options.force If true, enables caching temporarily even if disabled in compiler options
+     * @param options.precompile If true, performs a second match to ensure cache hits are recorded
+     * @returns Statistics about the warming operation
+     */
+    warmCache(commonPaths: Array<{
+        path: string;
+        method: HTTPMethod;
+    }>, options?: {
+        force?: boolean;
+        precompile?: boolean;
+    }): {
+        warmedPaths: number;
+        cacheSize: number;
+        hitRate: number;
+    };
+    /**
+     * Clear all caches and reset statistics
+     */
+    clear(): void;
+    /**
+     * Get performance statistics
+     */
+    getStats(): RouteMatchStats;
+    /**
+     * Get cache statistics
+     */
+    getCacheStats(): {
+        size: number;
+        maxSize: number;
+        hitRate: number;
+        enabled: boolean;
+    };
+    /**
+     * Optimize route order based on usage patterns
+     */
+    optimizeRouteOrder(_usageStats: Record<string, number>): void;
+    /**
+     * Get route conflicts (overlapping patterns)
+     */
+    getRouteConflicts(): Array<{
+        routes: CompiledRoute[];
+        conflictType: 'overlap' | 'duplicate' | 'ambiguous';
+        severity: 'low' | 'medium' | 'high';
+    }>;
+    /**
+     * Check if two routes conflict
+     */
+    private routesConflict;
+    /**
+     * Check if two route patterns overlap
+     */
+    private patternsOverlap;
+    /**
+     * Get conflict severity
+     */
+    private getConflictSeverity;
+    /**
+     * Get conflict type
+     */
+    private getConflictType;
+    /**
+     * Check if routes have ambiguous parameters
+     */
+    private hasAmbiguousParameters;
+}

package/dist/router/route-matching.d.ts

@@ -0,0 +1,5 @@
+import type { Router } from './router';
+/**
+ * Route matching extension for Router class
+ */
+export declare function registerRouteMatching(RouterClass: typeof Router): void;

package/dist/router/route-trie.d.ts

@@ -0,0 +1,114 @@
+import type { HTTPMethod, Route } from '../types';
+/**
+ * Route segment types for the trie
+ */
+export type RouteSegmentType = 'static' | 'parameter' | 'wildcard' | 'optional';
+export interface RouteSegment {
+    type: RouteSegmentType;
+    value: string;
+    paramName?: string;
+    pattern?: RegExp;
+    optional?: boolean;
+}
+export interface CompiledRoute {
+    route: Route;
+    segments: RouteSegment[];
+    paramNames: string[];
+    priority: number;
+    staticScore: number;
+    dynamicScore: number;
+}
+/**
+ * Trie node for efficient route matching
+ */
+export declare class TrieNode {
+    children: Map<string, TrieNode>;
+    paramChild: TrieNode | null;
+    wildcardChild: TrieNode | null;
+    routes: Map<HTTPMethod, CompiledRoute>;
+    paramName: string | null;
+    pattern: RegExp | null;
+    isEndpoint: boolean;
+    /**
+     * Add a route to this node
+     */
+    addRoute(method: HTTPMethod, compiledRoute: CompiledRoute): void;
+    /**
+     * Get route for a specific HTTP method
+     */
+    getRoute(method: HTTPMethod): CompiledRoute | undefined;
+    /**
+     * Get all routes at this node
+     */
+    getAllRoutes(): CompiledRoute[];
+}
+/**
+ * Route matching result with extracted parameters
+ */
+export interface RouteMatch {
+    route: Route;
+    params: Record<string, string>;
+    score: number;
+}
+/**
+ * High-performance route trie for O(log n) route matching
+ */
+export declare class RouteTrie {
+    private root;
+    private compiledRoutes;
+    private methodTries;
+    constructor();
+    /**
+     * Compile a route pattern into segments
+     */
+    compileRoute(route: Route): CompiledRoute;
+    /**
+     * Parse path into segments
+     */
+    private parsePathSegments;
+    /**
+     * Calculate route priority (higher = more specific)
+     */
+    private calculateRoutePriority;
+    /**
+     * Add a route to the trie
+     */
+    addRoute(route: Route): void;
+    /**
+     * Insert compiled route into trie
+     */
+    private insertRoute;
+    /**
+     * Match a path against the trie
+     */
+    match(path: string, method: HTTPMethod): RouteMatch | null;
+    /**
+     * Recursively match path segments
+     */
+    private matchSegments;
+    /**
+     * Get all routes for debugging
+     */
+    getAllRoutes(): CompiledRoute[];
+    /**
+     * Remove a route from the trie
+     */
+    removeRoute(route: Route): void;
+    /**
+     * Clear the trie
+     */
+    clear(): void;
+    /**
+     * Get trie statistics for debugging
+     */
+    getStats(): {
+        totalRoutes: number;
+        totalNodes: number;
+        averageDepth: number;
+        methodDistribution: Record<string, number>;
+    };
+    /**
+     * Count total nodes in trie
+     */
+    private countNodes;
+}