exisjs 0.7.4 → 0.7.6

package/dist/docs/content/requests.mdx

@@ -97,7 +97,9 @@ Handling `multipart/form-data` in Node.js can be difficult. ExisJS provides mult
 
 ### A. Declarative Route Uploads (Recommended)
 
-You can declare file upload requirements directly inside your route schema. ExisJS automatically executes the multipart parser, validates MIME types, enforces byte caps, and populates `req.file` or `req.files` along with non-file fields in `req.body`:
+You can declare file upload requirements directly inside your route schema or decorators. ExisJS automatically executes the multipart parser, validates MIME types, enforces byte caps, and populates `req.file` or `req.files` along with non-file fields in `req.body`:
+
+#### Functional Paradigm
 
 ```typescript filename="src/http/upload/route.ts"
 import { controller, route } from 'exisjs/router'
@@ -128,10 +130,47 @@ export default controller({
 })
 ```
 
+#### Class-Based (OOP) Paradigm
+
+```typescript filename="src/http/upload/route.ts"
+import { Controller, Post, UseUpload, UploadedFile, Body } from 'exisjs/decorators'
+import { tex } from 'exisjs/validator'
+import type { UploadedFile as IUploadedFile } from 'exisjs/router'
+
+const TitleSchema = tex.object({
+  title: tex.string({ min: 1 }),
+})
+
+@Controller('/upload')
+export default class UploadController {
+  @Post('/')
+  @UseUpload({
+    field: 'photo',
+    maxBytes: 10 * 1024 * 1024,
+    mimeTypes: ['image/jpeg', 'image/png', 'image/webp'],
+  })
+  async uploadPhoto(
+    @UploadedFile() file: IUploadedFile,
+    @Body(TitleSchema) body: { title: string }
+  ) {
+    console.log(`Uploaded ${file.originalname} (${file.size} bytes)`)
+
+    return {
+      success: true,
+      filename: file.filename,
+      mimetype: file.mimetype,
+      title: body.title,
+    }
+  }
+}
+```
+
 ### B. First-Party `fileUpload` Middleware
 
 ExisJS exports a dedicated `fileUpload` middleware from `exisjs/middleware` supporting single, multiple, and multi-field uploads:
 
+#### Functional Paradigm
+
 ```typescript filename="src/http/documents/route.ts"
 import { controller, route } from 'exisjs/router'
 import { fileUpload } from 'exisjs/middleware'
@@ -173,10 +212,44 @@ export default controller({
 })
 ```
 
+#### Class-Based (OOP) Paradigm
+
+```typescript filename="src/http/documents/route.ts"
+import { Controller, Post, Use, UploadedFile, UploadedFiles } from 'exisjs/decorators'
+import { fileUpload } from 'exisjs/middleware'
+import type { UploadedFile as IUploadedFile } from 'exisjs/router'
+
+@Controller('/documents')
+export default class DocumentsController {
+  // Single file upload
+  @Post('/single')
+  @Use(fileUpload.single('document', { maxBytes: 15 * 1024 * 1024, dest: './uploads/docs' }))
+  async uploadSingle(@UploadedFile() file: IUploadedFile) {
+    return { file }
+  }
+
+  // Multiple files with the same field name
+  @Post('/gallery')
+  @Use(fileUpload.array('photos', 5, { mimeTypes: ['image/*'] }))
+  async uploadGallery(@UploadedFiles() files: IUploadedFile[]) {
+    return { count: files.length, files }
+  }
+
+  // Multiple distinct fields
+  @Post('/profile')
+  @Use(fileUpload.fields([{ name: 'avatar', maxCount: 1 }, { name: 'cover', maxCount: 1 }]))
+  async uploadProfile(@UploadedFiles() files: Record<string, IUploadedFile[]>) {
+    return { files }
+  }
+}
+```
+
 ### C. Integrating Express/Connect Middleware (e.g. Multer)
 
 If your enterprise project relies on existing Express middleware like **Multer** (for custom storage engines, S3 direct-to-cloud streams, or specialized filters), ExisJS provides the `fromExpress()` bridge:
 
+#### Functional Paradigm
+
 ```typescript filename="src/http/legacy/route.ts"
 import { controller, route } from 'exisjs/router'
 import { fromExpress } from 'exisjs/middleware'
@@ -199,10 +272,36 @@ export default controller({
 })
 ```
 
+#### Class-Based (OOP) Paradigm
+
+```typescript filename="src/http/legacy/route.ts"
+import { Controller, Post, Use, Req } from 'exisjs/decorators'
+import { fromExpress } from 'exisjs/middleware'
+import type { Request } from 'exisjs/router'
+import multer from 'multer'
+
+const upload = multer({
+  storage: multer.memoryStorage(),
+  limits: { fileSize: 10 * 1024 * 1024 },
+})
+
+@Controller('/legacy')
+export default class LegacyUploadController {
+  @Post('/upload')
+  @Use(fromExpress(upload.single('file')))
+  async upload(@Req() req: Request) {
+    const file = (req.raw as any).file || req.file
+    return { success: true, originalname: file?.originalname }
+  }
+}
+```
+
 ### D. Manual `req.formData()` & Streaming Uploads
 
 For manual control over incoming multipart streams without route middleware:
 
+#### Functional Paradigm
+
 ```typescript filename="src/http/upload/route.ts"
 import { controller, route } from 'exisjs/router'
 
@@ -225,6 +324,29 @@ export default controller({
 })
 ```
 
+#### Class-Based (OOP) Paradigm
+
+```typescript filename="src/http/upload/route.ts"
+import { Controller, Post, Req } from 'exisjs/decorators'
+import type { Request } from 'exisjs/router'
+
+@Controller('/upload')
+export default class ManualUploadController {
+  @Post('/avatar')
+  async uploadAvatar(@Req() req: Request) {
+    const { fields, files } = await req.formData()
+    const uploadedFile = files['profile_pic']
+
+    if (uploadedFile) {
+      const savedPath = await uploadedFile.saveToDisk('./uploads/avatars')
+      return { success: true, path: savedPath }
+    }
+
+    return { success: false, error: 'No file uploaded' }
+  }
+}
+```
+
 ---
 
 ## 4. Body Size Limits & HTTP 413
@@ -260,22 +382,24 @@ ExisJS ships with a **60-second default request timeout** in its `timeout()` mid
 
 ### Dynamic In-Handler Control
 
-Handlers can dynamically extend or cancel the active timeout on the fly using `req.setTimeout()` and `req.clearTimeout()`:
+Handlers can dynamically extend or cancel the active timeout on the fly using `req.setTimeout()` and `req.clearTimeout()`, or declaratively via `@Timeout(ms)`:
+
+#### Functional Paradigm
 
 ```typescript filename="src/http/ai/route.ts"
 import { controller, route } from 'exisjs/router'
 
 export default controller({
   generateVideo: route.post('/', {
+    timeoutMs: 180000, // 1. Declarative 3-minute timeout for this endpoint
     async handle({ req }) {
-      // 1. Extend timeout for heavy AI pass generation (e.g. 3 minutes)
-      req.setTimeout(180000)
+      // 2. Or dynamically adjust timeout during processing
+      req.setTimeout(240000)
 
       try {
         const result = await longRunningAiTask()
         return { success: true, result }
       } finally {
-        // 2. Clear timeout once work completes
         req.clearTimeout()
       }
     }
@@ -283,6 +407,30 @@ export default controller({
 })
 ```
 
+#### Class-Based (OOP) Paradigm
+
+```typescript filename="src/http/ai/route.ts"
+import { Controller, Post, Timeout, Req } from 'exisjs/decorators'
+import type { Request } from 'exisjs/router'
+
+@Controller('/ai')
+export default class AiTaskController {
+  @Post('/generate-video')
+  @Timeout(180000) // 1. Declarative 3-minute timeout
+  async generateVideo(@Req() req: Request) {
+    // 2. Or dynamically adjust on the fly
+    req.setTimeout(240000)
+
+    try {
+      const result = await longRunningAiTask()
+      return { success: true, result }
+    } finally {
+      req.clearTimeout()
+    }
+  }
+}
+```
+
 ---
 
 ## 6. HTTP Headers & Content Negotiation
@@ -303,19 +451,78 @@ const language = req.acceptsLanguages('en', 'es', 'fr')
 
 ---
 
-## 5. Network Information
+## 7. Network Information & IPv6 Normalization
 
-ExisJS handles trust-proxies. If you are behind Cloudflare, Nginx, or an AWS Load Balancer, simply set `trustProxy: true` in your `exis()` config, and these properties will automatically resolve the true client IP from `X-Forwarded-For`.
+ExisJS handles trust-proxies and dual-stack IP networks automatically. If you are behind Cloudflare, Nginx, or an AWS Load Balancer, simply set `trustProxy: true` in your `exis()` config, and these properties will automatically resolve the true client IP from `X-Forwarded-For`.
 
-- **`req.ip`**: The client's IP address.
-- **`req.ips`**: An array of IPs if multiple proxies were traversed.
+- **`req.ip`**: The client's IP address. Automatically normalizes IPv6-mapped IPv4 dual-stack addresses (e.g., `::ffff:192.168.1.50` $\to$ `192.168.1.50`) and converts IPv6 loopback `::1` $\to$ `127.0.0.1` for consistent rate limiting and geo-IP lookups.
+- **`req.ips`**: An array of IPs if multiple proxies were traversed, each normalized cleanly.
 - **`req.hostname`**: The resolved hostname (from `Host` or `X-Forwarded-Host`).
 - **`req.protocol`**: Returns `'http'` or `'https'`.
 - **`req.secure`**: A boolean (true if `req.protocol === 'https'`).
 
 ---
 
-## 6. Context & Metadata
+## 8. Request Cancellation & Abort Signals (`req.signal`)
+
+ExisJS provides a first-class standard Web API `req.signal: AbortSignal` tied directly to the underlying HTTP connection lifecycle. 
+
+When a client closes their browser tab, cancels a download, or aborts an HTTP request, `req.signal` immediately triggers an `abort` event. You can pass `req.signal` directly to ORMs, database drivers, and HTTP clients to cancel expensive in-flight operations and eliminate wasted server resources.
+
+#### Functional Paradigm
+
+```typescript filename="src/http/reports/route.ts"
+import { controller, route } from 'exisjs/router'
+
+export default controller({
+  heavyReport: route.get('/', {
+    async handle({ req }) {
+      // 1. Pass req.signal to fetch() — if the client leaves, fetch aborts immediately
+      const upstream = await fetch('https://api.external.com/data', {
+        signal: req.signal
+      })
+      const payload = await upstream.json()
+
+      // 2. Pass req.signal to your database queries (Prisma, Drizzle, pg, etc.)
+      const results = await db.query(sql`SELECT * FROM heavy_analytics`, {
+        signal: req.signal
+      })
+
+      return { payload, results }
+    }
+  })
+})
+```
+
+#### Class-Based (OOP) Paradigm
+
+```typescript filename="src/http/reports/route.ts"
+import { Controller, Get, Req } from 'exisjs/decorators'
+import type { Request } from 'exisjs/router'
+
+@Controller('/reports')
+export default class ReportsController {
+  @Get('/')
+  async heavyReport(@Req() req: Request) {
+    // 1. Pass req.signal to fetch()
+    const upstream = await fetch('https://api.external.com/data', {
+      signal: req.signal,
+    })
+    const payload = await upstream.json()
+
+    // 2. Pass req.signal to your database queries
+    const results = await db.query(sql`SELECT * FROM heavy_analytics`, {
+      signal: req.signal,
+    })
+
+    return { payload, results }
+  }
+}
+```
+
+---
+
+## 9. Context & Metadata
 
 As your request moves through ExisJS Middlewares, various properties are attached to `req` for your convenience: