exisjs 0.7.8 → 0.7.10

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 { 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/decorators.mdx

@@ -178,6 +178,10 @@ export default class CheckoutController {
 
 ### Available Lifecycle & Middleware Decorators
 - `@Use(...items)` — Unified decorator that attaches middlewares, guards (`canActivate`), interceptors (`intercept`), or exception filters (`catch`) to a class or method.
+- `@UseGuards(...guards)` — Explicit alias for `@Use` dedicated to route guards.
+- `@UseInterceptors(...interceptors)` — Explicit alias for `@Use` dedicated to interceptors.
+- `@UseFilters(...filters)` — Explicit alias for `@Use` dedicated to exception filters.
+- `@Catch(...exceptions)` — Declares exception classes handled by an Exception Filter.
 - `@Timeout(ms: number | TimeoutOptions)` — Overrides the request timeout for a class or method.
 - `@Idempotent(options?)` — Caches responses based on the `Idempotency-Key` header using native in-memory off-heap storage.
 - `@RateLimit(options?)` — Enforces request rate limits on a controller class or route method.
@@ -190,7 +194,88 @@ export default class CheckoutController {
 
 ---
 
-## 5. Response & Metadata Modifiers
+## 5. Security & Authorization Decorators
+
+Declare access control rules directly on controller classes and route methods:
+
+```typescript filename="src/http/roles/route.ts"
+import { Controller, Get, Post, Body, Use, Permissions, Roles, Public } from 'exisjs/decorators'
+import { AuthGuard } from '@/common/guards/auth.guard'
+
+@Controller('/roles')
+@Use(AuthGuard) // Enforced on all routes in this controller
+export default class RolesController {
+  @Get('/public')
+  @Public() // Bypasses auth guard for public inspection
+  async getPublicInfo() {
+    return { status: 'public' }
+  }
+
+  @Get('/')
+  @Roles('admin', 'manager') // Requires user to have admin or manager role
+  async getRoles() {
+    return { roles: [] }
+  }
+
+  @Post('/')
+  @Permissions('role:create', 'role:manage') // Granular permission check
+  async createRole(@Body() body: any) {
+    return { success: true }
+  }
+}
+```
+
+### Available Security Decorators
+- `@Permissions(...permissions: string[])` — Declares required permissions (auto-bypassed when `req.user.isSuperAdmin` is true).
+- `@Roles(...roles: string[])` — Declares required role names.
+- `@Public()` / `@IsPublic()` / `@AllowAnonymous()` — Marks an endpoint or controller as public, instructing global auth guards to skip credential verification.
+
+---
+
+## 6. Service Enhancements: Caching, Transactions & Profiling
+
+ExisJS provides high-performance method decorators for `@Injectable()` services:
+
+```typescript filename="src/http/orders/service.ts"
+import { Injectable, Cacheable, CacheEvict, Transactional, Profile, type OnInit, type OnDestroy } from 'exisjs/decorators'
+
+@Injectable()
+export class OrderService implements OnInit, OnDestroy {
+  async onInit() {
+    console.log('OrderService initialized')
+  }
+
+  async onDestroy() {
+    console.log('OrderService destroyed')
+  }
+
+  // Caches result in off-heap Rust cache for 300 seconds
+  @Cacheable({ ttl: 300, key: (id: string) => `order:${id}` })
+  @Profile({ thresholdMs: 50, warnSlow: true })
+  async getOrder(id: string) {
+    return this.db.query('SELECT * FROM orders WHERE id = $1', [id])
+  }
+
+  // Automatically runs in a database transaction and evicts cached entries
+  @Transactional()
+  @CacheEvict({ key: (id: string) => `order:${id}` })
+  async updateOrder(id: string, data: any) {
+    return this.db.update('orders', id, data)
+  }
+}
+```
+
+### Available Service Decorators & Lifecycle Interfaces
+- `@Cacheable({ ttl?: number, key?: string | ((...args) => string) })` — Caches method return values in off-heap memory.
+- `@CacheEvict({ key: string | ((...args) => string) })` — Evicts cached keys on mutation.
+- `@Transactional(options?)` — Wraps service operations in an atomic database transaction.
+- `@Profile({ thresholdMs?: number, warnSlow?: boolean, log?: Function })` — Measures method execution time with sub-millisecond precision.
+- `OnInit` (`onInit()`) & `OnDestroy` (`onDestroy()`) — Service startup and shutdown lifecycle hooks.
+- `OnModuleInit`, `OnModuleDestroy`, `OnApplicationBootstrap` — Module lifecycle hooks.
+
+---
+
+## 7. Response & Metadata Modifiers
 
 Modify HTTP response status codes, redirect clients, or set headers declaratively:
 
@@ -219,14 +304,13 @@ export default class ApiController {
 - `@Header(name: string, value: string)` — Injects a response header.
 - `@Returns(schema)` — Attaches response schema for OpenAPI/Swagger generation.
 - `@Redirect(url: string, statusCode?: number)` — Redirects the client.
-- `@Permissions(...permissions: string[])` — Attaches route permissions metadata.
 - `@Hosts(...hosts: string[])` — Restricts route/controller to specific Host headers.
 - `@SetMetadata(key, value)` — Attaches custom metadata to a class or method.
-- `Reflector` — Static utility to inspect metadata attached via `@SetMetadata` across classes and methods (`Reflector.get`, `Reflector.getAllAndOverride`, `Reflector.getAllAndMerge`).
+- `Reflector` — Static utility to inspect metadata attached via `@SetMetadata` across classes and methods.
 
 ---
 
-## 6. Dependency Injection & Modules
+## 8. Dependency Injection & Modules
 
 To mark a service class as an injectable provider for the IoC container, use the `@Injectable()` decorator. ExisJS supports `singleton` (default), `request`, and `transient` scopes:
 
@@ -281,3 +365,4 @@ import { UserService } from './service'
 })
 export class UsersModule {}
 ```
+

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"
 }
 ```
 
@@ -335,26 +342,42 @@ export default controller({
 
 ### Class-Based (OOP) Paradigm
 
-```typescript filename="src/http/users/route.ts"
-import { Controller, Get, UseFilters } from 'exisjs/decorators'
-import type { Request, Response } from 'exisjs/router'
+You can use function handlers or structured class-based `ExceptionFilter` implementations with `@Catch()`:
+
+```typescript filename="src/http/filters/not-found.filter.ts"
+import { Catch, type ExceptionFilter, type ArgumentsHost } from 'exisjs/decorators'
+import { NotFoundException } from 'exisjs/error'
 
-function localErrorHandler(err: any, req: Request, res: Response, next: any) {
-  console.log('Users Controller Error Handler Caught:', err.message)
-  res.status(400).json({ success: false, localError: err.message })
+@Catch(NotFoundException)
+export class NotFoundExceptionFilter implements ExceptionFilter<NotFoundException> {
+  catch(exception: NotFoundException, host: ArgumentsHost) {
+    const { res } = host
+    res.status(404).json({
+      statusCode: 404,
+      error: 'Not Found',
+      message: exception.message,
+      timestamp: new Date().toISOString(),
+    })
+  }
 }
+```
 
-@Controller()
-@UseFilters(localErrorHandler)
+```typescript filename="src/http/users/route.ts"
+import { Controller, Get, UseFilters, Use } from 'exisjs/decorators'
+import { NotFoundException } from 'exisjs/error'
+import { NotFoundExceptionFilter } from '../filters/not-found.filter'
+
+@Controller('/users')
+@Use(NotFoundExceptionFilter) // or @UseFilters(NotFoundExceptionFilter)
 export default class UsersController {
-  @Get('/crash')
-  async crash() {
-    throw new Error("Something went wrong in the users module")
+  @Get('/:id')
+  async getUser() {
+    throw new NotFoundException('User')
   }
 }
 ```
 
-By combining Exception Filters and Local Error Hooks, ExisJS gives you control over your error boundaries.
+By combining Exception Filters and Local Error Hooks, ExisJS gives you complete control over your error boundaries.
 
 ## Observability (BYOM/BYOT)
 

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