exisjs 0.7.8 → 0.7.10

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
@@ -78,6 +80,54 @@ const app = getActiveApp()
 const usersService = app.container.resolve(UsersService)
 ```
 
+## Service Lifecycle Hooks
+
+ExisJS `@Injectable()` services can implement lifecycle interfaces. When the application starts up or shuts down gracefully, ExisJS automatically triggers these hooks on all managed singletons:
+
+```typescript filename="src/http/database/service.ts"
+import { Injectable, type OnInit, type OnDestroy } from 'exisjs/decorators'
+
+@Injectable()
+export class DatabaseService implements OnInit, OnDestroy {
+  async onInit(): Promise<void> {
+    // Invoked automatically during app startup (app.create / app.listen)
+    await this.connectPool()
+  }
+
+  async onDestroy(): Promise<void> {
+    // Invoked automatically during graceful termination (app.close / SIGINT / SIGTERM)
+    await this.drainPool()
+  }
+}
+```
+
+## Service Method Enhancements
+
+You can supercharge service methods with off-heap caching, automated transaction wrapping, and SLA performance profiling:
+
+```typescript filename="src/http/users/service.ts"
+import { Injectable, Cacheable, CacheEvict, Transactional, Profile } from 'exisjs/decorators'
+
+@Injectable()
+export class UsersService {
+  constructor(private db: DatabaseService) {}
+
+  // Caches return values off-heap in Rust LRU cache
+  @Cacheable({ ttl: 300, key: (id: string) => `user:${id}` })
+  @Profile({ thresholdMs: 100, warnSlow: true })
+  async findById(id: string) {
+    return this.db.query('SELECT * FROM users WHERE id = $1', [id])
+  }
+
+  // Runs in an atomic transaction; automatically rolls back on error
+  @Transactional()
+  @CacheEvict({ key: (id: string) => `user:${id}` })
+  async updateUser(id: string, data: any) {
+    return this.db.update('users', id, data)
+  }
+}
+```
+
 ## Custom Providers
 
 ExisJS's DI container is flexible. By default, when you register a class, ExisJS instantiates it for you. However, you often need more control. You can register standard classes, raw values, factories, or aliased classes natively using `app.provide()`.
@@ -134,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')
@@ -157,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,9 +83,21 @@ 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.
+- `@UseFilters(...filters)`: Dedicated decorator to apply exception filters to a class or method.
+- `@Catch(...exceptions)`: Class decorator for `ExceptionFilter` implementations declaring handled exception types.
 - `@Upload(fieldName, options?)` / `@UseUpload(...)`: Configures multipart file upload handling for a method, populating `@UploadedFile()` or `@UploadedFiles()`.
 - `@Timeout(ms: number | TimeoutOptions)`: Overrides the request timeout for a class or method (e.g. `@Timeout(120000)`). Passing `0` disables timeouts for long-running streaming or exports.
 - `@Idempotent(options?)`: Caches responses based on the `Idempotency-Key` header using native in-memory off-heap storage. Works at class and method level.
@@ -98,13 +110,32 @@ Parameter decorators automatically extract data from the incoming request and in
 
 ---
 
-## 4. Response & Metadata Modifiers
+## 4. Security & Access Control Decorators
+
+- `@Permissions(...permissions: string[])`: Sets required permission keys for a controller or route method (automatically bypassed if `req.user.isSuperAdmin` is true).
+- `@Roles(...roles: string[])`: Sets required role names for a controller or route method.
+- `@Public()` / `@IsPublic()` / `@AllowAnonymous()`: Marks a controller or route as public, instructing global authentication guards to bypass credential checks.
+
+---
+
+## 5. Service Enhancements: Caching, Transactions & Profiling
+
+- `@Cacheable({ ttl?: number, key?: string | ((...args) => string) })`: Caches method return values in ExisJS's off-heap native memory LRU cache.
+- `@CacheEvict({ key: string | ((...args) => string) })`: Evicts cached entries matching the key when the method completes.
+- `@Transactional(options?)`: Automatically wraps service operations in an atomic database transaction.
+- `@Profile({ thresholdMs?: number, warnSlow?: boolean, log?: Function })`: Profiles method execution time with sub-millisecond precision.
+- `OnInit` (`onInit()`): Invoked when the application or service boots up.
+- `OnDestroy` (`onDestroy()`): Invoked when the application gracefully terminates.
+- `OnModuleInit`, `OnModuleDestroy`, `OnApplicationBootstrap`: Modular lifecycle hooks.
+
+---
+
+## 6. Response & Metadata Modifiers
 
 - `@HttpCode(code: number)`: Enforces a custom HTTP status code on success.
 - `@Header(name: string, value: string)`: Appends an HTTP header to the response.
 - `@Returns(schema)`: Attaches response schema for OpenAPI documentation.
 - `@Redirect(url: string, statusCode?: number)`: Redirects request to target URL.
-- `@Permissions(...permissions: string[])`: Sets required permissions on the route.
 - `@Hosts(...hosts: string[])`: Restricts routes to specific Host headers.
 - `@SetMetadata(key, value)`: Attaches arbitrary custom metadata to a class or handler method, retrievable via `Reflector`.
 - `Reflector`: Utility class to inspect metadata attached by `@SetMetadata`:
@@ -114,20 +145,23 @@ Parameter decorators automatically extract data from the incoming request and in
 
 ---
 
-## 5. Dependency Injection & Modules
+## 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.
 
 ---
 
-## 6. Cron & Task Scheduling
+## 8. Cron & Task Scheduling
 
 - `@Cron(schedule: string, options?: CronJobOptions)`: Schedules a class method as a recurring cron job on any `@Injectable()` service.
 - `@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,16 +151,30 @@ 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')
+---
+
+## Lifecycle Hooks (`OnInit`, `OnDestroy`)
+
+Providers can implement lifecycle interfaces. When the application container initializes or gracefully closes, ExisJS automatically triggers these hooks:
+
+- **`OnInit` (`onInit()` / `onModuleInit()`)**: Executed when the container initializes during `app.create()` or `app.listen()`.
+- **`OnDestroy` (`onDestroy()` / `onModuleDestroy()`)**: Executed when the application receives a termination signal or `app.close()` is called.
+- **`OnApplicationBootstrap` (`onApplicationBootstrap()`)**: Executed after all modules are initialized and before the server begins listening for incoming requests.
+
+```typescript filename="src/http/database/service.ts"
+import { Injectable, type OnInit, type OnDestroy } from 'exisjs/decorators'
+
+@Injectable()
+export class DatabaseService implements OnInit, OnDestroy {
+  async onInit(): Promise<void> {
+    await this.pool.connect()
+  }
+
+  async onDestroy(): Promise<void> {
+    await this.pool.end()
   }
 }
 ```
 
+

package/dist/docs/reference/router.mdx

@@ -47,6 +47,81 @@ export default controller({
 - `onResponse` (`HookResponse`): A file-level response hook.
 - `[key: string]` (`RouteDefinition`): **Any other key** is treated as a route definition (e.g. `getUser: route.get(...)`). This is how you bind routes to the controller!
 
+### `controller.merge(...controllers)`
+
+Merges multiple functional controllers into a single unified controller definition. This enables splitting large `route.ts` files into modular, domain-specific controller pieces while exporting a single composite controller from the route file.
+
+```typescript filename="src/http/auth/route.ts"
+import { controller, route } from 'exisjs/router'
+
+// Sub-controller 1: credentials & sessions
+const authRoutes = controller({
+  login: route.post('/login', {
+    async handle({ body }) {
+      return { token: 'jwt-token' }
+    }
+  }),
+  logout: route.post('/logout', {
+    async handle() {
+      return { success: true }
+    }
+  })
+})
+
+// Sub-controller 2: OAuth integrations
+const oauthRoutes = controller({
+  google: route.get('/google', {
+    async handle() {
+      return { redirectUrl: 'https://accounts.google.com/o/oauth2/auth' }
+    }
+  })
+})
+
+// Export combined controller as default
+export default controller.merge(authRoutes, oauthRoutes)
+```
+
+### `controller.extend(base, overrides)`
+
+Inherits all route definitions, middlewares, filters, and configuration from a `base` controller and applies overrides or adds new route endpoints. This provides the functional equivalent of class-based controller inheritance for reusable CRUD templates.
+
+```typescript filename="src/http/products/route.ts"
+import { controller, route } from 'exisjs/router'
+
+// Reusable generic CRUD controller factory
+function createBaseCrud(resource: string) {
+  return controller({
+    list: route.get('/', {
+      async handle() {
+        return { resource, items: [] }
+      }
+    }),
+    getById: route.get('/:id', {
+      async handle({ params }) {
+        return { resource, id: params.id }
+      }
+    })
+  })
+}
+
+// Inherit base endpoints and add specialized or overridden 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 }
+    }
+  })
+})
+```
+
 ---
 
 ## `route`

package/dist/docs/reference/validator.mdx

@@ -14,8 +14,8 @@ ExisJS ships with a efficient, integrated validation library out of the box, exp
 The `tex` object provides factory functions for every common primitive and data structure:
 
 - `tex.string(options?)`: Validates a string (supports min, max, trim, sanitizers, masking, SQL injection prevention, defaults).
-- `tex.number(options?)`: Validates a numeric value (supports min, max, coercion, defaults).
-- `tex.boolean(options?)`: Validates a boolean value (supports coercion, defaults).
+- `tex.number(options?)`: Validates a numeric value. Automatically coerces numeric strings in query parameters (e.g., `?limit=100` $\to$ `100`) and supports `{ coerce: true, min, max, default }`.
+- `tex.boolean(options?)`: Validates a boolean value. Automatically coerces boolean strings in query parameters (e.g., `?active=true` $\to$ `true`, `"1"`/`"0"`, `"yes"`/`"no"`) and supports `{ coerce: true, default }`.
 - `tex.email(options?)`: Validates standard email formatting.
 - `tex.uuid(options?)`: Validates UUID v1 or v4 strings (`{ version: 1 | 4 }`).
 - `tex.cuid(options?)`: Validates CUID identifiers.

package/dist/error/errors.d.ts

@@ -51,18 +51,30 @@ export declare class ServiceUnavailableError extends HttpError {
 export declare class GatewayTimeoutError extends HttpError {
     constructor(message?: string);
 }
-export declare const HttpException: typeof HttpError;
-export declare const BadRequestException: typeof BadRequestError;
-export declare const UnauthorizedException: typeof UnauthorizedError;
-export declare const ForbiddenException: typeof ForbiddenError;
-export declare const NotFoundException: typeof NotFoundError;
-export declare const ConflictException: typeof ConflictError;
-export declare const PayloadTooLargeException: typeof PayloadTooLargeError;
-export declare const UnprocessableException: typeof UnprocessableError;
-export declare const RateLimitException: typeof RateLimitError;
-export declare const InternalException: typeof InternalError;
-export declare const ServiceUnavailableException: typeof ServiceUnavailableError;
-export declare const GatewayTimeoutException: typeof GatewayTimeoutError;
+export declare class HttpException extends HttpError {
+}
+export declare class BadRequestException extends BadRequestError {
+}
+export declare class UnauthorizedException extends UnauthorizedError {
+}
+export declare class ForbiddenException extends ForbiddenError {
+}
+export declare class NotFoundException extends NotFoundError {
+}
+export declare class ConflictException extends ConflictError {
+}
+export declare class PayloadTooLargeException extends PayloadTooLargeError {
+}
+export declare class UnprocessableException extends UnprocessableError {
+}
+export declare class RateLimitException extends RateLimitError {
+}
+export declare class InternalException extends InternalError {
+}
+export declare class ServiceUnavailableException extends ServiceUnavailableError {
+}
+export declare class GatewayTimeoutException extends GatewayTimeoutError {
+}
 export declare function renderValidationTable(rows: {
     field: string;
     received: string;

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

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/error/errors.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/error/errors.ts"],"names":[],"mappings":"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"}

package/dist/error/errors.js

@@ -63,6 +63,7 @@ class HttpError extends Error {
                 message: this.message,
                 ...(this.details !== undefined && { details: this.details }),
             },
+            ...(this.details && typeof this.details === 'object' ? this.details : {}),
         };
     }
 }
@@ -145,18 +146,42 @@ class GatewayTimeoutError extends HttpError {
 }
 exports.GatewayTimeoutError = GatewayTimeoutError;
 // ─── Exception Aliases ────────────────────────────────────────────────────────
-exports.HttpException = HttpError;
-exports.BadRequestException = BadRequestError;
-exports.UnauthorizedException = UnauthorizedError;
-exports.ForbiddenException = ForbiddenError;
-exports.NotFoundException = NotFoundError;
-exports.ConflictException = ConflictError;
-exports.PayloadTooLargeException = PayloadTooLargeError;
-exports.UnprocessableException = UnprocessableError;
-exports.RateLimitException = RateLimitError;
-exports.InternalException = InternalError;
-exports.ServiceUnavailableException = ServiceUnavailableError;
-exports.GatewayTimeoutException = GatewayTimeoutError;
+class HttpException extends HttpError {
+}
+exports.HttpException = HttpException;
+class BadRequestException extends BadRequestError {
+}
+exports.BadRequestException = BadRequestException;
+class UnauthorizedException extends UnauthorizedError {
+}
+exports.UnauthorizedException = UnauthorizedException;
+class ForbiddenException extends ForbiddenError {
+}
+exports.ForbiddenException = ForbiddenException;
+class NotFoundException extends NotFoundError {
+}
+exports.NotFoundException = NotFoundException;
+class ConflictException extends ConflictError {
+}
+exports.ConflictException = ConflictException;
+class PayloadTooLargeException extends PayloadTooLargeError {
+}
+exports.PayloadTooLargeException = PayloadTooLargeException;
+class UnprocessableException extends UnprocessableError {
+}
+exports.UnprocessableException = UnprocessableException;
+class RateLimitException extends RateLimitError {
+}
+exports.RateLimitException = RateLimitException;
+class InternalException extends InternalError {
+}
+exports.InternalException = InternalException;
+class ServiceUnavailableException extends ServiceUnavailableError {
+}
+exports.ServiceUnavailableException = ServiceUnavailableException;
+class GatewayTimeoutException extends GatewayTimeoutError {
+}
+exports.GatewayTimeoutException = GatewayTimeoutException;
 // ─── Global Error Handler ─────────────────────────────────────────────────────
 function escapeHtml(str) {
     if (typeof str !== 'string')
@@ -478,11 +503,14 @@ function createErrorHandler(isDev = false) {
                 httpPart: err.httpPart,
             }));
             res.status(400).json({
+                success: false,
                 statusCode: 400,
                 error: 'Bad Request',
                 message: message || 'Validation Error',
+                validationErrors: errorsMap,
                 errors: errorsMap,
                 details: responseDetails,
+                timestamp: new Date().toISOString(),
             });
             return;
         }
@@ -490,10 +518,14 @@ function createErrorHandler(isDev = false) {
         if (err instanceof SyntaxError && 'body' in err) {
             res.status(400).json({
                 success: false,
+                statusCode: 400,
                 error: {
                     code: 'INVALID_JSON',
                     message: 'Invalid JSON in request body',
                 },
+                message: 'Invalid JSON in request body',
+                validationErrors: null,
+                timestamp: new Date().toISOString(),
             });
             return;
         }
@@ -514,11 +546,15 @@ function createErrorHandler(isDev = false) {
         }
         res.status(500).json({
             success: false,
+            statusCode: 500,
             error: {
                 code: 'INTERNAL_ERROR',
                 message: isDev ? err.message : 'An unexpected error occurred',
                 ...(isDev && { stack: err.stack }),
             },
+            message: isDev ? err.message : 'An unexpected error occurred',
+            validationErrors: null,
+            timestamp: new Date().toISOString(),
         });
     };
 }