exisjs 0.7.2 → 0.7.4

package/dist/docs/content/cli/commands.mdx

@@ -85,16 +85,18 @@ $ npx exisjs g <type> <name> [options]
 
 | Option | Description |
 | :--- | :--- |
+| `-n, --named` | Names generated files using the feature prefix (e.g. `<name>.route.ts`, `<name>.schema.ts`, `<name>.service.ts`). |
 | `--oop` | Generates using Class-Based (OOP) decorators instead of Functional syntax. |
 
 **Supported Schematics**
 
 | Schematic | Alias | Description | Output Path |
 | :--- | :--- | :--- | :--- |
-| `resource` | | Complete domain slice (`schema.ts`, `service.ts`, `boundary.ts`, `route.ts`) | `src/http/<name>/` |
+| `crud` | `resource` | Full 4-file CRUD slice (`schema.ts`, `service.ts`, `route.ts`, and `model.ts` entity), 100% database-agnostic | `src/http/<name>/` & `src/models/` |
+| `model` | | Standalone database-agnostic TypeScript entity and input types | `src/models/<Name>.ts` |
 | `route` | `r`, `c`, `controller` | HTTP route file | `src/http/<name>/route.ts` |
-| `service` | `s` | Injectable service / business logic | `src/http/<name>/service.ts` |
-| `schema` | `sc` | Validation schemas powered by `tex` | `src/http/<name>/schema.ts` |
+| `service` | `s` | Injectable service / business logic with pagination helpers | `src/http/<name>/service.ts` |
+| `schema` | `sc` | Validation schemas powered by `tex` (includes pagination) | `src/http/<name>/schema.ts` |
 | `boundary` | `b` | Folder-scoped configuration and request pipeline | `src/http/<name>/boundary.ts` |
 | `plugin` | `p` | Distributable plugin module | `src/plugins/<name>.ts` |
 | `middleware` | `m` | Standalone middleware handler | `src/middleware/<name>.ts` |
@@ -104,7 +106,7 @@ $ npx exisjs g <type> <name> [options]
 
 ### `exisjs routes`
 
-Analyzes and prints the application routing table to the terminal.
+Analyzes and prints the application routing table to the terminal in an interactive, formatted grid with method badges and dynamic parameter highlighting.
 
 ```bash
 $ npx exisjs routes [options]
@@ -114,7 +116,17 @@ $ npx exisjs routes [options]
 
 | Option | Description |
 | :--- | :--- |
-| `-e, --entry <file>` | Custom entry file path to bootstrap the app from. |
+| `-e, --entry <file>` | Custom entry file path to bootstrap the app from (default: `src/http/server.ts`). |
+| `-m, --method <method>` | Filter endpoints by HTTP method (e.g. `GET`, `POST`, `PUT`, `DELETE`). |
+| `-f, --filter <keyword>` | Filter endpoints matching path, method, or source file keyword. |
+| `--json` | Output the parsed routes and middleware metadata directly as structured JSON. |
+
+**Features**
+- **Method Badges**: Visually styled badges (`GET`, `POST`, `PUT`, `PATCH`, `DEL`, `ALL`).
+- **Parameter Highlighting**: Dynamically distinguishes path parameters (`:id`, `*slug`).
+- **Middleware Counting**: Displays total attached middleware / boundary steps.
+- **Source Resolution**: Displays relative file source path (e.g. `src/http/users/user.route.ts`).
+- **Summary Metrics**: Displays total endpoint counts and method breakdown.
 
 ---
 
@@ -155,6 +167,12 @@ $ npx exisjs repl [options]
 $ npx exisjs console [options]
 ```
 
+**Options**
+
+| Option | Description |
+| :--- | :--- |
+| `-e, --entry <file>` | Custom entry file path to bootstrap the REPL context. |
+
 ---
 
 ### `exisjs exports`
@@ -174,3 +192,19 @@ Displays runtime environment, Node.js version, platform, architecture, and ExisJ
 ```bash
 $ npx exisjs info
 ```
+
+---
+
+### `exisjs doctor`
+
+Performs an end-to-end diagnostic audit of the local project environment, verifying Node.js version compatibility, native Rust hardware acceleration (`@exisjs/rs`), `tsconfig.json` strictness, entry-point resolution, route naming patterns, and file-system route counts.
+
+```bash
+$ npx exisjs doctor
+```
+
+**Diagnostic Checks**
+- **Runtime**: Validates Node.js engine compatibility (v18+ recommended for N-API and worker thread pools).
+- **Native Engine**: Verifies `@exisjs/rs` compiled native binaries are active for hardware-accelerated radix tree traversal, off-heap caching, and native JSON serialization.
+- **Project Configuration**: Checks `package.json` root and `tsconfig.json` strict mode.
+- **Routes & Pipeline**: Confirms application entry point (`src/http/server.ts`), discovers active route slices, and flags non-standard or orphan file naming conventions.

package/dist/docs/content/cli/overview.mdx

@@ -79,4 +79,5 @@ $ npx exisjs g r users --oop
 | `repl` | `console` | Starts an interactive Node.js REPL loaded with the application context. |
 | `exports` | | Displays all available `@exisjs` and `exisjs/*` subpath exports. |
 | `info` | | Displays system, Node.js, and ExisJS runtime information. |
+| `doctor` | | Performs system, native Rust acceleration, TypeScript, and routing diagnostics. |
 | `init` | | Initializes a new ExisJS application in the current directory. |

package/dist/docs/content/config.mdx

@@ -140,7 +140,14 @@ Here is a full breakdown of the configuration schema:
 
 ### Global Middleware
 
-- `cors` _(object | boolean)_: Global CORS policy configuration (`origin`, `methods`, `credentials`, etc.).
+- `cors` _(object | boolean)_: Global CORS policy configuration. Supports:
+  - Exact string origins (e.g. `'https://example.com'` or `'*'`).
+  - Regular expressions (e.g. `/localhost:\d+/`).
+  - Arrays mixing strings and regexes (`['https://app.example.com', /https:\/\/.*\.domain\.com/']`).
+  - Dynamic callbacks: `(origin, cb) => ...` or async functions: `async (origin) => boolean` for multi-tenant setups.
+- `transformResponse` _(boolean | function)_: Automatically wraps all successful handler responses into a standardized envelope:
+  - When `true`: `{ success: true, data: ..., timestamp: ... }` (matching `HttpError`'s `{ success: false, error: ... }`).
+  - When a function: `(data, req, res) => ({ ... })` to provide your own custom envelope.
 - `helmet` _(object | boolean)_: Automatically secures your app with standard HTTP headers. (Enabled by default).
 - `compression` _(object | boolean)_: Enables Gzip/Brotli compression for all HTTP responses.
 - `logger` _(object | boolean)_: Configures the internal Pino-based logger (`level`, `pretty`).
@@ -148,7 +155,7 @@ Here is a full breakdown of the configuration schema:
 
 ### Performance & Security
 
-- `bodyLimit` _(number)_: The maximum allowed size (in bytes) for incoming request bodies. (Default: `1MB`)
+- `bodyLimit` _(number)_: The maximum allowed size (in bytes) for incoming request bodies. (Default: `10MB` / `10485760` bytes, raising HTTP 413 `PayloadTooLargeError` when exceeded)
 - `trustProxy` _(boolean | number)_: If true, respects `X-Forwarded-For` and `X-Forwarded-Host` headers (essential for apps deployed behind NGINX, Cloudflare, or AWS ELB). If a number, trusts that many hops.
 - `keepAlive` _(object | boolean)_: Tunes the Keep-Alive timeout and Header timeout limits.
 - `workers` _(number | 'safe' | 'max')_: Number of CPU workers for cluster mode. Defaults to 1. 'safe' caps to 2. 'max' uses all available cores.

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
@@ -247,8 +281,8 @@ You can use the `metrics` middleware to track request durations and counts.
 
 ### Functional Paradigm
 
-```typescript filename="src/http/gateway.ts"
-import { defineGateway } from 'exisjs/router'
+```typescript filename="src/http/boundary.ts"
+import { defineBoundary } from 'exisjs/router'
 import { metrics } from 'exisjs/observability'
 
 const myPrometheusAdapter = {
@@ -261,15 +295,15 @@ const myPrometheusAdapter = {
   }
 }
 
-export default defineGateway({
+export const config = defineBoundary({
   middleware: [metrics(myPrometheusAdapter)]
 })
 ```
 
 ### Class-Based (OOP) Paradigm
 
-```typescript filename="src/http/gateway.ts"
-import { Gateway } from 'exisjs/decorators'
+```typescript filename="src/http/boundary.ts"
+import { Boundary } from 'exisjs/decorators'
 import { metrics } from 'exisjs/observability'
 
 const myPrometheusAdapter = {
@@ -280,10 +314,10 @@ const myPrometheusAdapter = {
   }
 }
 
-@Gateway({
+@Boundary({
   middleware: [metrics(myPrometheusAdapter)]
 })
-export default class RootGateway {}
+export default class RootBoundary {}
 ```
 
 *Note: ExisJS normalizes dynamic paths (e.g., turning `/users/123` into `/users/:id`) to prevent metrics cardinality issues.*
@@ -294,8 +328,8 @@ ExisJS seamlessly integrates with OpenTelemetry (OTel) via the `tracing` middlew
 
 ### Functional Paradigm
 
-```typescript filename="src/http/gateway.ts"
-import { defineGateway } from 'exisjs/router'
+```typescript filename="src/http/boundary.ts"
+import { defineBoundary } from 'exisjs/router'
 import { tracing } from 'exisjs/observability'
 
 const myOtelAdapter = {
@@ -312,15 +346,15 @@ const myOtelAdapter = {
   }
 }
 
-export default defineGateway({
+export const config = defineBoundary({
   middleware: [tracing(myOtelAdapter)]
 })
 ```
 
 ### Class-Based (OOP) Paradigm
 
-```typescript filename="src/http/gateway.ts"
-import { Gateway } from 'exisjs/decorators'
+```typescript filename="src/http/boundary.ts"
+import { Boundary } from 'exisjs/decorators'
 import { tracing } from 'exisjs/observability'
 
 const myOtelAdapter = {
@@ -335,10 +369,10 @@ const myOtelAdapter = {
   }
 }
 
-@Gateway({
+@Boundary({
   middleware: [tracing(myOtelAdapter)]
 })
-export default class RootGateway {}
+export default class RootBoundary {}
 ```
 
 By providing these standard interfaces natively, your application metrics and traces are bound to the ExisJS router lifecycle.

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' })
+  )
+}
+```
+
+