@stacksjs/bun-router 0.0.14 → 0.0.15

package/dist/router/router.d.ts

@@ -0,0 +1,317 @@
+import type { Server } from 'bun';
+import type { MiddlewareDependency, MiddlewarePipeline, MiddlewarePipelineStats, MiddlewareSkipCondition } from '../middleware/pipeline';
+import type { ActionHandler, CookieOptions, EnhancedRequest, MiddlewareHandler, Route, RouteGroup, RouteHandler, RouterConfig, WebSocketConfig, WebSocketData } from '../types';
+/**
+ * Route compiler interface for pattern matching
+ */
+export interface RouteCompiler {
+    compile: (path: string) => RegExp;
+    match: (path: string, pattern: RegExp) => Record<string, string> | null;
+}
+/**
+ * Middleware cache info interface
+ */
+export interface MiddlewareCacheInfo {
+    size: number;
+    routes: string[];
+    hitRate: number;
+}
+export type { ActionHandler, MiddlewareHandler, Route, RouteGroup, RouteHandler, RouterConfig, WebSocketConfig, };
+export type MiddlewareCondition = (_req: EnhancedRequest) => boolean;
+/**
+ * Unified Router class with advanced middleware patterns
+ */
+export declare class Router {
+    routes: Route[];
+    currentGroup: RouteGroup | null;
+    globalMiddleware: MiddlewareHandler[];
+    namedRoutes: Map<string, Route>;
+    fallbackHandler: ActionHandler | null;
+    patterns: Map<string, string>;
+    currentDomain: string | null;
+    domains: Record<string, Route[]>;
+    serverInstance: Server<WebSocketData> | null;
+    wsConfig: WebSocketConfig | null;
+    errorHandler: ((_error: Error) => Response | Promise<Response>) | null;
+    templateCache: Map<string, string>;
+    routeCache: Map<string, {
+        route: Route;
+        params: Record<string, string>;
+    }>;
+    staticRoutes: Map<string, Map<string, Route>>;
+    staticResponses: Map<string, Response>;
+    precompiledPatterns: Map<string, RegExp>;
+    domainPatternCache: Map<string, RegExp>;
+    routeCompiler: RouteCompiler | null;
+    private middlewareGroups;
+    private namedMiddleware;
+    private conditionalMiddleware;
+    _middlewarePipeline?: MiddlewarePipeline;
+    config: RouterConfig;
+    constructor(config?: Partial<RouterConfig>);
+    /**
+     * Initialize default named middleware
+     */
+    private initializeDefaultMiddleware;
+    /**
+     * Register a middleware group
+     */
+    middlewareGroup(name: string, middlewareNames: string[]): this;
+    /**
+     * Apply middleware group to routes
+     */
+    middlewareGroupRoutes(name: string): RouteGroupBuilder;
+    /**
+     * Conditional middleware execution
+     */
+    when(condition: MiddlewareCondition): ConditionalBuilder;
+    /**
+     * Apply middleware with parameters
+     */
+    middleware(middlewareName: string): MiddlewareBuilder;
+    /**
+     * Get the server instance
+     */
+    getServer(): Server<WebSocketData> | null;
+    /**
+     * Extend the router with custom methods
+     */
+    extend(methods: Record<string, (...args: unknown[]) => unknown>): Router;
+    /**
+     * Register routes from a package or module file.
+     * Loads the route file within an optional group (prefix + middleware).
+     */
+    register(routePath: string, options?: {
+        prefix?: string;
+        middleware?: MiddlewareHandler[];
+    }): Promise<Router>;
+    /**
+     * Invalidate route caches
+     */
+    invalidateCache(): void;
+    /**
+     * Internal method to add a route with full HTTP method support
+     * This is the core route registration method used by get/post/put/patch/delete
+     */
+    registerRoute(method: string, path: string, handler: ActionHandler, type?: 'api' | 'web', name?: string, middleware?: (string | MiddlewareHandler)[]): Router;
+    /**
+     * Resolve middleware from string or handler (synchronous)
+     */
+    resolveMiddleware(middleware: string | MiddlewareHandler): MiddlewareHandler | null;
+    /**
+     * HTTP GET method.
+     *
+     * `TPath` is inferred from the path literal at the call site, so an
+     * inline handler's `request.params` narrows to the extracted keyset:
+     *
+     * ```ts
+     * router.get('/api/users/{id}', (req) => {
+     *   req.params.id // typed `string`, no `as any`
+     *   // @ts-expect-error wrong key
+     *   req.params.bogus
+     * })
+     * ```
+     *
+     * The string-action / class-handler forms (`'Actions/Foo/BarAction'`)
+     * keep working — `ActionHandler<TPath>` is a union that accepts them.
+     * See stacksjs/stacks#1851 for the broader typed-request work.
+     */
+    get<TPath extends string>(path: TPath, handler: ActionHandler<TPath>, type?: 'api' | 'web', name?: string, middleware?: (string | MiddlewareHandler)[]): Router;
+    /**
+     * HTTP POST method. See {@link get} for `TPath`-driven param
+     * narrowing on inline handlers.
+     */
+    post<TPath extends string>(path: TPath, handler: ActionHandler<TPath>, type?: 'api' | 'web', name?: string, middleware?: (string | MiddlewareHandler)[]): Router;
+    /**
+     * HTTP PUT method. See {@link get} for `TPath`-driven param
+     * narrowing on inline handlers.
+     */
+    put<TPath extends string>(path: TPath, handler: ActionHandler<TPath>, type?: 'api' | 'web', name?: string, middleware?: (string | MiddlewareHandler)[]): Router;
+    /**
+     * HTTP PATCH method. See {@link get} for `TPath`-driven param
+     * narrowing on inline handlers.
+     */
+    patch<TPath extends string>(path: TPath, handler: ActionHandler<TPath>, type?: 'api' | 'web', name?: string, middleware?: (string | MiddlewareHandler)[]): Router;
+    /**
+     * HTTP DELETE method. See {@link get} for `TPath`-driven param
+     * narrowing on inline handlers.
+     */
+    delete<TPath extends string>(path: TPath, handler: ActionHandler<TPath>, type?: 'api' | 'web', name?: string, middleware?: (string | MiddlewareHandler)[]): Router;
+    /**
+     * HTTP OPTIONS method. See {@link get} for `TPath`-driven param
+     * narrowing on inline handlers.
+     */
+    options<TPath extends string>(path: TPath, handler: ActionHandler<TPath>, type?: 'api' | 'web', name?: string, middleware?: (string | MiddlewareHandler)[]): Router;
+    /**
+     * Register the same handler against multiple HTTP methods. The
+     * handler is type-narrowed via {@link ActionHandler}'s `TPath`
+     * generic, same as the single-method overloads.
+     */
+    match<TPath extends string>(methods: string[], path: TPath, handler: ActionHandler<TPath>, type?: 'api' | 'web', name?: string, middleware?: (string | MiddlewareHandler)[]): Router;
+    /**
+     * Register the handler against every HTTP method. See {@link get}
+     * for `TPath`-driven param narrowing on inline handlers.
+     */
+    any<TPath extends string>(path: TPath, handler: ActionHandler<TPath>, type?: 'api' | 'web', name?: string, middleware?: (string | MiddlewareHandler)[]): Router;
+    /**
+     * Set fallback handler for unmatched routes
+     */
+    fallback(handler: ActionHandler): Router;
+    /**
+     * Generate URL for a named route
+     */
+    route(name: string, params?: Record<string, string>): string;
+    /**
+     * Set error handler
+     */
+    onError(handler: (error: Error) => Response | Promise<Response>): Router;
+    /**
+     * Create redirect response
+     */
+    redirect(url: string, status?: 301 | 302 | 303 | 307 | 308): Response;
+    /**
+     * Create permanent redirect response
+     */
+    permanentRedirect(url: string): Response;
+    /**
+     * Register redirect route
+     */
+    redirectRoute(from: string, to: string, status?: 301 | 302 | 303 | 307 | 308): Router;
+    /**
+     * Start the HTTP server
+     */
+    serve(options?: {
+        port?: number;
+        hostname?: string;
+    }): Promise<Server<WebSocketData>>;
+    /**
+     * Handle an HTTP request
+     */
+    handleRequest(req: Request): Promise<Response>;
+    /**
+     * Get all allowed HTTP methods for a given path
+     * Used to determine if a 405 Method Not Allowed should be returned instead of 404
+     */
+    getAllowedMethods(path: string, domain?: string): string[];
+    /**
+     * Match a route based on the path, method, and domain
+     */
+    matchRoute(path: string, method: string, domain?: string): {
+        route: Route;
+        params: Record<string, string>;
+    } | undefined;
+    /**
+     * Enhance a request with params and other utilities
+     */
+    enhanceRequest(req: Request, params?: Record<string, string>): EnhancedRequest;
+    /**
+     * Apply modified cookies to a response
+     */
+    applyModifiedCookies(response: Response, req: EnhancedRequest): Response;
+    /**
+     * Serialize a cookie for the Set-Cookie header
+     */
+    serializeCookie(name: string, value: string, options?: CookieOptions): string;
+    /**
+     * Build an optimized middleware chain
+     */
+    buildMiddlewareChain(middlewares: MiddlewareHandler[]): (req: EnhancedRequest) => Promise<Response | null>;
+    /**
+     * Run middleware stack for a request
+     */
+    runMiddleware(req: EnhancedRequest, middlewareStack: MiddlewareHandler[]): Promise<Response | null>;
+    /**
+     * Resolve an action handler
+     */
+    resolveHandler(handler: ActionHandler, req: EnhancedRequest): Promise<Response>;
+    /**
+     * Add middleware to the router
+     */
+    use(...middleware: (string | MiddlewareHandler)[]): Router;
+    /**
+     * Create a route group with prefix and middleware
+     */
+    group(options: {
+        prefix?: string;
+        middleware?: (string | MiddlewareHandler)[];
+    }, callback: () => void | Promise<void>): Router;
+    /**
+     * Add route to the router
+     */
+    addRoute(route: Route): this;
+    /**
+     * Register middleware dependency
+     */
+    registerMiddlewareDependency(dependency: MiddlewareDependency): this;
+    /**
+     * Register middleware skip conditions
+     */
+    registerMiddlewareSkipConditions(_middlewareName: string, _conditions: MiddlewareSkipCondition[]): this;
+    /**
+     * Get middleware statistics
+     */
+    getMiddlewareStats(): MiddlewarePipelineStats | Record<string, never>;
+    /**
+     * Get middleware cache info
+     */
+    getMiddlewareCacheInfo(): MiddlewareCacheInfo;
+    /**
+     * Clear middleware cache
+     */
+    clearMiddlewareCache(): this;
+    /**
+     * Execute middleware pipeline
+     */
+    executeMiddleware(middleware: MiddlewareHandler[], request: EnhancedRequest, handler: () => Promise<Response>): Promise<Response>;
+}
+/**
+ * Builder for conditional middleware
+ */
+export declare class ConditionalBuilder {
+    private router;
+    private condition;
+    constructor(router: Router, condition: MiddlewareCondition);
+    middleware(middlewareName: string): this;
+}
+/**
+ * Builder for middleware with parameters
+ */
+export declare class MiddlewareBuilder {
+    private router;
+    private middleware;
+    constructor(router: Router, middleware: MiddlewareHandler[]);
+    get(_path: string, _handler: RouteHandler): this;
+    post(_path: string, _handler: RouteHandler): this;
+    put(_path: string, _handler: RouteHandler): this;
+    delete(_path: string, _handler: RouteHandler): this;
+}
+/**
+ * Builder for route groups with middleware
+ */
+export declare class RouteGroupBuilder {
+    private router;
+    private middleware;
+    constructor(router: Router, middleware: MiddlewareHandler[]);
+    get(_path: string, _handler: RouteHandler): this;
+    post(_path: string, _handler: RouteHandler): this;
+    put(_path: string, _handler: RouteHandler): this;
+    delete(_path: string, _handler: RouteHandler): this;
+}
+/**
+ * Attach bun-router's request macros (`bearerToken`, `getParam`, `cookie`,
+ * `cookies`, `header`, `params`, plus the Laravel-style input helpers
+ * `get`, `input`, `string`, `integer`, `float`, `boolean`, `array`, `has`,
+ * `filled`, etc.) to a request.
+ *
+ * Idempotent: calling on an already-enhanced request returns it unchanged.
+ * We sniff `req.bearerToken` as the marker — cheap and reliable since no
+ * native Request has it.
+ *
+ * @example
+ * import { applyRequestEnhancements } from '@stacksjs/bun-router'
+ *
+ * const enhanced = applyRequestEnhancements(req, { id: '42' })
+ * enhanced.bearerToken()  // → string | null
+ * enhanced.getParam('id') // → '42'
+ */
+export declare function applyRequestEnhancements(req: Request | EnhancedRequest, params?: Record<string, string>): EnhancedRequest;

package/dist/router/server.d.ts

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

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

@@ -0,0 +1,170 @@
+/**
+ * Router Validation Integration
+ *
+ * Integration layer for validation and macros with the router.
+ * Provides RouteBuilder and FluentRouter for building routes with validation support.
+ */
+import type { EnhancedRequest, MiddlewareHandler, RouteHandler } from '../types';
+import type { ValidationRules, ValidatorConfig } from '../validation/validator';
+/**
+ * Route builder with validation support
+ */
+export declare class RouteBuilder {
+    private method;
+    private path;
+    private handler;
+    private validationRules?;
+    private validatorConfig?;
+    constructor(method: string, path: string, handler: RouteHandler);
+    /**
+     * Add validation to the route
+     */
+    validate(rules: ValidationRules, config?: ValidatorConfig): this;
+    /**
+     * Build the route with middleware
+     */
+    build(): {
+        method: string;
+        path: string;
+        handler: RouteHandler;
+        middleware?: MiddlewareHandler[];
+    };
+}
+/**
+ * Fluent router for enhanced routing functionality
+ */
+export declare class FluentRouter {
+    private routes;
+    /**
+     * Create GET route
+     */
+    get(path: string, handler: RouteHandler): RouteBuilder;
+    /**
+     * Create POST route
+     */
+    post(path: string, handler: RouteHandler): RouteBuilder;
+    /**
+     * Create PUT route
+     */
+    put(path: string, handler: RouteHandler): RouteBuilder;
+    /**
+     * Create PATCH route
+     */
+    patch(path: string, handler: RouteHandler): RouteBuilder;
+    /**
+     * Create DELETE route
+     */
+    delete(path: string, handler: RouteHandler): RouteBuilder;
+    /**
+     * Register a built route
+     */
+    register(routeBuilder: RouteBuilder): void;
+    /**
+     * Get all registered routes
+     */
+    getRoutes(): Array<{
+        method: string;
+        path: string;
+        handler: RouteHandler;
+        middleware?: MiddlewareHandler[];
+    }>;
+}
+/**
+ * Router middleware factory for request/response enhancements
+ */
+export declare function createEnhancementMiddleware(): (req: EnhancedRequest, next: () => Promise<Response>) => Promise<Response>;
+/**
+ * Validation middleware factory with fluent API
+ */
+export declare class ValidationMiddlewareBuilder {
+    private rules;
+    private config;
+    /**
+     * Add validation rule for field
+     */
+    field(name: string, rules: string): this;
+    /**
+     * Add multiple validation rules
+     */
+    fields(rules: ValidationRules): this;
+    /**
+     * Set validator configuration
+     */
+    configure(config: ValidatorConfig): this;
+    /**
+     * Stop on first validation failure
+     */
+    stopOnFirstFailure(): this;
+    /**
+     * Set custom error messages
+     */
+    messages(messages: Record<string, string>): this;
+    /**
+     * Set custom field attributes
+     */
+    attributes(attributes: Record<string, string>): this;
+    /**
+     * Build the validation middleware
+     */
+    build(): MiddlewareHandler;
+}
+/**
+ * Factory function to create validation middleware builder
+ */
+export declare function validate(): ValidationMiddlewareBuilder;
+/** Resource handlers configuration */
+export interface ResourceHandlers {
+    index?: RouteHandler;
+    show?: RouteHandler;
+    store?: RouteHandler;
+    update?: RouteHandler;
+    destroy?: RouteHandler;
+}
+/** Resource validation configuration */
+export interface ResourceValidation {
+    store?: ValidationRules;
+    update?: ValidationRules;
+}
+/**
+ * Route helper functions
+ */
+export declare const RouteHelpers: {
+    validated: (method: string, path: string, handler: RouteHandler, rules: ValidationRules, config?: ValidatorConfig) => RouteBuilder;
+    apiRoute: (method: string, path: string, handler: RouteHandler, rules?: ValidationRules) => RouteBuilder;
+    resourceRoute: (basePath: string, handlers: ResourceHandlers, validation?: ResourceValidation) => RouteBuilder[];
+};
+/**
+ * Fluent router factory
+ */
+export declare function createFluentRouter(): FluentRouter;
+/**
+ * Middleware composition helpers
+ */
+export declare const MiddlewareHelpers: {
+    /**
+     * Compose multiple middleware into one
+     */
+    compose: (...middleware: MiddlewareHandler[]) => MiddlewareHandler;
+    /**
+     * Create conditional middleware
+     */
+    when: (condition: (req: EnhancedRequest) => boolean, middleware: MiddlewareHandler) => MiddlewareHandler;
+    /**
+     * Create middleware that runs unless condition is met
+     */
+    unless: (condition: (req: EnhancedRequest) => boolean, middleware: MiddlewareHandler) => MiddlewareHandler;
+    /**
+     * Create middleware group
+     */
+    group: (middleware: MiddlewareHandler[]) => MiddlewareHandler;
+};
+/** Enhancement middleware type */
+export type EnhancementMiddleware = (req: EnhancedRequest, next: () => Promise<Response>) => Promise<Response>;
+/**
+ * Request/Response enhancement presets
+ */
+export declare const EnhancementPresets: {
+    api: () => EnhancementMiddleware[];
+    web: () => EnhancementMiddleware[];
+    validation: (rules: ValidationRules, config?: ValidatorConfig) => EnhancementMiddleware[];
+};

package/dist/router/view-rendering.d.ts

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

package/dist/router/websocket.d.ts

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

package/dist/routing/route-caching.d.ts

@@ -0,0 +1,129 @@
+import type { EnhancedRequest } from '../types';
+import { LRUCache } from '../cache/lru-cache';
+/**
+ * Route caching configuration
+ */
+export interface RouteCacheConfig {
+    ttl?: number;
+    maxSize?: number;
+    tags?: string[];
+    varyBy?: string[];
+    excludeQuery?: string[];
+    condition?: (req: EnhancedRequest) => boolean;
+}
+/**
+ * Cached response metadata
+ */
+export interface CachedResponse {
+    response: Response;
+    headers: Record<string, string>;
+    status: number;
+    body: string | Uint8Array;
+    timestamp: number;
+    ttl?: number;
+    tags: string[];
+    etag?: string;
+}
+/**
+ * Cache key generator for route responses
+ */
+export declare class RouteCacheKeyGenerator {
+    /**
+     * Generate cache key from request
+     */
+    static generateKey(req: EnhancedRequest, config: RouteCacheConfig): string;
+}
+/**
+ * Route cache manager with tag-based invalidation
+ */
+export declare class RouteCacheManager {
+    private cache;
+    private tagIndex;
+    private keyTags;
+    constructor(maxSize?: number);
+    /**
+     * Get cached response
+     */
+    get(key: string): Promise<CachedResponse | null>;
+    /**
+     * Set cached response
+     */
+    set(key: string, response: CachedResponse): Promise<void>;
+    /**
+     * Delete cached response
+     */
+    delete(key: string): boolean;
+    /**
+     * Invalidate cache by tags
+     */
+    invalidateByTags(tags: string[]): number;
+    /**
+     * Clear all cache
+     */
+    clear(): void;
+    /**
+     * Get cache statistics
+     */
+    getStats(): ReturnType<LRUCache<CachedResponse>['getStats']> & {
+        totalTags: number;
+        totalKeyTagMappings: number;
+    };
+}
+/**
+ * Global route cache manager instance
+ */
+export declare const routeCacheManager: RouteCacheManager;
+/**
+ * Create route caching middleware
+ */
+export declare function createRouteCacheMiddleware(config: RouteCacheConfig): (req: EnhancedRequest, next: () => Promise<Response>) => Promise<Response>;
+/**
+ * Factory functions for common cache configurations
+ */
+export declare const RouteCacheFactory: {
+    /**
+     * Short-term cache (5 minutes)
+     */
+    short: (tags?: string[]) => RouteCacheConfig;
+    /**
+     * Medium-term cache (1 hour)
+     */
+    medium: (tags?: string[]) => RouteCacheConfig;
+    /**
+     * Long-term cache (24 hours)
+     */
+    long: (tags?: string[]) => RouteCacheConfig;
+    /**
+     * API response cache with common settings
+     */
+    api: (tags?: string[]) => RouteCacheConfig;
+    /**
+     * Static content cache
+     */
+    static: (tags?: string[]) => RouteCacheConfig;
+    /**
+     * User-specific cache
+     */
+    user: (tags?: string[]) => RouteCacheConfig;
+};
+/**
+ * Cache invalidation utilities
+ */
+export declare const CacheInvalidation: {
+    /**
+     * Invalidate by tags
+     */
+    byTags: (tags: string[]) => number;
+    /**
+     * Invalidate all user-related cache
+     */
+    forUser: (userId: string) => number;
+    /**
+     * Invalidate model-related cache
+     */
+    forModel: (modelName: string, id?: string) => number;
+    /**
+     * Clear all cache
+     */
+    all: () => void;
+};