exisjs 0.7.3 → 0.7.4

package/dist/docs/content/errors.mdx

@@ -74,7 +74,9 @@ The `HttpError` class provides static factory methods for standard HTTP status c
 - `HttpError.forbidden('Message')` - 403
 - `HttpError.notFound('Resource')` - 404
 - `HttpError.conflict('Message')` - 409
+- `HttpError.payloadTooLarge('Message')` - 413
 - `HttpError.unprocessable('Message', details)` - 422
+- `HttpError.rateLimit('Message')` - 429
 - `HttpError.internal('Message')` - 500
 
 ### Direct Error Classes & Exceptions
@@ -82,15 +84,17 @@ The `HttpError` class provides static factory methods for standard HTTP status c
 If you prefer a class-based approach, ExisJS exports every standard error as its own class. We also provide `Exception` aliases for every error class. You can import and throw them directly:
 
 ```typescript filename="example.ts"
-import { NotFoundException, UnauthorizedException, BadRequestError } from 'exisjs/error'
-
-export const deleteBook = (req, res) => {
-  const book = db.findBook(req.params.id)
-  
-  if (!book) throw new NotFoundException('Book not found')
-  if (book.ownerId !== req.user.id) throw new UnauthorizedException('Unauthorized')
-    
-  // ...
+import { 
+  NotFoundException, 
+  UnauthorizedException, 
+  BadRequestError, 
+  PayloadTooLargeError 
+} from 'exisjs/error'
+
+export const uploadMedia = (req, res) => {
+  if (req.headers['content-length'] > 10 * 1024 * 1024) {
+    throw new PayloadTooLargeError('File exceeds 10MB limit')
+  }
 }
 ```
 
@@ -108,6 +112,36 @@ When an `HttpError` is thrown, the client will automatically receive a structure
 }
 ```
 
+### Validation Error Responses & Diagnostic Visibility
+
+When schema validation fails (via `tex`, Zod, or Yup), ExisJS produces a typed `400 Bad Request` featuring a clean `errors: Record<string, string>` map for seamless frontend form field binding:
+
+```json filename="HTTP 400 Bad Request Response"
+{
+  "statusCode": 400,
+  "error": "Bad Request",
+  "message": "Validation Error: email: Invalid email format, age: Field must be >= 18",
+  "errors": {
+    "email": "Invalid email format",
+    "age": "Field must be >= 18"
+  }
+}
+```
+
+#### Development Terminal Diagnostics
+
+In development mode, ExisJS automatically outputs formatted tabular diagnostics to the terminal displaying the exact HTTP part, field, received value, and expected requirement:
+
+```text
+[VALIDATION FAILED] POST /auth/register (part: body)
+┌─────────────┬───────────────────────────┬──────────────────┐
+│ Field       │ Received                  │ Expected         │
+├─────────────┼───────────────────────────┼──────────────────┤
+│ email       │ "alice"                   │ Valid email      │
+│ age         │ "16"                      │ min: 18          │
+└─────────────┴───────────────────────────┴──────────────────┘
+```
+
 If you throw an unhandled exception (like a database connection failure or a `TypeError`), ExisJS catches it and securely returns a `500 Internal Server Error`, hiding the stack trace from the client in production mode while logging the full trace to your internal logger.
 
 ## Error Handling Decision Tree

package/dist/docs/content/middleware.mdx

@@ -213,3 +213,141 @@ const config: ExisConfig = {
 
 export default config
 ```
+
+---
+
+## 9. Request Timeout (`timeout`)
+
+The `timeout()` middleware terminates runaway requests and returns `503 Service Unavailable` (or a custom status code).
+
+ExisJS defaults to **60 seconds (60000ms)** to provide generous headroom for slow network connections and third-party cloud operations (Cloudinary, AWS S3, OpenAI, Stripe).
+
+```typescript filename="src/http/server.ts"
+import { exis } from 'exisjs'
+import { timeout } from 'exisjs/middleware'
+
+export default exis({
+  async onStart(app) {
+    app.use(timeout({
+      ms: 60000,
+      statusCode: 504,
+      message: 'Gateway Timeout connecting to upstream cloud service',
+      // Bypass webhooks or long-lived streaming endpoints
+      exclude: ['/webhooks/*', '/ai/stream'],
+    }))
+  }
+})
+```
+
+Handlers can also dynamically adjust timeouts using `req.setTimeout(ms)` and `req.clearTimeout()`.
+
+### Route-Level Timeout Overrides
+
+Long-running routes (file uploads, PDF exports, AI inferences, data migrations) can declare custom timeouts directly in the route definition, overriding any global application timeout:
+
+```typescript filename="src/http/ai/route.ts"
+import { controller, route } from 'exisjs/router'
+
+export default controller({
+  heavyTask: route.post('/heavy-task', {
+    timeoutMs: 120000, // 2 minutes for this endpoint only
+    async handle({ body }) {
+      return await generateLargeReport(body)
+    }
+  }),
+
+  exportStream: route.get('/export', {
+    timeoutMs: 0, // 0 disables timeout completely for infinite SSE / streaming
+    async handle({ res }) {
+      return streamDataToClient(res)
+    }
+  })
+})
+```
+
+#### Class-Based (OOP) Paradigm
+
+Use the `@Timeout(ms)` decorator on any controller method:
+
+```typescript filename="src/http/ai/controller.ts"
+import { Controller, Post, Timeout } from 'exisjs/decorators'
+
+@Controller('/ai')
+export default class AiController {
+  @Post('/inference')
+  @Timeout(120000)
+  async runInference() {
+    return await computeModel()
+  }
+}
+```
+
+---
+
+### Declarative Route Uploads
+
+You can configure file uploads directly within functional route declarations:
+
+```typescript filename="src/http/media/route.ts"
+import { controller, route } from 'exisjs/router'
+
+export default controller({
+  upload: route.post('/photo', {
+    upload: {
+      field: 'file',
+      maxSize: '10MB',
+      allowedMimeTypes: ['image/jpeg', 'image/png', 'image/webp'],
+      destination: 'memory', // 'memory' | 'disk' | 'stream'
+    },
+    async handle({ file, fields, req }) {
+      // file.buffer, file.mimetype, file.filename are immediately accessible
+      return { success: true, filename: file.filename }
+    }
+  })
+})
+```
+
+### Class-Based (OOP) Upload Decorators
+
+Use `@UseUpload` or `@Upload` to configure file parsing on controller actions:
+
+```typescript filename="src/http/media/controller.ts"
+import { Controller, Post, UseUpload, UploadedFile, Body } from 'exisjs/decorators'
+
+@Controller('/media')
+export default class MediaController {
+  @Post('/photo')
+  @UseUpload({
+    field: 'file',
+    maxSize: '10MB',
+    allowedMimeTypes: ['image/jpeg', 'image/png', 'image/webp'],
+    destination: 'memory',
+  })
+  async uploadPhoto(@UploadedFile() file: any, @Body() fields: any) {
+    return { filename: file.filename, size: file.size }
+  }
+}
+```
+
+### Express / Connect Multer Bridge (`fromExpress`)
+
+Seamlessly run existing Express/Connect middleware such as **Multer** directly in ExisJS without manual Promise wrapping:
+
+```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() })
+
+export default controller({
+  upload: route.post('/', 
+    fromExpress(upload.single('file')),
+    ({ req }) => {
+      const file = (req.raw as any).file || req.file
+      return { success: true, originalname: file?.originalname }
+    }
+  )
+})
+```
+

package/dist/docs/content/providers.mdx

@@ -177,3 +177,92 @@ export class OperationContext {
 > [!WARNING]
 > **Request Scope Constraints**: A provider marked as `scope: 'request'` **must** be resolved within the lifecycle of an active HTTP request. If you try to `inject()` or resolve a request-scoped provider during application startup, inside a background queue worker, or from a cron job, the container will throw a runtime error.
 
+---
+
+## Database Providers & Lifecycle Interop (`exisjs/database`)
+
+ExisJS provides first-party lifecycle management and transaction coordination for databases (PostgreSQL, SQLite, MySQL, MongoDB, Prisma, Drizzle, Mongoose).
+
+### 1. Registering Database Lifecycle (`registerDatabase`)
+
+Registering your database with `registerDatabase` ensures connections are automatically connected on boot and safely closed with zero leaked sockets when the server receives `SIGTERM` / `SIGINT`:
+
+```typescript filename="src/http/server.ts"
+import { exis } from 'exisjs'
+import { registerDatabase } from 'exisjs/database'
+import mongoose from 'mongoose'
+
+export default exis({
+  async onStart(app) {
+    // Automatically handles startup and graceful shutdown
+    registerDatabase(app, {
+      name: 'mongodb',
+      connect: async () => {
+        await mongoose.connect(process.env.MONGODB_URI!)
+      },
+      disconnect: async () => {
+        await mongoose.disconnect()
+      },
+      healthCheck: async () => {
+        return mongoose.connection.readyState === 1
+      },
+    })
+  }
+})
+```
+
+### 2. Universal Transaction Runner (`withTransaction`)
+
+`withTransaction` provides a duck-typed transaction runner that automatically coordinates transaction lifecycles, commits, aborts, and session cleanups across different ORMs:
+
+```typescript filename="src/http/orders/service.ts"
+import { withTransaction } from 'exisjs/database'
+import mongoose from 'mongoose'
+import { Order } from '@/models/Order'
+import { Inventory } from '@/models/Inventory'
+
+export async function placeOrder(customerId: string, items: { sku: string; qty: number }[]) {
+  return withTransaction(mongoose, async (session) => {
+    // Automatically attaches session to queries and commits/aborts on error
+    const order = await Order.create([{ customerId, items }], { session })
+    
+    for (const item of items) {
+      const updated = await Inventory.findOneAndUpdate(
+        { sku: item.sku, stock: { $gte: item.qty } },
+        { $inc: { stock: -item.qty } },
+        { session, returnDocument: 'after' }
+      )
+      if (!updated) {
+        throw new Error(`Insufficient stock for SKU: ${item.sku}`)
+      }
+    }
+
+    return order[0]
+  })
+}
+```
+
+Works identically with Prisma (`prisma.$transaction`) and Drizzle (`db.transaction`).
+
+### 3. Modern Mongoose 8/9 Interop & Connection Pooling
+
+ExisJS exports helpers to prevent deprecation warnings in modern Mongoose:
+
+```typescript filename="src/models/user.ts"
+import { modernUpdateOptions, mongoPoolOptions } from 'exisjs/database'
+import mongoose from 'mongoose'
+
+// Cloud-hardened pool options (maxPoolSize, serverSelectionTimeoutMS, etc.)
+export const poolConfig = mongoPoolOptions({ maxPoolSize: 50 })
+
+// Automatically maps legacy { new: true } to { returnDocument: 'after' }
+export async function updateUsername(id: string, name: string) {
+  return User.findByIdAndUpdate(
+    id,
+    { $set: { name } },
+    modernUpdateOptions({ returnDocument: 'after' })
+  )
+}
+```
+
+

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.