@stacksjs/bun-router 0.0.14 → 0.0.15

package/src/router/http-methods.ts

@@ -0,0 +1,377 @@
+import type { ActionHandler, EnhancedRequest, MiddlewareHandler, Route } from '../types'
+import type { Router } from './router'
+import { registerNamedRoute } from '../url'
+import { extractParamNames, joinPaths, matchPath } from '../utils'
+
+/**
+ * HTTP methods extension for Router class
+ * Uses a class extension pattern instead of prototype manipulation
+ */
+export function registerHttpMethods(RouterClass: typeof Router): void {
+  // Extend the Router class with HTTP methods
+  Object.defineProperties(RouterClass.prototype, {
+    // Add a route to the router
+    addRoute: {
+      value(
+        method: string,
+        path: string,
+        handler: ActionHandler,
+        type?: 'api' | 'web',
+        name?: string,
+        middleware?: (string | MiddlewareHandler)[],
+      ): Router {
+        // Apply current group settings if in a group
+        let routePath = path
+        let routeMiddleware: MiddlewareHandler[] = []
+        const routeType = type || 'web'
+
+        if (this.currentGroup) {
+          // Apply prefix if it exists
+          if (this.currentGroup.prefix) {
+            routePath = joinPaths(this.currentGroup.prefix, path)
+          }
+
+          // Apply middleware if it exists
+          if (this.currentGroup.middleware && this.currentGroup.middleware.length > 0) {
+            routeMiddleware = [...this.currentGroup.middleware] as MiddlewareHandler[]
+          }
+        }
+
+        // Apply route-specific middleware if provided
+        if (middleware && middleware.length > 0) {
+          for (const middlewareItem of middleware) {
+            const resolved = this.resolveMiddleware(middlewareItem)
+            if (resolved) {
+              routeMiddleware.push(resolved)
+            }
+          }
+        }
+
+        // Apply API/Web path prefixes
+        if (routeType === 'api' && this.config.apiPrefix) {
+          routePath = joinPaths(this.config.apiPrefix, routePath)
+        }
+        else if (routeType === 'web' && this.config.webPrefix) {
+          routePath = joinPaths(this.config.webPrefix, routePath)
+        }
+
+        // Apply domain if in a domain group
+        let domain: string | undefined
+        if (this.currentDomain) {
+          domain = this.currentDomain
+        }
+
+        // Create the route
+        const route: Route = {
+          method: method.toUpperCase(),
+          path: routePath,
+          handler,
+          domain,
+          params: {},
+          middleware: routeMiddleware,
+        }
+
+        // Apply constraints from patterns map
+        const paramNames = extractParamNames(routePath)
+        const constraints: Record<string, string> = {}
+
+        paramNames.forEach((param: string) => {
+          // Remove optional marker for constraint lookup
+          const baseParam = param.replace('?', '')
+          if (this.patterns.has(baseParam)) {
+            constraints[baseParam] = this.patterns.get(baseParam)!
+          }
+        })
+
+        if (Object.keys(constraints).length > 0) {
+          route.constraints = constraints
+        }
+
+        // Add pattern property for route matching
+        route.pattern = {
+          exec: (url: URL): { pathname: { groups: Record<string, string> } } | null => {
+            const params: Record<string, string> = {}
+            // Pass constraints directly to matchPath for more efficient matching
+            const constraintsRecord = route.constraints && !Array.isArray(route.constraints)
+              ? route.constraints as Record<string, string>
+              : undefined
+
+            const isMatch = matchPath(routePath, url.pathname, params, constraintsRecord)
+
+            if (!isMatch) {
+              return null
+            }
+
+            return {
+              pathname: {
+                groups: params,
+              },
+            }
+          },
+        }
+
+        // If handler is a Response object, register it for Bun's native static dispatch.
+        // Static responses bypass the fetch handler entirely for zero-allocation serving.
+        if (handler instanceof Response) {
+          this.staticResponses.set(routePath, handler)
+        }
+
+        // Add to the appropriate collection
+        if (domain) {
+          if (!this.domains[domain]) {
+            this.domains[domain] = []
+          }
+          this.domains[domain].push(route)
+        }
+        else {
+          this.routes.push(route)
+        }
+
+        // Add to static routes map for fast lookup if it's a static route.
+        // First registration wins — if a route is already registered (e.g., by user code),
+        // the framework default is skipped so users can override any route.
+        if (!routePath.includes('{') && !routePath.includes('*')) {
+          if (!this.staticRoutes.has(method.toUpperCase())) {
+            this.staticRoutes.set(method.toUpperCase(), new Map())
+          }
+          const methodMap = this.staticRoutes.get(method.toUpperCase())!
+          if (!methodMap.has(routePath)) {
+            methodMap.set(routePath, route)
+          }
+        }
+
+        // Add to named routes if name is provided
+        if (name) {
+          route.name = name
+          this.namedRoutes.set(name, route)
+          registerNamedRoute(name, route.path)
+        }
+
+        // Add to optimized route compiler if available
+        if (this.addRouteToCompiler) {
+          this.addRouteToCompiler(route)
+        }
+
+        // Clear route cache when new routes are added
+        this.routeCache.clear()
+
+        return this
+      },
+      writable: true,
+      configurable: true,
+    },
+
+    // HTTP GET method
+    get: {
+      value(
+        path: string,
+        handler: ActionHandler,
+        type?: 'api' | 'web',
+        name?: string,
+        middleware?: (string | MiddlewareHandler)[],
+      ): Router {
+        return this.addRoute('GET', path, handler, type, name, middleware)
+      },
+      writable: true,
+      configurable: true,
+    },
+
+    // HTTP POST method
+    post: {
+      value(
+        path: string,
+        handler: ActionHandler,
+        type?: 'api' | 'web',
+        name?: string,
+        middleware?: (string | MiddlewareHandler)[],
+      ): Router {
+        return this.addRoute('POST', path, handler, type, name, middleware)
+      },
+      writable: true,
+      configurable: true,
+    },
+
+    // HTTP PUT method
+    put: {
+      value(
+        path: string,
+        handler: ActionHandler,
+        type?: 'api' | 'web',
+        name?: string,
+        middleware?: (string | MiddlewareHandler)[],
+      ): Router {
+        return this.addRoute('PUT', path, handler, type, name, middleware)
+      },
+      writable: true,
+      configurable: true,
+    },
+
+    // HTTP PATCH method
+    patch: {
+      value(
+        path: string,
+        handler: ActionHandler,
+        type?: 'api' | 'web',
+        name?: string,
+        middleware?: (string | MiddlewareHandler)[],
+      ): Router {
+        return this.addRoute('PATCH', path, handler, type, name, middleware)
+      },
+      writable: true,
+      configurable: true,
+    },
+
+    // HTTP DELETE method
+    delete: {
+      value(
+        path: string,
+        handler: ActionHandler,
+        type?: 'api' | 'web',
+        name?: string,
+        middleware?: (string | MiddlewareHandler)[],
+      ): Router {
+        return this.addRoute('DELETE', path, handler, type, name, middleware)
+      },
+      writable: true,
+      configurable: true,
+    },
+
+    // HTTP OPTIONS method
+    options: {
+      value(
+        path: string,
+        handler: ActionHandler,
+        type?: 'api' | 'web',
+        name?: string,
+        middleware?: (string | MiddlewareHandler)[],
+      ): Router {
+        return this.addRoute('OPTIONS', path, handler, type, name, middleware)
+      },
+      writable: true,
+      configurable: true,
+    },
+
+    // Register a route that responds to multiple HTTP methods
+    match: {
+      value(
+        methods: string[],
+        path: string,
+        handler: ActionHandler,
+        type?: 'api' | 'web',
+        name?: string,
+        middleware?: (string | MiddlewareHandler)[],
+      ): Router {
+        for (const method of methods) {
+          this.addRoute(method, path, handler, type, name, middleware)
+        }
+        return this
+      },
+      writable: true,
+      configurable: true,
+    },
+
+    // Register a route that responds to ANY HTTP method
+    any: {
+      value(
+        path: string,
+        handler: ActionHandler,
+        type?: 'api' | 'web',
+        name?: string,
+        middleware?: (string | MiddlewareHandler)[],
+      ): Router {
+        const methods = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS', 'HEAD']
+        return this.match(methods, path, handler, type, name, middleware)
+      },
+      writable: true,
+      configurable: true,
+    },
+
+    // Register a fallback handler for unmatched routes
+    fallback: {
+      value(handler: ActionHandler): Router {
+        this.fallbackHandler = handler
+        return this
+      },
+      writable: true,
+      configurable: true,
+    },
+
+    // Generate a URL for a named route
+    route: {
+      value(name: string, params: Record<string, string> = {}): string {
+        const route = this.namedRoutes.get(name)
+        if (!route) {
+          throw new Error(`Route with name "${name}" not found`)
+        }
+
+        let url = route.path
+        // Replace path parameters
+        for (const [param, value] of Object.entries(params)) {
+          url = url.replace(`{${param}}`, encodeURIComponent(value))
+          url = url.replace(`{${param}?}`, encodeURIComponent(value))
+        }
+
+        return url
+      },
+      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,
+    },
+  })
+}
+
+/**
+ * Register redirect methods on the Router class
+ */
+export function registerRedirectMethods(RouterClass: typeof Router): void {
+  Object.defineProperties(RouterClass.prototype, {
+    redirect: {
+      value(url: string, status: 301 | 302 | 303 | 307 | 308 = 302): Response {
+        const headers = new Headers()
+        headers.set('Location', url)
+        return new Response(null, {
+          status,
+          headers,
+        })
+      },
+      writable: true,
+      configurable: true,
+    },
+
+    permanentRedirect: {
+      value(url: string): Response {
+        return this.redirect(url, 301)
+      },
+      writable: true,
+      configurable: true,
+    },
+
+    redirectRoute: {
+      value(from: string, to: string, status: 301 | 302 | 303 | 307 | 308 = 302): Router {
+        this.get(from, (_req: EnhancedRequest) => {
+          return this.redirect(to, status)
+        })
+        return this
+      },
+      writable: true,
+      configurable: true,
+    },
+
+    permanentRedirectRoute: {
+      value(from: string, to: string): Router {
+        return this.redirectRoute(from, to, 301)
+      },
+      writable: true,
+      configurable: true,
+    },
+  })
+}

package/src/router/index.ts

@@ -0,0 +1,187 @@
+import type { ActionHandler, Route } from '../types'
+import { Dependencies, globalMiddlewarePipeline, MiddlewareFactory, MiddlewarePipeline, SkipConditions } from '../middleware/pipeline'
+import { registerApiRoutes } from './api-routes'
+import { registerFileBasedRouting } from './file-based-routing'
+import { registerFileStreaming } from './file-streaming'
+import { FluentRouteBuilder, FluentRouter, RouteFactory, router, RouterUtils } from './fluent-routing'
+import { registerGroupOrganization } from './group-organization'
+import { registerHttpMethods, registerRedirectMethods } from './http-methods'
+import { registerMiddlewareHandling } from './middleware'
+import { registerModelBinding } from './model-binding'
+import { registerOptimizedRouteMatching } from './optimized-route-matching'
+import { registerRouteBuilding } from './route-building'
+import { registerRouteMatching } from './route-matching'
+import { Router } from './router'
+import { registerServerHandling } from './server'
+import { registerViewRendering } from './view-rendering'
+import { registerWebSocketHandling } from './websocket'
+import '../types' // Import types for type augmentation
+
+// Register all the extensions to the Router class
+registerHttpMethods(Router)
+registerRedirectMethods(Router)
+registerRouteMatching(Router)
+registerOptimizedRouteMatching(Router) // Override with optimized version
+registerMiddlewareHandling(Router)
+registerViewRendering(Router)
+registerWebSocketHandling(Router)
+registerFileStreaming(Router)
+registerGroupOrganization(Router)
+registerServerHandling(Router)
+registerRouteBuilding(Router)
+registerModelBinding(Router)
+registerFileBasedRouting(Router)
+registerApiRoutes(Router)
+
+// 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' {
+  interface Router {
+    // Laravel-style streaming methods
+    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
+
+    // Laravel-style model binding methods
+    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
+    }
+
+    // Optimized route matching methods
+    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 check method
+    health: () => Router
+
+    // View rendering methods
+    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
+
+    // Route constraint methods
+    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 routing
+    domain: (domain: string, callback: () => void) => Router
+
+    // RESTful resource routing
+    resource: (name: string, handlers: {
+      index?: ActionHandler
+      show?: ActionHandler
+      store?: ActionHandler
+      update?: ActionHandler
+      destroy?: ActionHandler
+      create?: ActionHandler
+      edit?: ActionHandler
+    }) => Router
+
+    // Redirect and utility methods
+    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 routing features
+export * from '../routing/route-caching'
+export * from '../routing/route-throttling'
+export * from '../routing/subdomain-routing'
+
+// Export handler resolution utilities
+export { createHandlerResolver, resolveHandler, wrapResponse } from './handler-resolver'
+
+// Export validation integration
+export * from './validation-integration'
+
+// Export file-based routing
+export type { DiscoveredRoute, FileBasedRoutingConfig } from './file-based-routing'