exisjs 0.7.4 → 0.7.6

package/dist/docs/content/structure.mdx

@@ -23,6 +23,7 @@ my-backend/
 ├── src/
 │   ├── http/
 │   │   ├── server.ts         # Application entry point
+│   │   ├── error.ts          # Centralized framework exception handler (onError)
 │   │   ├── route.ts          # Root routes (e.g. GET /api)
 │   │   ├── boundary.ts       # Root boundary (config + request pipeline)
 │   │   ├── users/
@@ -72,6 +73,7 @@ Both styles are automatically detected by the route scanner, CLI manifest genera
 | `schema.ts` / `*.schema.ts` | `tex` validation schemas, imported by route files. Mandatory for every route accepting input. | Handlers, routing |
 | `service.ts` / `*.service.ts` | Business logic and data access. DI-injectable. | Routing, response shaping |
 | `boundary.ts` / `*.boundary.ts` | Folder-scoped config + request pipeline for everything in this folder and below. | — |
+| `error.ts` / `*.error.ts` | Centralized exception and validation error handler (`onError`). Auto-mounted by the framework. | Business logic, routes |
 
 ---
 
@@ -172,14 +174,16 @@ A `boundary.ts` applies to every route in its folder and all subfolders. It has
 two independent halves:
 
 1. **Config** — pure data, via `defineBoundary()` (functional) or `@Boundary()`
-   (OOP argument). CORS, headers, DI providers, excluded paths.
-2. **Pipeline** — real code, auto-detected by function signature. No imports,
+   (OOP argument). CORS, headers, DI providers, excluded paths, and lifecycle hooks.
+2. **Pipeline & Hooks** — real code, auto-detected by function signature. No imports,
    no manual registration required.
 
-| Signature                                                                    | Detected as  | Runs                                                 |
-| ---------------------------------------------------------------------------- | ------------ | ---------------------------------------------------- |
-| `(req, res, next)`                                                           | A chain step | In file/declaration order, before the route          |
-| `(ctx, next)` — default export (functional) or a method named `handle` (OOP) | The wrapper  | Around all chain steps and the nested route/boundary |
+| Signature | Detected as | Runs |
+| :--- | :--- | :--- |
+| `(req, res, next)` | Chain Step | In file/declaration order, before the route handler |
+| `beforeHandle(req, res)` | Boundary Guard Hook | Immediately before route execution. Short-circuits on `false` or when headers sent |
+| `afterHandle(req, res, data)` | Response Hook | Immediately after route execution. Receives returned data to transform or audit |
+| `(ctx, next)` — default export (functional) or `handle(ctx, next)` (OOP) | Pipeline Wrapper | Around all chain steps and the nested route/boundary |
 
 ### Functional
 
@@ -190,11 +194,25 @@ import type { Request, Response, Next, BoundaryContext } from "exisjs/router";
 export const config = defineBoundary({
   cors: { origin: ["https://myapp.com"], credentials: true },
   headers: { "X-Powered-By": "ExisJS" },
-  exclude: [{ path: "/health", method: "GET" }],
+  exclude: [{ path: "/admin/health", method: "GET" }],
+
+  // Pre-handler hook (returns false to block with 403, or sends response)
+  beforeHandle(req, res) {
+    if (req.headers["x-role"] !== "admin") {
+      res.status(403).json({ error: "Admin role required" });
+      return false;
+    }
+  },
+
+  // Post-handler hook (transforms returned payload or performs async audit)
+  afterHandle(req, res, data) {
+    res.setHeader("X-Audited-By", "AdminBoundary");
+    return { ...data, auditedAt: Date.now() };
+  },
 });
 
-export function auth(req: Request, res: Response, next: Next) {
-  if (!req.headers["x-api-key"]) throw new UnauthorizedError("Missing API key");
+export function logStep(req: Request, res: Response, next: Next) {
+  console.log(`[Admin] ${req.method} ${req.path}`);
   next();
 }
 
@@ -216,14 +234,29 @@ import type { Request, Response, Next, BoundaryContext } from "exisjs/router";
 @Boundary({
   cors: { origin: ["https://myapp.com"], credentials: true },
   headers: { "X-Powered-By": "ExisJS" },
+  exclude: ["/admin/health"],
 })
 export default class AdminBoundary {
-  auth(req: Request, res: Response, next: Next) {
-    if (!req.headers["x-api-key"])
-      throw new UnauthorizedError("Missing API key");
+  // Pre-handler hook
+  beforeHandle(req: Request, res: Response) {
+    if (req.headers["x-role"] !== "admin") {
+      res.status(403).json({ error: "Admin role required" });
+      return false;
+    }
+  }
+
+  // Post-handler hook
+  afterHandle(req: Request, res: Response, data: any) {
+    return { ...data, auditedAt: Date.now() };
+  }
+
+  // Chain step
+  logStep(req: Request, res: Response, next: Next) {
+    console.log(`[Admin] ${req.method} ${req.path}`);
     next();
   }
 
+  // Wrapper
   async handle(ctx: BoundaryContext, next: Next) {
     try {
       return { success: true, data: await next() };
@@ -234,6 +267,52 @@ export default class AdminBoundary {
 }
 ```
 
+---
+
+## `src/http/error.ts` (Framework-Level Exception Handler)
+
+ExisJS natively discovers and mounts `src/http/error.ts` (or `error.js`) at boot. It exports an `onError(err, req, res)` handler, giving developers a single, standard place to intercept, log, and format all unhandled or validation errors without writing custom `app.onError` boilerplate inside `server.ts`.
+
+### Functional
+
+```typescript filename="src/http/error.ts"
+import type { Request, Response } from "exisjs";
+
+export function onError(err: any, req: Request, res: Response) {
+  const status = err.statusCode || err.status || 500;
+
+  // Format consistent error response across the entire API
+  res.status(status).json({
+    success: false,
+    error: {
+      message: err.message || "Internal Server Error",
+      code: err.code || "INTERNAL_SERVER_ERROR",
+      path: req.path,
+    },
+  });
+}
+```
+
+### Class-Based (OOP)
+
+```typescript filename="src/http/error.ts"
+import type { Request, Response } from "exisjs";
+
+export default class GlobalErrorHandler {
+  onError(err: any, req: Request, res: Response) {
+    const status = err.statusCode || err.status || 500;
+    res.status(status).json({
+      success: false,
+      error: {
+        message: err.message || "Internal Server Error",
+        code: err.code || "INTERNAL_ERROR",
+        path: req.path,
+      },
+    });
+  }
+}
+```
+
 A nested folder's `boundary.ts` always runs _inside_ its parent's `next()` —
 pipeline depth mirrors folder depth automatically.
 

package/dist/docs/content/validation.mdx

@@ -32,20 +32,34 @@ const safeData = userSchema.parse(rawInput)
 
 ExisJS supports a comprehensive set of strict validation primitives:
 
-- `tex.string()` - String validation (supports options like `{ min: 5, max: 10 }`).
-- `tex.email()` - Validates standard email formatting.
-- `tex.number()` - Strict number validation (fails if passed a string).
+- `tex.string()` - String validation (supports options like `{ min, max, trim, toLowerCase, toUpperCase, escapeHtml, stripHtml, slugify, mask, default }`).
+- `tex.email()` - Validates standard email formatting (supports `{ trim, toLowerCase, mask, default }`).
+- `tex.uuid()` - Validates UUID strings (supports `{ version: 1 | 4, default }`).
+- `tex.cuid()` - Validates CUID identifiers (supports `{ default }`).
+- `tex.password()` - Validates password complexity (`{ min, max, requireNumbers, requireSymbols, requireUppercase, requireLowercase }`).
+- `tex.creditCard()` - Validates credit card number formats with optional masking (`{ mask: true }`).
+- `tex.number()` - Strict number validation (fails if passed a string unless `coerce: true`).
+- `tex.number({ coerce: true, min: 0, max: 100, default: 10 })` - Automatically coerces incoming string representations (e.g., query params) into native numbers with optional default fallback.
 - `tex.boolean()` - Strict boolean validation.
-- `tex.number({ coerce: true })` - Automatically coerces incoming string representations into native JavaScript numbers.
-- `tex.boolean({ coerce: true })` - Coerces `"true"`/`"1"` and `"false"`/`"0"` into native booleans.
-- `tex.array(schema)` - Validates an array of items. Accepts primitive types, `tex.object(...)`, or shorthand plain objects `{ ... }`.
+- `tex.boolean({ coerce: true, default: false })` - Coerces `"true"`/`"1"` and `"false"`/`"0"` into native booleans.
+- `tex.date()` - Strict Date instance validation.
+- `tex.date({ coerce: true, minDate: '2020-01-01', maxDate: '2030-01-01', default: () => new Date() })` - Automatically parses ISO 8601 strings, UNIX timestamps, or date strings into native JavaScript `Date` objects with optional boundary checks and lazy default factories.
+- `tex.array(schema, { coerce: true, min: 1, max: 10, default: [] })` - Validates an array of items. When `{ coerce: true }` is enabled, automatically converts single items or comma-separated query strings (`"apple,banana"`) into typed arrays. Accepts primitive types, `tex.object(...)`, or shorthand plain objects `{ ... }`.
+- `tex.enum(['admin', 'user'], { default: 'user' })` - Ensures the value matches one of the provided exact strings.
+- `tex.literal(value)` - Validates against an exact primitive literal (`string | number | boolean`).
+- `tex.record(schema)` - Validates a dictionary/record of key-value pairs matching the value schema.
+- `tex.any()` - Allows any payload value without constraint.
+- `tex.file({ maxSize: 5 * 1024 * 1024, mimeTypes: ['image/png', 'image/jpeg'] })` - Validates uploaded file payloads (size and MIME type).
 - `tex.object({ ... })` - Validates structured JSON objects.
-- `tex.enum(['A', 'B'])` - Ensures the value matches one of the provided exact strings.
 
 All primitives accept modifier options or chained helper methods:
 - `.optional()` / `{ optional: true }` - Allows `undefined`.
 - `.nullable()` / `{ nullable: true }` - Allows `null`.
 - `.nullish()` / `{ nullish: true }` - Allows both `null` and `undefined`.
+- `{ default: value | (() => value) }` - Provides a static default or dynamic factory function when the field is omitted or `undefined`. Automatically marks the field as optional in schemas and infers concrete types in TypeScript.
+
+> [!TIP]
+> **Unified Defaults without Method Chaining**: ExisJS avoids `.default()` chaining overhead in favor of declarative options objects (e.g. `tex.number({ default: 3000 })` or `tex.date({ default: () => new Date() })`). Dynamic factory functions evaluate per request so timestamps and UUIDs remain fresh!
 
 > [!TIP]
 > **Automatic Empty String `""` Normalization**: When forms or query parameters pass empty strings `""` for fields marked as `.optional()`, `.nullable()`, or `.nullish()`, ExisJS automatically converts them to `undefined` or `null` before running type validation. This prevents false positive type errors on numeric, UUID, or enum fields!
@@ -254,12 +268,75 @@ export const RegisterUserSchema = tex.object({
 - **Stringified JSON Support**: When submitting `multipart/form-data`, stringified JSON arrays (e.g. `items: "[{\"sku\":\"ABC\",\"quantity\":2}]"`) or stringified objects are automatically deserialized and validated.
 - **Type Inference**: TypeScript automatically infers the shape of array elements for both `tex.array(tex.object(...))` and `tex.array({ ... })`, ensuring full autocomplete without falling back to `never`.
 
+### Query String Array & Date Coercion
+
+Query strings in HTTP cannot natively represent arrays or date instances. ExisJS solves this elegantly through `{ coerce: true }`:
+
+#### Functional Paradigm
+
+```typescript filename="src/http/events/route.ts"
+import { controller, route } from 'exisjs/router'
+import { tex } from 'exisjs/validator'
+
+const FilterSchema = tex.object({
+  // Coerces ISO 8601 strings (?from=2026-09-01T00:00:00Z) into Date instances
+  from: tex.date({ coerce: true, optional: true }),
+  to: tex.date({ coerce: true, optional: true }),
+  
+  // Coerces both comma-separated strings (?tags=tech,ai) AND repeated params (?tags=tech&tags=ai)
+  // or single values (?tags=tech -> ['tech']) into a typed array of strings
+  tags: tex.array(tex.string(), { coerce: true, optional: true }),
+
+  // Numbers within comma-separated arrays (?ids=1,2,3 -> [1, 2, 3]) are also coerced
+  ids: tex.array(tex.number({ coerce: true }), { coerce: true, optional: true })
+})
+
+export default controller({
+  listEvents: route.get('/events', {
+    query: FilterSchema,
+    handle({ query, res }) {
+      // query.from is Date | undefined
+      // query.tags is string[] | undefined
+      // query.ids is number[] | undefined
+      res.json({ filter: query })
+    }
+  })
+})
+```
+
+#### Class-Based (OOP) Paradigm
+
+```typescript filename="src/http/events/route.ts"
+import { Controller, Get, Query } from 'exisjs/decorators'
+import { tex } from 'exisjs/validator'
+import type { ResolveSchema } from 'exisjs/validator'
+
+const FilterSchema = tex.object({
+  from: tex.date({ coerce: true, optional: true }),
+  to: tex.date({ coerce: true, optional: true }),
+  tags: tex.array(tex.string(), { coerce: true, optional: true }),
+  ids: tex.array(tex.number({ coerce: true }), { coerce: true, optional: true }),
+})
+
+type FilterDto = ResolveSchema<typeof FilterSchema>
+
+@Controller('/events')
+export default class EventsController {
+  @Get('/', { query: FilterSchema })
+  listEvents(@Query() query: FilterDto) {
+    return { filter: query }
+  }
+}
+```
+
 ---
 
 ## Pagination Schemas (`tex.pagination`)
 
 ExisJS provides a dedicated schema primitive for query pagination. It automatically coerces incoming string query parameters (`?page=2&limit=25&sort=name&order=asc`) into typed numbers and strings while enforcing sensible bounds:
 
+#### Functional Paradigm
+
 ```typescript filename="src/http/items/route.ts"
 import { controller, route } from 'exisjs/router'
 import { tex, paginate, getPaginationSkip } from 'exisjs/validator'
@@ -283,11 +360,35 @@ export default controller({
 })
 ```
 
+#### Class-Based (OOP) Paradigm
+
+```typescript filename="src/http/items/route.ts"
+import { Controller, Get, Query } from 'exisjs/decorators'
+import { tex, paginate, getPaginationSkip } from 'exisjs/validator'
+
+const ItemQuerySchema = tex.pagination({
+  defaultLimit: 20,
+  maxLimit: 100,
+})
+
+@Controller('/items')
+export default class ItemsController {
+  @Get('/', { query: ItemQuerySchema })
+  async list(@Query() query: any) {
+    const { skip, limit, page } = getPaginationSkip(query)
+    const items = await fetchItems({ skip, limit, sort: query.sort, order: query.order })
+    const total = await countItems()
+
+    return paginate(items, total, { page, limit })
+  }
+}
+```
+
 ---
 
 ## Error Handling & Developer Diagnostics
 
-If a request fails validation, ExisJS intercepts the rejection and returns a standardized `400 Bad Request` containing a machine-readable `errors: Record<string, string>` dictionary for frontend form field mapping:
+If a request fails validation, ExisJS intercepts the rejection and returns a standardized `400 Bad Request` containing both a legacy `errors: Record<string, string>` dictionary and a structured `details: ValidationErrorDescriptor[]` array for frontend form field mapping:
 
 ```json filename="HTTP 400 Bad Request Response"
 {
@@ -297,16 +398,32 @@ If a request fails validation, ExisJS intercepts the rejection and returns a sta
   "errors": {
     "username": "Field must be at least 4 characters",
     "profile.tags": "Expected array of strings"
-  }
+  },
+  "details": [
+    {
+      "path": "username",
+      "message": "Field must be at least 4 characters",
+      "expected": "min: 4",
+      "received": "abc",
+      "code": "VALUE_TOO_SMALL"
+    },
+    {
+      "path": "profile.tags",
+      "message": "Expected array of strings",
+      "expected": "Array of string",
+      "received": "number",
+      "code": "INVALID_TYPE"
+    }
+  ]
 }
 ```
 
 ### Dev Mode Terminal Diagnostics
 
-When validation fails in development mode, ExisJS prints an immediate tabular diagnostic to your terminal displaying the failing HTTP part, exact field path, received value, and expected schema constraint:
+When validation fails in development mode, ExisJS prints an immediate tabular diagnostic to your terminal displaying the HTTP method, route path, failing HTTP part (`body`, `query`, `params`, `headers`), exact field path, received value, and expected schema constraint:
 
 ```text
-[VALIDATION FAILED] POST /visits (part: body)
+[VALIDATION FAILED] POST /api/v1/visits (part: body)
 ┌─────────────┬───────────────────────────┬──────────────────┐
 │ Field       │ Received                  │ Expected         │
 ├─────────────┼───────────────────────────┼──────────────────┤
@@ -315,3 +432,101 @@ When validation fails in development mode, ExisJS prints an immediate tabular di
 └─────────────┴───────────────────────────┴──────────────────┘
 ```
 
+---
+
+## Environment Variable Validation (`tex.env`)
+
+Because `process.env` always supplies raw string values (e.g. `"4000"`, `"true"`, `"1"`), ExisJS includes a dedicated `tex.env()` schema parser. It automatically injects coercion for numbers, booleans, dates, and arrays, allowing you to validate your environment variables on boot without writing `{ coerce: true }` on every field:
+
+```typescript filename="src/config/env.ts"
+import { tex } from 'exisjs/validator'
+
+export const env = tex.env({
+  PORT: tex.number({ default: 4000 }), // Automatically coerced from "4000" -> 4000
+  DEBUG: tex.boolean({ default: false }), // Parsed from "true" | "1" | "false" | "0"
+  DATABASE_URL: tex.string(),
+  JWT_SECRET: tex.string({ min: 32 }),
+  ALLOWED_ORIGINS: tex.array(tex.string()), // Parsed from "http://localhost:3000,https://app.com"
+  NODE_ENV: tex.enum(['development', 'production', 'test'] as const, {
+    default: 'development',
+  }),
+}).parse(process.env)
+```
+
+> [!TIP]
+> **Zero-Boilerplate Boot Safety**: `tex.env()` automatically validates `process.env` on server startup. If a required environment variable is missing, it crashes immediately with a clean diagnostic log before the HTTP listener opens.
+
+---
+
+## Third-Party Validator Interoperability (Zod, Valibot, ArkType)
+
+While ExisJS provides the high-performance native `tex` engine out of the box, it is **100% interoperable with external schema libraries like Zod, Valibot, or ArkType** via Duck Typing.
+
+Any object with a `.parse()` or `.safeParse()` method can be passed directly as a route schema or used in `src/config/env.ts`.
+
+### Using Zod in Routes
+
+#### Functional Paradigm
+
+```typescript filename="src/http/users/route.ts"
+import { controller, route } from 'exisjs/router'
+import { z } from 'zod'
+
+const CreateUserSchema = z.object({
+  name: z.string().min(3),
+  email: z.string().email(),
+  role: z.enum(['admin', 'user']),
+})
+
+export default controller({
+  create: route.post('/', {
+    body: CreateUserSchema, // 👈 Directly pass your Zod schema!
+    async handle({ body, res }) {
+      return res.status(201).json({ success: true, user: body })
+    }
+  })
+})
+```
+
+#### Class-Based (OOP) Paradigm
+
+```typescript filename="src/http/users/route.ts"
+import { Controller, Post, Body, HttpCode } from 'exisjs/decorators'
+import { z } from 'zod'
+
+const CreateUserSchema = z.object({
+  name: z.string().min(3),
+  email: z.string().email(),
+  role: z.enum(['admin', 'user']),
+})
+
+type CreateUserDto = z.infer<typeof CreateUserSchema>
+
+@Controller('/users')
+export default class UsersController {
+  @Post('/')
+  @HttpCode(201)
+  async create(@Body(CreateUserSchema) body: CreateUserDto) {
+    return { success: true, user: body }
+  }
+}
+```
+
+### Using Zod for Environment Validation
+
+```typescript filename="src/config/env.ts"
+import { z } from 'zod'
+
+const EnvSchema = z.object({
+  PORT: z.coerce.number().default(4000),
+  NODE_ENV: z.enum(['development', 'production', 'test']).default('development'),
+  DATABASE_URL: z.string().url(),
+  JWT_SECRET: z.string().min(32),
+})
+
+export const env = EnvSchema.parse(process.env)
+```
+
+> [!NOTE]
+> **Universal Error Normalization**: Regardless of which library you use (**Zod**, **Valibot**, **Yup**, **Joi**, **ArkType**, or any Standard Schema-compliant library), ExisJS inspects the error structure (`issues`, `errors`, `inner`) and automatically normalizes it into standardized `400 Bad Request` JSON responses with complete field mappings and dev-mode terminal overlays.
+

package/dist/docs/reference/context.mdx

@@ -166,3 +166,14 @@ export default class UserController {
 
 > [!TIP]
 > For deep services inside an OOP architecture, you can still seamlessly use `getContext()`, `getRequest()`, or `after()` from `exisjs/router` to access the async context without prop-drilling!
+
+---
+
+## Context Isolation & Memory Leak Safety
+
+In high-concurrency micro-benchmarks or long-lived streaming connections (SSE / WebSockets), holding references in `AsyncLocalStorage` without explicit teardown can lead to memory retention. ExisJS enforces a deterministic context cleanup lifecycle:
+
+1. **Deterministic Teardown (`cleanupContext`)**: When a response emits the `'finish'` or `'close'` event, ExisJS automatically executes all remaining `after()` callbacks, clears request-scoped dependency injection instances (`diCache`), purges the `state` dictionary, and unlinks circular references (`req = null!`, `res = null!`, `app = null!`).
+2. **`try / finally` Dispatch Boundary**: The router wraps every handler dispatch in a `try ... finally` boundary, guaranteeing that unhandled exceptions or rejected promises cannot leak state into subsequent async continuations.
+3. **Recycling Pool Memory Scrubbing**: When recycled `ExisRequest` and `ExisResponse` instances return to the internal object pool, their internal dependency injection caches and request metadata are scrubbed clean.
+

package/dist/docs/reference/decorators.mdx

@@ -68,6 +68,10 @@ Parameter decorators automatically extract data from the incoming request and in
 - `@Param(nameOrPipe?)`: Injects a URL path parameter (e.g., `id` from `/:id`).
 - `@Headers(nameOrPipe?)`: Injects an HTTP header by name.
 - `@QueryParam(nameOrPipe?)` / `@Query(nameOrPipe?)`: Injects a URL query parameter (e.g., `?search=term`).
+- `@Cookies(nameOrPipe?)` / `@Cookie(nameOrPipe?)`: Injects incoming parsed cookies or a specific cookie value.
+- `@State(keyOrPipe?)`: Injects request state from execution context or middleware.
+- `@AppCtx()`: Injects the root ExisJS Application instance.
+- `@Fields(nameOrPipe?)`: Injects non-file multipart form fields.
 - `@UploadedFile()`: Injects the uploaded file (`req.file`) into the method argument.
 - `@UploadedFiles()`: Injects the uploaded files array or dictionary (`req.files`) into the method argument.
 - `@HostParam(nameOrPipe?)`: Injects a subdomain parameter.
@@ -83,8 +87,14 @@ Parameter decorators automatically extract data from the incoming request and in
 
 - `@Use(...middlewaresOrGuardsOrInterceptorsOrFilters)`: Unified decorator that binds middlewares, guards (`canActivate`), interceptors (`intercept`), or exception filters (`catch`) to a controller class or method.
 - `@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 this 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.
+- `@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.
+- `@RateLimit(options?)`: Enforces rate limits (e.g. `@RateLimit({ max: 100, windowMs: 60000 })`) at class or method level.
+- `@Cors(options?)`: Enforces Cross-Origin Resource Sharing rules at class or method level.
+- `@IpFilter(options)`: Enforces CIDR and IP allow/deny lists at class or method level.
+- `@Compress()`: Enables automatic Gzip and Brotli compression on responses.
+- `@Dedupe(options)`: Deduplicates concurrent identical requests sharing the same key.
+- `@BlockProbes(options?)`: Intercepts vulnerability scanner probes (`.env`, `/.git`, `/.DS_Store`) and blackholes them without triggering log noise.
 
 ---
 
@@ -108,8 +118,8 @@ Parameter decorators automatically extract data from the incoming request and in
 
 - `@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 for injecting dependencies by class, string, or symbol token.
-- `@Optional()`: Constructor parameter decorator resolving missing dependencies to `undefined` without throwing.
+- `@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.
 - `@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.
 

package/dist/docs/reference/error.mdx

@@ -170,3 +170,47 @@ app.use((err, req, res, next) => {
 ExisJS natively intercepts and handles Promise rejections at the core routing level. 
 
 Unlike Express, you do **not** need to wrap your routes in an `asyncHandler`. However, for strict compatibility with older Express middleware ecosystems, `exisjs/error` does export an `asyncHandler` wrapper. Note that using it in ExisJS is entirely redundant and merely adds unnecessary Promise allocations.
+
+---
+
+## Developer Error Formatting & Overlay Utilities
+
+`exisjs/error` also exports powerful error diagnostic utilities that you can use in custom error handlers, CLI scripts, background workers, and testing:
+
+```typescript
+import {
+  formatDevError,
+  renderDevErrorToString,
+  categorizeError,
+  generateErrorHint,
+  buildCodeFrame,
+  stripInternalStackFrames,
+  devErrorResponse,
+  type ParsedError,
+} from 'exisjs/error'
+```
+
+### Utility Functions
+
+| Function | Signature | Description |
+| :--- | :--- | :--- |
+| `formatDevError` | `(err: Error, optionsOrFile?: string \| { routeFile?: string; title?: string }) => void` | Prints a formatted terminal error envelope with code frames and actionable hints |
+| `renderDevErrorToString` | `(err: Error, optionsOrFile?: ...) => string` | Returns the formatted terminal error envelope string |
+| `categorizeError` | `(err: Error) => string` | Intelligently classifies errors into domain categories (`Validation Schema Error`, `Environment Configuration Error`, etc.) |
+| `generateErrorHint` | `(err: Error) => string \| null` | Generates actionable hints for common coding mistakes |
+| `buildCodeFrame` | `(filePath: string, line: number, col?: number) => string` | Builds a source code snippet visualizer with gutter line numbers and caret indicator |
+| `stripInternalStackFrames` | `(stack?: string) => string[]` | Strips internal Node.js and framework runtime stack frames |
+| `devErrorResponse` | `(err: Error, routeFile?: string) => object` | Generates a structured developer error envelope payload for JSON API responses |
+
+### Example: Custom Worker or Script Error Handling
+
+```typescript filename="src/workers/import-csv.ts"
+import { formatDevError, categorizeError } from 'exisjs/error'
+
+try {
+  await processCsvImport(filePath)
+} catch (err: any) {
+  // Prints a clean code frame with line numbers and actionable hints directly in terminal
+  formatDevError(err, { routeFile: filePath, title: categorizeError(err) })
+}
+```