exisjs 0.7.12 → 0.7.14

package/dist/docs/content/routing.mdx

@@ -1,753 +1,390 @@
 ---
-nextUrl: "/docs/controllers"
-nextTitle: "Controllers"
+title: 'Routing & Endpoints'
+description: 'File-system routing conventions, HTTP methods, dynamic route segments, catch-all parameters, and route options.'
+nextUrl: '/docs/controllers'
+nextTitle: 'Controllers'
 ---
 
-# Routing
+# Routing & Endpoints
 
-Routes are responsible for handling incoming requests and sending responses back to the client. The routing mechanism determines which handler will process each request.
+ExisJS uses file-system routing to map directory structures directly to HTTP endpoints. Dropping a `route.ts` or `<name>.route.ts` file inside a directory registers endpoints automatically with the native routing engine.
 
-<Info title="Functional vs OOP">
-ExisJS natively supports both a **Functional Paradigm** and a **Class-Based OOP Paradigm** (for dependency injection and decorators). You can mix and match them throughout your application.
-</Info>
-
-## Folder-Based Routing
-
-ExisJS uses **folder-based file-system routing** instead of programmatic route declaration in a single entry file.
-
-For a folder to become an accessible API endpoint, it must contain a `route.ts` or `<feature>.route.ts` (e.g. `user.route.ts`) file that exports a route definition. 
-
-In addition to `route.ts`, the ExisJS router utilizes two other special gatekeeper files:
-- **`server.ts`**: Placed at the root of your `http` directory, it is the entry point that boots your application, registers global plugins, and connects to databases.
-- **`boundary.ts`** (or `*.boundary.ts`): Can be placed in any folder. It acts as a gatekeeper and request pipeline, automatically configuring middleware, CORS, headers, and dependencies for *all* routes within its directory and subdirectories.
-
-### Routing Conventions
-
-The ExisJS file-system router natively supports advanced folder naming conventions to handle dynamic segments and logical grouping:
-
-- **Dynamic Parameters (`[param]`)**: A folder named `[id]` creates a dynamic route segment (e.g., `/:id`). The value is accessible in your handler via `ctx.params.id`.
-- **Catch-all Routes (`[...param]`)**: A folder named `[...slug]` catches all subsequent URL segments, matching anything that follows (e.g., `/*slug`).
-- **Route Groups (`(group)`)**: A folder wrapped in parentheses (e.g., `(admin)`) is ignored in the final URL path. This is useful for grouping related routes or applying shared controller-level middleware without adding `/admin` to the URL.
-
-### The Application Entry Point (`server.ts`)
-
-The `server.ts` file acts as the root configuration for your application. It provides lifecycle hooks to boot databases, register global plugins, and provide root-level dependencies.
-
-#### Functional Paradigm
-```typescript filename="src/http/server.ts"
-import { exis } from 'exisjs'
-
-export default exis({
-  providers: [
-    ['LoggerService', { useValue: console }]
-  ]
-})
-```
-
-#### Class-Based (OOP) Paradigm
-```typescript filename="src/http/server.ts"
-import { Server } from 'exisjs/decorators'
-import type { App } from 'exisjs'
-
-@Server({
-  providers: [['LoggerService', { useValue: console }]]
-})
-export default class RootServer {
-  async onStart(app: App) {
-    // Boot your database here!
-  }
-}
-```
-
-### Folder Boundaries (`boundary.ts`)
-
-Boundaries apply configurations, security policies, and request pipelines to all routes in their directory and subdirectories.
-
-#### Functional Paradigm
-```typescript filename="src/http/admin/boundary.ts"
-import { defineBoundary } from 'exisjs/router'
-
-export const config = defineBoundary({
-  headers: { 'X-Admin-Area': 'true' }
-})
-```
-
-#### Class-Based (OOP) Paradigm
-```typescript filename="src/http/admin/boundary.ts"
-import { Boundary } from 'exisjs/decorators'
-
-@Boundary({
-  headers: { 'X-Admin-Area': 'true' }
-})
-export default class AdminBoundary {}
-```
-
-### Route Definitions (`route.ts`)
-
-For example, to create a simple `/health` endpoint, you create the folder `src/http/health/` and place a `route.ts` file inside it:
-
-#### Functional Paradigm
-
-
-```typescript filename="src/http/health/route.ts"
-import { controller, route } from 'exisjs/router'
+---
 
-export default controller({
-  check: route.get('/', {
-    handle() {
-      return { status: 'ok', timestamp: new Date().toISOString() }
-    }
-  })
-})
-```
+## Routing Principles
 
-  
-#### Class-Based (OOP) Paradigm
+1. **Folder-Based URL Mapping**: The folder structure relative to `src/http/` determines the base URL path.
+2. **Dual-Paradigm Support**: Routes can be authored using either the **Functional Paradigm** (`controller()`, `route.*`) or the **Class-Based (OOP) Paradigm** (`@Controller()`, `@Get()`, `@Post()`). Choose one paradigm per project.
+3. **Automatic Parameter Inference**: Dynamic URL segments defined in path strings (such as `/:id` or `/:postId`) or folder names (`[id]`) automatically populate typed route parameters in handler contexts.
 
+---
 
-```typescript filename="src/http/health/route.ts"
-import { Controller, Get } from 'exisjs/decorators'
+## File-System Route Conventions
 
-@Controller()
-export default class HealthController {
-  @Get('/')
-  check() {
-    return { status: 'ok', timestamp: new Date().toISOString() }
-  }
-}
-```
+| Directory Path | URL Endpoint | Description |
+| :--- | :--- | :--- |
+| `src/http/route.ts` | `/` | Root application endpoint |
+| `src/http/health/route.ts` | `/health` | Static route endpoint |
+| `src/http/users/route.ts` | `/users` | Collection endpoint |
+| `src/http/users/[id]/route.ts` | `/users/:id` | Dynamic parameter route |
+| `src/http/docs/[...slug]/route.ts` | `/docs/*slug` | Catch-all wildcard route |
+| `src/http/(admin)/dashboard/route.ts` | `/dashboard` | Route group (parentheses are omitted from the URL path) |
 
-  
+---
 
-## Supported Methods
+## Route Definitions
 
-ExisJS natively exposes standard HTTP methods alongside advanced routing paradigms like WebSockets and Server-Sent Events. Choose your paradigm below to see the available methods.
+### Basic Route Handlers
 
 #### Functional Paradigm
 
-    <div className="overflow-x-auto mb-6">
-      <table className="w-full text-sm text-left border border-border/50 rounded-lg overflow-hidden">
-        <thead className="bg-muted/50 text-foreground">
-          <tr>
-            <th className="px-4 py-3 border-b border-border/50 font-semibold w-1/3">Method</th>
-            <th className="px-4 py-3 border-b border-border/50 font-semibold">Description</th>
-          </tr>
-        </thead>
-        <tbody className="divide-y divide-border/50">
-          <tr className="bg-background hover:bg-muted/30 transition-colors">
-            <td className="px-4 py-3 font-mono text-xs"><span className="text-primary">route.</span>get() / post() / put()</td>
-            <td className="px-4 py-3 text-muted-foreground">Standard HTTP methods. Also includes patch, delete, options, head, connect, and trace.</td>
-          </tr>
-          <tr className="bg-background hover:bg-muted/30 transition-colors">
-            <td className="px-4 py-3 font-mono text-xs"><span className="text-primary">route.</span>all()</td>
-            <td className="px-4 py-3 text-muted-foreground">Matches any HTTP request method for the given path.</td>
-          </tr>
-          <tr className="bg-background hover:bg-muted/30 transition-colors">
-            <td className="px-4 py-3 font-mono text-xs"><span className="text-primary">route.</span>query()</td>
-            <td className="px-4 py-3 text-muted-foreground">The new experimental HTTP QUERY method, solving complex idempotent fetches.</td>
-          </tr>
-          <tr className="bg-background hover:bg-muted/30 transition-colors">
-            <td className="px-4 py-3 font-mono text-xs"><span className="text-primary">route.</span>ws()</td>
-            <td className="px-4 py-3 text-muted-foreground">Exposes a native WebSocket endpoint with automatic pub/sub support.</td>
-          </tr>
-          <tr className="bg-background hover:bg-muted/30 transition-colors">
-            <td className="px-4 py-3 font-mono text-xs"><span className="text-primary">route.</span>sse()</td>
-            <td className="px-4 py-3 text-muted-foreground">Exposes a Server-Sent Events stream for one-way realtime data.</td>
-          </tr>
-        </tbody>
-      </table>
-    </div>
-
 ```typescript filename="src/http/users/route.ts"
 import { controller, route } from 'exisjs/router'
 
 export default controller({
-  list: route.get('/', {
-    handle() {
-      // Fetch all users from database
+  // GET /users
+  listUsers: route.get('/', {
+    summary: 'List users',
+    handle: async () => {
       return [
-        { id: 1, name: 'Alice' },
-        { id: 2, name: 'Bob' }
+        { id: '1', name: 'Alice' },
+        { id: '2', name: 'Bob' },
       ]
-    }
+    },
   }),
-  create: route.post('/', {
-    handle({ req }) {
-      // Create a new user with parsed payload
-      const payload = req.body
-      return { id: 3, ...payload }
-    }
+
+  // POST /users
+  createUser: route.post('/', {
+    summary: 'Create user',
+    handle: async ({ body }) => {
+      return { id: '3', ...body }
+    },
   }),
-  preflight: route.options('/', {
-    handle({ res }) {
-      // Handle custom preflight logic if `preflightContinue: true` is configured in CORS
-      res.header('X-Custom-Options', 'true')
-      return { allowed: true }
-    }
-  })
 })
 ```
-  
-#### Class-Based (OOP) Paradigm
 
-    <div className="overflow-x-auto mb-6">
-      <table className="w-full text-sm text-left border border-border/50 rounded-lg overflow-hidden">
-        <thead className="bg-muted/50 text-foreground">
-          <tr>
-            <th className="px-4 py-3 border-b border-border/50 font-semibold w-1/3">Decorator</th>
-            <th className="px-4 py-3 border-b border-border/50 font-semibold">Description</th>
-          </tr>
-        </thead>
-        <tbody className="divide-y divide-border/50">
-          <tr className="bg-background hover:bg-muted/30 transition-colors">
-            <td className="px-4 py-3 font-mono text-xs"><span className="text-primary">@</span>Get() / <span className="text-primary">@</span>Post() / <span className="text-primary">@</span>Put()</td>
-            <td className="px-4 py-3 text-muted-foreground">Standard HTTP methods. Also includes @Patch, @Delete, @Options, @Head, @Connect, and @Trace.</td>
-          </tr>
-          <tr className="bg-background hover:bg-muted/30 transition-colors">
-            <td className="px-4 py-3 font-mono text-xs"><span className="text-primary">@</span>All()</td>
-            <td className="px-4 py-3 text-muted-foreground">Matches any HTTP request method for the given path.</td>
-          </tr>
-          <tr className="bg-background hover:bg-muted/30 transition-colors">
-            <td className="px-4 py-3 font-mono text-xs"><span className="text-primary">@</span>Query()</td>
-            <td className="px-4 py-3 text-muted-foreground">The new experimental HTTP QUERY method, solving complex idempotent fetches.</td>
-          </tr>
-          <tr className="bg-background hover:bg-muted/30 transition-colors">
-            <td className="px-4 py-3 font-mono text-xs"><span className="text-primary">@</span>Ws()</td>
-            <td className="px-4 py-3 text-muted-foreground">Exposes a native WebSocket endpoint with automatic pub/sub support.</td>
-          </tr>
-          <tr className="bg-background hover:bg-muted/30 transition-colors">
-            <td className="px-4 py-3 font-mono text-xs"><span className="text-primary">@</span>Sse()</td>
-            <td className="px-4 py-3 text-muted-foreground">Exposes a Server-Sent Events stream for one-way realtime data.</td>
-          </tr>
-        </tbody>
-      </table>
-    </div>
+#### Class-Based (OOP) Paradigm
 
 ```typescript filename="src/http/users/route.ts"
-import { Controller, Get, Post, Body } from 'exisjs/decorators'
+import { Controller, Get, Post, Body, ApiOperation } from 'exisjs/decorators'
 
 @Controller()
 export default class UsersController {
   @Get('/')
-  list() {
-    // Fetch all users from database
+  @ApiOperation({ summary: 'List users' })
+  async listUsers() {
     return [
-      { id: 1, name: 'Alice' },
-      { id: 2, name: 'Bob' }
+      { id: '1', name: 'Alice' },
+      { id: '2', name: 'Bob' },
     ]
   }
 
   @Post('/')
-  create(@Body() data: any) {
-    // Create a new user with parsed payload
-    return { id: 3, ...data }
+  @ApiOperation({ summary: 'Create user' })
+  async createUser(@Body() body: Record<string, any>) {
+    return { id: '3', ...body }
   }
 }
 ```
-  
-
-## Sub-Paths in a Single File
 
-While folder-based routing is standard, you can also define multiple sub-paths in a single `route.ts` file to group related endpoints.
-
-#### Functional Paradigm
-
-
-```typescript filename="src/http/users/route.ts"
-import { controller, route } from 'exisjs/router'
-
-export default controller({
-  list: route.get('/', {
-    handle() {
-      return { message: 'Fetching all users' }
-    }
-  }),
-  getSingle: route.get('/:id', {
-    handle({ params }) {
-      // params.id is automatically inferred as string with full autocomplete!
-      const { id } = params
-      return { message: `Fetching user ${id}` }
-    }
-  })
-})
-```
-
-<Info title="Automatic Route Parameter Type Inference">
-In ExisJS v0.7+, paths with named parameters like `route.get('/users/:userId/posts/:postId', ...)` automatically parse the path string literal to infer `params: { userId: string; postId: string }` on the `handle` context. No manual casting or boilerplate interfaces required.
-</Info>
-
-  
-#### Class-Based (OOP) Paradigm
+---
 
+## Supported HTTP Methods
 
-```typescript filename="src/http/users/route.ts"
-import { Controller, Get, Param } from 'exisjs/decorators'
+ExisJS supports all standard HTTP methods across both paradigms:
 
-@Controller()
-export default class UsersController {
-  @Get('/')
-  list() {
-    return { message: 'Fetching all users' }
-  }
+| HTTP Verb | Functional Method | OOP Decorator | Description |
+| :--- | :--- | :--- | :--- |
+| `GET` | `route.get(path, config)` | `@Get(path, schema)` | Retrieve resources |
+| `POST` | `route.post(path, config)` | `@Post(path, schema)` | Create resources or trigger actions |
+| `PUT` | `route.put(path, config)` | `@Put(path, schema)` | Replace existing resources |
+| `PATCH` | `route.patch(path, config)` | `@Patch(path, schema)` | Apply partial updates |
+| `DELETE` | `route.delete(path, config)` | `@Delete(path, schema)` | Remove resources |
+| `OPTIONS` | `route.options(path, config)` | `@Options(path, schema)` | Describe communication options / preflight |
+| `HEAD` | `route.head(path, config)` | `@Head(path, schema)` | Retrieve headers identical to a GET request |
+| `CONNECT` | `route.connect(path, config)` | `@Connect(path, schema)` | Establish a two-way tunnel |
+| `TRACE` | `route.trace(path, config)` | `@Trace(path, schema)` | Loop-back testing along network path |
+| `QUERY` | `route.query(path, config)` | `@Query(path, schema)` | Safe query method with request payload (RFC 9535) |
+| `ALL` | `route.all(path, config)` | `@All(path, schema)` | Matches any HTTP method for the given path |
 
-  @Get('/:id')
-  getSingle(@Param('id') id: string) {
-    return { message: \`Fetching user \${id}\` }
-  }
-}
-```
+---
 
-  
+## Dynamic Route Parameters
 
-## Route Parameters (Dynamic Routing)
+### Folder-Based Parameters (`[param]`)
 
-Routes with static paths won’t work when you need to accept dynamic data as part of the request (e.g., `GET /users/123`). To create dynamic routes using folders, enclose the folder name in brackets `[]`.
+Creating a folder named `[id]` creates a parameterized route segment.
 
 #### Functional Paradigm
 
-
 ```typescript filename="src/http/users/[id]/route.ts"
-// Location: src/http/users/[id]/route.ts
 import { controller, route } from 'exisjs/router'
+import { tex } from 'exisjs/validator'
+
+const UserParamsSchema = tex.object({
+  id: tex.string({ min: 1 }),
+})
 
 export default controller({
-  getSingle: route.get('/', {
-    handle({ params }) {
-      const { id } = params
-      return { message: \`Fetching user \${id}\` }
-    }
-  })
+  getUser: route.get('/', {
+    params: UserParamsSchema,
+    handle: async ({ params }) => {
+      return { id: params.id, name: 'Alice' }
+    },
+  }),
 })
 ```
 
-  
 #### Class-Based (OOP) Paradigm
 
-
 ```typescript filename="src/http/users/[id]/route.ts"
-// Location: src/http/users/[id]/route.ts
-import { Controller, Get, Param } from 'exisjs/decorators'
+import { Controller, Get, Param, ApiOperation } from 'exisjs/decorators'
+import { tex } from 'exisjs/validator'
+
+const UserParamsSchema = tex.object({
+  id: tex.string({ min: 1 }),
+})
 
 @Controller()
 export default class SingleUserController {
-  @Get('/')
-  getSingle(@Param('id') id: string) {
-    return { message: \`Fetching user \${id}\` }
+  @Get('/', { params: UserParamsSchema })
+  @ApiOperation({ summary: 'Get user by ID' })
+  async getUser(@Param('id') id: string) {
+    return { id, name: 'Alice' }
   }
 }
 ```
 
-  
-
-## Request & Response Objects
-
-Handlers often need access to the client’s request details, or fine-grained control over the response headers and status codes. Every route handler natively receives powerful `req` and `res` objects.
+---
 
-#### Functional Paradigm
+### In-File Sub-Paths
 
+You can also define multiple sub-paths with route parameters inside a single `route.ts` file:
 
-```typescript filename="src/http/profile/route.ts"
+```typescript filename="src/http/users/route.ts"
 import { controller, route } from 'exisjs/router'
+import { tex } from 'exisjs/validator'
 
 export default controller({
-  profile: route.get('/profile', {
-    handle({ req, res }) {
-      // Read Request details
-      const ip = req.ip
-      const headers = req.headers
-
-      // Chain Response methods
-      res
-        .status(202)
-        .cookie('session', 'xyz123', { httpOnly: true, secure: true })
-        .header('X-Custom-Header', 'Exis')
-        .json({ message: 'Accepted' })
-    }
-  })
-})
-```
-
-  
-#### Class-Based (OOP) Paradigm
-
+  // GET /users
+  list: route.get('/', {
+    handle: async () => [{ id: '1', name: 'Alice' }],
+  }),
 
-```typescript filename="src/http/profile/route.ts"
-import { Controller, Get, Req, Res } from 'exisjs/decorators'
-import type { Request, Response } from 'exisjs/router'
+  // GET /users/:id
+  getById: route.get('/:id', {
+    params: tex.object({ id: tex.string() }),
+    handle: async ({ params }) => ({ id: params.id, name: 'Alice' }),
+  }),
 
-@Controller()
-export default class ProfileController {
-  @Get('/profile')
-  profile(@Req() req: Request, @Res() res: Response) {
-    // Read Request details
-    const ip = req.ip
-    const headers = req.headers
-
-    // Chain Response methods
-    res
-      .status(202)
-      .cookie('session', 'xyz123', { httpOnly: true, secure: true })
-      .header('X-Custom-Header', 'Exis')
-      .json({ message: 'Accepted' })
-  }
-}
+  // GET /users/:id/posts/:postId
+  getUserPost: route.get('/:id/posts/:postId', {
+    params: tex.object({
+      id: tex.string(),
+      postId: tex.string(),
+    }),
+    handle: async ({ params }) => {
+      return { userId: params.id, postId: params.postId, title: 'Hello ExisJS' }
+    },
+  }),
+})
 ```
 
-  
-
-<Info title="Default Responses">
-When a request handler returns a JavaScript object or array, it is automatically serialized to JSON and sent with a default `200 OK` status code. You only need to use the `res` object when you want to explicitly modify headers, cookies, or status codes!
-</Info>
-
-## Payloads & Query Parameters
-
-You can easily extract query strings from the URL or parsed JSON bodies from POST requests directly through the `req` object (or via decorators in OOP).
+---
 
-#### Functional Paradigm
+## Catch-All Routes (`[...slug]`)
 
+Folders named `[...slug]` match all subsequent nested URL paths.
 
-```typescript filename="src/http/search/route.ts"
+```typescript filename="src/http/docs/[...slug]/route.ts"
 import { controller, route } from 'exisjs/router'
 
 export default controller({
-  search: route.get('/search', {
-    handle({ req }) {
-      // e.g., GET /search?q=exis&limit=10
-      const { q, limit } = req.query
-      return { query: q, limit }
-    }
+  renderDoc: route.get('/', {
+    handle: async ({ params }) => {
+      // For a request to /docs/getting-started/installation
+      // params.slug contains "getting-started/installation"
+      return { slug: params.slug }
+    },
   }),
-  create: route.post('/create', {
-    handle({ req }) {
-      // Access parsed JSON body natively
-      const data = req.body
-      return { received: data }
-    }
-  })
 })
 ```
 
-  
-#### Class-Based (OOP) Paradigm
+---
 
+## Route Groups (`(group)`)
 
-```typescript filename="src/http/search/route.ts"
-import { Controller, Get, Post, Query, Body } from 'exisjs/decorators'
+Parenthesized directory names group routes logically without appending the folder name to the URL path:
 
-@Controller()
-export default class SearchController {
-  @Get('/search')
-  search(@Query('q') q: string, @Query('limit') limit: number) {
-    // e.g., GET /search?q=exis&limit=10
-    return { query: q, limit }
-  }
-
-  @Post('/create')
-  create(@Body() data: any) {
-    // Access parsed JSON body natively
-    return { received: data }
-  }
-}
+```
+src/http/
+├── (auth)/
+│   ├── login/
+│   │   └── route.ts         # Maps to /login (not /auth/login)
+│   └── register/
+│       └── route.ts         # Maps to /register (not /auth/register)
+└── (marketing)/
+    └── pricing/
+        └── route.ts         # Maps to /pricing (not /marketing/pricing)
 ```
 
-  
-
-## Declarative Route Options (Uploads, Timeouts & Validation)
-
-ExisJS allows configuring input validation schemas, multipart file uploads, and per-route timeouts directly inside the route definition without manual middleware plumbing.
-
-### Declarative File Uploads
+---
 
-Specify `upload` in your route definition to automatically handle `multipart/form-data`. Uploaded files are parsed and attached to `req.file` or `req.files`, while non-file form fields are populated in `req.body`.
+## Handler Execution Context (`SuperContext`)
 
-#### Functional Paradigm
-```typescript filename="src/http/avatar/route.ts"
-import { controller, route } from 'exisjs/router'
-import { tex } from 'exisjs/validator'
+In the functional paradigm, `handle` receives a single context object containing all request properties and utilities:
 
+```typescript
 export default controller({
-  uploadAvatar: route.post('/', {
-    upload: {
-      field: 'avatar',
-      maxBytes: 5 * 1024 * 1024, // 5MB limit
-      mimeTypes: ['image/png', 'image/jpeg', 'image/webp'],
+  endpoint: route.post('/example', {
+    handle: async (ctx) => {
+      const { body, query, params, headers, req, res, app, resolve, file } = ctx
+      // ...
     },
-    body: tex.object({
-      caption: tex.string({ optional: true }),
-    }),
-    handle({ req }) {
-      const file = req.file! // UploadedFile { filename, buffer, size, mimetype }
-      const caption = req.body?.caption
-      
-      return {
-        success: true,
-        filename: file.filename,
-        size: file.size,
-        caption,
-      }
-    }
-  })
+  }),
 })
 ```
 
-#### Class-Based (OOP) Paradigm
-```typescript filename="src/http/avatar/route.ts"
-import { Controller, Post, Body } from 'exisjs/decorators'
-import { Upload, UploadedFile } from 'exisjs/decorators'
-import type { UploadedFile as UploadedFileType } from 'exisjs/middleware'
+### Context Properties
+
+| Property | Type | Description |
+| :--- | :--- | :--- |
+| `ctx.body` | `TBody` | Parsed and validated request body payload |
+| `ctx.query` | `TQuery` | Parsed and validated URL query parameters |
+| `ctx.params` | `TParams` | Extracted route parameters |
+| `ctx.headers` | `Record<string, string>` | Request headers map |
+| `ctx.req` | `Request` | The underlying `ExisRequest` instance |
+| `ctx.res` | `Response` | The underlying `ExisResponse` instance |
+| `ctx.resolve` | `(token) => T` | Resolves a dependency from the IoC container |
+| `ctx.file` | `ExisFile` | Uploaded file instance (when multipart upload is enabled) |
+| `ctx.files` | `ExisFile[]` | Uploaded files array (for multiple file uploads) |
+| `ctx.state` | `Record<string, any>` | Request-scoped custom state |
 
-@Controller('/avatar')
-export default class AvatarController {
-  @Post('/')
-  @Upload('avatar', {
-    maxBytes: 5 * 1024 * 1024,
-    mimeTypes: ['image/png', 'image/jpeg', 'image/webp'],
-  })
-  upload(
-    @UploadedFile() file: UploadedFileType,
-    @Body('caption') caption?: string
-  ) {
-    return {
-      success: true,
-      filename: file.filename,
-      size: file.size,
-      caption,
-    }
-  }
-}
-```
+---
 
-### Route-Level Timeout Overrides
+## Declarative Route Configuration Options
 
-While ExisJS provides a generous 60-second default global timeout, long-running batch jobs, PDF generation, or third-party AI integrations can override the timeout at the individual route level:
+Each route handler accepts an options object supporting validation, security policies, file uploads, and timeouts:
 
-#### Functional Paradigm
-```typescript filename="src/http/reports/route.ts"
+### 1. Request Validation Schemas
+
+```typescript filename="src/http/products/route.ts"
 import { controller, route } from 'exisjs/router'
+import { tex } from 'exisjs/validator'
 
-export default controller({
-  generateAnnualReport: route.post('/annual', {
-    timeout: 120000, // 2 minutes specifically for this route
-    async handle() {
-      // Intensive document rendering or AI workflow
-      const reportUrl = await buildReport()
-      return { success: true, reportUrl }
-    }
-  })
+const ProductQuerySchema = tex.object({
+  page: tex.number({ coerce: true, default: 1 }),
+  limit: tex.number({ coerce: true, default: 20 }),
 })
-```
 
-### Route-Level CORS Overrides
-
-Routes can also override CORS policies defined in parent `boundary.ts` files or `exis.config.ts`. Route-level CORS has the **highest precedence** in the framework:
-
-#### Functional Paradigm
-```typescript filename="src/http/webhooks/stripe/route.ts"
-import { controller, route } from 'exisjs/router'
+const ProductBodySchema = tex.object({
+  name: tex.string({ min: 2 }),
+  price: tex.number({ min: 0 }),
+})
 
 export default controller({
-  // Open webhook endpoint to Stripe servers only, bypassing restrictive boundary CORS
-  webhook: route.post('/', {
-    cors: {
-      origin: 'https://hooks.stripe.com',
-      methods: ['POST'],
+  create: route.post('/', {
+    query: ProductQuerySchema,
+    body: ProductBodySchema,
+    handle: async ({ query, body }) => {
+      return { page: query.page, product: body }
     },
-    handle({ req }) {
-      return { received: true }
-    }
   }),
-
-  // Disable CORS completely for internal endpoints
-  internalHealth: route.get('/health', {
-    cors: false,
-    handle() {
-      return { status: 'healthy' }
-    }
-  })
 })
 ```
 
-#### Class-Based (OOP) Paradigm
-```typescript filename="src/http/webhooks/stripe/route.ts"
-import { Controller, Post, Cors } from 'exisjs/decorators'
-
-@Controller('/webhooks/stripe')
-export default class StripeWebhookController {
-  @Post('/')
-  @Cors({ origin: 'https://hooks.stripe.com', methods: ['POST'] })
-  handleWebhook() {
-    return { received: true }
-  }
-}
-```
-
-### Query Pagination Schemas
+---
 
-ExisJS provides the `tex.pagination()` primitive for declarative pagination, sorting, and ordering query parameters. String query parameters are automatically coerced into numbers:
+### 2. Multipart File Uploads
 
-```typescript filename="src/http/products/route.ts"
+```typescript filename="src/http/upload/route.ts"
 import { controller, route } from 'exisjs/router'
-import { tex, paginate, getPaginationSkip } from 'exisjs/validator'
-
-const ProductQuerySchema = tex.pagination({
-  defaultLimit: 20,
-  maxLimit: 100,
-})
 
 export default controller({
-  list: route.get('/', {
-    query: ProductQuerySchema,
-    async handle({ query }) {
-      // query.page and query.limit are guaranteed positive numbers
-      const { skip, limit, page } = getPaginationSkip(query)
-      
-      // Fetch data using your preferred database query
-      const [items, total] = await Promise.all([
-        db.products.findMany({ skip, take: limit }),
-        db.products.count()
-      ])
-      
-      return paginate(items, total, { page, limit })
-    }
-  })
+  uploadFile: route.post('/', {
+    upload: {
+      field: 'file',
+      maxBytes: 5 * 1024 * 1024, // 5MB limit
+      mimeTypes: ['image/png', 'image/jpeg', 'application/pdf'],
+    },
+    handle: async ({ file }) => {
+      return {
+        filename: file?.filename,
+        size: file?.size,
+        mimeType: file?.mimeType,
+      }
+    },
+  }),
 })
 ```
 
-## Dependency Injection in Functional Controllers
+---
 
-ExisJS natively supports **Request-Scoped Dependency Injection** directly inside functional routes. You don't need to use classes to get the benefits of DI!
+### 3. Route-Specific Timeout Overrides
 
-By destructuring `resolve` from the context, you can dynamically fetch services without relying on global imports. This perfectly solves the "Fat Handler" problem by encouraging you to abstract business logic into clean Service classes, and makes unit testing incredibly easy.
+You can override default timeouts for long-running endpoints:
 
-```typescript filename="src/http/users/route.ts"
+```typescript filename="src/http/reports/route.ts"
 import { controller, route } from 'exisjs/router'
-import { UsersService } from './service'
 
 export default controller({
-  list: route.get('/', {
-    async handle({ resolve }) {
-      // 1. Resolves UsersService from the IoC Container
-      // 2. Maintains request-scope (the same instance is returned throughout this HTTP request)
-      const usersService = resolve(UsersService)
-      
-      return usersService.getAll()
-    }
-  })
+  generateReport: route.post('/annual', {
+    timeout: 120000, // 120 seconds in milliseconds
+    handle: async () => {
+      // Perform long-running export
+      return { status: 'completed' }
+    },
+  }),
 })
 ```
 
-## The Context API (Advanced)
-
-For applications where passing `(req, res)` arguments through multiple service layers becomes tedious, ExisJS offers a Next.js-inspired approach: **The Context API**. Powered by Node.js `AsyncLocalStorage`, ExisJS provides hooks to access the current request state from anywhere in the execution context.
+---
 
-#### Functional Paradigm
+### 4. Route-Specific CORS Overrides
 
+Route-level CORS configuration takes precedence over boundary and global settings:
 
-```typescript filename="src/http/users/route.ts"
-import { controller, route, getContext, getRequest, getResponse, after } from 'exisjs/router'
+```typescript filename="src/http/webhooks/stripe/route.ts"
+import { controller, route } from 'exisjs/router'
 
 export default controller({
-  create: route.post('/', {
-    async handle() {
-      // Access request/response without prop-drilling
-      const req = getRequest()
-      const res = getResponse()
-      
-      // Access data injected by gateways
-      const { userId } = getContext<{ userId: string }>()
-      
-      // Run background tasks after sending response to client
-      after(async () => {
-        await sendNotificationEmail(userId)
-      })
-
-      res.status(201)
-      return { success: true }
-    }
-  })
+  stripeWebhook: route.post('/', {
+    cors: {
+      origin: 'https://hooks.stripe.com',
+      methods: ['POST'],
+    },
+    handle: async ({ body }) => {
+      return { received: true }
+    },
+  }),
 })
 ```
 
-  
-#### Class-Based (OOP) Paradigm
-
-
-```typescript filename="src/http/users/route.ts"
-import { Controller, Post } from 'exisjs/decorators'
-import { getContext, getRequest, getResponse, after } from 'exisjs/router'
-
-@Controller()
-export default class OrdersController {
-  @Post('/')
-  async create() {
-    // You can still use the Context API seamlessly in OOP classes!
-    const req = getRequest()
-    const res = getResponse()
-    const { userId } = getContext<{ userId: string }>()
-    
-    after(async () => {
-      await sendNotificationEmail(userId)
-    })
-
-    res.status(201)
-    return { success: true }
-  }
-}
-```
-
-  
-
-## Type-Safe Client Route Manifest Contract (`AppRouter`)
+---
 
-ExisJS generates a compile-time route manifest in `.exis/types.d.ts` (and exposed via root `exis.d.ts`), converting your filesystem routes into an `AppRouter` type definition.
+## Dependency Resolution in Functional Routes
 
-### Zero-Cost Return Type & DTO Preservation
-When you return data from `handle()`, ExisJS preserves the exact TypeScript return type (including Drizzle/Prisma models, Tex schemas, or custom records) on the route definition:
+Functional routes can resolve dependencies directly from the IoC container using `ctx.resolve()`:
 
 ```typescript filename="src/http/users/route.ts"
 import { controller, route } from 'exisjs/router'
-import { tex } from 'exisjs/validator'
+import { UserService } from './service'
 
 export default controller({
-  getUser: route.get('/:id', {
-    params: tex.object({ id: tex.string() }),
-    async handle({ params }) {
-      // Inferred return type is strictly preserved as { id: string, name: string, active: boolean }
-      return { id: params.id, name: 'Alice', active: true }
-    }
-  })
-})
-```
-
-### Consuming `AppRouter` with `@exisjs/fetch`
-You can import `AppRouter` in your frontend or external client applications for zero-cost end-to-end type safety and autocomplete:
-
-```typescript filename="src/client/api.ts"
-import { createClient } from '@exisjs/fetch'
-import type { AppRouter } from '../server/.exis/types'
-
-const api = createClient<AppRouter>({
-  baseUrl: 'http://localhost:4000',
+  list: route.get('/', {
+    handle: async ({ resolve }) => {
+      const userService = resolve(UserService)
+      return userService.findAll()
+    },
+  }),
 })
-
-// 1. Hierarchical dot-notation RPC call:
-const user = await api.users('123').getUser.get()
-
-// 2. Direct path index call:
-const userByPath = await api['/users/:id'].getUser.get({ params: { id: '123' } })
 ```
 
-### Dynamic Dev Watcher Sync
-During `exis dev`, adding, renaming, moving, or deleting route files automatically updates `.exis/types.d.ts` and `.exis/types/index.d.ts` in real-time without requiring a dev server restart or manual `.exis` folder deletion.
-
 ---
 
-## Modular Architecture
-
-While putting all logic in `route.ts` is fine for small apps, ExisJS strongly encourages separating concerns alongside your route definition:
-
-- **`schema.ts`**: Defines expected input validation constraints.
-- **`service.ts`**: Pure functions that interact with your database.
-- **`controller.ts`**: Handles business orchestration.
-- **`route.ts`**: Wires it to the HTTP network.
+## Next Steps
 
+- **[Controllers & Decorators](/docs/controllers)**: Complete guide to class-based routing and parameter decorators.
+- **[Request Object](/docs/requests)**: Deep dive into the `ExisRequest` API.
+- **[Response Object](/docs/responses)**: Status codes, cookie management, streaming, and Server-Sent Events.
+- **[Boundaries](/docs/boundaries)**: Scoped middleware cascading, directory guards, and error boundaries.