@stacksjs/bun-router 0.0.4 → 0.0.6

package/src/router/middleware.ts

@@ -0,0 +1,231 @@
+import type { EnhancedRequest, MiddlewareHandler, NextFunction, Route } from '../types'
+import type { Router } from './router'
+import { resolveHandler as resolveHandlerUtil, wrapResponse } from './handler-resolver'
+
+/**
+ * Middleware handling extension for Router class
+ */
+export function registerMiddlewareHandling(RouterClass: typeof Router): void {
+  Object.defineProperties(RouterClass.prototype, {
+    /**
+     * Add middleware to the router
+     */
+    use: {
+      value(...middleware: (string | MiddlewareHandler)[]): Router {
+        for (const mw of middleware) {
+          const resolvedMiddleware = this.resolveMiddleware(mw)
+          if (resolvedMiddleware) {
+            this.globalMiddleware.push(resolvedMiddleware)
+          }
+        }
+        return this
+      },
+      writable: true,
+      configurable: true,
+    },
+
+    /**
+     * Resolve a middleware string or function to a middleware handler.
+     * Returns synchronously — for string-based middleware not found in the
+     * named registry, a lazy wrapper is returned that imports the module on
+     * first invocation and caches it for subsequent calls.
+     */
+    resolveMiddleware: {
+      value(middleware: string | MiddlewareHandler): MiddlewareHandler | null {
+        if (typeof middleware === 'function') {
+          return middleware
+        }
+
+        // Class instance with handle() method (e.g. new JsonBody())
+        if (typeof middleware === 'object' && middleware !== null && 'handle' in middleware && typeof (middleware as any).handle === 'function') {
+          return (req: EnhancedRequest, next: NextFunction) => {
+            return (middleware as any).handle(req, next)
+          }
+        }
+
+        if (typeof middleware === 'string') {
+          // Check named middleware registry first (synchronous)
+          const [name, params] = middleware.split(':')
+          const factory = (this as any).namedMiddleware?.get(name)
+          if (factory) {
+            return factory(params)
+          }
+
+          // Create a lazy wrapper that imports on first request, then caches
+          let cached: MiddlewareHandler | null = null
+          const middlewareName = middleware
+          return async (req: EnhancedRequest, next: NextFunction) => {
+            if (!cached) {
+              try {
+                const importedMiddleware = await import(`../middleware/${middlewareName}.ts`)
+                if (importedMiddleware.default && typeof importedMiddleware.default === 'function') {
+                  cached = importedMiddleware.default
+                }
+                else if (importedMiddleware.default && typeof importedMiddleware.default.handle === 'function') {
+                  cached = (r: EnhancedRequest, n: NextFunction) => importedMiddleware.default.handle(r, n)
+                }
+              }
+              catch (error) {
+                console.error(`Failed to load middleware "${middlewareName}":`, error)
+              }
+            }
+            if (cached) {
+              return cached(req, next)
+            }
+            return next()
+          }
+        }
+
+        return null
+      },
+      writable: true,
+      configurable: true,
+    },
+
+    /**
+     * Build an optimized middleware chain
+     */
+    buildMiddlewareChain: {
+      value(middlewares: MiddlewareHandler[]): (req: EnhancedRequest) => Promise<Response | null> {
+        if (middlewares.length === 0) {
+          return async (_req: EnhancedRequest) => null
+        }
+
+        // Build the chain from the end to start for better performance
+        let chain = async (_req: EnhancedRequest): Promise<Response | null> => null
+
+        for (let i = middlewares.length - 1; i >= 0; i--) {
+          const middleware = middlewares[i]
+          const nextChain = chain
+          chain = async (req: EnhancedRequest): Promise<Response | null> => {
+            const next = async (): Promise<Response> => {
+              const result = await nextChain(req)
+              return result || new Response(null, { status: 200 })
+            }
+            return middleware(req, next)
+          }
+        }
+
+        return chain
+      },
+      writable: true,
+      configurable: true,
+    },
+
+    /**
+     * Run middleware stack for a request
+     */
+    runMiddleware: {
+      async value(req: EnhancedRequest, middlewareStack: MiddlewareHandler[]): Promise<Response | null> {
+        if (middlewareStack.length === 0) {
+          return null // No middleware to run
+        }
+
+        try {
+          // Build and execute optimized middleware chain
+          const chain = this.buildMiddlewareChain(middlewareStack)
+          return await chain(req)
+        }
+        catch (error) {
+          if (this.errorHandler) {
+            return this.errorHandler(error as Error)
+          }
+          throw error
+        }
+      },
+      writable: true,
+      configurable: true,
+    },
+
+    /**
+     * Add middleware to a route group
+     */
+    middleware: {
+      value(...middleware: (string | MiddlewareHandler)[]): Router {
+        // Validate string middleware names against the named middleware registry
+        for (const mw of middleware) {
+          if (typeof mw === 'string') {
+            const [name] = mw.split(':')
+            if (!this.namedMiddleware.has(name)) {
+              throw new Error(`Unknown middleware: ${name}`)
+            }
+          }
+        }
+
+        if (this.currentGroup) {
+          if (!this.currentGroup.middleware) {
+            this.currentGroup.middleware = []
+          }
+          this.currentGroup.middleware.push(...middleware)
+        }
+        else {
+          // Apply to the most recently added route
+          const lastRoute = this.routes[this.routes.length - 1]
+          if (lastRoute) {
+            this.applyMiddlewareToRoute(lastRoute, middleware)
+          }
+        }
+
+        return this
+      },
+      writable: true,
+      configurable: true,
+    },
+
+    /**
+     * Apply middleware to a specific route
+     */
+    applyMiddlewareToRoute: {
+      value(route: Route, middleware: (string | MiddlewareHandler)[]): void {
+        for (const mw of middleware) {
+          const resolvedMiddleware = this.resolveMiddleware(mw)
+          if (resolvedMiddleware) {
+            route.middleware.push(resolvedMiddleware)
+          }
+        }
+      },
+      writable: true,
+      configurable: true,
+    },
+
+    /**
+     * Resolve an action handler
+     *
+     * Supports:
+     * - Functions returning Response or any value (auto-wrapped)
+     * - String file paths like 'UserAction.ts', './actions/UserAction'
+     * - Controller@method patterns like 'UserController@index'
+     * - Class constructors with handle() method
+     * - Class instances with handle() method
+     */
+    resolveHandler: {
+      async value(handler: any, req: EnhancedRequest): Promise<Response> {
+        return resolveHandlerUtil(handler, req, this.config)
+      },
+      writable: true,
+      configurable: true,
+    },
+
+    /**
+     * Wrap a value in a Response object
+     * Useful for handlers that return non-Response values
+     */
+    wrapResponse: {
+      value: wrapResponse,
+      writable: true,
+      configurable: true,
+    },
+
+    /**
+     * Register an error handler
+     */
+    onError: {
+      value(handler: (error: Error) => Response | Promise<Response>): Router {
+        this.errorHandler = handler
+        return this
+      },
+      writable: true,
+      configurable: true,
+    },
+  })
+}

package/src/router/model-binding.ts

@@ -0,0 +1,215 @@
+import type {
+  EnhancedRequest,
+  MiddlewareHandler,
+  NextFunction,
+} from '../types'
+import type { Router } from './router'
+import {
+  modelRegistry,
+} from '../model-binding/model-registry'
+
+/**
+ * Model binding extension for Router class
+ */
+export function registerModelBinding(RouterClass: typeof Router): void {
+  Object.defineProperties(RouterClass.prototype, {
+    /**
+     * Model binding registry for this router instance
+     */
+    modelRegistry: {
+      value: modelRegistry,
+      writable: true,
+      configurable: true,
+    },
+
+    /**
+     * Laravel-style Route::model() - Explicit binding
+     * Explicitly bind a route parameter to a model
+     */
+    model: {
+      value<T>(
+        this: Router,
+        key: string,
+        modelClass: string | ((_value: string) => Promise<T | null>),
+        callback?: (model: T | null) => Response | null,
+      ): Router {
+        if (typeof modelClass === 'string') {
+          // Register string-based model class
+          this.modelRegistry.register(key, {
+            resolver: async (params: Record<string, string>) => {
+              // For string-based registration, we'll just pass through
+              // In a real Laravel app, this would resolve the model class
+              console.warn(`Model class ${modelClass} not implemented`)
+              // Return a mock model for testing
+              return { id: params[key], modelClass }
+            },
+            errorHandling: callback
+              ? {
+                  notFound: (_params: Record<string, string>) => callback(null) || new Response('Not Found', { status: 404 }),
+                }
+              : undefined,
+          })
+        }
+        else {
+          // Register function-based resolver
+          this.modelRegistry.register(key, {
+            resolver: async (params: Record<string, string>) => {
+              const value = params[key]
+              if (!value)
+                return null
+              return modelClass(value)
+            },
+            errorHandling: callback
+              ? {
+                  notFound: (_params: Record<string, string>) => callback(null) || new Response('Not Found', { status: 404 }),
+                }
+              : undefined,
+          })
+        }
+        return this
+      },
+      writable: true,
+      configurable: true,
+    },
+
+    /**
+     * Laravel-style implicit binding middleware
+     * Automatically resolves models based on route parameters
+     */
+    implicitBinding: {
+      value(this: Router): MiddlewareHandler {
+        return async (req: EnhancedRequest, next: NextFunction): Promise<Response> => {
+          if (!req.params) {
+            const result = await next()
+            return result || new Response('Not Found', { status: 404 })
+          }
+
+          // Resolve all parameters that might be models
+          for (const [paramName, _paramValue] of Object.entries(req.params)) {
+            // Check if we have a registered model for this parameter
+            if (this.modelRegistry.has(paramName)) {
+              try {
+                const result = await this.modelRegistry.resolve(paramName, req.params, req)
+
+                if (result.model === null) {
+                  if (result.status === 500) {
+                    // Handle resolver errors
+                    return new Response(JSON.stringify({
+                      error: 'Internal Server Error',
+                      message: result.error || 'Model resolution failed',
+                    }), {
+                      status: 500,
+                      headers: { 'Content-Type': 'application/json' },
+                    })
+                  }
+                  else if (result.status === 404) {
+                    return this.modelRegistry.createErrorResponse(paramName, result, req.params)
+                  }
+                }
+                else {
+                  // Attach the resolved model to the request
+                  ;(req as any)[paramName] = result.model
+                }
+              }
+              catch (error) {
+                // Handle unexpected errors in model resolution
+                return new Response(JSON.stringify({
+                  error: 'Internal Server Error',
+                  message: error instanceof Error ? error.message : 'Model resolution failed',
+                }), {
+                  status: 500,
+                  headers: { 'Content-Type': 'application/json' },
+                })
+              }
+            }
+          }
+
+          const result = await next()
+          return result || new Response('Not Found', { status: 404 })
+        }
+      },
+      writable: true,
+      configurable: true,
+    },
+
+    /**
+     * Laravel-style missing() method for customizing 404 responses
+     */
+    missing: {
+      value(
+        this: Router,
+        callback: (req: EnhancedRequest) => Response,
+      ): MiddlewareHandler {
+        return async (req: EnhancedRequest, next: NextFunction): Promise<Response> => {
+          try {
+            const result = await next()
+            return result || callback(req)
+          }
+          catch (error) {
+            console.error(error)
+            // If it's a model not found error, use the custom callback
+            return callback(req)
+          }
+        }
+      },
+      writable: true,
+      configurable: true,
+    },
+
+    /**
+     * Laravel-style scoped bindings
+     * Scope a model binding to its parent
+     */
+    scopedBindings: {
+      value(this: Router, bindings: Record<string, string>): MiddlewareHandler {
+        return async (req: EnhancedRequest, next: NextFunction): Promise<Response> => {
+          if (!req.params) {
+            const result = await next()
+            return result || new Response('Not Found', { status: 404 })
+          }
+
+          // Apply scoped bindings
+          for (const [childParam, parentParam] of Object.entries(bindings)) {
+            if (req.params[childParam] && req.params[parentParam]) {
+              // This would validate that the child belongs to the parent
+              // For now, we just pass through
+            }
+          }
+
+          const result = await next()
+          return result || new Response('Not Found', { status: 404 })
+        }
+      },
+      writable: true,
+      configurable: true,
+    },
+
+    /**
+     * Clear model cache
+     */
+    clearModelCache: {
+      value(modelName?: string): Router {
+        if (modelName) {
+          this.modelRegistry.clearCache(modelName)
+        }
+        else {
+          this.modelRegistry.clearAllCache()
+        }
+        return this
+      },
+      writable: true,
+      configurable: true,
+    },
+
+    /**
+     * Get model registry statistics
+     */
+    getModelStats: {
+      value() {
+        return this.modelRegistry.getCacheStats()
+      },
+      writable: true,
+      configurable: true,
+    },
+  })
+}

package/src/router/optimized-route-matching.ts

@@ -0,0 +1,253 @@
+import type { HTTPMethod, MatchResult, Route } from '../types'
+import type { Router } from './router'
+import { RouteCompiler } from './route-compiler'
+
+/**
+ * Optimized route matching extension for Router class
+ * Replaces the original route matching with high-performance trie-based matching
+ */
+export function registerOptimizedRouteMatching(RouterClass: typeof Router): void {
+  Object.defineProperties(RouterClass.prototype, {
+    /**
+     * Initialize the route compiler
+     */
+    initializeRouteCompiler: {
+      value() {
+        if (!this.routeCompiler) {
+          this.routeCompiler = new RouteCompiler({
+            enableCaching: true,
+            enableMethodGrouping: true,
+            enablePriorityOptimization: true,
+            cacheSize: 1000,
+            precompilePatterns: true,
+          })
+        }
+      },
+      writable: true,
+      configurable: true,
+    },
+
+    /**
+     * Add route to the optimized compiler
+     */
+    addRouteToCompiler: {
+      value(route: Route) {
+        this.initializeRouteCompiler()
+        this.routeCompiler.addRoute(route)
+      },
+      writable: true,
+      configurable: true,
+    },
+
+    /**
+     * Optimized route matching using trie structure
+     */
+    matchRoute: {
+      value(path: string, method: HTTPMethod, domain?: string): MatchResult | undefined {
+        this.initializeRouteCompiler()
+
+        // Use the optimized compiler for matching
+        const match = this.routeCompiler.match(path, method)
+
+        if (match) {
+          // Check domain constraints if specified
+          if (domain && match.route.domain && match.route.domain !== domain) {
+            return undefined
+          }
+
+          return match
+        }
+
+        // Fallback to original matching for edge cases
+        return this.fallbackMatchRoute(path, method, domain)
+      },
+      writable: true,
+      configurable: true,
+    },
+
+    /**
+     * Fallback to original route matching logic
+     */
+    fallbackMatchRoute: {
+      value(path: string, method: HTTPMethod, domain?: string): MatchResult | undefined {
+        const url = new URL(path, 'http://localhost')
+
+        // Generate cache key
+        const cacheKey = `${domain || ''}:${method}:${url.pathname}`
+
+        // Check legacy cache first
+        if (this.routeCache.has(cacheKey)) {
+          return this.routeCache.get(cacheKey)
+        }
+
+        // Fast path for static routes
+        if (this.staticRoutes.has(method)) {
+          const staticRoute = this.staticRoutes.get(method)!.get(url.pathname)
+          if (staticRoute && (!domain || !staticRoute.domain || staticRoute.domain === domain)) {
+            const result = {
+              route: staticRoute,
+              params: {},
+            }
+            this.routeCache.set(cacheKey, result)
+            return result
+          }
+        }
+
+        // Get potential routes - either all routes or domain-specific routes
+        const potentialRoutes: Route[] = domain && this.domains[domain]
+          ? this.domains[domain]
+          : this.routes
+
+        // Filter routes to only those matching the HTTP method
+        const methodRoutes = potentialRoutes.filter((route: Route) => route.method === method)
+
+        // First, try to find an exact match
+        for (const route of methodRoutes) {
+          if (route.path === url.pathname) {
+            const result = {
+              route,
+              params: {},
+            }
+            this.routeCache.set(cacheKey, result)
+            return result
+          }
+        }
+
+        // If no exact match, try matching patterns
+        for (const route of methodRoutes) {
+          if (route.pattern) {
+            const match = route.pattern.exec(url)
+            if (match) {
+              const result = {
+                route,
+                params: match.pathname.groups,
+              }
+              this.routeCache.set(cacheKey, result)
+              return result
+            }
+          }
+        }
+
+        return undefined
+      },
+      writable: true,
+      configurable: true,
+    },
+
+    /**
+     * Get route matching statistics
+     */
+    getRouteStats: {
+      value() {
+        this.initializeRouteCompiler()
+        return this.routeCompiler.getStats()
+      },
+      writable: true,
+      configurable: true,
+    },
+
+    /**
+     * Get cache statistics
+     */
+    getCacheStats: {
+      value() {
+        this.initializeRouteCompiler()
+        return this.routeCompiler.getCacheStats()
+      },
+      writable: true,
+      configurable: true,
+    },
+
+    /**
+     * Warm up the route cache with common paths
+     */
+    warmRouteCache: {
+      value(commonPaths: Array<{ path: string, method: HTTPMethod }>) {
+        this.initializeRouteCompiler()
+        this.routeCompiler.warmCache(commonPaths)
+      },
+      writable: true,
+      configurable: true,
+    },
+
+    /**
+     * Get routes grouped by HTTP method for debugging
+     */
+    getRoutesByMethod: {
+      value() {
+        this.initializeRouteCompiler()
+        return this.routeCompiler.getRoutesByMethod()
+      },
+      writable: true,
+      configurable: true,
+    },
+
+    /**
+     * Get route conflicts for debugging
+     */
+    getRouteConflicts: {
+      value() {
+        this.initializeRouteCompiler()
+        return this.routeCompiler.getRouteConflicts()
+      },
+      writable: true,
+      configurable: true,
+    },
+
+    /**
+     * Clear route compiler caches
+     */
+    clearRouteCache: {
+      value() {
+        if (this.routeCompiler) {
+          this.routeCompiler.clear()
+        }
+        // Also clear legacy caches
+        this.routeCache.clear()
+      },
+      writable: true,
+      configurable: true,
+    },
+
+    /**
+     * Rebuild route compiler with current routes
+     */
+    rebuildRouteCompiler: {
+      value() {
+        this.routeCompiler = new RouteCompiler({
+          enableCaching: true,
+          enableMethodGrouping: true,
+          enablePriorityOptimization: true,
+          cacheSize: 1000,
+          precompilePatterns: true,
+        })
+
+        // Re-add all routes
+        for (const route of this.routes) {
+          this.routeCompiler.addRoute(route)
+        }
+
+        // Re-add domain-specific routes
+        for (const domainRoutes of Object.values(this.domains) as Route[][]) {
+          for (const route of domainRoutes) {
+            this.routeCompiler.addRoute(route)
+          }
+        }
+      },
+      writable: true,
+      configurable: true,
+    },
+
+    /**
+     * Optimize route order based on usage patterns
+     */
+    optimizeRoutes: {
+      value(usageStats: Record<string, number> = {}) {
+        this.initializeRouteCompiler()
+        this.routeCompiler.optimizeRouteOrder(usageStats)
+      },
+      writable: true,
+      configurable: true,
+    },
+  })
+}