exisjs 0.7.9 → 0.7.10

package/dist/di/index.d.ts

@@ -1,5 +1,6 @@
 export { inject } from './inject';
-export { Container } from './container';
+export { Container, INJECT_METADATA, PROPERTY_INJECT_METADATA, OPTIONAL_METADATA, SCOPE_METADATA, } from './container';
 export { Inject, Optional } from './decorators';
 export type { ProviderToken, ProviderDefinition, ValueProvider, FactoryProvider, ClassProvider, } from './container';
+export { forwardRef, isForwardRef, type ForwardReference } from './forward-ref';
 //# sourceMappingURL=index.d.ts.map

package/dist/di/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/di/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAA;AACjC,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AACvC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAA;AAC/C,YAAY,EACV,aAAa,EACb,kBAAkB,EAClB,aAAa,EACb,eAAe,EACf,aAAa,GACd,MAAM,aAAa,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/di/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAA;AACjC,OAAO,EACL,SAAS,EACT,eAAe,EACf,wBAAwB,EACxB,iBAAiB,EACjB,cAAc,GACf,MAAM,aAAa,CAAA;AACpB,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAA;AAC/C,YAAY,EACV,aAAa,EACb,kBAAkB,EAClB,aAAa,EACb,eAAe,EACf,aAAa,GACd,MAAM,aAAa,CAAA;AACpB,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,KAAK,gBAAgB,EAAE,MAAM,eAAe,CAAA"}

package/dist/di/index.js

@@ -1,11 +1,18 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Optional = exports.Inject = exports.Container = exports.inject = void 0;
+exports.isForwardRef = exports.forwardRef = exports.Optional = exports.Inject = exports.SCOPE_METADATA = exports.OPTIONAL_METADATA = exports.PROPERTY_INJECT_METADATA = exports.INJECT_METADATA = exports.Container = exports.inject = void 0;
 var inject_1 = require("./inject");
 Object.defineProperty(exports, "inject", { enumerable: true, get: function () { return inject_1.inject; } });
 var container_1 = require("./container");
 Object.defineProperty(exports, "Container", { enumerable: true, get: function () { return container_1.Container; } });
+Object.defineProperty(exports, "INJECT_METADATA", { enumerable: true, get: function () { return container_1.INJECT_METADATA; } });
+Object.defineProperty(exports, "PROPERTY_INJECT_METADATA", { enumerable: true, get: function () { return container_1.PROPERTY_INJECT_METADATA; } });
+Object.defineProperty(exports, "OPTIONAL_METADATA", { enumerable: true, get: function () { return container_1.OPTIONAL_METADATA; } });
+Object.defineProperty(exports, "SCOPE_METADATA", { enumerable: true, get: function () { return container_1.SCOPE_METADATA; } });
 var decorators_1 = require("./decorators");
 Object.defineProperty(exports, "Inject", { enumerable: true, get: function () { return decorators_1.Inject; } });
 Object.defineProperty(exports, "Optional", { enumerable: true, get: function () { return decorators_1.Optional; } });
+var forward_ref_1 = require("./forward-ref");
+Object.defineProperty(exports, "forwardRef", { enumerable: true, get: function () { return forward_ref_1.forwardRef; } });
+Object.defineProperty(exports, "isForwardRef", { enumerable: true, get: function () { return forward_ref_1.isForwardRef; } });
 //# sourceMappingURL=index.js.map

package/dist/di/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/di/index.ts"],"names":[],"mappings":";;;AAAA,mCAAiC;AAAxB,gGAAA,MAAM,OAAA;AACf,yCAAuC;AAA9B,sGAAA,SAAS,OAAA;AAClB,2CAA+C;AAAtC,oGAAA,MAAM,OAAA;AAAE,sGAAA,QAAQ,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/di/index.ts"],"names":[],"mappings":";;;AAAA,mCAAiC;AAAxB,gGAAA,MAAM,OAAA;AACf,yCAMoB;AALlB,sGAAA,SAAS,OAAA;AACT,4GAAA,eAAe,OAAA;AACf,qHAAA,wBAAwB,OAAA;AACxB,8GAAA,iBAAiB,OAAA;AACjB,2GAAA,cAAc,OAAA;AAEhB,2CAA+C;AAAtC,oGAAA,MAAM,OAAA;AAAE,sGAAA,QAAQ,OAAA;AAQzB,6CAA+E;AAAtE,yGAAA,UAAU,OAAA;AAAE,2GAAA,YAAY,OAAA"}

package/dist/docs/content/controllers.mdx

@@ -353,6 +353,236 @@ export default class UsersController {
 }
 ```
 
+## Controller Inheritance (Base & Abstract Controllers)
+
+ExisJS supports full OOP inheritance for controllers. You can create generic base or abstract CRUD controllers and inherit all route handlers, parameter decorators, middlewares, guards, interceptors, and filters down to subclasses:
+
+```typescript filename="src/http/base-crud.controller.ts"
+import { Get, Post, Delete, Param, Body } from 'exisjs/decorators'
+
+export abstract class BaseCrudController<T> {
+  protected abstract resourceName: string
+
+  @Get('/')
+  async findAll(): Promise<T[]> {
+    return []
+  }
+
+  @Get('/:id')
+  async findById(@Param('id') id: string): Promise<T> {
+    return { id, resource: this.resourceName } as any
+  }
+
+  @Delete('/:id')
+  async remove(@Param('id') id: string): Promise<{ deleted: boolean }> {
+    return { deleted: true }
+  }
+}
+```
+
+Subclasses inherit all parent endpoints and can add new routes or selectively override base methods:
+
+```typescript filename="src/http/users/route.ts"
+import { Controller, Post, Body, Param } from 'exisjs/decorators'
+import { BaseCrudController } from '../base-crud.controller'
+
+export interface User {
+  id: string
+  name: string
+}
+
+@Controller('/users')
+export default class UsersController extends BaseCrudController<User> {
+  protected resourceName = 'users'
+
+  // Subclass defines additional route
+  @Post('/')
+  async create(@Body() user: User) {
+    return { created: true, user }
+  }
+
+  // Subclass can override inherited remove handler
+  override async remove(@Param('id') id: string) {
+    return { deleted: true, id, customAudit: true }
+  }
+}
+```
+
+### Functional Controller Inheritance (`controller.extend`)
+
+In the functional paradigm, inheritance is achieved via `controller.extend(base, overrides)`. This inherits all route handlers, lifecycle hooks, and middlewares from a base controller factory and allows overriding endpoints or adding new routes with full type inference:
+
+```typescript filename="src/http/products/route.ts"
+import { controller, route } from 'exisjs/router'
+
+// 1. Generic functional base CRUD controller
+function createBaseCrud(resourceName: string) {
+  return controller({
+    list: route.get('/', {
+      async handle() {
+        return { resource: resourceName, items: [] }
+      }
+    }),
+    getById: route.get('/:id', {
+      async handle({ params }) {
+        return { resource: resourceName, id: params.id }
+      }
+    }),
+    remove: route.delete('/:id', {
+      async handle({ params }) {
+        return { deleted: true, id: params.id }
+      }
+    })
+  })
+}
+
+// 2. Extend base controller with overrides and additional routes
+export default controller.extend(createBaseCrud('products'), {
+  // Additional specialized route
+  featured: route.get('/featured', {
+    async handle() {
+      return { featured: ['Product 1', 'Product 2'] }
+    }
+  }),
+
+  // Override base endpoint
+  getById: route.get('/:id', {
+    async handle({ params }) {
+      return { customProduct: true, id: params.id }
+    }
+  })
+})
+```
+
+## Functional Controller Composition (`controller.merge`)
+
+When a single `route.ts` manages a feature area with multiple concerns (for example, auth flows containing credentials, sessions, and OAuth), `controller.merge(...controllers)` allows splitting logic into modular controller objects and merging them into a single default export:
+
+```typescript filename="src/http/auth/route.ts"
+import { controller, route } from 'exisjs/router'
+
+// 1. Modular controller for password authentication
+const passwordAuth = controller({
+  login: route.post('/login', {
+    async handle({ body }) {
+      return { token: 'jwt-auth-token' }
+    }
+  }),
+  logout: route.post('/logout', {
+    async handle() {
+      return { success: true }
+    }
+  })
+})
+
+// 2. Modular controller for OAuth providers
+const oauthProviders = controller({
+  google: route.get('/google', {
+    async handle() {
+      return { redirectUrl: 'https://accounts.google.com/o/oauth2/auth' }
+    }
+  }),
+  github: route.get('/github', {
+    async handle() {
+      return { redirectUrl: 'https://github.com/login/oauth/authorize' }
+    }
+  })
+})
+
+// 3. Merge both into the single exported controller for this folder
+export default controller.merge(passwordAuth, oauthProviders)
+```
+
+## Built-in Transformation Pipes & `@UsePipes`
+
+Pipes transform and validate incoming request data before it reaches the route handler. ExisJS provides built-in pipes for common primitives:
+
+<div className="overflow-x-auto mb-6">
+  <table className="w-full text-sm text-left border border-border/50 rounded-lg overflow-hidden">
+    <thead className="bg-muted/50 text-foreground">
+      <tr>
+        <th className="px-4 py-3 border-b border-border/50 font-semibold w-1/3">Pipe</th>
+        <th className="px-4 py-3 border-b border-border/50 font-semibold">Description</th>
+      </tr>
+    </thead>
+    <tbody className="divide-y divide-border/50">
+      <tr className="bg-background hover:bg-muted/30 transition-colors">
+        <td className="px-4 py-3 font-mono text-xs">ParseIntPipe</td>
+        <td className="px-4 py-3 text-muted-foreground">Parses string/number parameter into integer or throws 400 Bad Request</td>
+      </tr>
+      <tr className="bg-background hover:bg-muted/30 transition-colors">
+        <td className="px-4 py-3 font-mono text-xs">ParseFloatPipe</td>
+        <td className="px-4 py-3 text-muted-foreground">Parses parameter into floating-point number</td>
+      </tr>
+      <tr className="bg-background hover:bg-muted/30 transition-colors">
+        <td className="px-4 py-3 font-mono text-xs">ParseBoolPipe</td>
+        <td className="px-4 py-3 text-muted-foreground">Parses boolean strings (<code>'true'</code>, <code>'false'</code>, <code>1</code>, <code>0</code>) into native booleans</td>
+      </tr>
+      <tr className="bg-background hover:bg-muted/30 transition-colors">
+        <td className="px-4 py-3 font-mono text-xs">ParseUUIDPipe</td>
+        <td className="px-4 py-3 text-muted-foreground">Validates UUID format (v3, v4, v5, or all)</td>
+      </tr>
+      <tr className="bg-background hover:bg-muted/30 transition-colors">
+        <td className="px-4 py-3 font-mono text-xs">ParseArrayPipe</td>
+        <td className="px-4 py-3 text-muted-foreground">Splits comma-separated strings into arrays and applies item pipes</td>
+      </tr>
+      <tr className="bg-background hover:bg-muted/30 transition-colors">
+        <td className="px-4 py-3 font-mono text-xs">ValidationPipe</td>
+        <td className="px-4 py-3 text-muted-foreground">Validates and transforms DTO classes or schema metatypes</td>
+      </tr>
+    </tbody>
+  </table>
+</div>
+
+```typescript filename="src/http/items/route.ts"
+import {
+  Controller,
+  Get,
+  Post,
+  Param,
+  Query,
+  Body,
+  UsePipes,
+  ParseIntPipe,
+  ParseBoolPipe,
+  ParseUUIDPipe,
+  ParseArrayPipe,
+  ValidationPipe,
+} from 'exisjs/decorators'
+
+@Controller('/items')
+export default class ItemsController {
+  // 1. Parameter-level pipe
+  @Get('/:id')
+  async getItem(@Param('id', ParseIntPipe) id: number) {
+    return { id, isNumber: typeof id === 'number' }
+  }
+
+  // 2. Query boolean & array pipes
+  @Get('/')
+  async listItems(
+    @Query('active', ParseBoolPipe) active: boolean,
+    @Query('ids', new ParseArrayPipe({ items: ParseIntPipe })) ids: number[]
+  ) {
+    return { active, ids }
+  }
+
+  // 3. UUID validation pipe
+  @Get('/by-uuid/:uuid')
+  async getByUUID(@Param('uuid', ParseUUIDPipe) uuid: string) {
+    return { uuid }
+  }
+
+  // 4. Method-level or Class-level @UsePipes
+  @Post('/')
+  @UsePipes(new ValidationPipe({ transform: true }))
+  async createItem(@Body() body: any) {
+    return { created: true, body }
+  }
+}
+```
+
 <Info title="Tip: Safely Returning with @Res">
 In some frameworks, injecting the `@Res()` object disables auto-serialization, causing the request to hang if you forget to call `res.send()`. ExisJS handles this differently: if you return a value from your handler, ExisJS will still safely auto-serialize it to JSON even if you injected `@Res()` to set a custom header.
 </Info>
+

package/dist/docs/content/errors.mdx

@@ -98,33 +98,40 @@ export const uploadMedia = (req, res) => {
 }
 ```
 
-### The Standardized Response
+### The Standardized Error Response Envelope
 
-When an `HttpError` is thrown, the client will automatically receive a structured JSON payload.
+When an `HttpError` is thrown or a validation failure occurs, the client automatically receives a standardized JSON payload with status codes, error descriptions, and ISO timestamps:
 
-```json filename="Response"
+```json filename="HTTP Error Response Envelope"
 {
   "success": false,
-  "error": {
-    "code": "NOT_FOUND",
-    "message": "User not found"
-  }
+  "statusCode": 404,
+  "error": "Not Found",
+  "message": "User not found",
+  "validationErrors": null,
+  "timestamp": "2026-09-27T10:11:42.000Z"
 }
 ```
 
 ### 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:
+When schema validation fails (via `tex`, Zod, or Yup), ExisJS produces a typed `400 Bad Request` containing both a concise `validationErrors` (and `errors`) map for seamless frontend form field binding:
 
 ```json filename="HTTP 400 Bad Request Response"
 {
+  "success": false,
   "statusCode": 400,
   "error": "Bad Request",
   "message": "Validation Error: email: Invalid email format, age: Field must be >= 18",
+  "validationErrors": {
+    "email": "Invalid email format",
+    "age": "Field must be >= 18"
+  },
   "errors": {
     "email": "Invalid email format",
     "age": "Field must be >= 18"
-  }
+  },
+  "timestamp": "2026-09-27T10:11:42.000Z"
 }
 ```
 

package/dist/docs/content/modules.mdx

@@ -76,7 +76,7 @@ export default exis({
 
 ```
 
-#### Class-Based (OOP) Paradigm (`@Module`)
+#### Class-Based (OOP) Paradigm (`@Module` & `@Global`)
 
 For applications following the OOP paradigm, you can define modules using the `@Module` class decorator:
 
@@ -95,23 +95,42 @@ import { DatabaseModule } from './database.module'
 export class AuthModule {}
 ```
 
-You can then register it into your server:
+#### Global Modules (`@Global`)
+
+If you have utility services, audit loggers, or database connections that should be globally available across all modules without having to list the module in every `imports: [...]` array, decorate the module with `@Global()`:
+
+```typescript filename="src/modules/core.module.ts"
+import { Global, Module } from 'exisjs/decorators'
+import { AuditService } from './audit.service'
+import { LoggerService } from './logger.service'
+
+@Global()
+@Module({
+  providers: [AuditService, LoggerService],
+  exports: [AuditService, LoggerService],
+})
+export class CoreModule {}
+```
+
+You can then register it into your server or root module once:
 
 ```typescript filename="src/http/server.ts"
 import { Server } from 'exisjs/decorators'
 import { AuthModule } from '../modules/auth.module'
+import { CoreModule } from '../modules/core.module'
 import type { App } from 'exisjs'
 
 @Server({
-  plugins: [AuthModule]
+  plugins: [CoreModule, AuthModule]
 })
 export default class RootServer {
   async onStart(app: App) {
-    console.log("Server with AuthModule booted")
+    console.log("Server with Global CoreModule and AuthModule booted")
   }
 }
 ```
 
+
 ---
 
 ## 2. Framework Plugins (`definePlugin`)

package/dist/docs/content/providers.mdx

@@ -64,7 +64,9 @@ export default class UsersController {
 ```
 
 <Info title="Note on Dependency Injection">
-ExisJS utilizes a runtime container system. By default, ExisJS does not aggressively use `reflect-metadata` for automatic constructor injection (unlike NestJS) to maintain a minimal footprint. The `inject()` function is the primary and recommended way to resolve dependencies.
+ExisJS provides two elegant ways to inject dependencies:
+1. **Property-Level / Functional Injection**: Use `inject(UsersService)` for concise, boilerplate-free injection.
+2. **Constructor Injection**: In OOP controllers and services, ExisJS inspects TypeScript's emitted `design:paramtypes` and `INJECTABLE_REGISTRY` to automatically inject service instances into constructor parameters (`constructor(private usersService: UsersService)`) without requiring explicit `@Inject()` decorators on every parameter!
 </Info>
 
 ### Extended: Manual Resolution
@@ -182,20 +184,31 @@ import { UsersService } from './users/service'
 export default class RootServer {}
 ```
 
-### Constructor Injection (`@Inject` and `@Optional`)
+### Constructor & Property Injection (`@Inject`, `@Optional`, and `forwardRef`)
 
-In addition to property-level `inject()`, ExisJS provides full OOP constructor parameter injection with `@Inject(token)` and `@Optional()`:
+In addition to property-level `inject()`, ExisJS provides full OOP constructor and property field injection with `@Inject(token)`, `@Optional()`, and `forwardRef()`:
 
 ```typescript filename="src/http/users/route.ts"
-import { Controller, Get, Param, Inject, Optional } from 'exisjs/decorators'
+import { Controller, Get, Param } from 'exisjs/decorators'
+import { Inject, Optional, forwardRef } from 'exisjs/di'
 import { UsersService } from './service'
+import { ConfigService } from '../config/service'
 
 @Controller('/users')
 export default class UsersController {
+  // 1. Property-level decorator injection
+  @Inject(ConfigService)
+  private config!: ConfigService
+
+  // 2. Optional token injection
+  @Inject('METRICS')
+  @Optional()
+  private metrics?: any
+
+  // 3. Constructor injection with forwardRef for circular dependencies
   constructor(
     private usersService: UsersService,
-    @Inject('DATABASE_URL') private dbUrl: string,
-    @Optional() @Inject('METRICS') private metrics?: any
+    @Inject(forwardRef(() => UsersService)) private circularRef: UsersService
   ) {}
 
   @Get('/:id')
@@ -205,6 +218,29 @@ export default class UsersController {
 }
 ```
 
+### Forward References (`forwardRef`) & Circular Dependencies
+
+When two services mutually depend on each other (`ServiceA` requires `ServiceB` and `ServiceB` requires `ServiceA`), circular references normally lead to `ReferenceError` during module evaluation. ExisJS solves this using `forwardRef(() => Service)` alongside lazy ES6 proxy resolution:
+
+```typescript filename="src/services/order.service.ts"
+import { Injectable } from 'exisjs/decorators'
+import { Inject, forwardRef } from 'exisjs/di'
+import { InventoryService } from './inventory.service'
+
+@Injectable()
+export class OrderService {
+  constructor(
+    @Inject(forwardRef(() => InventoryService))
+    private inventory: InventoryService
+  ) {}
+
+  processOrder(id: string) {
+    return this.inventory.reserveStock(id)
+  }
+}
+```
+
+
 ## Injection Scopes
 
 For people coming from different programming language backgrounds, it might be unexpected to learn that in ExisJS, almost everything is shared across incoming requests. We have a connection pool to the database, singleton services with global state, etc. This is because Node.js doesn't follow the request/response Multi-Threaded Stateless Model.

package/dist/docs/content/requests.mdx

@@ -451,11 +451,17 @@ const language = req.acceptsLanguages('en', 'es', 'fr')
 
 ---
 
-## 7. Network Information & IPv6 Normalization
+## 7. Network Information & Reverse Proxy IP Resolution
 
-ExisJS handles trust-proxies and dual-stack IP networks automatically. If you are behind Cloudflare, Nginx, or an AWS Load Balancer, simply set `trustProxy: true` in your `exis()` config, and these properties will automatically resolve the true client IP from `X-Forwarded-For`.
+ExisJS handles reverse proxies, CDNs, and dual-stack IP networks automatically. When deployed behind Cloudflare, AWS ALB, NGINX, Render, or GCP, set `trustProxy: true` in your `exis.config.ts` or define `TRUST_PROXY=true` in your environment variables.
 
-- **`req.ip`**: The client's IP address. Automatically normalizes IPv6-mapped IPv4 dual-stack addresses (e.g., `::ffff:192.168.1.50` $\to$ `192.168.1.50`) and converts IPv6 loopback `::1` $\to$ `127.0.0.1` for consistent rate limiting and geo-IP lookups.
+When proxy trust is enabled, ExisJS evaluates industry-standard proxy and CDN headers in priority order:
+1. `CF-Connecting-IP` (Cloudflare)
+2. `True-Client-IP` (Akamai / Cloudflare Enterprise)
+3. `X-Real-IP` / `X-Client-IP` (NGINX / Reverse Proxies)
+4. `X-Forwarded-For` (Standard multi-hop proxy chains)
+
+- **`req.ip`**: The real client's IP address. Automatically strips proxy hops, normalizes IPv6-mapped IPv4 dual-stack addresses (e.g., `::ffff:192.168.1.50` $\to$ `192.168.1.50`), and converts IPv6 loopback `::1` $\to$ `127.0.0.1` for consistent rate limiting and geo-IP lookups.
 - **`req.ips`**: An array of IPs if multiple proxies were traversed, each normalized cleanly.
 - **`req.hostname`**: The resolved hostname (from `Host` or `X-Forwarded-Host`).
 - **`req.protocol`**: Returns `'http'` or `'https'`.

package/dist/docs/content/responses.mdx

@@ -575,17 +575,31 @@ export default class AuthController {
 
 ---
 
-## 6. ETags & Conditional Requests (304 Not Modified)
+## 6. Safe Response Serialization (BSON, Dates & Prototype Auto-Unwrapping)
 
-ExisJS features native, automatic ETag generation. 
+ExisJS includes a robust, zero-crash serialization engine that automatically prepares complex objects before sending them down the wire:
 
-If the client sends an `If-None-Match` header matching the ETag of the current response, ExisJS will immediately abort serialization and send a `304 Not Modified` header with an empty body, saving bandwidth and CPU cycles.
+- **Mongoose / ORM Documents**: Automatically unwraps documents by invoking `.toObject({ virtuals: true, getters: true })` or `.toJSON()`. You no longer need to call `.lean()` or sanitize documents manually.
+- **MongoDB BSON Types**: Automatically converts `ObjectId`, `Decimal128`, `Long`, and `Binary` buffers to their clean string / base64 representations.
+- **BigInt & Dates**: Converts native `BigInt` values to strings and `Date` instances to ISO 8601 strings.
+- **Maps & Sets**: Automatically converts `Map` to plain objects and `Set` to arrays.
+- **Circular Reference Guard**: Circular object references are safely detected and replaced with `'[Circular]'` rather than throwing fatal V8 JSON serialization exceptions.
+- **Enhanced Diagnostics**: If an unhandled serialization issue occurs, ExisJS logs the exact property path (e.g. `'recentTransactions[0].accountId'`) for immediate debugging clarity.
 
-*Note: ETag generation is disabled by default, but can be enabled globally in your `exis()` config, or manually per-route via `res.etagEnabled = true`.*
+---
+
+## 7. ETags & Conditional Requests (304 Not Modified)
+
+ExisJS features native ETag generation.
+
+By default, ETags are disabled (`etag: false`) on dynamic REST API endpoints to minimize hashing CPU overhead and provide transparent logging timings. 
+
+When enabled globally (`etag: true` in `exis.config.ts`) or on a per-route basis (`res.etagEnabled = true`):
+- If the client sends an `If-None-Match` header matching the response ETag, ExisJS immediately sends `304 Not Modified` with an empty body, saving bandwidth.
 
 ---
 
-## 7. Server-Sent Events (SSE) & AI Streaming
+## 8. Server-Sent Events (SSE) & AI Streaming
 
 ExisJS provides a first-class `res.sse()` method for real-time live events and AI chat completions (OpenAI, Anthropic, Ollama, LangChain).
 

package/dist/docs/reference/config.mdx

@@ -103,14 +103,15 @@ Here is the full list of options supported natively by the ExisJS configuration
 - **`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.
+- **`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`).
+- **`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`).
 
 ### Extended Integrations
 - **`queue`**: Define your background queue driver (`memory` or `redis`) and configure `maxConcurrent` processing limits.

package/dist/docs/reference/decorators.mdx

@@ -83,8 +83,16 @@ Parameter decorators automatically extract data from the incoming request and in
 
 ---
 
-## 3. Middleware & Pipeline Decorators
-
+## 3. Transformation Pipes & Middleware Decorators
+
+- `@UsePipes(...pipes)`: Binds transformation and validation pipes to a controller class or route method.
+- **Built-in Pipes**:
+  - `ParseIntPipe`: Parses numeric strings to integers (`options?: { errorHttpStatusCode, exceptionFactory }`).
+  - `ParseFloatPipe`: Parses numeric float strings (`options?: { errorHttpStatusCode, exceptionFactory }`).
+  - `ParseBoolPipe`: Parses boolean strings (`'true'`, `'false'`, `1`, `0`).
+  - `ParseUUIDPipe`: Validates UUID format (`options?: { version: '3' | '4' | '5' | 'all' }`).
+  - `ParseArrayPipe`: Splits comma-separated strings and applies item-level transformation pipes.
+  - `ValidationPipe`: Validates DTO classes and schemas (`options?: { transform: boolean }`).
 - `@Use(...middlewaresOrGuardsOrInterceptorsOrFilters)`: Unified decorator that binds middlewares, guards (`canActivate`), interceptors (`intercept`), or exception filters (`catch`) to a controller class or method.
 - `@UseGuards(...guards)`: Dedicated decorator to apply guards to a class or method.
 - `@UseInterceptors(...interceptors)`: Dedicated decorator to apply interceptors to a class or method.
@@ -139,10 +147,12 @@ Parameter decorators automatically extract data from the incoming request and in
 
 ## 7. Dependency Injection & Modules
 
+- `@Global()`: Marks a `@Module()` as global, automatically making its exported providers available across the entire application without explicit re-importing.
 - `@Module({ imports?, controllers?, providers?, exports? })`: OOP class decorator equivalent to `defineModule()` for structuring application modules.
 - `@Injectable(options?)`: Marks a service class as an IoC provider managed by the container. Supports `{ scope: 'singleton' | 'request' | 'transient' }`.
-- `@Inject(token)`: Constructor parameter decorator from `exisjs/di` for injecting dependencies by class, string, or symbol token.
-- `@Optional()`: Constructor parameter decorator from `exisjs/di` resolving missing dependencies to `undefined` without throwing.
+- `@Inject(token)`: Constructor parameter and class property decorator from `exisjs/di` for injecting dependencies by class, string, or symbol token.
+- `@Optional()`: Parameter and property decorator from `exisjs/di` resolving missing dependencies to `undefined` without throwing.
+- `forwardRef(() => Target)`: Creates a lazy forward reference for resolving circular dependencies in constructor or property injection.
 - `@Boundary(config)`: Marks a class as a folder-scoped Boundary configuring CORS, headers, exclusions, and pipeline steps.
 - `@Server(config)`: Marks a class as a root server definition.
 
@@ -154,3 +164,4 @@ Parameter decorators automatically extract data from the incoming request and in
 - `@Interval(ms: number, options?: IntervalOptions)`: Schedules a class method to execute repeatedly every `ms` milliseconds.
 - `@TimeoutTask(ms: number, options?: TimeoutOptions)` (alias `@ScheduledTimeout`): Schedules a class method to execute once after `ms` milliseconds following application bootstrap.
 
+

package/dist/docs/reference/di.mdx

@@ -109,20 +109,39 @@ export default controller({
 > [!NOTE]
 > `inject()` relies on the active execution context. If you call `inject()` outside of an active HTTP request or application lifecycle hook (e.g., in a background `setInterval` without context), it will throw an error.
 
-### 2. Constructor Injection in Classes (OOP)
+### 2. Constructor & Property Injection in Classes (OOP)
 
-ExisJS supports full OOP constructor parameter injection. You can inject services directly via type annotation or specify tokens with `@Inject()`, and designate optional dependencies with `@Optional()`:
+ExisJS supports full OOP constructor parameter and property field injection with **automatic parameter type reflection**:
+- **Automatic Type Reflection**: If `emitDecoratorMetadata: true` is enabled in `tsconfig.json`, ExisJS inspects `design:paramtypes` and automatically maps constructor parameter classes directly to dependencies registered in `INJECTABLE_REGISTRY`. You do not need `@Inject()` on standard service classes!
+- **Property-Level `@Inject()`**: Inject dependencies directly onto class properties (`@Inject(Token) public service!: Service`) with automatic `design:type` reflection fallback.
+- **Token Injection (`@Inject(token)`)**: Use `@Inject('TOKEN')` when injecting custom strings, config objects, or symbols.
+- **Optional Dependencies (`@Optional()`)**: Mark dependencies that can safely resolve to `undefined` if not registered.
+- **Forward References (`forwardRef(() => Service)`)**: Resolve circular dependencies between services using lazy forward references and ES6 Proxy delegates.
 
 ```typescript filename="src/http/users/route.ts"
-import { Controller, Get, Param, Inject, Optional } from 'exisjs/decorators'
+import { Controller, Get, Param } from 'exisjs/decorators'
+import { Inject, Optional, forwardRef } from 'exisjs/di'
 import { UserService } from './service'
+import { ConfigService } from '../config/service'
 
 @Controller('/users')
 export default class UserController {
+  // 1. Property-level injection
+  @Inject(ConfigService)
+  private config!: ConfigService
+
+  // 2. Optional property injection
+  @Inject('ANALYTICS')
+  @Optional()
+  private analytics?: any
+
   constructor(
+    // 3. Automatically resolved from INJECTABLE_REGISTRY via type reflection!
     private userService: UserService,
+    // 4. Explicit token injection
     @Inject('DATABASE_URL') private dbUrl: string,
-    @Optional() @Inject('ANALYTICS') private analytics?: any
+    // 5. Circular dependency resolution via forwardRef
+    @Inject(forwardRef(() => UserService)) private circularRef: UserService
   ) {}
 
   @Get('/:id')
@@ -132,18 +151,6 @@ export default class UserController {
 }
 ```
 
-You can also use property-level `inject()` inside your Controller methods:
-
-```typescript
-@Controller('/users')
-export default class UserController {
-  @Get('/')
-  async getUsers() {
-    const db = inject(Database)
-    return db.query('SELECT * FROM users')
-  }
-}
-```
 
 ---