exisjs 0.7.3 → 0.7.4

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/validation.mdx

@@ -38,11 +38,17 @@ ExisJS supports a comprehensive set of strict validation primitives:
 - `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.array(schema)` - Validates an array of items. 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 +223,95 @@ 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 }),
+  }),
+})
+```
 
-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.
+#### 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`.
+
+---
+
+## 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
+})
 
-```json filename="Response"
+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, 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="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.

package/dist/docs/reference/validator.mdx

@@ -21,17 +21,50 @@ The `tex` object provides factory functions for every common primitive and data
 
 ### Objects & Arrays
 
-- `tex.object({ ... })`: Validates an object against a strict shape.
-- `tex.array(schema)`: Validates an array of items matching the given schema.
+- `tex.object({ ... })`: Validates an object against a strict shape. Supports arbitrarily nested sub-documents (`tex.object({ nested: tex.object(...) })`).
+- `tex.array(schema, options?)`: Validates an array of items matching the given schema.
+  - **Schema Types**: Accepts primitive types (`tex.string()`), nested `tex.object(...)`, or shorthand plain objects (`tex.array({ ... })`).
+  - **TypeScript Inference**: TypeScript automatically infers the element object shape for both `tex.object(...)` and plain objects without falling back to `never`.
+  - **Single-Object Coercion**: Automatically coerces single objects (e.g. `{ item: { ... } }` from HTML forms) into single-item arrays `[ { ... } ]` rather than throwing `"Must be an array"`.
+  - **Stringified JSON**: Automatically parses and deserializes stringified JSON arrays (e.g. from `multipart/form-data`).
+  - **Options**: Supports `{ min, max, dedupe, optional, nullable, nullish }`.
 
 ```typescript
 const UserProfile = tex.object({
   id: tex.string(),
-  tags: tex.array(tex.string()),
-  role: tex.enum(['admin', 'user'])
+  profile: tex.object({
+    bio: tex.string().nullish(), // allows undefined, null, or ""
+    skills: tex.array(tex.string()),
+  }),
+  // Can use plain object shorthand directly inside tex.array
+  items: tex.array({
+    id: tex.string(),
+    quantity: tex.number({ min: 1 }),
+  }),
+  role: tex.enum(['admin', 'user']),
 })
 ```
 
+### Pagination Primitive (`tex.pagination`)
+
+- `tex.pagination(options?)`: Pre-compiled query schema validating `page` (default 1), `limit` (with coercion and clamping), `sort`, and `order` (`asc` | `desc`).
+
+```typescript
+import { tex, paginate, getPaginationSkip } from 'exisjs/validator'
+
+const paginationSchema = tex.pagination({
+  defaultLimit: 20,
+  maxLimit: 100,
+})
+
+// Database offset calculation helper
+const { skip, limit, page } = getPaginationSkip({ page: 2, limit: 20 })
+// skip = 20, limit = 20, page = 2
+
+// Standardized envelope builder
+const paginatedResponse = paginate(items, 150, { page: 2, limit: 20 })
+```
+
 ---
 
 ## Usage in Routes
@@ -78,9 +111,14 @@ export default controller({
 
 All validators accept an options object that allows you to configure validation constraints and behaviors.
 
-- `optional`: Marks the field as optional (allows `undefined`).
+- `optional` / `.optional()`: Marks the field as optional (allows `undefined`).
+- `nullable` / `.nullable()`: Marks the field as nullable (allows `null`).
+- `nullish` / `.nullish()`: Marks the field as nullish (allows both `null` and `undefined`).
 - `coerce`: Instructs the Rust engine to automatically convert types when possible before validating. For example, converting `"123"` into a number, or `3000` into a string.
 
+> [!NOTE]
+> **Empty String Interop**: If an incoming string is empty (`""`), and the field is configured as `optional`, `nullable`, or `nullish`, ExisJS automatically converts it to `undefined` or `null` before running type checks. This cleanly handles form submissions and query strings without requiring ad-hoc pre-processors.
+
 ```typescript
 // Type Conversion Examples using { coerce: true }
 const EnvSchema = tex.object({

package/dist/error/errors.d.ts

@@ -11,6 +11,7 @@ export declare class HttpError extends Error {
     static notFound(resource?: string): HttpError;
     static conflict(message: string): HttpError;
     static unprocessable(message: string, details?: unknown): HttpError;
+    static payloadTooLarge(message?: string, details?: unknown): HttpError;
     static tooManyRequests(message?: string): HttpError;
     static internal(message?: string): HttpError;
     static serviceUnavailable(message?: string): HttpError;
@@ -35,6 +36,9 @@ export declare class ConflictError extends HttpError {
 export declare class UnprocessableError extends HttpError {
     constructor(message?: string, details?: unknown);
 }
+export declare class PayloadTooLargeError extends HttpError {
+    constructor(message?: string, details?: unknown);
+}
 export declare class RateLimitError extends HttpError {
     constructor(message?: string);
 }
@@ -53,11 +57,17 @@ export declare const UnauthorizedException: typeof UnauthorizedError;
 export declare const ForbiddenException: typeof ForbiddenError;
 export declare const NotFoundException: typeof NotFoundError;
 export declare const ConflictException: typeof ConflictError;
+export declare const PayloadTooLargeException: typeof PayloadTooLargeError;
 export declare const UnprocessableException: typeof UnprocessableError;
 export declare const RateLimitException: typeof RateLimitError;
 export declare const InternalException: typeof InternalError;
 export declare const ServiceUnavailableException: typeof ServiceUnavailableError;
 export declare const GatewayTimeoutException: typeof GatewayTimeoutError;
+export declare function renderValidationTable(rows: {
+    field: string;
+    received: string;
+    expected: string;
+}[]): string;
 export declare function createErrorHandler(isDev?: boolean): ErrorHandler;
 /**
  * Async handler wrapper — catches promise rejections.

package/dist/error/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/error/errors.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,UAAU,CAAA;AAKrD,qBAAa,SAAU,SAAQ,KAAK;IAClC,SAAgB,UAAU,EAAE,MAAM,CAAA;IAClC,SAAgB,IAAI,EAAE,MAAM,CAAA;IAC5B,SAAgB,aAAa,EAAE,OAAO,CAAA;IACtC,SAAgB,OAAO,CAAC,EAAE,OAAO,CAAA;gBAG/B,OAAO,EAAE,MAAM,EACf,UAAU,SAAM,EAChB,IAAI,SAAmB,EACvB,OAAO,CAAC,EAAE,OAAO;IAenB,MAAM,CAAC,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,SAAS;IAIhE,MAAM,CAAC,YAAY,CAAC,OAAO,SAAiB,GAAG,SAAS;IAIxD,MAAM,CAAC,SAAS,CAAC,OAAO,SAAc,GAAG,SAAS;IAIlD,MAAM,CAAC,QAAQ,CAAC,QAAQ,SAAa,GAAG,SAAS;IAIjD,MAAM,CAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS;IAI3C,MAAM,CAAC,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,SAAS;IAInE,MAAM,CAAC,eAAe,CAAC,OAAO,SAAsB,GAAG,SAAS;IAIhE,MAAM,CAAC,QAAQ,CAAC,OAAO,SAA0B,GAAG,SAAS;IAI7D,MAAM,CAAC,kBAAkB,CAAC,OAAO,SAAwB,GAAG,SAAS;IAIrE,MAAM,CAAC,cAAc,CAAC,OAAO,SAAoB,GAAG,SAAS;IAI7D,MAAM,IAAI,MAAM;CAUjB;AAED,qBAAa,eAAgB,SAAQ,SAAS;gBAChC,OAAO,SAAgB,EAAE,OAAO,CAAC,EAAE,OAAO;CAIvD;AAED,qBAAa,iBAAkB,SAAQ,SAAS;gBAClC,OAAO,SAAiB;CAIrC;AAED,qBAAa,cAAe,SAAQ,SAAS;gBAC/B,OAAO,SAAc;CAIlC;AAED,qBAAa,aAAc,SAAQ,SAAS;gBAC9B,QAAQ,SAAa;CAIlC;AAED,qBAAa,aAAc,SAAQ,SAAS;gBAC9B,OAAO,SAAa;CAIjC;AAED,qBAAa,kBAAmB,SAAQ,SAAS;gBACnC,OAAO,SAAyB,EAAE,OAAO,CAAC,EAAE,OAAO;CAIhE;AAED,qBAAa,cAAe,SAAQ,SAAS;gBAC/B,OAAO,SAAsB;CAI1C;AAED,qBAAa,aAAc,SAAQ,SAAS;gBAC9B,OAAO,SAA0B;CAI9C;AAED,qBAAa,uBAAwB,SAAQ,SAAS;gBACxC,OAAO,SAAwB;CAI5C;AAED,qBAAa,mBAAoB,SAAQ,SAAS;gBACpC,OAAO,SAAoB;CAIxC;AAGD,eAAO,MAAM,aAAa,kBAAY,CAAA;AACtC,eAAO,MAAM,mBAAmB,wBAAkB,CAAA;AAClD,eAAO,MAAM,qBAAqB,0BAAoB,CAAA;AACtD,eAAO,MAAM,kBAAkB,uBAAiB,CAAA;AAChD,eAAO,MAAM,iBAAiB,sBAAgB,CAAA;AAC9C,eAAO,MAAM,iBAAiB,sBAAgB,CAAA;AAC9C,eAAO,MAAM,sBAAsB,2BAAqB,CAAA;AACxD,eAAO,MAAM,kBAAkB,uBAAiB,CAAA;AAChD,eAAO,MAAM,iBAAiB,sBAAgB,CAAA;AAC9C,eAAO,MAAM,2BAA2B,gCAA0B,CAAA;AAClE,eAAO,MAAM,uBAAuB,4BAAsB,CAAA;AA6G1D,wBAAgB,kBAAkB,CAAC,KAAK,UAAQ,GAAG,YAAY,CAoH9D;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,EAAE,EAAE,OAAO,GAAG,OAAO,CAIjD"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/error/errors.ts"],"names":[],"mappings":"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"}