exisjs 0.7.12 → 0.7.13

package/dist/docs/content/responses.mdx

@@ -1,253 +1,170 @@
 ---
-nextUrl: "/docs/prisma"
-nextTitle: "Prisma Integration"
+title: 'Response Helpers & Streaming'
+description: 'API reference for ExisResponse: automatic JSON serialization, response builders, problem details, cookies, file downloads, streaming, and Server-Sent Events.'
+nextUrl: '/docs/boundaries'
+nextTitle: 'Boundaries & Middleware Cascading'
 ---
 
-# Responses
+# Response Helpers & Streaming (`ExisResponse`)
 
-Unlike standard Node.js `ServerResponse` objects, ExisJS wraps every response in an `ExisResponse` class. It provides a chainable API while maintaining the raw performance of native Node.
-
-While ExisJS routes allow you to simply `return { data: ... }` (which automatically serializes to JSON), the `res` object gives you granular control over headers, cookies, streams, and file downloads.
+ExisJS wraps standard Node.js `ServerResponse` objects in an `ExisResponse` instance (`res`). Handlers can return JavaScript objects or arrays directly for automatic JSON serialization, or use `res` methods for status codes, headers, cookie management, file downloads, streaming, and Server-Sent Events (SSE).
 
 ---
 
-## 1. Returning Data vs Sending Data
+## Automatic JSON Serialization
 
-The most common way to respond to a request in ExisJS is to simply **return an object or array**. ExisJS intercepts the return value, automatically serializes it to JSON, sets the `Content-Type`, calculates the `Content-Length`, and sends it down the wire.
+When a route handler returns an object or array, ExisJS automatically serializes the data, sets `Content-Type: application/json; charset=utf-8`, and finishes the response:
 
-#### Functional Paradigm
+### Functional Route
 
-```typescript filename="src/http/route.ts"
+```typescript filename="src/http/users/route.ts"
 import { controller, route } from 'exisjs/router'
 
 export default controller({
-  getUsers: route.get('/', {
-    handle(req, res) {
-      // ExisJS automatically handles JSON serialization
-      return [{ id: 1, name: "Alice" }] 
-    }
-  })
-})
-```
-
-#### Class-Based (OOP) Paradigm
-
-```typescript filename="src/http/route.ts"
-import { Controller, Get } from 'exisjs/decorators'
-
-@Controller()
-export default class UsersController {
-  @Get('/')
-  async getUsers() {
-    // ExisJS automatically handles JSON serialization
-    return [{ id: 1, name: "Alice" }] 
-  }
-}
-```
-
-However, you can completely bypass this and use the `res` object manually:
-
-#### Functional Paradigm
-
-```typescript filename="src/http/route.ts"
-export default controller({
-  getUsers: route.get('/', {
-    handle(req, res) {
-      // Chainable response API
-      res.status(201).json([{ id: 1, name: "Alice" }])
-    }
-  })
+  listUsers: route.get('/', {
+    handle: async () => {
+      // Automatically serialized as JSON with 200 OK
+      return [
+        { id: 1, name: 'Alice' },
+        { id: 2, name: 'Bob' },
+      ]
+    },
+  }),
 })
 ```
 
-#### Class-Based (OOP) Paradigm
+### Class-Based (OOP) Controller
 
-```typescript filename="src/http/route.ts"
-import { Controller, Get, Res } from 'exisjs/decorators'
+```typescript filename="src/http/users/route.ts"
+import { Controller, Get, ApiOperation } from 'exisjs/decorators'
 
 @Controller()
 export default class UsersController {
   @Get('/')
-  async getUsers(@Res() res: any) {
-    // Chainable response API
-    res.status(201).json([{ id: 1, name: "Alice" }])
+  @ApiOperation({ summary: 'List users' })
+  async listUsers() {
+    return [
+      { id: 1, name: 'Alice' },
+      { id: 2, name: 'Bob' },
+    ]
   }
 }
 ```
 
 ---
 
-## 2. Standardized JSON Responses (`exisjs/response`)
+## Response Envelope Builders (`exisjs/response`)
 
-To keep your APIs consistent and predictable across teams, ExisJS provides standard response helpers, envelope constructors, status code constants, and RFC 7807 problem details in `exisjs/response` (also re-exported from the root `exisjs` package).
+ExisJS exports standardized response builders from `exisjs/response` to provide uniform `{ success: boolean, data?: any, error?: any, meta?: any }` structures across all endpoints:
 
-Using these ensures your entire backend adheres to a clean, strongly-typed `{ success: boolean, data?: any, error?: any, meta?: any }` structure that frontend clients and SDK generators can reliably consume.
+| Builder | HTTP Status | Response Structure | Description |
+| :--- | :--- | :--- | :--- |
+| `success(data, message?, meta?)` | `200 OK` | `{ success: true, data, message?, meta? }` | Standard successful response |
+| `created(data, message?, meta?)` | `201 Created` | `{ success: true, data, message: 'Created', meta? }` | Newly created entity |
+| `accepted(data?, message?, meta?)` | `202 Accepted` | `{ success: true, data, message: 'Accepted', meta? }` | Asynchronous or queued action |
+| `noContent()` | `204 No Content` | `{ success: true, data: null }` | Action succeeded with no payload |
+| `error(message, code?, details?, status?)` | `4xx / 5xx` | `{ success: false, error: { message, code?, details? } }` | Structured error envelope |
+| `problem(title, status, detail?, opts?)` | Custom | RFC 7807 / RFC 9457 Problem Details object | Standardized HTTP Problem Details |
+| `paginate(items, total, options)` | `200 OK` | `{ success: true, data, pagination: { ... } }` | Paginated response envelope |
 
-### Available Response Builders
+### Example Usage
 
-| Builder | HTTP Status | Envelope / Output | Purpose |
-| :--- | :--- | :--- | :--- |
-| `success(data, message?, meta?)` | 200 OK | `{ success: true, data, message?, meta? }` | Standard successful payload |
-| `created(data, message?, meta?)` | 201 Created | `{ success: true, data, message: 'Created', meta? }` | Created resource |
-| `accepted(data?, message?, meta?)` | 202 Accepted | `{ success: true, data, message: 'Accepted', meta? }` | Queued async/background job |
-| `noContent()` | 204 No Content | `{ success: true, data: null }` | Empty successful action |
-| `error(msg, code?, details?, status?)` | 4xx / 5xx | `{ success: false, error: { message, code?, details?, status? } }` | Structured error envelope |
-| `problem(title, status, detail?, opts?)` | Custom | RFC 7807 / RFC 9457 Problem Details object | Standard API problem specification |
-| `paginate(items, total, options)` | 200 OK | `{ success: true, data: items, pagination: { ... } }` | Standard pagination envelope |
-| `getPaginationSkip(query)` | N/A | `{ skip, limit, page }` | Database offset/limit calculator |
-| `json(data, status?, headers?)` | Custom | `{ data, status, headers }` | Typed JSON payload descriptor |
-| `redirect(url, status?)` | 3xx | `{ redirect, status }` | Redirection descriptor |
-
-#### Functional Paradigm Example
-
-```typescript filename="src/http/route.ts"
+```typescript filename="src/http/users/route.ts"
 import { controller, route } from 'exisjs/router'
 import { success, created, error, HttpStatus } from 'exisjs/response'
 
 export default controller({
   getUser: route.get('/:id', {
-    handle(req, res) {
-      const user = db.users.find(req.params.id)
-      
+    handle: async ({ params, res }) => {
+      const user = await db.users.find(params.id)
       if (!user) {
         res.status(HttpStatus.NOT_FOUND)
-        // Generates: { success: false, error: { message: "User not found", code: "NOT_FOUND" } }
-        return error("User not found", "NOT_FOUND")
+        return error('User not found', 'NOT_FOUND')
       }
-      
-      // Generates: { success: true, data: { id: 1, name: "Alice" }, message: "Found user" }
-      return success(user, "Found user")
-    }
+      return success(user, 'User retrieved')
+    },
   }),
 
   createUser: route.post('/', {
-    handle(req, res) {
-      const user = db.users.create(req.body)
+    handle: async ({ body, res }) => {
+      const user = await db.users.create(body)
       res.status(HttpStatus.CREATED)
-      // Generates: { success: true, data: user, message: "User registered" }
-      return created(user, "User registered")
-    }
-  })
+      return created(user, 'User registered')
+    },
+  }),
 })
 ```
 
-#### Class-Based (OOP) Paradigm Example
-
-```typescript filename="src/http/route.ts"
-import { Controller, Get, Post, Param, Body, Res } from 'exisjs/decorators'
-import { success, created, error, HttpStatus } from 'exisjs/response'
-
-@Controller()
-export default class UsersController {
-  @Get('/:id')
-  async getUser(@Param('id') id: string, @Res() res: any) {
-    const user = db.users.find(id)
-    
-    if (!user) {
-      res.status(HttpStatus.NOT_FOUND)
-      return error("User not found", "NOT_FOUND")
-    }
-    
-    return success(user, "Found user")
-  }
-
-  @Post('/')
-  async createUser(@Body() body: any, @Res() res: any) {
-    const user = db.users.create(body)
-    res.status(HttpStatus.CREATED)
-    return created(user, "User created successfully")
-  }
-}
-```
+---
 
-### RFC 7807 / RFC 9457 Problem Details (`problem`)
+## RFC 7807 / RFC 9457 Problem Details
 
-For enterprise and public REST APIs requiring standardized error models, `problem()` produces RFC-compliant Problem Details:
+For public or enterprise REST APIs, `problem()` generates standard Problem Details objects:
 
-```typescript
+```typescript filename="src/http/checkout/route.ts"
+import { controller, route } from 'exisjs/router'
 import { problem, HttpStatus } from 'exisjs/response'
 
-res.status(HttpStatus.UNPROCESSABLE_ENTITY)
-return problem('Invalid Request Parameters', 422, 'One or more fields failed schema validation', {
-  type: 'https://api.example.com/errors/validation',
-  instance: req.url,
-  invalidParams: [
-    { name: 'email', reason: 'Must be a valid email address' },
-    { name: 'age', reason: 'Must be greater than 18' }
-  ]
+export default controller({
+  checkout: route.post('/', {
+    handle: async ({ req, res }) => {
+      res.status(HttpStatus.UNPROCESSABLE_ENTITY)
+      return problem(
+        'Out of Stock',
+        422,
+        'One or more requested items are no longer available in inventory.',
+        {
+          type: 'https://api.example.com/errors/inventory',
+          instance: req.path,
+          unavailableItems: ['item_101', 'item_204'],
+        }
+      )
+    },
+  }),
 })
 ```
 
-
 ---
 
-## 3. Standardized Pagination Envelopes (`paginate`)
-
-To eliminate pagination inconsistency across different endpoints, ExisJS exports standard `paginate()` and `getPaginationSkip()` utilities directly from `exisjs/validator` (as well as `exisjs/response`).
+## Standardized Pagination (`paginate`)
 
-#### Functional Paradigm
+The `paginate()` helper combines a data array with calculated total counts to produce a uniform pagination object:
 
 ```typescript filename="src/http/products/route.ts"
 import { controller, route } from 'exisjs/router'
-import { tex, paginate, getPaginationSkip } from 'exisjs/validator'
+import { paginate, getPaginationSkip, tex } from 'exisjs/validator'
+
+const QuerySchema = tex.pagination({ defaultLimit: 20, maxLimit: 100 })
 
 export default controller({
-  listProducts: route.get('/', {
-    query: tex.pagination({ defaultLimit: 15, maxLimit: 50 }),
-    async handle({ query }) {
-      // 1. Automatically extracts { skip, limit, page } with fallback defaults
+  list: route.get('/', {
+    query: QuerySchema,
+    handle: async ({ query }) => {
       const { skip, limit, page } = getPaginationSkip(query)
 
-      // 2. Fetch items and count total from your database
       const [items, total] = await Promise.all([
-        db.product.findMany({ skip, take: limit, orderBy: { createdAt: 'desc' } }),
-        db.product.count(),
+        db.products.findMany({ skip, take: limit }),
+        db.products.count(),
       ])
 
-      // 3. Return standardized pagination envelope
       return paginate(items, total, { page, limit })
-    }
-  })
+    },
+  }),
 })
 ```
 
-#### Class-Based (OOP) Paradigm
-
-```typescript filename="src/http/products/route.ts"
-import { Controller, Get, Query } from 'exisjs/decorators'
-import { tex, paginate, getPaginationSkip } from 'exisjs/validator'
-
-const ProductQuerySchema = tex.pagination({ defaultLimit: 15, maxLimit: 50 })
-
-@Controller('/products')
-export default class ProductsController {
-  @Get('/', { query: ProductQuerySchema })
-  async listProducts(@Query() query: any) {
-    const { skip, limit, page } = getPaginationSkip(query)
-
-    const [items, total] = await Promise.all([
-      db.product.findMany({ skip, take: limit, orderBy: { createdAt: 'desc' } }),
-      db.product.count(),
-    ])
-
-    return paginate(items, total, { page, limit })
-  }
-}
-```
-
-### The Standardized Pagination Envelope
-
-Calling `paginate(items, total, { page, limit })` produces a uniform envelope:
+### JSON Output Format
 
 ```json
 {
+  "success": true,
   "data": [
-    { "id": 1, "name": "Mechanical Keyboard" },
-    { "id": 2, "name": "Ergonomic Mouse" }
+    { "id": "p1", "name": "Keyboard" },
+    { "id": "p2", "name": "Mouse" }
   ],
   "pagination": {
     "page": 1,
-    "limit": 15,
+    "limit": 20,
     "total": 42,
     "totalPages": 3,
     "hasNext": true,
@@ -258,478 +175,228 @@ Calling `paginate(items, total, { page, limit })` produces a uniform envelope:
 }
 ```
 
-Both `hasNext`/`hasPrev` and `hasNextPage`/`hasPrevPage` are provided out-of-the-box, ensuring full compatibility with both cursor-style and page-number frontend UI components.
-
 ---
 
-## 4. Setting Headers & Status
+## Setting Headers & Status Codes
 
-The `ExisResponse` object implements a chainable API for HTTP headers and status codes.
+`ExisResponse` methods can be chained:
 
 ```typescript
 res.status(404)
-   .set('X-Custom-Header', 'exis-is-awesome')
-   .append('Set-Cookie', 'foo=bar')
+   .set('X-Custom-Header', 'custom-value')
+   .append('Set-Cookie', 'pref=dark')
    .json({ error: 'Not Found' })
 ```
 
-### Supported Header Methods
-- `res.status(code)`: Sets the HTTP status code.
-- `res.set(key, value)` (or `res.header()`): Sets an HTTP header.
-- `res.append(key, value)`: Appends to an existing header (e.g., multiple `Set-Cookie` directives).
-- `res.removeHeader(key)`: Deletes a header.
-- `res.type(mimeType)`: A shorthand for setting the `Content-Type` header (e.g., `res.type('html')` becomes `text/html`).
-- `res.vary(field)`: Adds a field to the `Vary` header for caching.
+### Header Methods
+
+- `res.status(code)`: Sets the numeric HTTP status code.
+- `res.set(name, value)` / `res.header(name, value)`: Sets a header.
+- `res.append(name, value)`: Appends to a header (e.g. multiple `Set-Cookie` directives).
+- `res.type(mimeType)`: Shorthand for setting `Content-Type` (e.g. `res.type('html')` $\to$ `text/html`).
+- `res.removeHeader(name)`: Removes a previously set header.
+- `res.vary(field)`: Adds a field to the `Vary` caching header.
 
 ---
 
-## 3. Cookies
+## Cookie Management
 
-ExisJS provides native helper methods for setting and clearing cookies safely, supporting modern web standards including CHIPS (Partitioned Cookies) and Priority hints.
+Set and clear cookies with modern web standard options (including CHIPS Partitioning and Priority hints):
 
 ### Setting Cookies
 
 ```typescript
-// Set a secure, HTTP-only session cookie
-res.cookie('session_id', '123456', {
-  maxAge: 86400, // 1 day in seconds
+// Standard secure HTTP-only cookie
+res.cookie('token', 'xyz123', {
+  maxAge: 86400, // 24 hours in seconds
   httpOnly: true,
   secure: true,
-  sameSite: 'Strict'
+  sameSite: 'Strict',
+  path: '/',
 })
 
-// Cross-site embedded iframe cookie with CHIPS (Partitioned)
-res.cookie('widget_pref', 'dark_mode', {
-  sameSite: 'None', // Automatically forces `secure: true` per modern browser specs
+// Cross-site iframe cookie with CHIPS partitioning
+res.cookie('embed_pref', 'theme_dark', {
+  sameSite: 'None', // Forces secure: true automatically
   partitioned: true, // Cookies Having Independent Partitioned State (CHIPS)
-  priority: 'high',  // Hints browser cookie retention under storage pressure ('low' | 'medium' | 'high')
-  path: '/'
+  priority: 'high',
+  path: '/',
 })
 ```
 
-#### Cookie Options Reference
-
-| Option | Type | Default | Description |
-| :--- | :--- | :--- | :--- |
-| `maxAge` | `number` | `undefined` | Lifetime of the cookie in seconds (sets both `Max-Age` and computed `Expires`). |
-| `expires` | `Date` | `undefined` | Absolute expiration date for the cookie. |
-| `httpOnly` | `boolean` | `false` | Mitigates XSS by preventing client-side JavaScript access. |
-| `secure` | `boolean` | `false` | Requires HTTPS. *Automatically set to `true` if `sameSite: 'None'` is provided.* |
-| `sameSite` | `'Strict' \| 'Lax' \| 'None' \| boolean` | `undefined` | Controls cross-site request cookie inclusion. |
-| `partitioned` | `boolean` | `false` | Enables CHIPS for third-party contexts across top-level site partitions. |
-| `priority` | `'low' \| 'medium' \| 'high'` | `undefined` | RFC 6265bis storage priority hint when client cookie capacity is exhausted. |
-| `path` | `string` | `'/'` | Path where the cookie is valid. |
-| `domain` | `string` | `undefined` | Domain scope for the cookie. |
-
 ### Clearing Cookies
 
-When clearing cookies, browsers require the matching `path` and `domain` used when the cookie was originally set:
-
 ```typescript
-// Clear default root cookie
-res.clearCookie('session_id')
-
-// Clear scoped cookie matching original domain & path
-res.clearCookie('tenant_token', {
-  path: '/api',
-  domain: '.example.com'
-})
+res.clearCookie('token', { path: '/' })
 ```
 
----
+#### Cookie Options
 
-## 4. File Downloads & Streaming
+| Option | Type | Description |
+| :--- | :--- | :--- |
+| `maxAge` | `number` | Expiration time in seconds from current time |
+| `expires` | `Date` | Absolute expiration date |
+| `httpOnly` | `boolean` | Flags cookie as inaccessible to client scripts |
+| `secure` | `boolean` | Requires HTTPS transport (forced if `sameSite: 'None'`) |
+| `sameSite` | `'Strict' \| 'Lax' \| 'None' \| boolean` | Cross-site request cookie behavior |
+| `partitioned` | `boolean` | Enables CHIPS cookie partitioning |
+| `priority` | `'low' \| 'medium' \| 'high'` | Storage priority under client disk pressure |
+| `path` | `string` | URL path scope (default: `'/'`) |
+| `domain` | `string` | Domain scope for the cookie |
 
-ExisJS makes streaming files simple, bypassing V8 memory bottlenecks by piping native Node streams directly to the socket with automated resource cleanup.
+---
 
-### `res.download()`
-Automatically reads a file from disk, sets the `Content-Disposition` header to force a download in the browser, and infers the correct MIME type based on the file extension.
+## File Downloads & Streaming
 
-#### Functional Paradigm
+### File Downloads with `res.download()`
 
-```typescript
+Reads a file from disk, sets `Content-Disposition: attachment`, and infers MIME type:
+
+```typescript filename="src/http/reports/route.ts"
 import { controller, route } from 'exisjs/router'
 
 export default controller({
-  downloadReport: route.get('/report', {
-    handle(req, res) {
-      res.download('/absolute/path/to/report.pdf', 'Q4-Report.pdf')
-    }
-  })
+  download: route.get('/annual', {
+    handle: async ({ res }) => {
+      res.download('./storage/annual-report.pdf', 'Annual-Report-2026.pdf')
+    },
+  }),
 })
 ```
 
-#### Class-Based (OOP) Paradigm
-
-```typescript
-import { Controller, Get, Res } from 'exisjs/decorators'
-
-@Controller()
-export default class ReportController {
-  @Get('/report')
-  async downloadReport(@Res() res: any) {
-    res.download('/absolute/path/to/report.pdf', 'Q4-Report.pdf')
-  }
-}
-```
+---
 
-### `res.sendStream()` & `res.stream()`
-ExisJS provides first-class streaming support across `res.sendStream()` (aliased as `res.stream()`), accepting:
-- **Node.js `Readable` streams** (e.g. `fs.createReadStream`, database cursors, zlib streams)
-- **Web Standard `ReadableStream`** (e.g. from `fetch()`, OpenAI SDK, Anthropic SDK, and AI frameworks)
-- **`AsyncIterable` & Async Generators** (e.g. `async function* generate() { yield ... }`)
+### Stream Piping (`res.stream()` / `res.sendStream()`)
 
-#### Core Reliability Guarantees:
-- **Socket Backpressure Control**: If the underlying network socket buffer fills up (`res.raw.write()` returns `false`), ExisJS automatically pauses stream consumption until the `'drain'` event fires, preventing fast producers from exhausting server RAM.
-- **Client Disconnect Teardown**: If the client aborts or closes the connection prematurely (`req.raw.on('close')`), ExisJS cancels Web stream readers (`reader.cancel()`), destroys Node streams (`stream.destroy()`), or terminates async generators (`generator.return()`).
-- **Resilient Error Trapping**: Stream transmission failures are trapped without crashing the Node.js process. If headers have not yet been sent, a structured 500 error envelope is returned.
+ExisJS supports direct streaming for:
+- Node.js `Readable` streams (`fs.createReadStream`, database cursor streams)
+- Web standard `ReadableStream` (OpenAI SDK, fetch responses)
+- `AsyncIterable` and async generators
 
 #### 1. Streaming Node.js Readable Streams
 
-##### Functional Paradigm
-```typescript filename="src/http/video/route.ts"
+```typescript filename="src/http/export/route.ts"
 import { controller, route } from 'exisjs/router'
 import fs from 'node:fs'
 
 export default controller({
-  streamVideo: route.get('/', {
-    handle(req, res) {
-      const videoStream = fs.createReadStream('/path/to/video.mp4')
-      res.type('video/mp4')
-      res.sendStream(videoStream)
-    }
-  })
+  exportCsv: route.get('/', {
+    handle: ({ res }) => {
+      const stream = fs.createReadStream('./data/export.csv')
+      res.type('text/csv')
+      res.stream(stream)
+    },
+  }),
 })
 ```
 
-##### Class-Based (OOP) Paradigm
-```typescript filename="src/http/video/route.ts"
-import { Controller, Get, Res } from 'exisjs/decorators'
-import type { Response } from 'exisjs/router'
-import fs from 'node:fs'
+#### 2. Streaming Web Standard Streams (AI Chat & Fetch)
 
-@Controller('/video')
-export default class VideoController {
-  @Get('/')
-  streamVideo(@Res() res: Response) {
-    const videoStream = fs.createReadStream('/path/to/video.mp4')
-    res.type('video/mp4')
-    res.sendStream(videoStream)
-  }
-}
-```
-
-#### 2. Streaming Web Standard `ReadableStream` (AI SDKs & Fetch)
-
-##### Functional Paradigm
 ```typescript filename="src/http/ai/route.ts"
 import { controller, route } from 'exisjs/router'
 
 export default controller({
   chat: route.post('/', {
-    async handle(req, res) {
-      const response = await fetch('https://api.openai.com/v1/chat/completions', {
+    handle: async ({ req, res }) => {
+      const upstream = await fetch('https://api.openai.com/v1/chat/completions', {
         method: 'POST',
-        headers: { 'Authorization': `Bearer ${process.env.OPENAI_API_KEY}` },
-        body: JSON.stringify({ model: 'gpt-4o', stream: true, messages: req.body.messages }),
+        headers: {
+          'Authorization': `Bearer ${process.env.OPENAI_API_KEY}`,
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({
+          model: 'gpt-4o',
+          stream: true,
+          messages: req.body.messages,
+        }),
       })
 
       res.type('text/event-stream')
-      res.stream(response.body!) // Web ReadableStream piped with backpressure
-    }
-  })
-})
-```
-
-##### Class-Based (OOP) Paradigm
-```typescript filename="src/http/ai/route.ts"
-import { Controller, Post, Body, Res } from 'exisjs/decorators'
-import type { Response } from 'exisjs/router'
-
-@Controller('/ai')
-export default class AiController {
-  @Post('/chat')
-  async chat(@Body() body: any, @Res() res: Response) {
-    const response = await fetch('https://api.openai.com/v1/chat/completions', {
-      method: 'POST',
-      headers: { 'Authorization': `Bearer ${process.env.OPENAI_API_KEY}` },
-      body: JSON.stringify({ model: 'gpt-4o', stream: true, messages: body.messages }),
-    })
-
-    res.type('text/event-stream')
-    res.stream(response.body!)
-  }
-}
-```
-
-#### 3. Streaming Async Generators
-
-##### Functional Paradigm
-```typescript filename="src/http/feed/route.ts"
-import { controller, route } from 'exisjs/router'
-
-export default controller({
-  feed: route.get('/', {
-    handle(req, res) {
-      async function* generateData() {
-        for (let i = 0; i < 100; i++) {
-          yield `data: item ${i}\n\n`
-          await new Promise((r) => setTimeout(r, 50))
-        }
-      }
-
-      res.type('text/event-stream')
-      res.stream(generateData())
-    }
-  })
+      res.stream(upstream.body!)
+    },
+  }),
 })
 ```
 
-##### Class-Based (OOP) Paradigm
-```typescript filename="src/http/feed/route.ts"
-import { Controller, Get, Res } from 'exisjs/decorators'
-import type { Response } from 'exisjs/router'
+#### 3. Automatic Return Stream Piping
 
-@Controller('/feed')
-export default class FeedController {
-  @Get('/')
-  streamFeed(@Res() res: Response) {
-    async function* generateData() {
-      for (let i = 0; i < 100; i++) {
-        yield `data: item ${i}\n\n`
-        await new Promise((r) => setTimeout(r, 50))
-      }
-    }
+If a route handler returns a `Readable` stream directly, ExisJS detects and pipes it automatically:
 
-    res.type('text/event-stream')
-    res.stream(generateData())
-  }
-}
-```
-
-#### 4. Automatic Stream Piping from Handler Return Values
-Route handlers returning a stream or async generator directly are automatically detected by the ExisJS pipeline and piped via `res.sendStream()`:
-
-##### Functional Paradigm
-```typescript filename="src/http/export/route.ts"
+```typescript filename="src/http/files/route.ts"
 import { controller, route } from 'exisjs/router'
 import fs from 'node:fs'
 
 export default controller({
-  exportCsv: route.get('/', {
-    handle() {
-      // Simply return the readable stream; ExisJS auto-pipes it to res!
-      return fs.createReadStream('./data/export.csv')
-    }
-  })
+  getFile: route.get('/', {
+    handle: () => {
+      return fs.createReadStream('./data/report.csv')
+    },
+  }),
 })
 ```
 
-##### Class-Based (OOP) Paradigm
-```typescript filename="src/http/export/route.ts"
-import { Controller, Get } from 'exisjs/decorators'
-import fs from 'node:fs'
-
-@Controller('/export')
-export default class ExportController {
-  @Get('/')
-  exportCsv() {
-    // Simply return the readable stream; ExisJS auto-pipes it to res!
-    return fs.createReadStream('./data/export.csv')
-  }
-}
-```
-
 ---
 
-## 5. Redirects
+## Server-Sent Events (SSE)
 
-You can instantly redirect users to another URL using `res.redirect()`. It defaults to a `302 Found` temporary redirect, but you can override the status code.
-
-#### Functional Paradigm
-```typescript filename="src/http/auth/route.ts"
-import { controller, route } from 'exisjs/router'
-
-export default controller({
-  login: route.get('/login', {
-    handle(req, res) {
-      res.redirect('https://auth.example.com/login', 302)
-    }
-  })
-})
-```
-
-#### Class-Based (OOP) Paradigm
-```typescript filename="src/http/auth/route.ts"
-import { Controller, Get, Res } from 'exisjs/decorators'
-import type { Response } from 'exisjs/router'
-
-@Controller('/auth')
-export default class AuthController {
-  @Get('/login')
-  login(@Res() res: Response) {
-    res.redirect('https://auth.example.com/login', 302)
-  }
-}
-```
-
----
-
-## 6. Safe Response Serialization (BSON, Dates & Prototype Auto-Unwrapping)
-
-ExisJS includes a robust, zero-crash serialization engine that automatically prepares complex objects before sending them down the wire:
-
-- **Mongoose / ORM Documents**: Automatically unwraps documents by invoking `.toObject({ virtuals: true, getters: true })` or `.toJSON()`. You no longer need to call `.lean()` or sanitize documents manually.
-- **MongoDB BSON Types**: Automatically converts `ObjectId`, `Decimal128`, `Long`, and `Binary` buffers to their clean string / base64 representations.
-- **BigInt & Dates**: Converts native `BigInt` values to strings and `Date` instances to ISO 8601 strings.
-- **Maps & Sets**: Automatically converts `Map` to plain objects and `Set` to arrays.
-- **Circular Reference Guard**: Circular object references are safely detected and replaced with `'[Circular]'` rather than throwing fatal V8 JSON serialization exceptions.
-- **Enhanced Diagnostics**: If an unhandled serialization issue occurs, ExisJS logs the exact property path (e.g. `'recentTransactions[0].accountId'`) for immediate debugging clarity.
-
----
-
-## 7. ETags & Conditional Requests (304 Not Modified)
-
-ExisJS features native ETag generation.
-
-By default, ETags are disabled (`etag: false`) on dynamic REST API endpoints to minimize hashing CPU overhead and provide transparent logging timings. 
-
-When enabled globally (`etag: true` in `exis.config.ts`) or on a per-route basis (`res.etagEnabled = true`):
-- If the client sends an `If-None-Match` header matching the response ETag, ExisJS immediately sends `304 Not Modified` with an empty body, saving bandwidth.
-
----
-
-## 8. Server-Sent Events (SSE) & AI Streaming
-
-ExisJS provides a first-class `res.sse()` method for real-time live events and AI chat completions (OpenAI, Anthropic, Ollama, LangChain).
-
-When called, `res.sse()` automatically configures and flushes the required HTTP headers:
-- `Content-Type: text/event-stream; charset=utf-8`
-- `Cache-Control: no-cache, no-transform`
-- `Connection: keep-alive`
-- `X-Accel-Buffering: no` (disables NGINX proxy buffering)
-
-You can import `SSEStream`, `formatSSEEvent`, `SSEMessage`, and `SSEOptions` from `exisjs/router`.
-
-### Basic SSE Stream
-
-#### Functional Paradigm
+Use `res.sse()` to open a real-time event stream:
 
 ```typescript filename="src/http/events/route.ts"
 import { controller, route } from 'exisjs/router'
 
 export default controller({
-  liveEvents: route.get('/', {
-    handle(req, res) {
-      // Initialize the stream (heartbeat ping every 15s by default)
+  liveFeed: route.get('/', {
+    handle: ({ res }) => {
       const sse = res.sse()
 
       sse.send({ event: 'connected', data: { timestamp: Date.now() } })
 
       const interval = setInterval(() => {
-        sse.send({ event: 'price-update', data: { symbol: 'BTC', price: 95000 } })
+        sse.send({ event: 'price', data: { symbol: 'BTC', price: 95000 } })
       }, 1000)
 
-      // Automatically clean up intervals when the client disconnects or closes the tab
       sse.onClose(() => {
         clearInterval(interval)
       })
-    }
-  })
+    },
+  }),
 })
 ```
 
-#### Class-Based (OOP) Paradigm
-
-```typescript filename="src/http/events/route.ts"
-import { Controller, Get, Res } from 'exisjs/decorators'
-import type { Response } from 'exisjs/router'
-
-@Controller()
-export default class EventsController {
-  @Get('/events')
-  streamEvents(@Res() res: Response) {
-    const sse = res.sse()
-
-    sse.send({ event: 'connected', data: { status: 'ok' } })
-
-    sse.onClose(() => {
-      console.log('Client disconnected from SSE stream')
-    })
-  }
-}
-```
-
-### AI / LLM Streaming with `sse.pipeFrom()`
-
-You can directly stream chunks from any `AsyncIterable` (such as the OpenAI SDK, Anthropic SDK, or custom async generators) using `sse.pipeFrom()`:
+### Streaming Async Iterables with `sse.pipeFrom()`
 
-#### Functional Paradigm
+Stream chunks from an async generator or AI SDK directly:
 
 ```typescript filename="src/http/ai/route.ts"
 import { controller, route } from 'exisjs/router'
 
 export default controller({
-  chat: route.post('/', {
-    handle(req, res) {
+  streamTokens: route.post('/', {
+    handle: ({ res }) => {
       res.sse(async (sse) => {
-        // Stream directly from an async generator or AI SDK
-        async function* generateTokens() {
-          yield 'Hello'
-          yield ' from'
-          yield ' ExisJS'
-          yield ' AI streaming!'
+        async function* tokenGenerator() {
+          yield 'Hello '
+          yield 'from '
+          yield 'ExisJS SSE!'
         }
 
-        await sse.pipeFrom(generateTokens(), (token) => ({
-          event: 'delta',
-          data: { text: token }
+        await sse.pipeFrom(tokenGenerator(), (chunk) => ({
+          event: 'token',
+          data: { text: chunk },
         }))
 
         sse.close()
       })
-    }
-  })
+    },
+  }),
 })
 ```
 
-#### Class-Based (OOP) Paradigm
-
-```typescript filename="src/http/ai/route.ts"
-import { Controller, Post, Res } from 'exisjs/decorators'
-import type { Response } from 'exisjs/router'
-
-@Controller('/ai')
-export default class AiController {
-  @Post('/chat')
-  chat(@Res() res: Response) {
-    res.sse(async (sse) => {
-      async function* generateTokens() {
-        yield 'Hello'
-        yield ' from'
-        yield ' ExisJS'
-        yield ' AI streaming!'
-      }
-
-      await sse.pipeFrom(generateTokens(), (token) => ({
-        event: 'delta',
-        data: { text: token }
-      }))
-
-      sse.close()
-    })
-  }
-}
-```
-
-### SSE Options & Methods
+---
 
-- `res.sse(options?)`: Options include:
-  - `heartbeat`: Heartbeat interval in milliseconds (default: `15000`). Pass `false` to disable.
-  - `heartbeatComment`: Custom comment string for keep-alive pings (default: `": ping\n\n"`).
-  - `headers`: Additional custom HTTP headers.
-- `sse.send(message)`: Sends an event. Accepts string, number, object (auto JSON-stringified), or `{ event, data, id, retry }`.
-- `sse.comment(text)`: Sends a raw SSE comment line (e.g. `: ping\n\n`) without triggering client-side event listeners.
-- `sse.onClose(callback)`: Registers a callback fired when the client disconnects.
-- `sse.close()`: Gracefully terminates the stream and closes the HTTP response.
+## Next Steps
 
+- **[Boundaries & Cascading](/docs/boundaries)**: Folder-level middleware, security guards, and error boundaries.
+- **[Validation Guide](/docs/validation)**: Input validation with `tex` schema builder.
+- **[Controllers](/docs/controllers)**: Working with class-based response decorators.
+- **[Requests](/docs/requests)**: Inspecting request details, headers, and abort signals.