@stacksjs/bun-router 0.0.6 → 0.0.8

package/dist/cli.js

@@ -1879,7 +1879,7 @@ var prefix = getPrefix();
 var color18 = __toESM(require_picocolors(), 1);
 var import_picocolors19 = __toESM(require_picocolors(), 1);
 // package.json
-var version = "0.0.6";
+var version = "0.0.8";
 
 // src/cli/middleware.ts
 import fs from "fs/promises";

package/dist/index.js

@@ -8847,7 +8847,12 @@ class Router {
       const allowedMethods = this.getAllowedMethods(url2.pathname, hostname);
       if (allowedMethods.length > 0) {
         const methodNotAllowedHandler = async (_req, _next) => {
-          return new Response(JSON.stringify({ error: "Method Not Allowed" }), {
+          return new Response(JSON.stringify({
+            error: "Method Not Allowed",
+            path: url2.pathname,
+            method: req.method,
+            allowed: allowedMethods
+          }), {
             status: 405,
             headers: {
               "Content-Type": "application/json",
@@ -8869,7 +8874,11 @@ class Router {
           if (this.fallbackHandler) {
             return await this.resolveHandler(this.fallbackHandler, enhancedReq);
           }
-          return new Response(JSON.stringify({ error: "Not Found" }), {
+          return new Response(JSON.stringify({
+            error: "Not Found",
+            path: url2.pathname,
+            method: req.method
+          }), {
             status: 404,
             headers: { "Content-Type": "application/json" }
           });
@@ -8884,7 +8893,11 @@ class Router {
         const response2 = await this.resolveHandler(this.fallbackHandler, enhancedReq);
         return this.applyModifiedCookies(response2, enhancedReq);
       }
-      return new Response(JSON.stringify({ error: "Not Found" }), {
+      return new Response(JSON.stringify({
+        error: "Not Found",
+        path: url2.pathname,
+        method: req.method
+      }), {
         status: 404,
         headers: { "Content-Type": "application/json" }
       });
@@ -9263,6 +9276,10 @@ class Router {
     enhancedReq.header = (name) => {
       return req.headers.get(name) || req.headers.get(name.toLowerCase()) || null;
     };
+    enhancedReq.cookie = (name, defaultValue) => {
+      const value = getCookies()[name];
+      return value !== undefined ? value : defaultValue ?? null;
+    };
     enhancedReq.getParam = (name, defaultValue) => {
       const value = params?.[name];
       return value !== undefined ? value : defaultValue;
@@ -9517,6 +9534,17 @@ class RouteGroupBuilder2 {
     return this;
   }
 }
+var _enhancementHost = null;
+function getEnhancementHost() {
+  if (_enhancementHost === null)
+    _enhancementHost = new Router;
+  return _enhancementHost;
+}
+function applyRequestEnhancements(req, params = {}) {
+  if (typeof req.bearerToken === "function")
+    return req;
+  return getEnhancementHost().enhanceRequest(req, params);
+}
 
 // src/router/server.ts
 function registerServerHandling(RouterClass) {
@@ -9637,31 +9665,52 @@ function registerServerHandling(RouterClass) {
             return new Response("No response from middleware chain", { status: 500 });
           }
           const allowedMethods = this.getAllowedMethods(url2.pathname, hostname);
+          const corsHeaders = {
+            "Content-Type": "application/json",
+            "Access-Control-Allow-Origin": "*",
+            "Access-Control-Allow-Methods": "GET, POST, PUT, DELETE, PATCH, OPTIONS",
+            "Access-Control-Allow-Headers": "Content-Type, Authorization, X-Requested-With, Accept, Origin"
+          };
           if (allowedMethods.length > 0) {
-            return new Response(JSON.stringify({ success: false, message: "Method Not Allowed" }), {
-              status: 405,
-              headers: {
-                "Content-Type": "application/json",
-                Allow: allowedMethods.join(", "),
-                "Access-Control-Allow-Origin": "*",
-                "Access-Control-Allow-Methods": "GET, POST, PUT, DELETE, PATCH, OPTIONS",
-                "Access-Control-Allow-Headers": "Content-Type, Authorization, X-Requested-With, Accept, Origin"
-              }
-            });
+            const methodNotAllowedHandler = async (_req, _next) => {
+              return new Response(JSON.stringify({
+                success: false,
+                message: "Method Not Allowed",
+                path: url2.pathname,
+                method: req.method,
+                allowed: allowedMethods
+              }), {
+                status: 405,
+                headers: { ...corsHeaders, Allow: allowedMethods.join(", ") }
+              });
+            };
+            if (this.globalMiddleware.length > 0) {
+              const stack = [...this.globalMiddleware, methodNotAllowedHandler];
+              const response2 = await this.runMiddleware(enhancedReq, stack);
+              if (response2)
+                return this.applyModifiedCookies(response2, enhancedReq);
+            }
+            return await methodNotAllowedHandler(enhancedReq, async () => null);
           }
           if (this.fallbackHandler) {
             const response2 = await this.resolveHandler(this.fallbackHandler, enhancedReq);
             return this.applyModifiedCookies(response2, enhancedReq);
           }
-          return new Response(JSON.stringify({ success: false, message: "Not Found" }), {
-            status: 404,
-            headers: {
-              "Content-Type": "application/json",
-              "Access-Control-Allow-Origin": "*",
-              "Access-Control-Allow-Methods": "GET, POST, PUT, DELETE, PATCH, OPTIONS",
-              "Access-Control-Allow-Headers": "Content-Type, Authorization, X-Requested-With, Accept, Origin"
-            }
-          });
+          const notFoundHandler = async (_req, _next) => {
+            return new Response(JSON.stringify({
+              success: false,
+              message: "Not Found",
+              path: url2.pathname,
+              method: req.method
+            }), { status: 404, headers: corsHeaders });
+          };
+          if (this.globalMiddleware.length > 0) {
+            const stack = [...this.globalMiddleware, notFoundHandler];
+            const response2 = await this.runMiddleware(enhancedReq, stack);
+            if (response2)
+              return this.applyModifiedCookies(response2, enhancedReq);
+          }
+          return await notFoundHandler(enhancedReq, async () => null);
         } catch (error) {
           console.error("Error handling request:", error);
           if (this.errorHandler) {
@@ -13781,6 +13830,7 @@ export {
   authMocks,
   authHelpers,
   auth,
+  applyRequestEnhancements,
   apiKeyAuth,
   WebSocketTester,
   ValidationMiddlewareBuilder,

package/dist/router/index.d.ts

@@ -4,6 +4,7 @@ import { FluentRouteBuilder, FluentRouter, RouteFactory, router, RouterUtils } f
 import { Router } from './router';
 import '../types';
 export { Router };
+export { applyRequestEnhancements } from './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;

package/dist/router/router.d.ts

@@ -274,3 +274,21 @@ export declare class RouteGroupBuilder {
     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/types.d.ts

@@ -688,6 +688,12 @@ export interface EnhancedRequest extends Request, Omit<RequestMacroMethods, 'ip'
      * Route parameters extracted from the URL
      */
     params: Record<string, string>;
+    /**
+     * Lookup a single route param. Equivalent to `request.params[name]` but
+     * with optional default-value handling, matching the Laravel-style
+     * `$request->route('name')` ergonomics.
+     */
+    getParam: <T = string>(name: string, defaultValue?: T) => T | undefined;
     /**
      * Query parameters from the URL
      */

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@stacksjs/bun-router",
   "type": "module",
-  "version": "0.0.6",
+  "version": "0.0.8",
   "description": "A fast, type-safe router for Bun.",
   "author": "Chris Breuer <chris@stacksjs.org>",
   "license": "MIT",

package/src/router/index.ts

@@ -33,8 +33,10 @@ registerModelBinding(Router)
 registerFileBasedRouting(Router)
 registerApiRoutes(Router)
 
-// Export the Router class and fluent routing features
+// Export the Router class, the standalone request-enhancement helper, and
+// fluent routing features.
 export { Router }
+export { applyRequestEnhancements } from './router'
 
 // Type augmentation for Laravel-style methods
 declare module './router' {

package/src/router/router.ts

@@ -611,13 +611,21 @@ export class Router {
         return new Response('No response from middleware chain', { status: 500 })
       }
 
-      // No route found - check if the path exists with a different method (405 vs 404)
+      // No route found - check if the path exists with a different method (405 vs 404).
+      // 404/405 bodies now include path + method so client-side debugging (typo'd
+      // endpoint, stale SPA cache, missing route registration) is one grep away.
+      // Both responses still flow through globalMiddleware so user middleware
+      // (X-Request-ID, audit, custom CORS) sees them.
       const allowedMethods = this.getAllowedMethods(url.pathname, hostname)
 
-      // If there are allowed methods, return 405 Method Not Allowed
       if (allowedMethods.length > 0) {
         const methodNotAllowedHandler = async (_req: EnhancedRequest, _next: NextFunction) => {
-          return new Response(JSON.stringify({ error: 'Method Not Allowed' }), {
+          return new Response(JSON.stringify({
+            error: 'Method Not Allowed',
+            path: url.pathname,
+            method: req.method,
+            allowed: allowedMethods,
+          }), {
             status: 405,
             headers: {
               'Content-Type': 'application/json',
@@ -643,7 +651,11 @@ export class Router {
           if (this.fallbackHandler) {
             return await this.resolveHandler(this.fallbackHandler, enhancedReq)
           }
-          return new Response(JSON.stringify({ error: 'Not Found' }), {
+          return new Response(JSON.stringify({
+            error: 'Not Found',
+            path: url.pathname,
+            method: req.method,
+          }), {
             status: 404,
             headers: { 'Content-Type': 'application/json' },
           })
@@ -661,8 +673,12 @@ export class Router {
         return this.applyModifiedCookies(response, enhancedReq)
       }
 
-      // No fallback handler, return a 404
-      return new Response(JSON.stringify({ error: 'Not Found' }), {
+      // No fallback handler, return a 404 with path context
+      return new Response(JSON.stringify({
+        error: 'Not Found',
+        path: url.pathname,
+        method: req.method,
+      }), {
         status: 404,
         headers: { 'Content-Type': 'application/json' },
       })
@@ -1131,6 +1147,15 @@ export class Router {
       return req.headers.get(name) || req.headers.get(name.toLowerCase()) || null
     }
 
+    // Convenience cookie reader. The full `enhancedReq.cookies.get(name)` API
+    // is also available below — `cookie(name)` is the shorter form callers
+    // (and the Laravel-style macros) reach for first, so it deserves a
+    // direct method on the enhanced request, not just on the macros class.
+    ;(enhancedReq as any).cookie = (name: string, defaultValue?: string): string | null => {
+      const value = getCookies()[name]
+      return value !== undefined ? value : (defaultValue ?? null)
+    }
+
     ;(enhancedReq as any).getParam = <T = string>(name: string, defaultValue?: T): T | undefined => {
       const value = params?.[name] as T | undefined
       return value !== undefined ? value : defaultValue
@@ -1506,3 +1531,51 @@ export class RouteGroupBuilder {
     return this
   }
 }
+
+// ---------------------------------------------------------------------------
+// Standalone enhancement helper
+// ---------------------------------------------------------------------------
+
+// Singleton scratch Router used to expose `enhanceRequest` as a standalone
+// function. Downstream consumers (frameworks layered on bun-router) often
+// need to attach the request macros to a request that was created outside
+// of `route.serve()` — for instance, when a higher-level router wraps
+// each handler with its own middleware chain. Without an exported function,
+// those consumers either spin up their own `new Router()` per call or
+// duplicate the attachment logic in user code.
+//
+// We share one instance because `enhanceRequest` does not depend on any
+// per-router state (route table, middleware groups, etc.) — it only reads
+// from the request and the supplied params.
+let _enhancementHost: Router | null = null
+
+function getEnhancementHost(): Router {
+  if (_enhancementHost === null) _enhancementHost = new Router()
+  return _enhancementHost
+}
+
+/**
+ * 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 function applyRequestEnhancements(
+  req: Request | EnhancedRequest,
+  params: Record<string, string> = {},
+): EnhancedRequest {
+  if (typeof (req as any).bearerToken === 'function')
+    return req as EnhancedRequest
+  return getEnhancementHost().enhanceRequest(req as Request, params)
+}

package/src/router/server.ts

@@ -195,21 +195,38 @@ export function registerServerHandling(RouterClass: typeof Router): void {
             return new Response('No response from middleware chain', { status: 500 })
           }
 
-          // No route found - check if the path exists with a different method (405 vs 404)
+          // No route found - check if the path exists with a different method (405 vs 404).
+          // The 404/405 responses below now (a) include path + method in the body so client
+          // debugging is one grep away, and (b) flow through globalMiddleware so cross-cutting
+          // concerns (X-Request-ID, Server-Timing, audit logging, custom CORS) can observe
+          // them. Previously these paths short-circuited entirely.
           const allowedMethods = this.getAllowedMethods(url.pathname, hostname)
+          const corsHeaders = {
+            'Content-Type': 'application/json',
+            'Access-Control-Allow-Origin': '*',
+            'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE, PATCH, OPTIONS',
+            'Access-Control-Allow-Headers': 'Content-Type, Authorization, X-Requested-With, Accept, Origin',
+          }
 
-          // If there are allowed methods, return 405 Method Not Allowed
           if (allowedMethods.length > 0) {
-            return new Response(JSON.stringify({ success: false, message: 'Method Not Allowed' }), {
-              status: 405,
-              headers: {
-                'Content-Type': 'application/json',
-                'Allow': allowedMethods.join(', '),
-                'Access-Control-Allow-Origin': '*',
-                'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE, PATCH, OPTIONS',
-                'Access-Control-Allow-Headers': 'Content-Type, Authorization, X-Requested-With, Accept, Origin',
-              },
-            })
+            const methodNotAllowedHandler = async (_req: EnhancedRequest, _next: any) => {
+              return new Response(JSON.stringify({
+                success: false,
+                message: 'Method Not Allowed',
+                path: url.pathname,
+                method: req.method,
+                allowed: allowedMethods,
+              }), {
+                status: 405,
+                headers: { ...corsHeaders, Allow: allowedMethods.join(', ') },
+              })
+            }
+            if (this.globalMiddleware.length > 0) {
+              const stack = [...this.globalMiddleware, methodNotAllowedHandler]
+              const response = await this.runMiddleware(enhancedReq, stack)
+              if (response) return this.applyModifiedCookies(response, enhancedReq)
+            }
+            return await methodNotAllowedHandler(enhancedReq, async () => null as any)
           }
 
           // No route found, try the fallback handler
@@ -218,16 +235,22 @@ export function registerServerHandling(RouterClass: typeof Router): void {
             return this.applyModifiedCookies(response, enhancedReq)
           }
 
-          // No fallback handler, return a 404 with CORS headers
-          return new Response(JSON.stringify({ success: false, message: 'Not Found' }), {
-            status: 404,
-            headers: {
-              'Content-Type': 'application/json',
-              'Access-Control-Allow-Origin': '*',
-              'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE, PATCH, OPTIONS',
-              'Access-Control-Allow-Headers': 'Content-Type, Authorization, X-Requested-With, Accept, Origin',
-            },
-          })
+          // No fallback — emit a 404 enriched with path + method, also through
+          // globalMiddleware so user middleware sees it.
+          const notFoundHandler = async (_req: EnhancedRequest, _next: any) => {
+            return new Response(JSON.stringify({
+              success: false,
+              message: 'Not Found',
+              path: url.pathname,
+              method: req.method,
+            }), { status: 404, headers: corsHeaders })
+          }
+          if (this.globalMiddleware.length > 0) {
+            const stack = [...this.globalMiddleware, notFoundHandler]
+            const response = await this.runMiddleware(enhancedReq, stack)
+            if (response) return this.applyModifiedCookies(response, enhancedReq)
+          }
+          return await notFoundHandler(enhancedReq, async () => null as any)
         }
         catch (error) {
           console.error('Error handling request:', error)

package/src/types.ts

@@ -793,6 +793,12 @@ export interface EnhancedRequest extends Request, Omit<RequestMacroMethods, 'ip'
    * Route parameters extracted from the URL
    */
   params: Record<string, string>
+  /**
+   * Lookup a single route param. Equivalent to `request.params[name]` but
+   * with optional default-value handling, matching the Laravel-style
+   * `$request->route('name')` ergonomics.
+   */
+  getParam: <T = string>(name: string, defaultValue?: T) => T | undefined
   /**
    * Query parameters from the URL
    */