feat(request): add enhanced request handling with automatic parsing 🦋

- Add DeserveRequest class with query and parameter parsing methods
- Add detailed request handling documentation
- Reorder exports to prioritize Request functionality
- Update Handler to pass DeserveRequest instead of native Request
- Update navigation and README with new documentation links
- Update RouterHandler type to use DeserveRequest

Author: NeaByteLab

README.md

@@ -25,7 +25,8 @@ Follow our [installing guide](https://docs-deserve.neabyte.com/getting-started/i
 - **Core Concepts**
   - [File-based Routing](https://docs-deserve.neabyte.com/core-concepts/file-based-routing) - How file structure becomes API endpoints
   - [Route Patterns](https://docs-deserve.neabyte.com/core-concepts/route-patterns) - Dynamic routes and parameter matching
-  - [HTTP Methods](https://docs-deserve.neabyte.com/core-concepts/http-methods) - Supported HTTP methods
+  - [HTTP Methods](https://docs-deserve.neabyte.com/core-concepts/http-methods) - All supported HTTP methods
+  - [Request Handling](https://docs-deserve.neabyte.com/core-concepts/request-handling) - Enhanced request object with automatic parsing
 
 - **Middleware**
   - [Global Middleware](https://docs-deserve.neabyte.com/middleware/global) - Cross-cutting functionality
@@ -45,7 +46,7 @@ Follow our [installing guide](https://docs-deserve.neabyte.com/getting-started/i
   - [Multiple Directories](https://docs-deserve.neabyte.com/static-file/multiple) - Serve from multiple locations
 
 - **Error Handling**
-  - [Object Details](https://docs-deserve.neabyte.com/error-handling/object-details) - Comprehensive error information
+  - [Object Details](https://docs-deserve.neabyte.com/error-handling/object-details) - Detailed error information
 
 ## Contributing
 

docs/.vitepress/config.ts

@@ -24,7 +24,8 @@ export default defineConfig({
         items: [
           { text: 'File-based Routing', link: '/core-concepts/file-based-routing' },
           { text: 'Route Patterns', link: '/core-concepts/route-patterns' },
-          { text: 'HTTP Methods', link: '/core-concepts/http-methods' }
+          { text: 'HTTP Methods', link: '/core-concepts/http-methods' },
+          { text: 'Request Handling', link: '/core-concepts/request-handling' }
         ]
       },
       {

docs/core-concepts/request-handling.md

@@ -0,0 +1,147 @@
+# Request Handling
+
+> **Reference**: [Deno Request API Documentation](https://docs.deno.com/deploy/classic/api/runtime-request/)
+
+Deserve provides an enhanced `DeserveRequest` class that extends the native `Request` object with methods for accessing query and route parameters automatically.
+
+## Basic Usage
+
+Import `DeserveRequest` and use it in your route handlers:
+
+```typescript
+import { Send, DeserveRequest } from '@neabyte/deserve'
+
+// routes/users.ts
+export function GET(req: DeserveRequest): Response {
+  const query = req.query()
+  return Send.json({ query })
+}
+```
+
+## Query Parameters
+
+Access URL query parameters with automatic parsing:
+
+### Single Query Parameters
+```typescript
+// URL: /search?q=deno&limit=10
+export function GET(req: DeserveRequest): Response {
+  const query = req.query() // Expected: { q: 'deno', limit: '10' }
+  return Send.json({
+    search: query.q,
+    limit: parseInt(query.limit || '10')
+  })
+}
+```
+
+### Multiple Values for Same Key
+```typescript
+// URL: /search?tags=deno&tags=typescript&tags=javascript
+export function GET(req: DeserveRequest): Response {
+  const tags = req.queries('tags') // Expected: ['deno', 'typescript', 'javascript']
+  return Send.json({ tags })
+}
+```
+
+### Complete Query Object
+```typescript
+// URL: /api/users?page=1&limit=20&sort=name&order=asc
+export function GET(req: DeserveRequest): Response {
+  const query = req.query() // Expected: { page: '1', limit: '20', sort: 'name', order: 'asc' }
+  return Send.json({
+    page: parseInt(query.page || '1'),
+    limit: parseInt(query.limit || '10'),
+    sort: query.sort || 'id',
+    order: query.order || 'asc'
+  })
+}
+```
+
+## Route Parameters
+
+Access dynamic route parameters from file-based routing:
+
+### Single Parameter
+```typescript
+// routes/users/[id].ts
+// URL: /users/123
+export function GET(req: DeserveRequest): Response {
+  const id = req.param('id') // Expected: '123'
+  return Send.json({ userId: id })
+}
+```
+
+### Multiple Parameters
+```typescript
+// routes/users/[id]/posts/[postId].ts
+// URL: /users/123/posts/456
+export function GET(req: DeserveRequest): Response {
+  const id = req.param('id')
+  const postId = req.param('postId') // Expected: id='123', postId='456'
+  return Send.json({ userId: id, postId })
+}
+```
+
+### All Parameters
+```typescript
+// routes/api/v1/users/[userId]/posts/[postId]/comments/[commentId].ts
+// URL: /api/v1/users/123/posts/456/comments/789
+export function GET(req: DeserveRequest): Response {
+  const params = req.params() // Expected: { userId: '123', postId: '456', commentId: '789' }
+  return Send.json(params)
+}
+```
+
+## Method Reference
+
+### `req.query()`
+Returns all query parameters as an object.
+
+```typescript
+// URL: /search?q=deno&limit=10
+const query = req.query()
+// Expected: { q: 'deno', limit: '10' }
+```
+
+### `req.queries(key)`
+Returns all values for a specific query parameter key.
+
+```typescript
+// URL: /search?tags=deno&tags=typescript
+const tags = req.queries('tags')
+// Expected: ['deno', 'typescript']
+```
+
+### `req.param(key)`
+Returns a single route parameter value.
+
+```typescript
+// Route: /users/[id]
+// URL: /users/123
+const id = req.param('id')
+// Expected: '123'
+```
+
+### `req.params()`
+Returns all route parameters as an object.
+
+```typescript
+// Route: /users/[id]/posts/[postId]
+// URL: /users/123/posts/456
+const params = req.params()
+// Expected: { id: '123', postId: '456' }
+```
+
+## Best Practices
+
+1. **Validate parameters** - Check format and type before using
+2. **Provide defaults** - Use fallback values for optional parameters
+3. **Handle missing values** - Check for undefined/null values
+4. **Use appropriate types** - Convert strings to numbers when needed
+5. **Keep parameter names descriptive** - Use clear, meaningful names
+
+## Next Steps
+
+- [File-based Routing](/core-concepts/file-based-routing) - Understanding route structure
+- [Route Patterns](/core-concepts/route-patterns) - Dynamic parameter patterns
+- [HTTP Methods](/core-concepts/http-methods) - Supported request methods

src/Handler.ts

@@ -1,5 +1,6 @@
 import { serveDir, type ServeDirOptions } from '@std/http/file-server'
 import type { ErrorMiddleware, RouterHandler, RouterMiddleware } from '@app/Types.ts'
+import { DeserveRequest } from '@app/Request.ts'
 
 /**
  * Executes the appropriate handler method for the request.
@@ -19,7 +20,8 @@ async function executeHandler(
 ): Promise<Response> {
   if (module[method]) {
     try {
-      return await module[method](req, params)
+      const deserveReq = new DeserveRequest(req, params)
+      return await module[method](deserveReq, params)
     } catch (error) {
       if (errorMiddleware) {
         const customResponse = errorMiddleware(req, {

src/Request.ts

@@ -0,0 +1,58 @@
+/**
+ * Request class with automatic query parsing.
+ * @description Extends Request with convenient methods.
+ */
+export class DeserveRequest extends Request {
+  /** Route parameters extracted from URL pattern matching */
+  private urlParams: Record<string, string>
+
+  /**
+   * Create a new DeserveRequest instance.
+   * @param req - Native Request object
+   * @param params - Route parameters from URL pattern matching
+   */
+  constructor(req: Request, params: Record<string, string>) {
+    super(req)
+    this.urlParams = params
+  }
+
+  /**
+   * Get a single route parameter value.
+   * @param key - Route parameter key
+   * @returns Parameter value or empty string
+   */
+  param(key: string): string {
+    return this.urlParams[key] || ''
+  }
+
+  /**
+   * Get all route parameters as an object.
+   * @returns Object with route parameter key-value pairs
+   */
+  params(): Record<string, string> {
+    return this.urlParams
+  }
+
+  /**
+   * Get all query parameters as an object.
+   * @returns Object with query parameter key-value pairs
+   */
+  query(): Record<string, string> {
+    const url = new URL(this.url)
+    const result: Record<string, string> = {}
+    url.searchParams.forEach((value, key) => {
+      result[key] = value
+    })
+    return result
+  }
+
+  /**
+   * Get multiple values for the same query parameter key.
+   * @param key - Query parameter key
+   * @returns Array of values for the key
+   */
+  queries(key: string): string[] {
+    const url = new URL(this.url)
+    return url.searchParams.getAll(key)
+  }
+}

src/Types.ts

@@ -1,3 +1,5 @@
+import type { DeserveRequest } from '@app/Request.ts'
+
 /**
  * Error middleware function type.
  * @param req - HTTP request object
@@ -16,12 +18,12 @@ export type ErrorMiddleware = (
 
 /**
  * Route handler function type.
- * @param req - HTTP request object
+ * @param req - Enhanced request object with query parsing
  * @param params - Route parameters from URL
  * @returns HTTP response or promise
  */
 export type RouterHandler = (
-  req: Request,
+  req: DeserveRequest,
   params: Record<string, string>
 ) => Response | Promise<Response>
 

src/index.ts

@@ -1,15 +1,21 @@
 /**
- * Response utility for HTTP responses.
- * @description Provides static methods for responses.
+ * Enhanced Request class with automatic parsing.
+ * @description Extends native Request with convenient methods.
  */
-export * from '@app/Send.ts'
+export * from '@app/Request.ts'
 
 /**
  * Router class for file-based routing.
  * @description File-based routing with Deno serve API.
  */
 export * from '@app/Router.ts'
 
+/**
+ * Response utility for HTTP responses.
+ * @description Provides static methods for responses.
+ */
+export * from '@app/Send.ts'
+
 /**
  * Type definitions for router configuration and handlers.
  * @description TypeScript interfaces and types.