@stacksjs/bun-router 0.0.15 → 0.0.17

package/dist/middleware/cors.d.ts

@@ -1,5 +1,14 @@
 import type { EnhancedRequest, NextFunction } from '../types';
 export default class Cors {
+    /**
+     * Resolve the `Access-Control-Allow-Origin` value for a request.
+     *
+     * Supports a string origin (`'*'` or an explicit origin) or an array of
+     * allowed origins. For an allowlist, the request `Origin` is reflected back
+     * only when it is present in the list. When credentials are enabled a literal
+     * `*` is never returned (it would be both spec-violating and dangerous).
+     */
+    private resolveAllowOrigin;
     private getCorsHeaders;
     handle(req: EnhancedRequest, next: NextFunction): Promise<Response>;
 }

package/dist/middleware/csrf.d.ts

@@ -2,6 +2,13 @@ import type { EnhancedRequest, NextFunction } from '../types';
 export default class Csrf {
     private static tokens;
     handle(req: EnhancedRequest, next: NextFunction): Promise<Response>;
+    /**
+     * Constant-time string comparison — a plain `!==` leaks how many leading
+     * characters of the token were correct through response timing.
+     */
+    private static safeCompare;
+    private static storeToken;
+    private static isTokenValid;
     private generateToken;
     private parseCookies;
 }

package/dist/middleware/ddos_protection.d.ts

@@ -13,13 +13,27 @@ export interface DDoSProtectionOptions {
     skipSuccessfulRequests?: boolean;
     skipFailedRequests?: boolean;
     keyGenerator?: (req: EnhancedRequest) => string;
-    onLimitReached?: (req: EnhancedRequest, rateLimitInfo: any) => Response | Promise<Response>;
+    onLimitReached?: (req: EnhancedRequest, rateLimitInfo: DDoSRateLimitInfo) => Response | Promise<Response>;
     store?: 'memory' | 'redis';
     redis?: {
         url: string;
         prefix?: string;
     };
 }
+interface RequestInfo {
+    count: number;
+    firstRequest: number;
+    lastRequest: number;
+    blocked: boolean;
+    blockExpires?: number;
+}
+/**
+ * Rate-limit details passed to `onLimitReached` when a client is blocked.
+ */
+export interface DDoSRateLimitInfo extends RequestInfo {
+    /** Seconds until the block lifts (mirrors the Retry-After header) */
+    retryAfter: number;
+}
 export default class DDoSProtection {
     private options;
     private requestStore;
@@ -37,3 +51,4 @@ export default class DDoSProtection {
     destroy(): void;
 }
 export declare function ddosProtection(options?: DDoSProtectionOptions): (req: EnhancedRequest, next: NextFunction) => Promise<Response>;
+export {};

package/dist/middleware/rate_limit.d.ts

@@ -1,3 +1,4 @@
+import type { StorageProvider } from 'ts-rate-limiter';
 import type { EnhancedRequest, Middleware, MiddlewareHandler, NextFunction } from '../types';
 export interface RateLimitOptions {
     windowMs?: number;
@@ -12,7 +13,12 @@ export interface RateLimitOptions {
         resetTime: number;
     }) => Response | Promise<Response>;
     skip?: (request: Request) => boolean | Promise<boolean>;
-    storage?: any;
+    /**
+     * Custom storage backend (ts-rate-limiter `StorageProvider`), or the
+     * string `'redis'` to use the built-in Redis store configured via
+     * the `redis` option.
+     */
+    storage?: StorageProvider | 'redis';
     algorithm?: 'fixed-window' | 'sliding-window' | 'token-bucket';
     draftMode?: boolean;
     redis?: {

package/dist/middleware/request_tracer.d.ts

@@ -7,17 +7,28 @@ export interface TraceSpan {
     startTime: number;
     endTime?: number;
     duration?: number;
-    tags: Record<string, any>;
+    tags: Record<string, unknown>;
     logs: Array<{
         timestamp: number;
         level: 'debug' | 'info' | 'warn' | 'error';
         message: string;
-        fields?: Record<string, any>;
+        fields?: Record<string, unknown>;
     }>;
     status: 'ok' | 'error' | 'timeout';
     error?: string;
     stackTrace?: string[];
 }
+/**
+ * Destination for exported spans. `endpoint`/`headers` configure the
+ * HTTP-based exporters (jaeger/zipkin/otlp); `customExporter` receives
+ * the spans directly.
+ */
+export interface TraceExporterConfig {
+    type: 'console' | 'jaeger' | 'zipkin' | 'otlp' | 'custom';
+    endpoint?: string;
+    headers?: Record<string, string>;
+    customExporter?: (spans: TraceSpan[]) => Promise<void>;
+}
 export interface TracingOptions {
     enabled?: boolean;
     sampleRate?: number;
@@ -27,12 +38,7 @@ export interface TracingOptions {
     includeRequestBody?: boolean;
     includeResponseBody?: boolean;
     maxBodySize?: number;
-    exporters?: Array<{
-        type: 'console' | 'jaeger' | 'zipkin' | 'otlp' | 'custom';
-        endpoint?: string;
-        headers?: Record<string, string>;
-        customExporter?: (spans: TraceSpan[]) => Promise<void>;
-    }>;
+    exporters?: TraceExporterConfig[];
     propagation?: {
         enabled?: boolean;
         headers?: string[];
@@ -63,7 +69,7 @@ export default class RequestTracer {
     getActiveSpans(): TraceSpan[];
     getSpanById(spanId: string): TraceSpan | undefined;
     createChildSpan(parentSpanId: string, operationName: string): string | null;
-    addTag(spanId: string, key: string, value: any): void;
+    addTag(spanId: string, key: string, value: unknown): void;
     addLog(spanId: string, level: 'debug' | 'info' | 'warn' | 'error', message: string, fields?: Record<string, any>): void;
     finish(spanId: string, status?: 'ok' | 'error' | 'timeout', error?: string): void;
     flush(): Promise<void>;

package/dist/middleware/response_cache.d.ts

@@ -5,7 +5,7 @@ export interface CacheEntry {
         status: number;
         statusText: string;
         headers: Record<string, string>;
-        body: number[];
+        body: Uint8Array | number[];
         contentType: string;
     };
     createdAt: number;
@@ -54,6 +54,7 @@ export declare class ResponseCache implements Middleware {
     private memoryCache;
     private cacheStats;
     private cleanupInterval?;
+    private compiledInvalidationPatterns;
     constructor(options?: ResponseCacheOptions);
     private initializeStorage;
     private startCleanupInterval;

package/dist/request/context.d.ts

@@ -9,7 +9,14 @@
  */
 import type { EnhancedRequest } from '../types';
 /**
- * Run `fn` inside an AsyncLocalStorage scope where `request()` and
+ * Force AsyncLocalStorage-backed request context on for all subsequent
+ * requests. Calling `request()`/`getCurrentRequest()` enables it
+ * automatically — use this when the very first request must already be
+ * fully isolated under concurrent load.
+ */
+export declare function enableRequestContext(): void;
+/**
+ * Run `fn` inside a request-context scope where `request()` and
  * `getCurrentRequest()` resolve to `initial`. The Router calls this around
  * each request automatically.
  */
@@ -23,6 +30,10 @@ export declare function setCurrentRequest(req: EnhancedRequest): void;
 /**
  * Returns the active request, or `undefined` when called outside a request
  * scope. Prefer `request()` when the request is required.
+ *
+ * First use switches the router to AsyncLocalStorage-backed context for
+ * all subsequent requests; this call itself resolves via a synchronous
+ * fallback (see `enableRequestContext` for eager opt-in).
  */
 export declare function getCurrentRequest(): EnhancedRequest | undefined;
 /**

package/dist/request/macros.d.ts

@@ -7,16 +7,25 @@ import type { EnhancedRequest } from '../types';
 export interface RequestMacro {
     name: string;
     handler: (this: EnhancedRequest, ...args: any[]) => any;
+    /**
+     * Accessor macros are installed as getters on the macro prototype —
+     * `req.<name>` invokes the handler instead of returning a function.
+     * Assignment shadows the accessor with an own property.
+     */
+    accessor?: boolean;
 }
+export declare function getParsedURL(req: EnhancedRequest): URL;
+export declare function getParsedCookies(req: EnhancedRequest): Record<string, string>;
 /**
  * Request macro registry
  */
 declare class RequestMacroRegistry {
     private macros;
+    private epoch;
     /**
      * Register a request macro
      */
-    register(name: string, handler: (this: EnhancedRequest, ...args: any[]) => any): void;
+    register(name: string, handler: (this: EnhancedRequest, ...args: any[]) => any, accessor?: boolean): void;
     /**
      * Get a registered macro
      */
@@ -37,6 +46,10 @@ declare class RequestMacroRegistry {
      * Clear all macros
      */
     clear(): void;
+    /**
+     * Monotonic registry version (see `RequestWithMacros.applyMacros`)
+     */
+    getEpoch(): number;
 }
 /**
  * Global request macro registry
@@ -51,7 +64,21 @@ export declare class RequestWithMacros {
      */
     static macro(name: string, handler: (this: EnhancedRequest, ...args: any[]) => any): void;
     /**
-     * Apply macros to a request object
+     * Register an accessor macro: `req.<name>` evaluates the getter
+     * (instead of exposing a callable). Assignment to the property
+     * shadows the accessor with an own value, so consumers that set
+     * `req.<name> = ...` keep working.
+     */
+    static macroAccessor(name: string, getter: (this: EnhancedRequest) => any): void;
+    /**
+     * Apply macros to a request object.
+     *
+     * Macros are attached via a shared prototype inserted between the
+     * request and its original prototype — one `setPrototypeOf` per
+     * request. The previous implementation looped over every macro and
+     * `bind`-assigned it, costing ~40 property writes and closures per
+     * request on the dispatch hot path. Macro handlers receive the
+     * request as `this`, so no per-request binding is needed.
      */
     static applyMacros(request: EnhancedRequest): EnhancedRequest;
     /**
@@ -119,6 +146,17 @@ export declare const BuiltInRequestMacros: {
      * Get authorization header
      */
     bearerToken(this: EnhancedRequest): string | null;
+    /**
+     * Get the raw, unparsed request body as a string.
+     *
+     * The body stream can only be consumed once, so this caches the result on
+     * `_rawBody`. Signature-verifying callbacks (Stripe/GitHub/Slack webhooks)
+     * need the exact bytes the client sent, before any JSON parsing — a parsed
+     * `jsonBody` re-serialized is NOT byte-identical and will fail HMAC checks.
+     * A framework body parser that has already read the body may populate
+     * `_rawBody` up front so this returns without re-reading.
+     */
+    rawBody(this: EnhancedRequest): Promise<string>;
     /**
      * Get basic auth credentials
      */

package/dist/response/macros.d.ts

@@ -7,16 +7,16 @@ export interface ResponseMacro {
     name: string;
     handler: (...args: any[]) => Response;
 }
-export interface ApiResponse<T = any> {
+export interface ApiResponse<T = unknown> {
     data?: T;
     message?: string;
     error?: string;
     errors?: Record<string, string[]>;
-    meta?: Record<string, any>;
+    meta?: Record<string, unknown>;
     links?: Record<string, string>;
     timestamp?: string;
 }
-export interface PaginatedResponse<T = any> extends ApiResponse<T[]> {
+export interface PaginatedResponse<T = unknown> extends ApiResponse<T[]> {
     meta: {
         current_page: number;
         per_page: number;

package/dist/router/fluent-routing.d.ts

@@ -4,6 +4,30 @@ import type { ThrottleConfig } from '../routing/route-throttling';
 import type { EnhancedRequest, MiddlewareHandler, RouteHandler, ThrottlePattern } from '../types';
 import { RouteCacheFactory } from '../routing/route-caching';
 import { ThrottleFactory } from '../routing/route-throttling';
+/**
+ * A route registered on a {@link FluentRouter}
+ */
+export interface RegisteredFluentRoute {
+    method: string;
+    path: string;
+    handler: RouteHandler;
+    middleware: MiddlewareHandler[];
+    name?: string;
+}
+/**
+ * Laravel-style resource controller shape accepted by
+ * {@link FluentRouter.resource}. Every action is optional — only the
+ * actions present (and allowed by `only`/`except`) are registered.
+ */
+export interface FluentResourceController {
+    index?: RouteHandler;
+    create?: RouteHandler;
+    store?: RouteHandler;
+    show?: RouteHandler;
+    edit?: RouteHandler;
+    update?: RouteHandler;
+    destroy?: RouteHandler;
+}
 /**
  * Fluent route builder with chainable API
  */
@@ -122,6 +146,16 @@ export declare class FluentRouter {
      * Conditional middleware execution
      */
     when(condition: MiddlewareCondition): FluentConditionalBuilder;
+    /**
+     * Look up a named middleware factory.
+     * @internal Used by the fluent builders — avoids `as any` reach-ins.
+     */
+    resolveNamedMiddleware(name: string): ((params?: string) => MiddlewareHandler) | undefined;
+    /**
+     * Register conditional middleware, evaluated per request in {@link handle}.
+     * @internal Used by the fluent builders.
+     */
+    addConditionalMiddleware(conditional: ConditionalMiddleware): void;
     /**
      * Apply middleware with parameters
      */
@@ -192,7 +226,7 @@ export declare class FluentRouter {
     /**
      * Create resource routes (Laravel-style)
      */
-    resource(name: string, controller: any, options?: {
+    resource(name: string, controller: FluentResourceController, options?: {
         only?: string[];
         except?: string[];
         model?: BunQueryBuilderModel;
@@ -200,23 +234,24 @@ export declare class FluentRouter {
     /**
      * Get all registered routes
      */
-    getRoutes(): Array<{
-        method: string;
-        path: string;
-        handler: RouteHandler;
-        middleware: MiddlewareHandler[];
-        name?: string;
-    }>;
+    getRoutes(): RegisteredFluentRoute[];
     /**
      * Handle incoming request
      */
     handle(request: EnhancedRequest): Promise<Response | null>;
     /**
-     * Check if route matches request
+     * Match a route against the request, extracting path parameters.
+     *
+     * Delegates to the same `matchPath` used by the main `Router`, so the
+     * fluent API has identical semantics for `{param}`, optional `{param?}`,
+     * and wildcard segments (the previous ad-hoc regex neither escaped
+     * static text nor extracted params at all).
+     *
+     * @returns the extracted params, or `null` when the route doesn't match
      */
-    private matchesRoute;
+    private matchRouteParams;
     /**
-     * Execute route with middleware
+     * Execute route with middleware (global → conditional → route-specific)
      */
     private executeRoute;
 }
@@ -249,7 +284,9 @@ export declare const RouteFactory: {
  */
 export declare const RouterUtils: {
     /**
-     * Generate route URL with parameters
+     * Generate a URL for a named route. Resolves the path from the shared
+     * named-route registry (the same one `router.route()`/`url()` use);
+     * falls back to `/<name>` when the name was never registered.
      */
     route: (name: string, params?: Record<string, string>, query?: Record<string, string>) => string;
     /**
@@ -259,7 +296,7 @@ export declare const RouterUtils: {
     /**
      * JSON response
      */
-    json: (data: any, status?: number) => Response;
+    json: (data: unknown, status?: number) => Response;
 };
 /**
  * Global router instance

package/dist/router/handler-resolver.d.ts

@@ -22,3 +22,11 @@ export declare function resolveHandler(handler: unknown, req: EnhancedRequest, c
  * Creates a handler resolver bound to a specific config
  */
 export declare function createHandlerResolver(config: RouterConfig): (handler: unknown, req: EnhancedRequest) => Promise<Response>;
+/**
+ * Precompile the dispatch branch for a handler whose shape never changes
+ * (a registered route's handler). `resolveHandler` re-sniffs the handler
+ * type — instanceof / typeof / prototype checks — on every request; this
+ * resolves the branch once and returns a specialized invoker for the
+ * per-request hot path.
+ */
+export declare function createHandlerInvoker(handler: unknown, config: RouterConfig): (req: EnhancedRequest) => Promise<Response>;

package/dist/router/index.d.ts

@@ -82,6 +82,7 @@ declare module './router' {
             status?: number;
             headers?: Record<string, string>;
         }) => Router;
+        withoutNativeDispatch: () => Router;
         where: ((_param: string, _pattern: string | RegExp) => Router) & ((constraints: Record<string, string | RegExp>) => Router);
         whereNumber: (param: string) => Router;
         whereAlpha: (param: string) => Router;
@@ -98,6 +99,7 @@ declare module './router' {
             create?: ActionHandler;
             edit?: ActionHandler;
         }) => Router;
+        head: (path: string, handler: ActionHandler, type?: 'api' | 'web', name?: string, middleware?: any[]) => Router;
         onError: (handler: (error: Error) => Response | Promise<Response>) => Router;
         redirect: (url: string, status?: 301 | 302 | 303 | 307 | 308) => Response;
         permanentRedirect: (url: string) => Response;

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

@@ -9,6 +9,12 @@ export interface RouteCompilerOptions {
     enablePriorityOptimization: boolean;
     cacheSize: number;
     precompilePatterns: boolean;
+    /**
+     * Record per-match timing via `performance.now()`. Off by default —
+     * timing every request costs two clock reads per match on the hot path.
+     * Match/hit/miss counters are always collected (they're just integers).
+     */
+    enableProfiling: boolean;
 }
 /**
  * Route matching statistics for performance monitoring
@@ -27,7 +33,7 @@ export interface RouteMatchStats {
 export declare class RouteCompiler {
     private trie;
     private matchCache;
-    private cacheKeys;
+    private routeKeys;
     private stats;
     private options;
     constructor(options?: Partial<RouteCompilerOptions>);
@@ -36,10 +42,6 @@ export declare class RouteCompiler {
      * @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
      */
@@ -67,11 +69,7 @@ export declare class RouteCompiler {
      */
     private addToCache;
     /**
-     * Update LRU tracking for a cache key
-     */
-    private updateCacheLRU;
-    /**
-     * Update average match time statistics
+     * Update average match time statistics (only when profiling is enabled)
      */
     private updateMatchTime;
     /**

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

@@ -83,7 +83,13 @@ export declare class RouteTrie {
      */
     match(path: string, method: HTTPMethod): RouteMatch | null;
     /**
-     * Recursively match path segments
+     * Recursively match path segments.
+     *
+     * Candidates are tried in specificity order — static, then parameter,
+     * then wildcard — and the first full match wins. This both fixes the
+     * old behavior (where a wildcard sibling could shadow a static route)
+     * and avoids allocating candidate arrays and params copies per segment:
+     * `params` is mutated in place and rolled back on backtrack.
      */
     private matchSegments;
     /**

package/dist/router/router.d.ts

@@ -47,6 +47,8 @@ export declare class Router {
     private namedMiddleware;
     private conditionalMiddleware;
     _middlewarePipeline?: MiddlewarePipeline;
+    _mwEpoch: number;
+    _allowedMethodsCache: Map<string, string[]>;
     config: RouterConfig;
     constructor(config?: Partial<RouterConfig>);
     /**
@@ -229,12 +231,21 @@ export declare class Router {
      */
     use(...middleware: (string | MiddlewareHandler)[]): Router;
     /**
-     * Create a route group with prefix and middleware
+     * Create a route group with prefix and middleware.
+     *
+     * Synchronous callbacks return the router for chaining. Asynchronous
+     * callbacks return a promise that resolves once the callback (and any
+     * routes it registers) has finished — await it, or routes registered
+     * after an `await` inside the callback would lose the group prefix.
      */
     group(options: {
         prefix?: string;
         middleware?: (string | MiddlewareHandler)[];
-    }, callback: () => void | Promise<void>): Router;
+    }, callback: () => Promise<void>): Promise<Router>;
+    group(options: {
+        prefix?: string;
+        middleware?: (string | MiddlewareHandler)[];
+    }, callback: () => void): Router;
     /**
      * Add route to the router
      */

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

@@ -2,7 +2,7 @@
  * Router Validation Integration
  *
  * Integration layer for validation and macros with the router.
- * Provides RouteBuilder and FluentRouter for building routes with validation support.
+ * Provides RouteBuilder and ValidationFluentRouter for building routes with validation support.
  */
 import type { EnhancedRequest, MiddlewareHandler, RouteHandler } from '../types';
 import type { ValidationRules, ValidatorConfig } from '../validation/validator';
@@ -31,9 +31,15 @@ export declare class RouteBuilder {
     };
 }
 /**
- * Fluent router for enhanced routing functionality
+ * Minimal route collector with validation support.
+ *
+ * Renamed from `FluentRouter`: this module used to declare a third class
+ * with that name. It was shadowed by the canonical `FluentRouter` exported
+ * from `fluent-routing.ts` (explicit exports win over `export *`), so
+ * `createFluentRouter()` silently returned a different class than the
+ * public `FluentRouter` symbol. The distinct name removes the ambiguity.
  */
-export declare class FluentRouter {
+export declare class ValidationFluentRouter {
     private routes;
     /**
      * Create GET route
@@ -136,7 +142,7 @@ export declare const RouteHelpers: {
 /**
  * Fluent router factory
  */
-export declare function createFluentRouter(): FluentRouter;
+export declare function createFluentRouter(): ValidationFluentRouter;
 /**
  * Middleware composition helpers
  */

package/dist/types/middleware-types.d.ts

@@ -4,7 +4,7 @@
  * Advanced TypeScript utilities for type-safe middleware with generic constraints
  */
 import type { RouteHandler, TypedRequest } from './route-inference';
-export interface TypedMiddleware<TInput = any, TOutput = TInput, _TContext = object, TNext = any> {
+export interface TypedMiddleware<TInput = Request, TOutput = Response, _TContext = object, TNext = () => Promise<TOutput>> {
     (request: TInput, next: TNext): Promise<TOutput> | TOutput;
 }
 export type AugmentContext<TBase, TAddition> = TBase & TAddition;

package/dist/types/route-inference.d.ts

@@ -3,7 +3,13 @@
  *
  * Advanced TypeScript utilities for inferring route parameter types from URL patterns
  */
-export type ExtractRouteParams<T extends string> = T extends `${infer _Start}:${infer Param}/${infer Rest}` ? {
+/** Strip an inline constraint from a brace parameter: `id:[0-9]+` → `id` */
+type StripInlineConstraint<T extends string> = T extends `${infer Name}:${string}` ? Name : T;
+export type ExtractRouteParams<T extends string> = T extends `${string}{${infer Param}}${infer Rest}` ? (Param extends `${infer Inner}?` ? {
+    [K in StripInlineConstraint<Inner>]?: string;
+} : {
+    [K in StripInlineConstraint<Param>]: string;
+}) & ExtractRouteParams<Rest> : T extends `${infer _Start}:${infer Param}/${infer Rest}` ? {
     [K in Param]: string;
 } & ExtractRouteParams<`/${Rest}`> : T extends `${infer _Start}:${infer Param}?${infer Rest}` ? {
     [K in Param]?: string;
@@ -100,7 +106,7 @@ export interface RouteGroup<TPrefix extends string = '', TContext = object> {
     middleware?: TypedMiddleware<any, any, any, TContext>[];
     routes: TypedRoute<any, any, any, TContext>[];
 }
-export interface TypedMiddleware<TRequest = any, TResponse = any, TNext = any, _TContext = Record<string, never>> {
+export interface TypedMiddleware<TRequest = Request, TResponse = Response, TNext = () => Promise<TResponse>, _TContext = Record<string, never>> {
     (request: TRequest, next: TNext): Promise<TResponse> | TResponse;
 }
 export interface RouteBuilder<TContext = object> {
@@ -166,3 +172,4 @@ export interface GenerateOpenAPISchema<T extends TypedRoute<any, any, any, any>>
 export type AssertEqual<T, U> = T extends U ? U extends T ? true : false : false;
 export type AssertExtends<T, U> = T extends U ? true : false;
 export type AssertNotEqual<T, U> = AssertEqual<T, U> extends true ? false : true;
+export {};