refactor(router): migrate to FastRouter with radix tree structure 🌳

- Add allowedExtensions constant for supported file extensions
- Add Request API delegation in DeserveRequest
- Add new utility modules for better code organization
- Convert Handler from functional to class-based architecture
- Enhance DeserveRequest with full Request API delegation
- Improve error handling with centralized error management
- Migrate from URLPattern to FastRouter for O(1) static route lookup
- Refactor Router to use Handler instance instead of direct functions
- Remove functional approach in favor of object-oriented design
- Remove URLPattern dependencies and route caching system
- Reorganize Handler class with improved request processing
- Simplify route pattern creation with string-based patterns
- Update documentation to reflect new routing system
- Update import paths configuration in deno.json
- Update middleware pipeline management with setter methods

Author: NeaByteLab

deno.json

@@ -88,6 +88,7 @@
   "imports": {
     "@app/": "./src/",
     "@middlewares/": "./src/middlewares/",
+    "@utils/": "./src/utils/",
     "@std/http": "jsr:@std/http@^1.0.21"
   },
   "publish": {

docs/core-concepts/file-based-routing.md

@@ -49,10 +49,10 @@ export function POST(req: Request): Response {
 
 ## Route Matching Priority
 
-Deserve uses URLPattern for efficient route matching with this priority:
+Deserve uses FastRouter with radix tree structure for efficient route matching with this priority:
 
-1. **Exact matches** - `users.ts` matches `/users`
-2. **Dynamic routes** - `users/[id].ts` matches `/users/123`
+1. **Static routes** - `users.ts` matches `/users` (O(1) lookup)
+2. **Dynamic routes** - `users/[id].ts` matches `/users/123` (O(k) tree traversal)
 3. **Longer paths** - More specific routes take precedence
 
 ## Examples
@@ -73,13 +73,17 @@ export function GET(req: Request): Response {
 ### Dynamic Routes
 ```typescript
 // routes/users/[id].ts
-export function GET(req: Request, params: Record<string, string>) {
+import { Send, DeserveRequest } from '@neabyte/deserve'
+
+export function GET(req: DeserveRequest, params: Record<string, string>) {
   const { id } = params
   return Send.json({ userId: id })
 }
 
 // routes/users/[id]/posts/[postId].ts
-export function GET(req: Request, params: Record<string, string>) {
+import { Send, DeserveRequest } from '@neabyte/deserve'
+
+export function GET(req: DeserveRequest, params: Record<string, string>) {
   const { id, postId } = params
   return Send.json({ userId: id, postId })
 }
@@ -96,3 +100,4 @@ export function GET(req: Request, params: Record<string, string>) {
 
 - [Route Patterns](/core-concepts/route-patterns) - Understanding pattern matching
 - [HTTP Methods](/core-concepts/http-methods) - Supported methods
+- [Request Handling](/core-concepts/request-handling) - Working with DeserveRequest

docs/core-concepts/http-methods.md

@@ -62,7 +62,9 @@ export async function POST(req: Request): Response {
 ### PUT - Update Resources
 ```typescript
 // routes/users/[id].ts
-export async function PUT(req: Request, params: Record<string, string>) {
+import { Send, DeserveRequest } from '@neabyte/deserve'
+
+export async function PUT(req: DeserveRequest, params: Record<string, string>) {
   const { id } = params
   const data = await req.json()
   // Update user with id...
@@ -73,7 +75,9 @@ export async function PUT(req: Request, params: Record<string, string>) {
 ### PATCH - Partial Updates
 ```typescript
 // routes/users/[id].ts
-export async function PATCH(req: Request, params: Record<string, string>) {
+import { Send, DeserveRequest } from '@neabyte/deserve'
+
+export async function PATCH(req: DeserveRequest, params: Record<string, string>) {
   const { id } = params
   const data = await req.json()
   // Partial update user with id...
@@ -84,7 +88,9 @@ export async function PATCH(req: Request, params: Record<string, string>) {
 ### DELETE - Remove Resources
 ```typescript
 // routes/users/[id].ts
-export function DELETE(req: Request, params: Record<string, string>) {
+import { Send, DeserveRequest } from '@neabyte/deserve'
+
+export function DELETE(req: DeserveRequest, params: Record<string, string>) {
   const { id } = params
   // Delete user with id...
   return Send.json({ message: 'User deleted', id })
@@ -160,3 +166,4 @@ router.onError((req, error) => {
 
 - [Route Patterns](/core-concepts/route-patterns) - Understanding pattern matching
 - [File-based Routing](/core-concepts/file-based-routing) - Core routing concepts
+- [Request Handling](/core-concepts/request-handling) - Working with DeserveRequest

docs/core-concepts/route-patterns.md

@@ -1,12 +1,10 @@
 # Route Patterns
 
-> **Reference**: [URLPattern API Documentation](https://docs.deno.com/api/web/~/URLPattern)
-
-Deserve uses `URLPattern` for efficient route matching with native pattern support.
+Deserve uses a **Simple Router** with radix tree structure algorithm.
 
 ## Pattern Matching
 
-Deserve converts file paths to `URLPattern` instances for route matching:
+Deserve converts file paths to route patterns using a radix tree implementation:
 
 ```
 .
@@ -23,7 +21,9 @@ Use `[param]` syntax for dynamic route segments:
 ### Single Parameter
 ```typescript
 // routes/users/[id].ts
-export function GET(req: Request, params: Record<string, string>) {
+import { Send, DeserveRequest } from '@neabyte/deserve'
+
+export function GET(req: DeserveRequest, params: Record<string, string>) {
   const { id } = params
   return Send.json({ userId: id })
 }
@@ -32,7 +32,9 @@ export function GET(req: Request, params: Record<string, string>) {
 ### Multiple Parameters
 ```typescript
 // routes/users/[id]/posts/[postId].ts
-export function GET(req: Request, params: Record<string, string>) {
+import { Send, DeserveRequest } from '@neabyte/deserve'
+
+export function GET(req: DeserveRequest, params: Record<string, string>) {
   const { id, postId } = params
   return Send.json({ userId: id, postId })
 }
@@ -41,7 +43,9 @@ export function GET(req: Request, params: Record<string, string>) {
 ### Nested Parameters
 ```typescript
 // routes/api/v1/users/[userId]/posts/[postId]/comments/[commentId].ts
-export function GET(req: Request, params: Record<string, string>) {
+import { Send, DeserveRequest } from '@neabyte/deserve'
+
+export function GET(req: DeserveRequest, params: Record<string, string>) {
   const { userId, postId, commentId } = params
   return Send.json({ userId, postId, commentId })
 }
@@ -52,32 +56,32 @@ export function GET(req: Request, params: Record<string, string>) {
 ### User Management
 ```
 routes/
-├── users.ts                       → /users
-├── users/[id].ts                  → /users/:id
-├── users/[id]/profile.ts          → /users/:id/profile
-├── users/[id]/posts.ts            → /users/:id/posts
-└── users/[id]/posts/[postId].ts   → /users/:id/posts/:postId
+├── users.ts                         → /users
+├── users/[id].ts                    → /users/:id
+├── users/[id]/profile.ts            → /users/:id/profile
+├── users/[id]/posts.ts              → /users/:id/posts
+└── users/[id]/posts/[postId].ts     → /users/:id/posts/:postId
 ```
 
 ### API Versioning
 ```
 routes/
 ├── api/
 │   ├── v1/
-│   │   └── users/[id].ts       → /api/v1/users/:id
+│   │   └── users/[id].ts            → /api/v1/users/:id
 │   └── v2/
-│       └── users/[id].ts       → /api/v2/users/:id
+│       └── users/[id].ts            → /api/v2/users/:id
 ```
 
 ### Blog System
 ```
 routes/
 ├── blog/
-│   ├── [slug].ts               → /blog/:slug
+│   ├── [slug].ts                    → /blog/:slug
 │   └── [year]/
 │       └── [month]/
 │           └── [day]/
-│               └── [slug].ts   → /blog/:year/:month/:day/:slug
+│               └── [slug].ts        → /blog/:year/:month/:day/:slug
 ```
 
 ## Route Matching Priority
@@ -103,7 +107,9 @@ Extract and validate parameters in your route handlers:
 
 ```typescript
 // routes/users/[id].ts
-export function GET(req: Request, params: Record<string, string>) {
+import { Send, DeserveRequest } from '@neabyte/deserve'
+
+export function GET(req: DeserveRequest, params: Record<string, string>) {
   const { id } = params
   // Validate parameter
   if (!id || !/^\d+$/.test(id)) {
@@ -118,7 +124,9 @@ export function GET(req: Request, params: Record<string, string>) {
 ### Optional Parameters
 ```typescript
 // routes/posts/[slug].ts
-export function GET(req: Request, params: Record<string, string>) {
+import { Send, DeserveRequest } from '@neabyte/deserve'
+
+export function GET(req: DeserveRequest, params: Record<string, string>) {
   const { slug } = params
   // Handle post by slug
   return Send.json({ slug })
@@ -128,26 +136,58 @@ export function GET(req: Request, params: Record<string, string>) {
 ### Multiple Segments
 ```typescript
 // routes/categories/[category]/products/[product].ts
-export function GET(req: Request, params: Record<string, string>) {
+import { Send, DeserveRequest } from '@neabyte/deserve'
+
+export function GET(req: DeserveRequest, params: Record<string, string>) {
   const { category, product } = params
   return Send.json({ category, product })
 }
 ```
 
+## Performance Benefits
+
+### Static Route Optimization
+Static routes (no parameters) are cached for O(1) lookup:
+```typescript
+// These routes are optimized for instant matching
+routes/index.ts                  → / (cached)
+routes/about.ts                  → /about (cached)
+routes/users.ts                  → /users (cached)
+```
+
+### Dynamic Route Matching
+Dynamic routes use radix tree traversal for efficient matching:
+```typescript
+// These routes use tree traversal
+routes/users/[id].ts             → /users/:id
+routes/users/[id]/posts.ts       → /users/:id/posts
+routes/api/v1/[version].ts       → /api/v1/:version
+```
+
 ## Pattern Limitations
 
 ### Invalid Patterns
 ```
-❌ routes/users/[...id].ts      // Rest parameters not supported
-❌ routes/users/(group).ts      // Groups not supported
-❌ routes/users/:id.ts          // Colon syntax not supported
+❌ routes/users/[...id].ts       // Rest parameters not supported
+❌ routes/users/(group).ts       // Groups not supported
+❌ routes/users/:id.ts           // Colon syntax not supported
+❌ routes/users/*.ts             // Wildcard without brackets
+❌ routes/users/**.ts            // Double wildcard without brackets
+```
+
+### Supported Patterns
+```
+✅ routes/users/[id].ts          // Single parameter
+✅ routes/users/[id]/posts.ts    // Nested parameters
+✅ routes/api/v1/[version].ts    // API versioning
+✅ routes/posts/[slug].ts        // Slug-based routing
 ```
 
 ### Valid Patterns
 ```
-✅ routes/users/[id].ts         // Single parameter
-✅ routes/users/[id]/posts.ts   // Nested parameters
-✅ routes/api/v1/users.ts       // Static segments
+✅ routes/users/[id].ts          // Single parameter
+✅ routes/users/[id]/posts.ts    // Nested parameters
+✅ routes/api/v1/users.ts        // Static segments
 ```
 
 ## Best Practices
@@ -179,3 +219,4 @@ router.onError((req, error) => {
 
 - [HTTP Methods](/core-concepts/http-methods) - Supported methods
 - [File-based Routing](/core-concepts/file-based-routing) - Core routing concepts
+- [Request Handling](/core-concepts/request-handling) - Working with DeserveRequest

docs/getting-started/installation.md

@@ -22,4 +22,6 @@ This will:
 
 Now that Deserve is installed, let's create your first server!
 
-[Quick Start →](/getting-started/quick-start)
+- [Quick Start](/getting-started/quick-start) - Create your first API
+- [Server Configuration](/getting-started/server-configuration) - Configure your server
+- [Custom Configuration](/getting-started/custom-configuration) - Advanced router options

docs/getting-started/quick-start.md

@@ -96,10 +96,10 @@ Create `routes/users/[id].ts`:
 
 ```typescript
 // routes/users/[id].ts
-import { Send } from '@neabyte/deserve'
+import { Send, DeserveRequest } from '@neabyte/deserve'
 
 // GET /users/:id -> Returns a JSON response with the user id and name
-export function GET(req: Request, params: Record<string, string>) {
+export function GET(req: DeserveRequest, params: Record<string, string>) {
   const { id } = params
   return Send.json({ userId: id, name: `User ${id}` })
 }
@@ -110,6 +110,34 @@ Test it:
 curl http://localhost:8000/users/123
 ```
 
+## Request Types
+
+Deserve provides two request types:
+
+- **`Request`**: Use for static routes without parameters
+- **`DeserveRequest`**: Use for dynamic routes with parameters (like `[id].ts`)
+
+### Static Routes (use `Request`)
+```typescript
+// routes/index.ts
+export function GET(req: Request): Response {
+  return Send.json({ message: 'Hello!' })
+}
+```
+
+### Dynamic Routes (use `DeserveRequest`)
+```typescript
+// routes/users/[id].ts
+import { DeserveRequest } from '@neabyte/deserve'
+
+// GET /users/:id -> Returns a JSON response with the user id and query parameters
+export function GET(req: DeserveRequest, params: Record<string, string>) {
+  const userId = req.param('id')  // Access route parameter
+  const query = req.query()       // Access query parameters
+  return Send.json({ userId, query })
+}
+```
+
 ## What's Next?
 
 You now have a working API! Explore more features:

docs/response/file.md

@@ -50,7 +50,9 @@ export async function GET(req: Request): Response {
 
 ```typescript
 // routes/downloads/[filename].ts
-export async function GET(req: Request, params: Record<string, string>): Response {
+import { Send, DeserveRequest } from '@neabyte/deserve'
+
+export async function GET(req: DeserveRequest, params: Record<string, string>): Response {
   const { filename } = params
   // Validate filename to prevent directory traversal
   if (filename.includes('..') || filename.includes('/')) {
@@ -141,7 +143,9 @@ export async function GET(req: Request): Response {
 ## Example Security Implementation
 
 ```typescript
-export async function GET(req: Request, params: Record<string, string>): Response {
+import { Send, DeserveRequest } from '@neabyte/deserve'
+
+export async function GET(req: DeserveRequest, params: Record<string, string>): Response {
   const { filename } = params
   // Security checks
   if (!filename || filename.includes('..') || filename.includes('/')) {

docs/response/html.md

@@ -52,7 +52,9 @@ export function GET(req: Request): Response {
 ## Dynamic Content
 
 ```typescript
-export function GET(req: Request, params: Record<string, string>) {
+import { Send, DeserveRequest } from '@neabyte/deserve'
+
+export function GET(req: DeserveRequest, params: Record<string, string>) {
   const { id } = params
   const html = `
 <!DOCTYPE html>

src/Constant.ts

@@ -1,3 +1,8 @@
+/**
+ * Supported file extensions for route files.
+ */
+export const allowedExtensions = ['.cjs', '.js', '.jsx', '.mjs', '.ts', '.tsx']
+
 /**
  * Standard HTTP methods supported.
  */