feat(router): add route-specific middleware and improve documentation 💫

- Add comprehensive documentation for route-specific middleware usage
- Add route-specific middleware support with path-based matching
- Fix static file serving documentation with correct URL examples
- Improve Handler function parameter organization and JSDoc comments
- Refactor import path resolution using Node.js pathToFileURL
- Remove deprecated parseImport method in favor of standard URL handling

Author: NeaByteLab

README.md

@@ -13,6 +13,8 @@ HTTP server with file-based routing library for Deno that supports middleware an
   - [Dynamic Routes](#dynamic-routes)
   - [Supported HTTP Methods](#supported-http-methods)
 - [Middleware](#middleware)
+  - [Global Middleware](#global-middleware)
+  - [Route-Specific Middleware](#route-specific-middleware)
 - [Built-in Middleware](#built-in-middleware)
   - [CORS Middleware](#cors-middleware)
 - [Static File Serving](#static-file-serving)
@@ -128,6 +130,14 @@ Export any of these HTTP methods from your route files:
 
 ## Middleware
 
+Deserve supports both global and route-specific middleware. Middleware executes in the following order:
+
+1. **Route-specific middleware** - Applied to matching route patterns
+2. **Global middleware** - Applied to all routes
+3. **Route handlers** - Execute the actual route logic
+
+### Global Middleware
+
 Add global middleware to process requests before they reach route handlers:
 
 ```typescript
@@ -164,6 +174,85 @@ router.use((req: Request) => {
 router.serve(8000)
 ```
 
+### Route-Specific Middleware
+
+Apply middleware to specific route patterns using the same `use()` method with a route path:
+
+```typescript
+import { Router } from '@neabyte/deserve'
+
+const router = new Router()
+
+// Global middleware (applies to ALL routes)
+router.use((req: Request) => {
+  console.log(`🌐 [GLOBAL] ${req.method} ${req.url}`)
+  return null
+})
+
+// Route-specific middleware
+router.use('/api', (req: Request) => {
+  const token = req.headers.get('Authorization')
+  if (!token) {
+    return new Response('Unauthorized', { status: 401 })
+  }
+  console.log('✅ API route authenticated')
+  return null
+})
+
+router.use('/api/admin', (req: Request) => {
+  const role = req.headers.get('X-User-Role')
+  if (role !== 'admin') {
+    return new Response('Forbidden', { status: 403 })
+  }
+  console.log('✅ Admin route authorized')
+  return null
+})
+
+router.use('/public', (req: Request) => {
+  console.log('🌍 Public route accessed')
+  return null
+})
+
+// Start the server
+router.serve(8000)
+```
+
+**Route Pattern Matching:**
+- `router.use('/api', middleware)` - Applies to `/api/*` routes
+- `router.use('/api/admin', middleware)` - Applies to `/api/admin/*` routes
+- `router.use('/public', middleware)` - Applies to `/public/*` routes
+
+**Multiple Middleware per Route:**
+```typescript
+// Apply multiple middleware to the same route
+router.use('/api', authMiddleware)
+router.use('/api', rateLimitMiddleware)
+router.use('/api', corsMiddleware)
+```
+
+**Middleware Composition:**
+```typescript
+// Compose middleware for cleaner code
+const apiMiddleware = (req: Request) => {
+  // Run auth check
+  const authResult = authMiddleware(req)
+  if (authResult) {
+    return authResult
+  }
+
+  // Run rate limiting
+  const rateLimitResult = rateLimitMiddleware(req)
+  if (rateLimitResult) {
+    return rateLimitResult
+  }
+
+  // ... more middleware ...
+}
+
+// Apply middleware to the API route
+router.use('/api', apiMiddleware)
+```
+
 ## Built-in Middleware
 
 Deserve includes built-in middleware that can be applied using the `apply()` method:
@@ -215,10 +304,10 @@ router.static('/', {
 router.serve(8000)
 ```
 
-This serves files from the `public/` directory at the `/static` URL path:
-- `GET /static/index.html` → serves `public/index.html`
-- `GET /static/css/style.css` → serves `public/css/style.css`
-- `GET /static/js/app.js` → serves `public/js/app.js`
+This serves files from the `public/` directory at the root URL path:
+- `GET /index.html` → serves `public/index.html`
+- `GET /css/style.css` → serves `public/css/style.css`
+- `GET /js/app.js` → serves `public/js/app.js`
 
 **Note:** The `urlRoot` parameter is automatically set to strip the leading `/` from the URL path, so you don't need to specify it manually.
 
@@ -419,7 +508,30 @@ Start the HTTP server on the specified port (default: 8000).
 
 ##### `use(middleware: RouterMiddleware): void`
 
-Add middleware to the request pipeline.
+Add global middleware to the request pipeline.
+
+##### `use(routePath: string, middleware: RouterMiddleware): void`
+
+Add route-specific middleware to the request pipeline.
+
+**Parameters:**
+- `routePath` - Route path pattern to apply middleware to (e.g., `/api`, `/admin`)
+- `middleware` - Middleware function to execute for matching routes
+
+**Examples:**
+```typescript
+// Global middleware
+router.use((req: Request) => {
+  console.log('Global middleware')
+  return null
+})
+
+// Route-specific middleware
+router.use('/api', (req: Request) => {
+  console.log('API middleware')
+  return null
+})
+```
 
 ##### `onError(middleware: ErrorMiddleware): void`
 

src/Handler.ts

@@ -89,20 +89,23 @@ function findMatchingRoute(
 
 /**
  * Request handler factory function.
+ * @param errorMiddleware - Optional error middleware for custom error responses
  * @param middleware - Array of middleware functions
  * @param routeCache - Map of route paths to handler modules
  * @param routePattern - Map of URLPattern instances to route paths
+ * @param routeSpecific - Map of route paths to route-specific middleware arrays
  * @param routesExt - File extension for route files
- * @param errorMiddleware - Optional error middleware for custom error responses
+ * @param staticRoutes - Map of static file routes configuration
  * @returns Request handler function
  */
 export function handleRequest(
+  errorMiddleware: ErrorMiddleware | null | undefined,
   middleware: Array<RouterMiddleware>,
   routeCache: Map<string, Record<string, RouterHandler>>,
   routePattern: Map<URLPattern, string>,
+  routeSpecific: Map<string, Array<RouterMiddleware>> | undefined,
   routesExt: string,
-  errorMiddleware?: ErrorMiddleware | null,
-  staticRoutes?: Map<string, ServeDirOptions>
+  staticRoutes: Map<string, ServeDirOptions> | undefined
 ): (req: Request) => Promise<Response> {
   return async (req: Request): Promise<Response> => {
     if (staticRoutes) {
@@ -117,11 +120,24 @@ export function handleRequest(
         }
       }
     }
+    const url = new URL(req.url)
+    if (routeSpecific) {
+      const pathname = url.pathname
+      for (const [routePath, middlewares] of routeSpecific) {
+        if (pathname.startsWith(routePath)) {
+          for (const middleware of middlewares) {
+            const result = middleware(req)
+            if (result) {
+              return result
+            }
+          }
+        }
+      }
+    }
     const middlewareResponse = processMiddleware(middleware, req)
     if (middlewareResponse) {
       return middlewareResponse
     }
-    const url = new URL(req.url)
     const method = req.method
     const normalizedPath = normalizePath(url.pathname)
     const exactPath = getExactPath(normalizedPath, routesExt)

src/Router.ts

@@ -1,5 +1,6 @@
 import type { ServeDirOptions } from '@std/http/file-server'
 import type { ErrorMiddleware, RouterHandler, RouterMiddleware, RouterOptions } from '@app/Types.ts'
+import { pathToFileURL } from 'node:url'
 import { handleRequest } from '@app/Handler.ts'
 import { middlewares } from '@middlewares/index.ts'
 
@@ -14,6 +15,8 @@ export class Router {
   private middlewarePipeline: Array<RouterMiddleware> = []
   /** Static file routes configuration */
   private staticRoutes = new Map<string, ServeDirOptions>()
+  /** Route-specific middleware configuration */
+  private routeSpecific = new Map<string, Array<RouterMiddleware>>()
   /** Cache of loaded route modules */
   private routeCache = new Map<string, Record<string, RouterHandler>>()
   /** URLPattern to route path mapping */
@@ -101,8 +104,21 @@ export class Router {
    * Add global middleware to the pipeline.
    * @param middleware - Middleware function to execute before route handlers.
    */
-  use(middleware: RouterMiddleware): void {
-    this.middlewarePipeline.push(middleware)
+  use(middleware: RouterMiddleware): void
+  /**
+   * Add route-specific middleware to the pipeline.
+   * @param routePath - Route path pattern to apply middleware to
+   * @param middleware - Middleware function to execute for matching routes
+   */
+  use(routePath: string, middleware: RouterMiddleware): void
+  use(routePathOrMiddleware: string | RouterMiddleware, middleware?: RouterMiddleware): void {
+    if (typeof routePathOrMiddleware === 'string' && middleware) {
+      const existing = this.routeSpecific.get(routePathOrMiddleware) || []
+      existing.push(middleware)
+      this.routeSpecific.set(routePathOrMiddleware, existing)
+    } else if (typeof routePathOrMiddleware === 'function') {
+      this.middlewarePipeline.push(routePathOrMiddleware)
+    }
   }
 
   /**
@@ -111,11 +127,12 @@ export class Router {
    */
   private createHandler(): (req: Request) => Promise<Response> {
     return handleRequest(
+      this.errorMiddleware,
       this.middlewarePipeline,
       this.routeCache,
       this.routePattern,
+      this.routeSpecific,
       this.routesExt,
-      this.errorMiddleware,
       this.staticRoutes
     )
   }
@@ -146,18 +163,6 @@ export class Router {
     await this.scanRoutes(this.routesDir)
   }
 
-  /**
-   * Parse import path by removing HTTPS URLs.
-   * @param str - Import path string
-   * @returns Cleaned import path
-   */
-  private parseImport(str: string): string {
-    if (str.startsWith('https://')) {
-      return str.replace(/^https:\/\/[^\/]+/, 'file://')
-    }
-    return str
-  }
-
   /**
    * Recursively scan directory for route files.
    * @param dir - Directory to scan
@@ -172,9 +177,8 @@ export class Router {
         if (entry.isDirectory) {
           await this.scanRoutes(fullPath, routePath)
         } else if (entry.name.endsWith(this.routesExt)) {
-          const resolvedPath = import.meta.resolve(fullPath)
-          const cleanPath = this.parseImport(resolvedPath)
-          const module = await import(cleanPath)
+          const fileURL = pathToFileURL(fullPath).href
+          const module = await import(fileURL)
           this.routeCache.set(routePath, module)
           const urlPattern = this.createURLPattern(routePath)
           if (urlPattern) {