exisjs 0.7.9 → 0.7.11

package/dist/docs/content/security.mdx

@@ -1,6 +1,6 @@
 ---
-nextUrl: "/docs/structure"
-nextTitle: "Project Structure"
+nextUrl: '/docs/structure'
+nextTitle: 'Project Structure'
 ---
 
 # Security & Edge Middleware
@@ -33,7 +33,7 @@ export default exis({
     app.use(timeout(10000))
     app.use(hpp())
     app.use(mongoSanitize())
-  }
+  },
 })
 ```
 
@@ -52,9 +52,9 @@ export const config = defineBoundary({})
 // Apply rate limiting chain step across the boundary
 export const limiter = rateLimit({
   windowMs: 60 * 1000, // 1 minute window
-  max: 100,            // 100 requests per window
+  max: 100, // 100 requests per window
   message: 'Too many requests from this IP, please try again after a minute',
-  keyGenerator: (req) => req.ip // Uses normalized IPv4/IPv6 client IP
+  keyGenerator: (req) => req.ip, // Uses normalized IPv4/IPv6 client IP
 })
 ```
 
@@ -62,13 +62,13 @@ export const limiter = rateLimit({
 
 `rateLimit` automatically emits standard IETF draft and legacy rate-limiting headers on every response:
 
-| Header | Description | Example |
-| :--- | :--- | :--- |
-| `RateLimit-Limit` | Maximum request quota for the configured window. | `100` |
-| `RateLimit-Remaining` | Remaining requests permitted within the current window. | `42` |
-| `RateLimit-Reset` | Time remaining in seconds until the window quota resets. | `18` |
-| `Retry-After` | Included on `429 Too Many Requests` (RFC 6585) indicating seconds to wait. | `18` |
-| `X-RateLimit-*` | Legacy header equivalents for backwards compatibility. | `X-RateLimit-Reset: 18` |
+| Header                | Description                                                                | Example                 |
+| :-------------------- | :------------------------------------------------------------------------- | :---------------------- |
+| `RateLimit-Limit`     | Maximum request quota for the configured window.                           | `100`                   |
+| `RateLimit-Remaining` | Remaining requests permitted within the current window.                    | `42`                    |
+| `RateLimit-Reset`     | Time remaining in seconds until the window quota resets.                   | `18`                    |
+| `Retry-After`         | Included on `429 Too Many Requests` (RFC 6585) indicating seconds to wait. | `18`                    |
+| `X-RateLimit-*`       | Legacy header equivalents for backwards compatibility.                     | `X-RateLimit-Reset: 18` |
 
 > [!NOTE]
 > The core `rateLimit` middleware runs using an in-memory native off-heap store. For distributed, multi-instance rate limiting backed by Redis, use `@exisjs/cache`.
@@ -77,34 +77,47 @@ export const limiter = rateLimit({
 
 ## 3. Role-Based Access Control (RBAC) Metadata
 
-ExisJS allows declarative permission metadata to be attached to routes:
-
-#### Functional Paradigm
+---
 
-```typescript filename="src/http/admin/route.ts"
-import { controller, route } from 'exisjs/router'
+## 4. Timing-Safe Operations & Authentication
 
-export default controller({
-  deleteItem: route.delete('/:id', {
-    permissions: ['admin'],
-    handle({ params }) {
-      return { success: true, deleted: params.id }
-    }
-  })
-})
-```
+To prevent side-channel timing attacks when validating authentication tokens, API keys, HMAC signatures, or webhook secrets, ExisJS provides the `timingSafeEqual` helper:
 
-#### Class-Based (OOP) Paradigm
+```typescript filename="src/http/common/guards/auth.guard.ts"
+import { timingSafeEqual } from 'exisjs/middleware'
+import { UnauthorizedException } from 'exisjs/error'
 
-```typescript filename="src/http/admin/route.ts"
-import { Controller, Delete, Param, Permissions } from 'exisjs/decorators'
+export function apiKeyGuard(req: any) {
+  const apiKey = req.headers['x-api-key']
+  const secretKey = process.env.API_KEY
 
-@Controller()
-export default class AdminController {
-  @Permissions('admin')
-  @Delete('/:id')
-  async deleteItem(@Param('id') id: string) {
-    return { success: true, deleted: id }
+  if (!timingSafeEqual(apiKey, secretKey)) {
+    throw new UnauthorizedException('Invalid API Key')
   }
 }
 ```
+
+`timingSafeEqual` executes in constant time regardless of string lengths or partial matching prefixes, neutralizing timing analysis exploits.
+
+---
+
+## 5. Security Scanner Noise Suppression & Blackhole Handler
+
+ExisJS includes built-in protection against automated vulnerability bots scanning for `.env`, `/.git`, `/.DS_Store`, WordPress/PHP configs, and Java actuator dumps:
+
+```typescript filename="src/http/server.ts"
+import { exis } from 'exisjs'
+import { blockSuspiciousProbes } from 'exisjs/middleware'
+
+export default exis({
+  async onStart(app) {
+    // Intercepts scanner probes and blackholes them without triggering downstream error logs
+    app.use(
+      blockSuspiciousProbes({
+        blackhole: true, // Terminate immediately with 404/empty body
+        silent: true, // Suppress 404 noise from production logs
+      })
+    )
+  },
+})
+```

package/dist/docs/content/structure.mdx

@@ -1,6 +1,6 @@
 ---
-nextUrl: "/docs/config"
-nextTitle: "Configuration"
+nextUrl: '/docs/config'
+nextTitle: 'Configuration'
 ---
 
 # Project Structure
@@ -22,17 +22,18 @@ my-backend/
 ├── .exis/                    # Internal framework cache and build artifacts
 ├── src/
 │   ├── http/
-│   │   ├── server.ts         # Application entry point
+│   │   ├── server.ts         # Application entry point & lifecycle hooks
 │   │   ├── error.ts          # Centralized framework exception handler (onError)
 │   │   ├── route.ts          # Root routes (e.g. GET /api)
 │   │   ├── boundary.ts       # Root boundary (config + request pipeline)
 │   │   ├── users/
 │   │   │   ├── route.ts      # User endpoints
-│   │   │   └── schema.ts     # Validation schemas (tex) — mandatory alongside route.ts
+│   │   │   ├── schema.ts     # Validation schemas (tex) — mandatory alongside route.ts
+│   │   │   └── service.ts    # Business logic / data access, DI-injectable
 │   │   ├── posts/
 │   │   │   ├── route.ts
 │   │   │   ├── schema.ts
-│   │   │   └── service.ts    # Business logic / data access, DI-injectable
+│   │   │   └── service.ts
 │   │   └── admin/
 │   │       ├── boundary.ts   # Applies to /admin/* and everything nested
 │   │       ├── route.ts
@@ -40,10 +41,16 @@ my-backend/
 │   │           ├── route.ts
 │   │           ├── schema.ts
 │   │           └── service.ts
-│   ├── models/                # Free-form. Populated once you add a data package.
-│   ├── services/               # Free-form. Shared business logic.
-│   ├── dto/                    # Free-form. Request/response types.
-│   └── config/env.ts                  # Type-safe environment schema (tex)
+│   ├── cron/                 # Scheduled tasks & background cron jobs (auto-discovered)
+│   │   └── cleanup.ts
+│   ├── database/             # Database connection, models/schemas, migrations, or repositories
+│   │   ├── db.ts             # Connection client & lifecycle registration (registerDatabase)
+│   │   └── models/           # Database entity models / ORM schemas (e.g. user.model.ts)
+│   ├── common/               # Shared cross-cutting guards, interceptors, or filters
+│   │   └── guards/
+│   │       └── auth.guard.ts
+│   └── config/
+│       └── env.ts            # Type-safe environment schema (tex.env)
 ├── tests/
 ├── .env
 ├── exis.config.ts
@@ -51,8 +58,7 @@ my-backend/
 └── tsconfig.json
 ```
 
-> `src/jobs/` is **not** part of the core structure. It only appears once you
-> install `@exisjs/queue` — see that package's docs for its convention.
+> `src/cron/` is natively auto-discovered by the framework at boot. All files inside `src/cron/` or colocated at `src/http/**/cron.ts` are automatically mounted. Database connections and models reside under `src/database/` (or `src/models/`).
 
 ---
 
@@ -62,18 +68,19 @@ A file's name declares its role. Functional vs. class-based (OOP) only changes
 _syntax_, never _responsibility_.
 
 ExisJS supports two naming conventions seamlessly:
+
 1. **Standard Flat Names** (default): `route.ts`, `schema.ts`, `service.ts`, `boundary.ts`.
 2. **Feature-Prefixed Named Files**: `<name>.route.ts`, `<name>.schema.ts`, `<name>.service.ts`, `<name>.boundary.ts` (e.g., `user.route.ts`, `user.schema.ts`, `user.service.ts`).
 
 Both styles are automatically detected by the route scanner, CLI manifest generator, and development watcher with 100% parity.
 
-| File Pattern | Role | Never contains |
-| :--- | :--- | :--- |
-| `route.ts` / `*.route.ts` | Binds a URL + method to a handler. | Business logic, validation logic |
-| `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 |
+| File Pattern                    | Role                                                                                           | Never contains                   |
+| :------------------------------ | :--------------------------------------------------------------------------------------------- | :------------------------------- |
+| `route.ts` / `*.route.ts`       | Binds a URL + method to a handler.                                                             | Business logic, validation logic |
+| `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           |
 
 ---
 
@@ -89,18 +96,18 @@ Any `route.ts` (or `.js`) under `src/http/` maps to a URL from its folder path:
 ### Functional
 
 ```typescript filename="src/http/users/route.ts"
-import { controller, route } from "exisjs/router";
-import { UserParamsSchema } from "./schema";
-import { fetchUser } from "./service";
+import { controller, route } from 'exisjs/router'
+import { UserParamsSchema } from './schema'
+import { fetchUser } from './service'
 
 export default controller({
-  getUser: route.get("/users/:id", {
+  getUser: route.get('/users/:id', {
     params: UserParamsSchema,
     async handle({ params }) {
-      return fetchUser(params.id);
+      return fetchUser(params.id)
     },
   }),
-});
+})
 ```
 
 ### Class-based (OOP)
@@ -108,17 +115,17 @@ export default controller({
 The decorated class **is** the route file — no separate controller file:
 
 ```typescript filename="src/http/users/route.ts"
-import { Controller, Get, Param } from "exisjs/decorators";
-import { UserParamsSchema } from "./schema";
-import { UserService } from "./service";
+import { Controller, Get, Param } from 'exisjs/decorators'
+import { UserParamsSchema } from './schema'
+import { UserService } from './service'
 
-@Controller("/users")
+@Controller('/users')
 export default class UserRoute {
   constructor(private userService: UserService) {}
 
-  @Get("/:id", UserParamsSchema)
-  async getUser(@Param("id") id: string) {
-    return this.userService.fetchUser(id);
+  @Get('/:id', UserParamsSchema)
+  async getUser(@Param('id') id: string) {
+    return this.userService.fetchUser(id)
   }
 }
 ```
@@ -132,9 +139,9 @@ export default class UserRoute {
 ## `src/http/**/schema.ts`
 
 ```typescript filename="src/http/users/schema.ts"
-import { tex } from "exisjs/validator";
+import { tex } from 'exisjs/validator'
 
-export const UserParamsSchema = tex.object({ id: tex.string() });
+export const UserParamsSchema = tex.object({ id: tex.string() })
 ```
 
 `tex` is the only validation engine. Schemas here are also the source for
@@ -156,7 +163,7 @@ export async function fetchUser(id: string) {
 
 ```typescript filename="src/http/users/service.ts"
 // OOP
-import { Injectable } from "exisjs/decorators";
+import { Injectable } from 'exisjs/decorators'
 
 @Injectable()
 export class UserService {
@@ -178,49 +185,49 @@ two independent halves:
 2. **Pipeline & Hooks** — real code, auto-detected by function signature. No imports,
    no manual registration required.
 
-| 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 |
+| 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
 
 ```typescript filename="src/http/admin/boundary.ts"
-import { defineBoundary } from "exisjs/router";
-import type { Request, Response, Next, BoundaryContext } from "exisjs/router";
+import { defineBoundary } from 'exisjs/router'
+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: "/admin/health", method: "GET" }],
+  cors: { origin: ['https://myapp.com'], credentials: true },
+  headers: { 'X-Powered-By': 'ExisJS' },
+  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;
+    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() };
+    res.setHeader('X-Audited-By', 'AdminBoundary')
+    return { ...data, auditedAt: Date.now() }
   },
-});
+})
 
 export function logStep(req: Request, res: Response, next: Next) {
-  console.log(`[Admin] ${req.method} ${req.path}`);
-  next();
+  console.log(`[Admin] ${req.method} ${req.path}`)
+  next()
 }
 
 export default async function (ctx: BoundaryContext, next: Next) {
   try {
-    return { success: true, data: await next() };
+    return { success: true, data: await next() }
   } catch (err) {
-    return { success: false, error: { message: (err as Error).message } };
+    return { success: false, error: { message: (err as Error).message } }
   }
 }
 ```
@@ -228,40 +235,40 @@ export default async function (ctx: BoundaryContext, next: Next) {
 ### Class-based (OOP)
 
 ```typescript filename="src/http/admin/boundary.ts"
-import { Boundary } from "exisjs/decorators";
-import type { Request, Response, Next, BoundaryContext } from "exisjs/router";
+import { Boundary } from 'exisjs/decorators'
+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"],
+  cors: { origin: ['https://myapp.com'], credentials: true },
+  headers: { 'X-Powered-By': 'ExisJS' },
+  exclude: ['/admin/health'],
 })
 export default class AdminBoundary {
   // Pre-handler hook
   beforeHandle(req: Request, res: Response) {
-    if (req.headers["x-role"] !== "admin") {
-      res.status(403).json({ error: "Admin role required" });
-      return false;
+    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() };
+    return { ...data, auditedAt: Date.now() }
   }
 
   // Chain step
   logStep(req: Request, res: Response, next: Next) {
-    console.log(`[Admin] ${req.method} ${req.path}`);
-    next();
+    console.log(`[Admin] ${req.method} ${req.path}`)
+    next()
   }
 
   // Wrapper
   async handle(ctx: BoundaryContext, next: Next) {
     try {
-      return { success: true, data: await next() };
+      return { success: true, data: await next() }
     } catch (err) {
-      return { success: false, error: { message: (err as Error).message } };
+      return { success: false, error: { message: (err as Error).message } }
     }
   }
 }
@@ -276,39 +283,39 @@ ExisJS natively discovers and mounts `src/http/error.ts` (or `error.js`) at boot
 ### Functional
 
 ```typescript filename="src/http/error.ts"
-import type { Request, Response } from "exisjs";
+import type { Request, Response } from 'exisjs'
 
 export function onError(err: any, req: Request, res: Response) {
-  const status = err.statusCode || err.status || 500;
+  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",
+      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";
+import type { Request, Response } from 'exisjs'
 
 export default class GlobalErrorHandler {
   onError(err: any, req: Request, res: Response) {
-    const status = err.statusCode || err.status || 500;
+    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",
+        message: err.message || 'Internal Server Error',
+        code: err.code || 'INTERNAL_ERROR',
         path: req.path,
       },
-    });
+    })
   }
 }
 ```
@@ -324,32 +331,46 @@ Global infrastructure: port, SSL, CORS defaults, security headers, and
 official package registration.
 
 ```typescript filename="exis.config.ts"
-import { defineConfig } from "exisjs";
+import { defineConfig } from 'exisjs'
 
 export default defineConfig({
   port: 3000,
-  cors: { origin: "*" },
+  cors: { origin: '*' },
   // plugins: [] — official packages (@exisjs/database, @exisjs/auth, etc.)
   // are registered here once installed. None are required by default.
-});
+})
 ```
 
 ---
 
-## `src/env.ts`
+## `src/config/env.ts`
 
-```typescript filename="src/env.ts"
-import { tex } from "exisjs/validator";
+```typescript filename="src/config/env.ts"
+import { tex } from 'exisjs/validator'
 
 export const env = tex
-  .object({
-    PORT: tex.number({ coerce: true, optional: true }),
-    NODE_ENV: tex.enum(["development", "production", "test"]),
+  .env({
+    PORT: tex.number({ default: 4000 }),
+    NODE_ENV: tex.enum(['development', 'production', 'test'] as const, {
+      default: 'development',
+    }),
+    CORS_ORIGIN: tex.string({ default: '*' }),
   })
-  .parse(process.env);
+  .parse(process.env)
 ```
 
-Boot fails immediately if a required variable is missing.
+Boot fails immediately with clear diagnostics if a required environment variable is missing or malformed.
+
+---
+
+## `src/database/`
+
+The `src/database/` directory organizes your persistent storage layer:
+
+- `src/database/db.ts`: Connection instance, client initialization, and lifecycle registration via `registerDatabase(app, { connect, disconnect, healthCheck })` (or ORMs like Prisma, Drizzle, Mongoose).
+- `src/database/models/` (or `src/models/`): Data models, entity definitions, and database schemas.
+- `src/database/repositories/`: Abstracted data access objects and custom query builders.
+- `src/database/migrations/`: Database migration scripts.
 
 ---
 
@@ -360,11 +381,16 @@ production. Add to `.gitignore`.
 
 ---
 
-## Custom Directories
+## Auto-Discovered vs Custom Directories
 
-Only `src/http/` (routing) and, if `@exisjs/queue` is installed, `src/jobs/`
-are enforced. Everything else — `src/models/`, `src/services/`, `src/dto/` —
-is free-form.
+- **Auto-Discovered by Framework**:
+  - `src/http/`: Route handlers (`route.ts`), request schemas (`schema.ts`), boundaries (`boundary.ts`), and global error handler (`error.ts`).
+  - `src/cron/`: Scheduled tasks and background cron jobs (`cleanup.ts`, `reports.ts`).
+- **Standard Recommended Conventions**:
+  - `src/database/`: Database client (`db.ts`), models (`models/`), and migrations.
+  - `src/common/`: Shared guards (`guards/`), interceptors, and exception filters.
+  - `src/config/`: Environment configuration (`config/env.ts`).
+  - `src/services/` or `src/dto/`: Optional shared business logic or global DTOs across multiple routes.
 
 ---
 

package/dist/docs/reference/config.mdx

@@ -1,6 +1,6 @@
 ---
-title: "Configuration"
-description: "API Reference for the global exis.config.ts file (`exisjs/config`)."
+title: 'Configuration'
+description: 'API Reference for the global exis.config.ts file (`exisjs/config`).'
 ---
 
 # Configuration (`exisjs/config`)
@@ -61,22 +61,22 @@ export default async (phase: string, { defaultConfig }) => {
 
   return defineConfig({
     port: Number(process.env.PORT) || 4000,
-    
+
     // Auto-spawn Worker threads based on CPU cores!
-    workers: isDev ? 1 : 'safe', 
-    
+    workers: isDev ? 1 : 'safe',
+
     // Globally configure native middleware
     cors: {
       origin: isDev ? '*' : 'https://myapp.com',
-      credentials: true
+      credentials: true,
     },
     helmet: { enabled: true },
     logger: isDev ? { level: 'debug', pretty: true } : false,
-    
+
     // Native plugin registration
     plugins: [
       // ... your plugins here
-    ]
+    ],
   })
 }
 ```
@@ -99,20 +99,31 @@ If you export a function from `exis.config.ts`, ExisJS will inject the current "
 Here is the full list of options supported natively by the ExisJS configuration engine:
 
 ### Server & Network
-- **`port`** *(number)*: The port the server listens on (default: `4000`).
-- **`host`** *(string)*: The host interface to bind to (default: `'0.0.0.0'`).
-- **`server`** *(`'node' | 'uws' | 'auto'`)*: ExisJS supports running on standard Node `http`, or incredibly fast C++ `uWebSockets.js` (`uws`). Default is `'auto'` (uses `uws` if installed, falls back to `node`).
-- **`workers`** *(number | `'safe'` | `'max'`)*: Number of Node.js Cluster workers to spawn. `'max'` uses all CPU cores. `'safe'` uses all cores minus 1 (to leave room for the OS).
-- **`trustProxy`** *(boolean)*: Enable if running behind a reverse proxy (like Nginx or AWS ALB) to trust the `X-Forwarded-For` headers.
+
+- **`port`** _(number)_: The port the server listens on (default: `4000`).
+- **`host`** _(string)_: The host interface to bind to (default: `'0.0.0.0'`).
+- **`server`** _(`'node' | 'uws' | 'auto'`)_: ExisJS supports running on standard Node `http`, or incredibly fast C++ `uWebSockets.js` (`uws`). Default is `'auto'` (uses `uws` if installed, falls back to `node`).
+- **`workers`** _(number | `'safe'` | `'max'`)_: Number of Node.js Cluster workers to spawn. `'max'` uses all CPU cores. `'safe'` uses all cores minus 1 (to leave room for the OS).
+- **`trustProxy`** _(boolean | number)_: Enable if running behind reverse proxies or CDNs (Cloudflare, AWS ALB, NGINX, Render) to evaluate `CF-Connecting-IP`, `True-Client-IP`, `X-Real-IP`, and `X-Forwarded-For`. (Can also be enabled via `TRUST_PROXY=true`).
 
 ### Security & Middlewares
-- **`cors`** *(boolean | object)*: Enable and configure Cross-Origin Resource Sharing globally.
-- **`helmet`** *(boolean | object)*: Enable strict security headers. Enabled by default.
-- **`logger`** *(boolean | object)*: Configure the efficient Pino request logger.
-- **`compression`** *(boolean | object)*: Enable gzip/brotli response compression.
-- **`bodyLimit`** *(number)*: Maximum JSON/URL-encoded payload size in bytes (default: `1MB`).
+
+- **`cors`** _(boolean | object)_: Enable and configure Cross-Origin Resource Sharing globally.
+- **`helmet`** _(boolean | object)_: Enable strict security headers. Enabled by default.
+- **`logger`** _(boolean | object)_: Configure the efficient Pino request logger.
+- **`compression`** _(boolean | object)_: Enable gzip/brotli response compression.
+- **`etag`** _(boolean)_: Automatic ETag generation for HTTP conditional requests (default: `false` for dynamic API routes).
+- **`bodyLimit`** _(number)_: Maximum JSON/URL-encoded payload size in bytes (default: `10MB`).
+
+### Development Server & File Watcher (`dev`)
+
+- **`dev.watch`** _(string[])_: Custom directories or files to watch during development (default: `[cwd]`).
+- **`dev.ignored`** _((string | RegExp)[])_: Additional files, extensions, or regex patterns to ignore during hot reload.
+- **`dev.usePolling`** _(boolean)_: Enables chokidar polling fallback (default: `true` on Windows).
+- **`dev.interval`** _(number)_: Polling file system interval in milliseconds (default: `100`).
 
 ### Extended Integrations
+
 - **`queue`**: Define your background queue driver (`memory` or `redis`) and configure `maxConcurrent` processing limits.
 - **`plugins`**: An array of `ExisPlugin` instances to register natively into the framework.
 - **`test`**: Configure testing environments (`include`, `exclude`, `setupFiles`, `coverage`).