exisjs 0.7.9 → 0.7.11

package/dist/di/forward-ref.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.forwardRef = forwardRef;
+exports.isForwardRef = isForwardRef;
+/**
+ * Creates a lazy forward reference for resolving circular dependencies between providers or modules.
+ *
+ * Example:
+ * ```ts
+ * @Injectable()
+ * export class OrderService {
+ *   constructor(
+ *     @Inject(forwardRef(() => InventoryService))
+ *     private inventoryService: InventoryService
+ *   ) {}
+ * }
+ * ```
+ */
+function forwardRef(fn) {
+    return { forwardRef: fn };
+}
+/**
+ * Checks if a value is a ForwardReference wrapper.
+ */
+function isForwardRef(val) {
+    return (val !== null &&
+        typeof val === 'object' &&
+        typeof val.forwardRef === 'function');
+}
+//# sourceMappingURL=forward-ref.js.map

package/dist/di/forward-ref.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"forward-ref.js","sourceRoot":"","sources":["../../src/di/forward-ref.ts"],"names":[],"mappings":";;AAkBA,gCAEC;AAKD,oCAMC;AA3BD;;;;;;;;;;;;;GAaG;AACH,SAAgB,UAAU,CAAU,EAAW;IAC7C,OAAO,EAAE,UAAU,EAAE,EAAE,EAAE,CAAA;AAC3B,CAAC;AAED;;GAEG;AACH,SAAgB,YAAY,CAAC,GAAQ;IACnC,OAAO,CACL,GAAG,KAAK,IAAI;QACZ,OAAO,GAAG,KAAK,QAAQ;QACvB,OAAO,GAAG,CAAC,UAAU,KAAK,UAAU,CACrC,CAAA;AACH,CAAC"}

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 type { ProviderToken, ProviderDefinition, ValueProvider, FactoryProvider, ClassProvider, ClassConstructor, } 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,EACb,gBAAgB,GACjB,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;AASzB,6CAA+E;AAAtE,yGAAA,UAAU,OAAA;AAAE,2GAAA,YAAY,OAAA"}

package/dist/docs/BENCHMARKS.md

@@ -12,16 +12,16 @@
 - **Trials:** 3 per framework, order randomized each trial, median reported
 - **Warmup:** 2s untimed warmup run before each timed trial
 - **Cores:** single-core, no clustering, for all four frameworks
-- **Framework versions:** Express ^5.2.1, Fastify ^5.12.1, Hono ^4.13.5, ExisJS 0.6.1
+- **Framework versions:** Express ^5.2.1, Fastify ^5.12.5, Hono ^4.13.8, ExisJS 0.7.3
 
 ### Performance Metrics
 
 | Framework | Req/Sec (median) | Latency avg (ms) | Latency p50 (ms) | Latency p99 (ms) | Errors | Server backend |
 |---|---|---|---|---|---|---|
-| Express | 16821.82 | 5.40 | 6.00 | 7.00 | 0 | n/a |
-| Fastify | 27625.46 | 3.12 | 3.00 | 5.00 | 0 | n/a |
-| Hono | 30645.82 | 2.79 | 3.00 | 4.00 | 0 | n/a |
-| Exis JS | 38022.55 | 2.14 | 2.00 | 4.00 | 0 | uws |
+| Express | 24778.91 | 3.41 | 3.00 | 5.00 | 0 | n/a |
+| Fastify | 41802.19 | 2.04 | 2.00 | 3.00 | 0 | n/a |
+| Hono | 43174.40 | 2.04 | 2.00 | 3.00 | 0 | n/a |
+| Exis JS | 51430.40 | 1.26 | 1.00 | 3.00 | 0 | uws |
 
 ### Handler Parity Note
 

package/dist/docs/content/config.mdx

@@ -75,11 +75,13 @@ We highly recommend using `v.env()` from `exisjs/validator` to strongly type and
 ```typescript filename="env.ts"
 import { tex } from 'exisjs/validator'
 
-export const env = tex.object({
-  PORT: tex.number({ coerce: true, optional: true }),
-  NODE_ENV: tex.string({ optional: true }),
-  MONGODB_URI: tex.string(),
-}).parse(process.env)
+export const env = tex
+  .object({
+    PORT: tex.number({ coerce: true, optional: true }),
+    NODE_ENV: tex.string({ optional: true }),
+    MONGODB_URI: tex.string(),
+  })
+  .parse(process.env)
 ```
 
 ```typescript filename="exis.config.ts"
@@ -167,6 +169,14 @@ Here is a full breakdown of the configuration schema:
 - `debugRouting` _(boolean)_: Enables detailed logging of the resolved route file and applied gateways for every incoming request.
 - `test` _(object)_: Configuration for the native test runner (`include`, `exclude`, `setupFiles`, `concurrency`, `coverage`).
 
+### Development Server & File Watcher (`dev`)
+
+- `dev.watch` _(string[])_: Custom paths or glob patterns to watch during development (defaults to `[cwd]`).
+- `dev.ignored` _((string | RegExp)[])_: Additional files or patterns to ignore during watch restarts.
+- `dev.usePolling` _(boolean)_: Enables filesystem polling for cross-platform/Windows NTFS reliability (defaults to `true` on Windows).
+- `dev.interval` _(number)_: Polling interval in milliseconds (default: `100`).
+- `dev.binaryInterval` _(number)_: Polling binary interval in milliseconds (default: `300`).
+
 ### Queues & Plugins
 
 - `queue` _(object)_: Configures the Global Job Queue driver (`memory` or `redis`) and backpressure settings.
@@ -242,6 +252,6 @@ export default exis({
   async onStop(app) {
     // Cleanly close database pools when SIGTERM or SIGINT is received
     await db.disconnect()
-  }
+  },
 })
 ```

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).