exisjs 0.7.3 → 0.7.5

package/dist/docs/content/structure.mdx

@@ -23,6 +23,7 @@ my-backend/
 ├── src/
 │   ├── http/
 │   │   ├── server.ts         # Application entry point
+│   │   ├── error.ts          # Centralized framework exception handler (onError)
 │   │   ├── route.ts          # Root routes (e.g. GET /api)
 │   │   ├── boundary.ts       # Root boundary (config + request pipeline)
 │   │   ├── users/
@@ -72,6 +73,7 @@ Both styles are automatically detected by the route scanner, CLI manifest genera
 | `schema.ts` / `*.schema.ts` | `tex` validation schemas, imported by route files. Mandatory for every route accepting input. | Handlers, routing |
 | `service.ts` / `*.service.ts` | Business logic and data access. DI-injectable. | Routing, response shaping |
 | `boundary.ts` / `*.boundary.ts` | Folder-scoped config + request pipeline for everything in this folder and below. | — |
+| `error.ts` / `*.error.ts` | Centralized exception and validation error handler (`onError`). Auto-mounted by the framework. | Business logic, routes |
 
 ---
 
@@ -172,14 +174,16 @@ A `boundary.ts` applies to every route in its folder and all subfolders. It has
 two independent halves:
 
 1. **Config** — pure data, via `defineBoundary()` (functional) or `@Boundary()`
-   (OOP argument). CORS, headers, DI providers, excluded paths.
-2. **Pipeline** — real code, auto-detected by function signature. No imports,
+   (OOP argument). CORS, headers, DI providers, excluded paths, and lifecycle hooks.
+2. **Pipeline & Hooks** — real code, auto-detected by function signature. No imports,
    no manual registration required.
 
-| Signature                                                                    | Detected as  | Runs                                                 |
-| ---------------------------------------------------------------------------- | ------------ | ---------------------------------------------------- |
-| `(req, res, next)`                                                           | A chain step | In file/declaration order, before the route          |
-| `(ctx, next)` — default export (functional) or a method named `handle` (OOP) | The wrapper  | Around all chain steps and the nested route/boundary |
+| Signature | Detected as | Runs |
+| :--- | :--- | :--- |
+| `(req, res, next)` | Chain Step | In file/declaration order, before the route handler |
+| `beforeHandle(req, res)` | Boundary Guard Hook | Immediately before route execution. Short-circuits on `false` or when headers sent |
+| `afterHandle(req, res, data)` | Response Hook | Immediately after route execution. Receives returned data to transform or audit |
+| `(ctx, next)` — default export (functional) or `handle(ctx, next)` (OOP) | Pipeline Wrapper | Around all chain steps and the nested route/boundary |
 
 ### Functional
 
@@ -190,11 +194,25 @@ import type { Request, Response, Next, BoundaryContext } from "exisjs/router";
 export const config = defineBoundary({
   cors: { origin: ["https://myapp.com"], credentials: true },
   headers: { "X-Powered-By": "ExisJS" },
-  exclude: [{ path: "/health", method: "GET" }],
+  exclude: [{ path: "/admin/health", method: "GET" }],
+
+  // Pre-handler hook (returns false to block with 403, or sends response)
+  beforeHandle(req, res) {
+    if (req.headers["x-role"] !== "admin") {
+      res.status(403).json({ error: "Admin role required" });
+      return false;
+    }
+  },
+
+  // Post-handler hook (transforms returned payload or performs async audit)
+  afterHandle(req, res, data) {
+    res.setHeader("X-Audited-By", "AdminBoundary");
+    return { ...data, auditedAt: Date.now() };
+  },
 });
 
-export function auth(req: Request, res: Response, next: Next) {
-  if (!req.headers["x-api-key"]) throw new UnauthorizedError("Missing API key");
+export function logStep(req: Request, res: Response, next: Next) {
+  console.log(`[Admin] ${req.method} ${req.path}`);
   next();
 }
 
@@ -216,14 +234,29 @@ import type { Request, Response, Next, BoundaryContext } from "exisjs/router";
 @Boundary({
   cors: { origin: ["https://myapp.com"], credentials: true },
   headers: { "X-Powered-By": "ExisJS" },
+  exclude: ["/admin/health"],
 })
 export default class AdminBoundary {
-  auth(req: Request, res: Response, next: Next) {
-    if (!req.headers["x-api-key"])
-      throw new UnauthorizedError("Missing API key");
+  // Pre-handler hook
+  beforeHandle(req: Request, res: Response) {
+    if (req.headers["x-role"] !== "admin") {
+      res.status(403).json({ error: "Admin role required" });
+      return false;
+    }
+  }
+
+  // Post-handler hook
+  afterHandle(req: Request, res: Response, data: any) {
+    return { ...data, auditedAt: Date.now() };
+  }
+
+  // Chain step
+  logStep(req: Request, res: Response, next: Next) {
+    console.log(`[Admin] ${req.method} ${req.path}`);
     next();
   }
 
+  // Wrapper
   async handle(ctx: BoundaryContext, next: Next) {
     try {
       return { success: true, data: await next() };
@@ -234,6 +267,52 @@ export default class AdminBoundary {
 }
 ```
 
+---
+
+## `src/http/error.ts` (Framework-Level Exception Handler)
+
+ExisJS natively discovers and mounts `src/http/error.ts` (or `error.js`) at boot. It exports an `onError(err, req, res)` handler, giving developers a single, standard place to intercept, log, and format all unhandled or validation errors without writing custom `app.onError` boilerplate inside `server.ts`.
+
+### Functional
+
+```typescript filename="src/http/error.ts"
+import type { Request, Response } from "exisjs";
+
+export function onError(err: any, req: Request, res: Response) {
+  const status = err.statusCode || err.status || 500;
+
+  // Format consistent error response across the entire API
+  res.status(status).json({
+    success: false,
+    error: {
+      message: err.message || "Internal Server Error",
+      code: err.code || "INTERNAL_SERVER_ERROR",
+      path: req.path,
+    },
+  });
+}
+```
+
+### Class-Based (OOP)
+
+```typescript filename="src/http/error.ts"
+import type { Request, Response } from "exisjs";
+
+export default class GlobalErrorHandler {
+  onError(err: any, req: Request, res: Response) {
+    const status = err.statusCode || err.status || 500;
+    res.status(status).json({
+      success: false,
+      error: {
+        message: err.message || "Internal Server Error",
+        code: err.code || "INTERNAL_ERROR",
+        path: req.path,
+      },
+    });
+  }
+}
+```
+
 A nested folder's `boundary.ts` always runs _inside_ its parent's `next()` —
 pipeline depth mirrors folder depth automatically.
 

package/dist/docs/content/validation.mdx

@@ -32,17 +32,25 @@ const safeData = userSchema.parse(rawInput)
 
 ExisJS supports a comprehensive set of strict validation primitives:
 
-- `tex.string()` - String validation (supports options like `{ min: 5, max: 10 }`).
+- `tex.string()` - String validation (supports options like `{ min: 5, max: 10, pattern: /regex/ }`).
 - `tex.email()` - Validates standard email formatting.
-- `tex.number()` - Strict number validation (fails if passed a string).
+- `tex.number()` - Strict number validation (fails if passed a string unless `coerce: true`).
+- `tex.number({ coerce: true, min: 0, max: 100 })` - Automatically coerces incoming string representations (e.g., query params) into native numbers.
 - `tex.boolean()` - Strict boolean validation.
-- `tex.number({ coerce: true })` - Automatically coerces incoming string representations into native JavaScript numbers.
 - `tex.boolean({ coerce: true })` - Coerces `"true"`/`"1"` and `"false"`/`"0"` into native booleans.
-- `tex.array(schema)` - Validates an array of items.
+- `tex.date()` - Strict Date instance validation.
+- `tex.date({ coerce: true, minDate: new Date('2020-01-01'), maxDate: new Date() })` - Automatically parses ISO 8601 strings, UNIX timestamps, or date strings into native JavaScript `Date` objects with optional boundary checks.
+- `tex.array(schema, { coerce: true, min: 1, max: 10 })` - Validates an array of items. When `{ coerce: true }` is enabled, automatically converts single items or comma-separated query strings (`"apple,banana"`) into typed arrays. Accepts primitive types, `tex.object(...)`, or shorthand plain objects `{ ... }`.
 - `tex.object({ ... })` - Validates structured JSON objects.
 - `tex.enum(['A', 'B'])` - Ensures the value matches one of the provided exact strings.
 
-All primitives accept an options object where you can pass `{ optional: true }` to allow `undefined`.
+All primitives accept modifier options or chained helper methods:
+- `.optional()` / `{ optional: true }` - Allows `undefined`.
+- `.nullable()` / `{ nullable: true }` - Allows `null`.
+- `.nullish()` / `{ nullish: true }` - Allows both `null` and `undefined`.
+
+> [!TIP]
+> **Automatic Empty String `""` Normalization**: When forms or query parameters pass empty strings `""` for fields marked as `.optional()`, `.nullable()`, or `.nullish()`, ExisJS automatically converts them to `undefined` or `null` before running type validation. This prevents false positive type errors on numeric, UUID, or enum fields!
 
 ### Data Sanitization (Trimming & Formatting)
 
@@ -217,16 +225,129 @@ export default class BooksController {
 ```
 
 
-## Error Handling
+### Nested Sub-Documents & Array Schemas
+
+ExisJS natively validates arbitrarily deep sub-documents and nested arrays off-heap with Rust acceleration:
+
+```typescript filename="src/http/users/schema.ts"
+import { tex } from 'exisjs/validator'
+
+export const RegisterUserSchema = tex.object({
+  username: tex.string({ min: 3 }),
+  profile: tex.object({
+    bio: tex.string().nullish(), // allows undefined, null, or ""
+    avatarUrl: tex.string({ optional: true }),
+    socials: tex.object({
+      twitter: tex.string({ optional: true }),
+      github: tex.string({ optional: true }),
+    }),
+    tags: tex.array(tex.string({ min: 2 })),
+  }),
+  // You can use tex.object(...) OR a plain object schema shorthand!
+  items: tex.array({
+    sku: tex.string(),
+    quantity: tex.number({ min: 1 }),
+  }),
+})
+```
+
+#### First-Class Form & Multipart Support
+- **Single-Object Coercion**: When HTML forms or mobile clients submit a single item instead of an array (e.g. `{ items: { sku: "ABC", quantity: 1 } }`), the Rust engine automatically coerces it into a single-element array `[ { sku: "ABC", quantity: 1 } ]` rather than throwing `"Must be an array"`.
+- **Stringified JSON Support**: When submitting `multipart/form-data`, stringified JSON arrays (e.g. `items: "[{\"sku\":\"ABC\",\"quantity\":2}]"`) or stringified objects are automatically deserialized and validated.
+- **Type Inference**: TypeScript automatically infers the shape of array elements for both `tex.array(tex.object(...))` and `tex.array({ ... })`, ensuring full autocomplete without falling back to `never`.
+
+### Query String Array & Date Coercion
+
+Query strings in HTTP cannot natively represent arrays or date instances. ExisJS solves this elegantly through `{ coerce: true }`:
+
+```typescript filename="src/http/events/route.ts"
+import { controller, route } from 'exisjs/router'
+import { tex } from 'exisjs/validator'
+
+const FilterSchema = tex.object({
+  // Coerces ISO 8601 strings (?from=2026-09-01T00:00:00Z) into Date instances
+  from: tex.date({ coerce: true, optional: true }),
+  to: tex.date({ coerce: true, optional: true }),
+  
+  // Coerces both comma-separated strings (?tags=tech,ai) AND repeated params (?tags=tech&tags=ai)
+  // or single values (?tags=tech -> ['tech']) into a typed array of strings
+  tags: tex.array(tex.string(), { coerce: true, optional: true }),
+
+  // Numbers within comma-separated arrays (?ids=1,2,3 -> [1, 2, 3]) are also coerced
+  ids: tex.array(tex.number({ coerce: true }), { coerce: true, optional: true })
+})
+
+export default controller({
+  listEvents: route.get('/events', {
+    query: FilterSchema,
+    handle({ query, res }) {
+      // query.from is Date | undefined
+      // query.tags is string[] | undefined
+      // query.ids is number[] | undefined
+      res.json({ filter: query })
+    }
+  })
+})
+```
+
+---
+
+## Pagination Schemas (`tex.pagination`)
+
+ExisJS provides a dedicated schema primitive for query pagination. It automatically coerces incoming string query parameters (`?page=2&limit=25&sort=name&order=asc`) into typed numbers and strings while enforcing sensible bounds:
+
+```typescript filename="src/http/items/route.ts"
+import { controller, route } from 'exisjs/router'
+import { tex, paginate, getPaginationSkip } from 'exisjs/validator'
+
+const ItemQuerySchema = tex.pagination({
+  defaultLimit: 20, // Default items per page if omitted
+  maxLimit: 100,    // Hard cap to prevent memory exhaustion
+})
+
+export default controller({
+  list: route.get('/', {
+    query: ItemQuerySchema,
+    async handle({ query }) {
+      const { skip, limit, page } = getPaginationSkip(query)
+      const items = await fetchItems({ skip, limit, sort: query.sort, order: query.order })
+      const total = await countItems()
+      
+      return paginate(items, total, { page, limit })
+    }
+  })
+})
+```
+
+---
+
+## Error Handling & Developer Diagnostics
 
-If a request fails validation (e.g., missing a required body field), the validation engine will instantly catch it and return a standardized `400 Bad Request` JSON response to the client.
+If a request fails validation, ExisJS intercepts the rejection and returns a standardized `400 Bad Request` containing a machine-readable `errors: Record<string, string>` dictionary for frontend form field mapping:
 
-```json filename="Response"
+```json filename="HTTP 400 Bad Request Response"
 {
   "statusCode": 400,
   "error": "Bad Request",
-  "message": "Validation Error: body.username is required"
+  "message": "Validation Error: username: Field must be at least 4 characters, profile.tags: Expected array of strings",
+  "errors": {
+    "username": "Field must be at least 4 characters",
+    "profile.tags": "Expected array of strings"
+  }
 }
 ```
 
-Because this is built right into the framework, you don't have to manually catch errors or construct complex schema error formatters. It just works exactly as you expect!
+### Dev Mode Terminal Diagnostics
+
+When validation fails in development mode, ExisJS prints an immediate tabular diagnostic to your terminal displaying the failing HTTP part, exact field path, received value, and expected schema constraint:
+
+```text
+[VALIDATION FAILED] POST /visits (part: body)
+┌─────────────┬───────────────────────────┬──────────────────┐
+│ Field       │ Received                  │ Expected         │
+├─────────────┼───────────────────────────┼──────────────────┤
+│ phone       │ "123"                     │ min: 7, max: 20  │
+│ idProofs    │ "[object Object]"         │ Array of IDProof │
+└─────────────┴───────────────────────────┴──────────────────┘
+```
+

package/dist/docs/reference/database.mdx

@@ -0,0 +1,152 @@
+---
+title: "Database"
+description: "API Reference for ExisJS Database Lifecycle & Transactions (exisjs/database)."
+---
+
+# Database (`exisjs/database`)
+
+ExisJS provides a unified, database-agnostic lifecycle and transaction layer. It enables automatic connection management, multi-database health checks, graceful zero-downtime teardowns, and ORM-agnostic transaction runners.
+
+---
+
+## 1. Lifecycle Management
+
+### `registerDatabase(app, options)`
+
+Registers a database connection into the application lifecycle. Automatically calls `connect()` during server boot and `disconnect()` during graceful shutdown (`SIGTERM`, `SIGINT`, or `app.close()`).
+
+#### Options (`DatabaseRegistrationOptions`)
+- `name` (`string`): Unique identifier for the database connection (e.g. `'postgres'`, `'mongodb'`).
+- `connect` (`() => Promise<void>`): Async callback to establish connection and connection pools.
+- `disconnect` (`() => Promise<void>`): Async callback to close connections gracefully.
+- `healthCheck` (`() => Promise<boolean>`): Optional health check callback returning `true` when healthy.
+
+```typescript filename="src/http/server.ts"
+import { exis } from 'exisjs'
+import { registerDatabase } from 'exisjs/database'
+import { PrismaClient } from '@prisma/client'
+
+const prisma = new PrismaClient()
+
+export default exis({
+  async onStart(app) {
+    registerDatabase(app, {
+      name: 'prisma-postgres',
+      connect: async () => {
+        await prisma.$connect()
+      },
+      disconnect: async () => {
+        await prisma.$disconnect()
+      },
+      healthCheck: async () => {
+        await prisma.$queryRaw`SELECT 1`
+        return true
+      },
+    })
+  }
+})
+```
+
+---
+
+### `DatabaseManager`
+
+Singleton registry managing all registered database adapters.
+
+- `DatabaseManager.register(options)`: Registers a database adapter.
+- `DatabaseManager.connectAll()`: Connects all registered databases concurrently.
+- `DatabaseManager.disconnectAll()`: Gracefully disconnects all databases concurrently.
+- `DatabaseManager.checkHealth()`: Runs health checks across all registered databases and returns `{ healthy: boolean, databases: Record<string, boolean> }`.
+- `DatabaseManager.clear()`: Clears all registered database adapters (useful for test tear-downs).
+
+```typescript filename="src/http/health/route.ts"
+import { controller, route } from 'exisjs/router'
+import { DatabaseManager } from 'exisjs/database'
+
+export default controller({
+  check: route.get('/health', async () => {
+    const health = await DatabaseManager.checkHealth()
+    return {
+      status: health.healthy ? 'ok' : 'degraded',
+      databases: health.databases,
+    }
+  })
+})
+```
+
+---
+
+## 2. Universal Transaction Runner
+
+### `withTransaction(client, callback)`
+
+A duck-typed transaction runner that coordinates database transaction lifecycles, commits, rollbacks, and session cleanups. Compatible with **Mongoose**, **Prisma**, and **Drizzle**.
+
+```typescript filename="src/services/transfer.ts"
+import { withTransaction } from 'exisjs/database'
+import mongoose from 'mongoose'
+import { Account } from '@/models/Account'
+
+export async function transferFunds(fromId: string, toId: string, amount: number) {
+  return withTransaction(mongoose, async (session) => {
+    // Session is automatically attached to MongoDB queries
+    const sender = await Account.findByIdAndUpdate(
+      fromId,
+      { $inc: { balance: -amount } },
+      { session, returnDocument: 'after' }
+    )
+
+    if (!sender || sender.balance < 0) {
+      // Throwing an error automatically aborts the transaction and rolls back
+      throw new Error('Insufficient funds')
+    }
+
+    const receiver = await Account.findByIdAndUpdate(
+      toId,
+      { $inc: { balance: amount } },
+      { session, returnDocument: 'after' }
+    )
+
+    return { sender, receiver }
+  })
+}
+```
+
+Works identically with Prisma:
+```typescript
+import { withTransaction } from 'exisjs/database'
+import { prisma } from '@/lib/prisma'
+
+const result = await withTransaction(prisma, async (tx) => {
+  return tx.user.create({ data: { name: 'Alice' } })
+})
+```
+
+---
+
+## 3. Mongoose 8/9 Interop & Pooling
+
+### `modernUpdateOptions(options?)`
+
+Maps deprecated Mongoose options (such as `{ new: true }`) to standard modern options (`{ returnDocument: 'after' }`), eliminating console warnings when upgrading to Mongoose 8 and 9.
+
+```typescript
+import { modernUpdateOptions } from 'exisjs/database'
+
+// Passes { returnDocument: 'after' } warning-free
+User.findByIdAndUpdate(id, { $set: updateData }, modernUpdateOptions())
+```
+
+### `mongoPoolOptions(customOptions?)`
+
+Returns pre-configured, production-hardened MongoDB connection pool settings:
+
+```typescript
+import { mongoPoolOptions } from 'exisjs/database'
+import mongoose from 'mongoose'
+
+await mongoose.connect(process.env.MONGODB_URI!, mongoPoolOptions({
+  maxPoolSize: 100,
+  minPoolSize: 10,
+}))
+```

package/dist/docs/reference/decorators.mdx

@@ -68,6 +68,8 @@ Parameter decorators automatically extract data from the incoming request and in
 - `@Param(nameOrPipe?)`: Injects a URL path parameter (e.g., `id` from `/:id`).
 - `@Headers(nameOrPipe?)`: Injects an HTTP header by name.
 - `@QueryParam(nameOrPipe?)` / `@Query(nameOrPipe?)`: Injects a URL query parameter (e.g., `?search=term`).
+- `@UploadedFile()`: Injects the uploaded file (`req.file`) into the method argument.
+- `@UploadedFiles()`: Injects the uploaded files array or dictionary (`req.files`) into the method argument.
 - `@HostParam(nameOrPipe?)`: Injects a subdomain parameter.
 - `@Req()`: Injects the raw ExisJS Request object.
 - `@Res(options?)`: Injects the raw ExisJS Response object (`{ passthrough: true }`).
@@ -80,6 +82,8 @@ Parameter decorators automatically extract data from the incoming request and in
 ## 3. Middleware & Pipeline Decorators
 
 - `@Use(...middlewaresOrGuardsOrInterceptorsOrFilters)`: Unified decorator that binds middlewares, guards (`canActivate`), interceptors (`intercept`), or exception filters (`catch`) to a controller class or method.
+- `@Upload(fieldName, options?)` / `@UseUpload(...)`: Configures multipart file upload handling for a method, populating `@UploadedFile()` or `@UploadedFiles()`.
+- `@Timeout(ms: number | TimeoutOptions)`: Overrides the request timeout for this method (e.g. `@Timeout(120000)`). Passing `0` disables timeouts for long-running streaming or exports.
 - `@Idempotent(options?)`: Caches responses based on the `Idempotency-Key` header using native in-memory off-heap storage.
 
 ---

package/dist/docs/reference/error.mdx

@@ -61,6 +61,7 @@ export default controller({
 - `HttpError.forbidden(msg?)` (403)
 - `HttpError.notFound(resource?)` (404)
 - `HttpError.conflict(msg)` (409)
+- `HttpError.payloadTooLarge(msg?)` (413)
 - `HttpError.unprocessable(msg, details?)` (422)
 - `HttpError.tooManyRequests(msg?)` (429)
 - `HttpError.internal(msg?)` (500)
@@ -83,7 +84,7 @@ If you catch an `HttpError` or intercept it, you have access to the following pr
 If you prefer class instantiation (common in NestJS workflows), you can directly instantiate the error classes or their `Exception` aliases.
 
 ```typescript filename="src/services/auth.ts"
-import { UnauthorizedError, ConflictException } from 'exisjs/error'
+import { UnauthorizedError, ConflictException, PayloadTooLargeError } from 'exisjs/error'
 
 export function verifyToken(token: string) {
   if (!isValid(token)) {
@@ -104,6 +105,7 @@ export function createUser(email: string) {
 - `ForbiddenError` / `ForbiddenException`
 - `NotFoundError` / `NotFoundException`
 - `ConflictError` / `ConflictException`
+- `PayloadTooLargeError` / `PayloadTooLargeException`
 - `UnprocessableError` / `UnprocessableException`
 - `RateLimitError` / `RateLimitException`
 - `InternalError` / `InternalException`

package/dist/docs/reference/middleware.mdx

@@ -62,8 +62,67 @@ app.use(helmet())
 ### `csrf(options)`
 Implements the Signed Double Submit Cookie pattern for Cross-Site Request Forgery (CSRF) protection.
 
-### `timeout(ms)`
-Automatically times out requests that exceed the specified milliseconds, returning a 503 response.
+### `timeout(options?)`
+Automatically times out requests that exceed the specified duration, returning a `503 Service Unavailable` response (or custom status code).
+
+- **Default**: `60000` (60 seconds)
+- **Options**:
+  - `ms` (`number`): Timeout duration in milliseconds.
+  - `statusCode` (`number`): Status code to respond with (default: `503`).
+  - `message` (`string`): Error message returned to the client.
+  - `exclude` (`(string | RegExp)[]`): Array of route paths or regex patterns to exempt from timeout checks.
+
+```typescript
+import { timeout } from 'exisjs/middleware'
+
+app.use(timeout({
+  ms: 60000,
+  exclude: ['/webhooks/*', '/ai/stream'],
+}))
+```
+
+Handlers can dynamically alter the active timeout using `req.setTimeout(ms)` or `req.clearTimeout()`.
+
+### `fileUpload(options?)`
+First-party multipart form data parsing and file upload middleware.
+
+- **Methods**:
+  - `fileUpload.single(fieldName, options?)`: Parses a single file into `req.file`.
+  - `fileUpload.array(fieldName, maxCount?, options?)`: Parses multiple files with the same field into `req.files` (`UploadedFile[]`).
+  - `fileUpload.fields([{ name, maxCount }])`: Parses multiple distinct fields into `req.files` (`Record<string, UploadedFile[]>`).
+  - `fileUpload.any(options?)`: Accepts any uploaded files.
+  - `fileUpload.none(options?)`: Accepts only text fields; rejects file uploads.
+- **Options**:
+  - `dest` (`string`): Directory path to save uploaded files to disk automatically.
+  - `maxBytes` (`number`): Maximum file size in bytes (shorthand for `limits.fileSize`).
+  - `mimeTypes` (`string[]`): Array of permitted MIME types (e.g. `['image/png', 'image/jpeg']`).
+  - `limits` (`{ fileSize?: number; files?: number }`): Detailed size and count limits.
+
+```typescript
+import { fileUpload } from 'exisjs/middleware'
+
+app.post('/avatar', fileUpload.single('avatar', {
+  maxBytes: 5 * 1024 * 1024,
+  mimeTypes: ['image/*'],
+}), (req, res) => {
+  const file = req.file // UploadedFile { filename, originalname, mimetype, size, buffer }
+  res.json({ success: true, filename: file.filename })
+})
+```
+
+### `fromExpress(middleware)`
+Seamlessly adapts standard Express/Connect middleware (such as `multer`) to run within the ExisJS pipeline.
+
+```typescript
+import { fromExpress } from 'exisjs/middleware'
+import multer from 'multer'
+
+const upload = multer({ dest: './uploads' })
+
+app.post('/upload', fromExpress(upload.single('file')), (req, res) => {
+  res.json({ file: (req.raw as any).file })
+})
+```
 
 ### `hpp()`
 HTTP Parameter Pollution protection.
@@ -90,6 +149,29 @@ app.use(rateLimit({
 }))
 ```
 
+### `timeout(options?)`
+Terminates long-running requests that exceed the specified threshold, responding with `503 Service Unavailable` (or custom status). Defaults to 60,000ms.
+
+```typescript
+import { timeout } from 'exisjs/middleware'
+
+app.use(timeout({
+  ms: 60000,
+  statusCode: 504,
+  message: 'Gateway Timeout',
+  exclude: ['/webhooks/*', '/ai/stream'],
+}))
+```
+
+### `routeTimeout(msOrOptions)`
+Applies an endpoint-specific timeout. If a global timeout is already active, dynamically overrides the timer for this route. If no global timeout exists, initializes an isolated timeout timer. Passing `0` disables timeouts for streaming/exports.
+
+```typescript
+import { routeTimeout } from 'exisjs/middleware'
+
+app.post('/heavy-task', routeTimeout(120000), (req, res) => { ... })
+```
+
 ### `idempotent(options?)`
 Caches responses based on the `Idempotency-Key` header into off-heap native memory to prevent duplicate mutations.
 

package/dist/docs/reference/router.mdx

@@ -78,9 +78,11 @@ export default controller({
 
 ### Options (`RouteConfig`)
 
-- `body`: A validation schema for the request body (e.g., using `v` or Zod).
-- `query`: A validation schema for the query string.
+- `body`: A validation schema for the request body (e.g., using `tex` or Zod).
+- `query`: A validation schema for the query string (e.g., `tex.pagination()`).
 - `params`: A validation schema for the URL path parameters.
+- `upload` (`string | RouteUploadOptions`): Declarative multipart upload configuration (e.g. `{ field: 'photo', maxBytes: 10 * 1024 * 1024, mimeTypes: [...] }`). Automatically mounts `fileUpload` middleware and populates `req.file` / `req.files`.
+- `timeout` (`number`): Per-route timeout override in milliseconds (e.g. `120000`). Overrides global timeout for this endpoint.
 - `response`: A validation schema to serialize/validate the outgoing response.
 - `middleware` (`Handler[]`): An array of middleware specific to this route.
 - `cors` (`boolean | CorsConfig`): Route-specific CORS overrides.