exisjs 0.7.2 → 0.7.4

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)

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.
 
@@ -269,3 +324,109 @@ ExisJS features native, automatic ETag generation.
 If the client sends an `If-None-Match` header matching the ETag of the current response, ExisJS will immediately abort serialization and send a `304 Not Modified` header with an empty body, saving bandwidth and CPU cycles.
 
 *Note: ETag generation is disabled by default, but can be enabled globally in your `exis()` config, or manually per-route via `res.etagEnabled = true`.*
+
+---
+
+## 7. 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
+
+```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)
+      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 } })
+      }, 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 or custom generators) using `sse.pipeFrom()`:
+
+```typescript filename="src/http/ai/route.ts"
+import { controller, route } from 'exisjs/router'
+
+export default controller({
+  chat: route.post('/', {
+    handle(req, 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!'
+        }
+
+        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.
+

package/dist/docs/content/routing.mdx

@@ -15,11 +15,11 @@ ExisJS natively supports both a **Functional Paradigm** and a **Class-Based OOP
 
 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` file that exports a route definition. 
+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.
-- **`gateway.ts`**: Can be placed in any folder. It acts as a gatekeeper, automatically applying middleware, CORS, headers, and dependencies to *all* routes within its directory and subdirectories.
+- **`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
 
@@ -38,9 +38,9 @@ The `server.ts` file acts as the root configuration for your application. It pro
 import { exis } from 'exisjs'
 
 export default exis({
-  async onStart(app) {
-    // Boot your database here!
-  }
+  providers: [
+    ['LoggerService', { useValue: console }]
+  ]
 })
 ```
 
@@ -59,27 +59,27 @@ export default class RootServer {
 }
 ```
 
-### Folder Gateways (`gateway.ts`)
+### Folder Boundaries (`boundary.ts`)
 
-Gateways apply configurations to all routes in their directory and subdirectories.
+Boundaries apply configurations, security policies, and request pipelines to all routes in their directory and subdirectories.
 
 #### Functional Paradigm
-```typescript filename="src/http/admin/gateway.ts"
-import { defineGateway } from 'exisjs/router'
+```typescript filename="src/http/admin/boundary.ts"
+import { defineBoundary } from 'exisjs/router'
 
-export default defineGateway({
+export const config = defineBoundary({
   headers: { 'X-Admin-Area': 'true' }
 })
 ```
 
 #### Class-Based (OOP) Paradigm
-```typescript filename="src/http/admin/gateway.ts"
-import { Gateway } from 'exisjs/decorators'
+```typescript filename="src/http/admin/boundary.ts"
+import { Boundary } from 'exisjs/decorators'
 
-@Gateway({
+@Boundary({
   headers: { 'X-Admin-Area': 'true' }
 })
-export default class AdminGateway {}
+export default class AdminBoundary {}
 ```
 
 ### Route Definitions (`route.ts`)
@@ -264,13 +264,18 @@ export default controller({
   }),
   getSingle: route.get('/:id', {
     handle({ params }) {
+      // params.id is automatically inferred as string with full autocomplete!
       const { id } = params
-      return { message: \`Fetching user \${id}\` }
+      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
 
@@ -447,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

@@ -16,18 +16,23 @@ The following security middlewares are available from `exisjs/middleware` and ca
 - `helmet(options?)`: Sets 14+ secure HTTP headers (Strict-Transport-Security, X-Content-Type-Options: nosniff, X-Frame-Options: DENY, and CSP).
 - `csrf(options)`: Enforces the Signed Double Submit Cookie pattern to protect state-changing requests (POST, PUT, DELETE) from CSRF attacks.
 - `hpp()`: Protects against HTTP Parameter Pollution attacks by ensuring array query parameters/form fields are safely handled.
+- `mongoSanitize()`: Strips MongoDB operator keys (keys starting with `$` or containing `.`) from `req.body`, `req.query`, and `req.params`.
 - `dbSanitize(options?)`: Protects against NoSQL query operator injection (`$where` and other malicious keys) before reaching database layers.
 - `timeout(ms)`: Automatically terminates requests that exceed the specified timeout limit, returning a 503 response.
 
+> [!TIP]
+> Security middlewares like `hpp()`, `mongoSanitize()`, and `dbSanitize()` automatically synchronize with the request body parser. If registered globally before route handlers, they safely await the body and sanitize it deterministically without runtime crashes.
+
 ```typescript filename="src/http/server.ts"
 import { exis } from 'exisjs'
-import { helmet, csrf, timeout, hpp } from 'exisjs/middleware'
+import { helmet, csrf, timeout, hpp, mongoSanitize } from 'exisjs/middleware'
 
 export default exis({
   async onStart(app) {
     app.use(helmet())
     app.use(timeout(10000))
     app.use(hpp())
+    app.use(mongoSanitize())
   }
 })
 ```