exisjs 0.7.3 → 0.7.5

package/dist/docs/content/requests.mdx

@@ -91,112 +91,201 @@ export default class ProcessController {
 
 ---
 
-## 3. File Uploads & Form Data
+## 3. File Uploads & Multipart Form Data
 
-Handling `multipart/form-data` in Node.js can be difficult. ExisJS provides a stream parser out-of-the-box.
+Handling `multipart/form-data` in Node.js can be difficult. ExisJS provides multiple robust, high-performance approaches:
 
-Calling `req.formData()` returns both the standard text fields and the uploaded files. ExisJS also attaches a `.saveToDisk()` helper to every uploaded file, which automatically handles writing the buffer and generating collision-free filenames.
+### A. Declarative Route Uploads (Recommended)
 
-#### Functional Paradigm
+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`:
+
+```typescript filename="src/http/upload/route.ts"
+import { controller, route } from 'exisjs/router'
+import { tex } from 'exisjs/validator'
+
+export default controller({
+  uploadPhoto: route.post('/', {
+    upload: {
+      field: 'photo',
+      maxBytes: 10 * 1024 * 1024, // 10MB limit
+      mimeTypes: ['image/jpeg', 'image/png', 'image/webp'],
+    },
+    body: tex.object({
+      title: tex.string({ min: 1 }),
+    }),
+    handle({ req }) {
+      const file = req.file! // Typed UploadedFile
+      console.log(`Uploaded ${file.originalname} (${file.size} bytes)`)
+
+      return {
+        success: true,
+        filename: file.filename,
+        mimetype: file.mimetype,
+        title: req.body.title,
+      }
+    }
+  })
+})
+```
+
+### B. First-Party `fileUpload` Middleware
+
+ExisJS exports a dedicated `fileUpload` middleware from `exisjs/middleware` supporting single, multiple, and multi-field uploads:
+
+```typescript filename="src/http/documents/route.ts"
+import { controller, route } from 'exisjs/router'
+import { fileUpload } from 'exisjs/middleware'
+
+export default controller({
+  // Single file upload
+  single: route.post('/single', 
+    fileUpload.single('document', {
+      maxBytes: 15 * 1024 * 1024, // 15MB
+      dest: './uploads/docs',
+    }),
+    ({ req }) => {
+      return { file: req.file }
+    }
+  ),
+
+  // Multiple files with the same field name
+  gallery: route.post('/gallery',
+    fileUpload.array('photos', 5, {
+      mimeTypes: ['image/*'],
+    }),
+    ({ req }) => {
+      const files = req.files // UploadedFile[]
+      return { count: files?.length }
+    }
+  ),
+
+  // Multiple distinct fields
+  profile: route.post('/profile',
+    fileUpload.fields([
+      { name: 'avatar', maxCount: 1 },
+      { name: 'cover', maxCount: 1 },
+    ]),
+    ({ req }) => {
+      // req.files is a dictionary Record<string, UploadedFile[]>
+      return { files: req.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:
+
+```typescript filename="src/http/legacy/route.ts"
+import { controller, route } from 'exisjs/router'
+import { fromExpress } from 'exisjs/middleware'
+import multer from 'multer'
+
+const upload = multer({
+  storage: multer.memoryStorage(),
+  limits: { fileSize: 10 * 1024 * 1024 },
+})
+
+export default controller({
+  upload: route.post('/', 
+    fromExpress(upload.single('file')),
+    ({ req }) => {
+      // Access multer's req.file or req.body seamlessly
+      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:
 
 ```typescript filename="src/http/upload/route.ts"
 import { controller, route } from 'exisjs/router'
 
 export default controller({
   uploadAvatar: route.post('/avatar', {
-    async handle(req, res) {
-      // 1. Parse the multipart form data
+    async handle({ req }) {
+      // Parse on-demand
       const { fields, files } = await req.formData()
-      
-      // 2. Access the file (e.g., from an input named "profile_pic")
       const uploadedFile = files['profile_pic']
       
       if (uploadedFile) {
-        // 3. Save it to disk safely. Returns the absolute saved path.
+        // Save to disk safely with automated collision-free naming
         const savedPath = await uploadedFile.saveToDisk('./uploads/avatars')
         return { success: true, path: savedPath }
       }
       
-      return { success: false, error: "No file uploaded" }
+      return { success: false, error: 'No file uploaded' }
     }
   })
 })
 ```
 
-#### Class-Based (OOP) Paradigm
+---
 
-```typescript filename="src/http/upload/route.ts"
-import { Controller, Post, UploadedFile } from 'exisjs/decorators'
+## 4. Body Size Limits & HTTP 413
 
-@Controller()
-export default class UploadController {
-  @Post('/avatar')
-  async uploadAvatar(@UploadedFile('profile_pic') profilePic: any) {
-    if (profilePic) {
-      // Save it to disk safely. Returns the absolute saved path.
-      const savedPath = await profilePic.saveToDisk('./uploads/avatars')
-      return { success: true, path: savedPath }
-    }
-    
-    return { success: false, error: "No file uploaded" }
+ExisJS comes pre-configured with a generous **10MB default body limit** (`10485760` bytes) across JSON, form-data, and raw payloads, preventing premature drops during photo or document uploads.
+
+If a client sends a payload exceeding the configured threshold, ExisJS halts parsing immediately and responds with `413 Payload Too Large`:
+
+```json
+{
+  "statusCode": 413,
+  "error": "Payload Too Large",
+  "message": "Request payload exceeded size limit of 10485760 bytes. Increase server.bodyLimit in exis.config.ts to allow larger payloads."
+}
+```
+
+To configure custom limits globally across your app, update `exis.config.ts`:
+
+```typescript filename="exis.config.ts"
+export default {
+  server: {
+    // Set custom maximum payload limit in bytes (e.g. 50MB)
+    bodyLimit: 50 * 1024 * 1024,
   }
 }
 ```
 
-#### Streaming (`streamUpload`)
+---
 
-If you are dealing with large files and don't want to buffer *anything* in memory, ExisJS provides a direct streaming helper. It pipes the multipart chunks directly to the disk in real-time.
+## 5. Dynamic Request Timeouts
 
-#### Functional Paradigm
+ExisJS ships with a **60-second default request timeout** in its `timeout()` middleware, offering ample headroom for slow network clients and third-party cloud operations (Cloudinary, AWS S3, OpenAI, Stripe).
 
-```typescript
+### Dynamic In-Handler Control
+
+Handlers can dynamically extend or cancel the active timeout on the fly using `req.setTimeout()` and `req.clearTimeout()`:
+
+```typescript filename="src/http/ai/route.ts"
 import { controller, route } from 'exisjs/router'
 
 export default controller({
-  uploadCover: route.post('/cover', {
-    async handle(req, res) {
-      // 1. Using the method on the request object
-      // const { fields, files } = await req.streamUpload('./uploads/covers')
-
-      // 2. Or using the exported helper from exisjs/storage
-      const { streamUpload } = await import('exisjs/storage')
-      const { fields, files } = await streamUpload(req, { dest: './uploads/covers' })
-      
-      return { 
-        success: true, 
-        uploadedFiles: files.map(f => f.filename),
-        customFields: fields 
+  generateVideo: route.post('/', {
+    async handle({ req }) {
+      // 1. Extend timeout for heavy AI pass generation (e.g. 3 minutes)
+      req.setTimeout(180000)
+
+      try {
+        const result = await longRunningAiTask()
+        return { success: true, result }
+      } finally {
+        // 2. Clear timeout once work completes
+        req.clearTimeout()
       }
     }
   })
 })
 ```
 
-#### Class-Based (OOP) Paradigm
-
-```typescript
-import { Controller, Post, Req } from 'exisjs/decorators'
-import { streamUpload } from 'exisjs/storage'
-
-@Controller()
-export default class UploadController {
-  @Post('/cover')
-  async uploadCover(@Req() req: any) {
-    // Both req.streamUpload() and the exported helper from exisjs/storage work.
-    const { fields, files } = await streamUpload(req, { dest: './uploads/covers' })
-    
-    return { 
-      success: true, 
-      uploadedFiles: files.map(f => f.filename),
-      customFields: fields 
-    }
-  }
-}
-```
-
 ---
 
-## 4. HTTP Headers & Content Negotiation
+## 6. HTTP Headers & Content Negotiation
 
 ```typescript
 // Get a specific header (case-insensitive)
@@ -214,19 +303,52 @@ 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.
+
+#### Example: Passing to Database Queries & Upstream Fetches
+
+```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 }
+    }
+  })
+})
+```
+
+---
+
+## 9. Context & Metadata
 
 As your request moves through ExisJS Middlewares, various properties are attached to `req` for your convenience:
 

package/dist/docs/content/responses.mdx

@@ -132,7 +132,62 @@ export default class UsersController {
 
 ---
 
-## 3. Setting Headers & Status
+## 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`).
+
+```typescript filename="src/http/products/route.ts"
+import { controller, route } from 'exisjs/router'
+import { tex, paginate, getPaginationSkip } from 'exisjs/validator'
+
+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
+      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(),
+      ])
+
+      // 3. Return standardized pagination envelope
+      return paginate(items, total, { page, limit })
+    }
+  })
+})
+```
+
+### The Standardized Pagination Envelope
+
+Calling `paginate(items, total, { page, limit })` produces a uniform envelope:
+
+```json
+{
+  "data": [
+    { "id": 1, "name": "Mechanical Keyboard" },
+    { "id": 2, "name": "Ergonomic Mouse" }
+  ],
+  "pagination": {
+    "page": 1,
+    "limit": 15,
+    "total": 42,
+    "totalPages": 3,
+    "hasNext": true,
+    "hasPrev": false,
+    "hasNextPage": true,
+    "hasPrevPage": false
+  }
+}
+```
+
+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
 
 The `ExisResponse` object implements a chainable API for HTTP headers and status codes.
 
@@ -155,10 +210,12 @@ res.status(404)
 
 ## 3. Cookies
 
-ExisJS provides native helper methods for setting and clearing cookies safely.
+ExisJS provides native helper methods for setting and clearing cookies safely, supporting modern web standards including CHIPS (Partitioned Cookies) and Priority hints.
+
+### Setting Cookies
 
 ```typescript
-// Set a secure, HTTP-only cookie
+// Set a secure, HTTP-only session cookie
 res.cookie('session_id', '123456', {
   maxAge: 86400, // 1 day in seconds
   httpOnly: true,
@@ -166,15 +223,49 @@ res.cookie('session_id', '123456', {
   sameSite: 'Strict'
 })
 
-// Clear a cookie
+// Cross-site embedded iframe cookie with CHIPS (Partitioned)
+res.cookie('widget_pref', 'dark_mode', {
+  sameSite: 'None', // Automatically forces `secure: true` per modern browser specs
+  partitioned: true, // Cookies Having Independent Partitioned State (CHIPS)
+  priority: 'high',  // Hints browser cookie retention under storage pressure ('low' | 'medium' | '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'
+})
 ```
 
 ---
 
 ## 4. File Downloads & Streaming
 
-ExisJS makes streaming files simple, bypassing V8 memory bottlenecks by piping native Node streams directly to the socket.
+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.
@@ -208,7 +299,9 @@ export default class ReportController {
 ```
 
 ### `res.sendStream()`
-If you are fetching data from an external source (like AWS S3) or generating data on the fly, you can pipe any `ReadableStream` directly to the client.
+Pipe any Node.js `Readable` stream directly to the client with built-in leak prevention:
+- **Client Disconnect Cleanup**: If the client aborts or closes the connection prematurely, the source stream is immediately destroyed (`stream.destroy()`), releasing underlying file handles or external sockets.
+- **Unhandled Error Catching**: Errors emitted during stream consumption are trapped gracefully, preventing unhandled stream crashes.
 
 #### Functional Paradigm
 

package/dist/docs/content/routing.mdx

@@ -452,6 +452,123 @@ export default class SearchController {
 
   
 
+## 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`.
+
+#### Functional Paradigm
+```typescript filename="src/http/avatar/route.ts"
+import { controller, route } from 'exisjs/router'
+import { tex } from 'exisjs/validator'
+
+export default controller({
+  uploadAvatar: route.post('/', {
+    upload: {
+      field: 'avatar',
+      maxBytes: 5 * 1024 * 1024, // 5MB limit
+      mimeTypes: ['image/png', 'image/jpeg', 'image/webp'],
+    },
+    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'
+
+@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
+
+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:
+
+#### Functional Paradigm
+```typescript filename="src/http/reports/route.ts"
+import { controller, route } from 'exisjs/router'
+
+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 }
+    }
+  })
+})
+```
+
+### 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:
+
+```typescript filename="src/http/products/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 })
+    }
+  })
+})
+```
+
 ## 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!

package/dist/docs/content/security.mdx

@@ -41,7 +41,7 @@ export default exis({
 
 ## 2. In-Memory Rate Limiting
 
-The core `rateLimit` middleware provides high-performance in-memory and off-heap native rate limiting:
+The core `rateLimit` middleware provides high-performance in-memory and off-heap native rate limiting with standard HTTP response headers:
 
 ```typescript filename="src/http/boundary.ts"
 import { defineBoundary } from 'exisjs/router'
@@ -51,12 +51,25 @@ export const config = defineBoundary({})
 
 // Apply rate limiting chain step across the boundary
 export const limiter = rateLimit({
-  windowMs: 60 * 1000, // 1 minute
-  max: 100, // 100 requests per minute
-  message: 'Too many requests from this IP, please try again after a minute'
+  windowMs: 60 * 1000, // 1 minute window
+  max: 100,            // 100 requests per window
+  message: 'Too many requests from this IP, please try again after a minute',
+  keyGenerator: (req) => req.ip // Uses normalized IPv4/IPv6 client IP
 })
 ```
 
+### Standard Rate Limit Headers
+
+`rateLimit` automatically emits standard IETF draft and legacy rate-limiting headers on every response:
+
+| Header | Description | Example |
+| :--- | :--- | :--- |
+| `RateLimit-Limit` | Maximum request quota for the configured window. | `100` |
+| `RateLimit-Remaining` | Remaining requests permitted within the current window. | `42` |
+| `RateLimit-Reset` | Time remaining in seconds until the window quota resets. | `18` |
+| `Retry-After` | Included on `429 Too Many Requests` (RFC 6585) indicating seconds to wait. | `18` |
+| `X-RateLimit-*` | Legacy header equivalents for backwards compatibility. | `X-RateLimit-Reset: 18` |
+
 > [!NOTE]
 > The core `rateLimit` middleware runs using an in-memory native off-heap store. For distributed, multi-instance rate limiting backed by Redis, use `@exisjs/cache`.