exisjs 0.7.12 → 0.7.13

package/dist/docs/content/README.md

@@ -1,44 +1,43 @@
-# ExisJS Documentation Blueprint
-
-This directory contains the core documentation for ExisJS. This `README.md` acts as a **blueprint** and index to help you navigate the features and understand what each markdown file contains.
-
-## 🚀 Getting Started
-*   **`introduction.mdx`**: High-level overview of ExisJS, its philosophy, and why it exists.
-*   **`installation.mdx`**: How to create a new project using `create-exis` and basic setup.
-*   **`structure.mdx`**: Explains the recommended folder structure (e.g., `src/http`, `src/jobs`, `src/services`).
-*   **`cli.mdx`**: Documentation for the Exis CLI (`exis dev`, `exis build`), including Esbuild integration and Smart Port Detection.
-*   **`config.mdx`**: How to configure the framework using `exis.config.ts`.
-
-## 🧠 Core Routing & HTTP
-*   **`routing.mdx`**: Covers File-System Routing, exact matches, parameters, and wildcards using the Radix Tree.
-*   **`controllers.mdx`**: Using OOP class-based controllers (`@Controller`) and Functional controllers.
-*   **`gateways.mdx`**: Explains Topological folder-based middleware (e.g., `_gateway.ts`) that runs before routes in a directory.
-*   **`middleware.mdx`**: Global and route-level middleware, CORS, and `req.log` interception.
-*   **`requests.mdx`**: How to read query params, body data, headers, and use the global `req` object.
-*   **`responses.mdx`**: Sending JSON, streams, raw data, and manipulating HTTP status codes.
-
-## 🏗️ Architecture & DI
-*   **`modules.mdx`**: Grouping controllers and providers into modular chunks.
-*   **`providers.mdx`**: Dependency Injection (DI) system, singletons, and injecting services.
-*   **`decorators.mdx`**: Overview of all decorators available for OOP paradigms (e.g., `@Get`, `@Inject`).
-
-## 🛡️ Data & Validation
-*   **`validation.mdx`**: The Zod-like type-safe validation engine (`v`), strict parsing, and the standalone `sanitize` utilities.
-*   **`dataloader.mdx`**: Solving the N+1 database problem automatically using integrated data loaders.
-*   **`cache.mdx`**: Application-level caching, response caching, and invalidation strategies.
-
-## ⚡ Advanced Capabilities
-*   **`websockets.mdx`**: Real-time bidirectional communication using the native uWebSockets integration.
-*   **`sse.mdx`**: Server-Sent Events for one-way streaming (useful for AI text generation).
-*   **`queues.mdx`**: Background job processing, workers, and Redis-backed queues.
-*   **`cron.mdx`**: Scheduling recurring tasks effortlessly using `cron` syntax.
-*   **`rpc.mdx`**: End-to-end type safety connecting the ExisJS backend with an `@exisjs/client` frontend.
-
-## 🔒 Security & Reliability
-*   **`security.mdx`**: Helmet integration, Rate Limiting, CORS configuration, and best practices.
-*   **`errors.mdx`**: Global error handling, custom `HttpException` classes, and safe error masking in production.
-*   **`circuit-breaker.mdx`**: Preventing cascading failures when external APIs or databases go down.
-*   **`testing.mdx`**: Using the integrated, native `node:test` runner to test your endpoints without Jest.
-
-## 🔌 Ecosystem
-*   **`adapters.mdx`**: How to run ExisJS inside serverless environments or mount it seamlessly alongside Next.js.
+# ExisJS Documentation Content Directory
+
+This directory contains the user guides, conceptual explanations, and how-to manuals for ExisJS.
+
+Documentation follows the [Diátaxis Framework](https://diataxis.fr/), separating conceptual overviews, procedural how-to guides, and reference materials.
+
+---
+
+## Content Index
+
+### 1. Getting Started & Architecture
+- [`introduction.mdx`](./introduction.mdx): Overview of framework architecture, design decisions, and supported paradigms.
+- [`installation.mdx`](./installation.mdx): Prerequisites, project scaffolding (`npm create exisjs@latest`), and manual setup.
+- [`structure.mdx`](./structure.mdx): Standardized directory layout (`src/http/`, `src/database/`, `src/common/`, `src/config/`, `src/cron/`).
+
+### 2. HTTP Routing & Request Pipeline
+- [`routing.mdx`](./routing.mdx): File-system routing conventions (`route.ts`), path parameters, route groups, and handlers.
+- [`controllers.mdx`](./controllers.mdx): Class-based routing, `@Controller` decorators, and parameter mappings.
+- [`decorators.mdx`](./decorators.mdx): Reference guide for all decorators across routing, parameters, pipes, middlewares, security, and lifecycle.
+- [`requests.mdx`](./requests.mdx): Request anatomy (`ExisRequest`), query strings, headers, cookies, and context augmentation.
+- [`responses.mdx`](./responses.mdx): Response helpers, JSON output, HTTP status codes, SSE, and stream handling.
+- [`boundaries.mdx`](./boundaries.mdx): Directory-scoped middleware cascading, hierarchical CORS inheritance, and boundary isolation.
+
+### 3. Validation, Dependency Injection & Data
+- [`validation.mdx`](./validation.mdx): Schema validation engine (`tex.*`), parameter coercion, custom validators, and sanitization.
+- [`providers.mdx`](./providers.mdx): Dependency injection, constructor injection, `@Injectable()`, `@Inject()`, and `forwardRef()`.
+- [`modules.mdx`](./modules.mdx): Module encapsulation, `@Module()`, dynamic module registration, and `@Global()` scopes.
+
+### 4. Middleware, Security & Operations
+- [`middleware.mdx`](./middleware.mdx): Global, boundary, and route-level middlewares, Express bridge, and execution order.
+- [`security.mdx`](./security.mdx): Security headers (Helmet), CSRF tokens, CIDR IP filtering, parameter pollution, and probe blocking.
+- [`errors.mdx`](./errors.mdx): HTTP exception classes, JSON error payloads, and custom error boundaries.
+- [`cron.mdx`](./cron.mdx): Background task scheduling (`cron()` and `@Cron()`) with drift correction and overlap protection.
+- [`swagger.mdx`](./swagger.mdx): Automatic OpenAPI 3.1 schema extraction, Swagger UI (`/docs`), and JSON documentation endpoints.
+- [`testing.mdx`](./testing.mdx): Test harness (`createTestContext`, `createTestApp`), mocking utilities (`ex`), and CLI test runner.
+- [`config.mdx`](./config.mdx): Global configuration options in `exis.config.ts`, lifecycle phases, clustering, and file watcher settings.
+- [`exisjs-mcp.mdx`](./exisjs-mcp.mdx): Model Context Protocol (MCP) server integration for IDE AI assistants.
+
+### 5. CLI Tooling (`cli/`)
+- [`cli/overview.mdx`](./cli/overview.mdx): CLI architecture and runtime execution.
+- [`cli/usage.mdx`](./cli/usage.mdx): Basic usage and script execution.
+- [`cli/commands.mdx`](./cli/commands.mdx): Reference for all CLI commands (`dev`, `build`, `start`, `routes`, `test`, `doctor`, `init`).
+

package/dist/docs/content/boundaries.mdx

@@ -1,86 +1,88 @@
 ---
-nextUrl: "/docs/validation"
-nextTitle: "Validation"
+title: 'Boundaries & Middleware Cascading'
+description: 'Folder-scoped middleware cascading, security guards, CORS inheritance hierarchy, exclusion rules, and error handling with boundary.ts.'
+nextUrl: '/docs/validation'
+nextTitle: 'Validation & Schemas'
 ---
 
-# Boundaries (Config & Request Pipeline)
+# Boundaries & Middleware Cascading (`boundary.ts`)
 
-A `boundary.ts` acts as a folder-scoped configuration and request pipeline in your file-system routing architecture.
+A `boundary.ts` (or `<name>.boundary.ts`) file defines a folder-scoped request pipeline and configuration module in the ExisJS file-system routing hierarchy.
 
-Any `boundary.ts` applies to every route in its folder and all subfolders recursively. Instead of manually registering middleware chains or route guards, placing a `boundary.ts` configures **CORS**, **Headers**, **Excluded Paths**, **Dependency Injection**, and an **auto-detected request pipeline** cleanly scoped to that sub-tree.
+Any `boundary.ts` automatically applies to every route within its directory and all descendant subdirectories recursively, providing scoped **CORS policies**, **custom headers**, **security guards**, **lifecycle hooks**, **route exclusions**, and **dependency injection scoping**.
 
 ---
 
 ## Anatomy of a Boundary
 
-A `boundary.ts` has two distinct, independent parts:
+A `boundary.ts` consists of two distinct components:
 
-1. **Config** — pure data, declared via `defineBoundary()` (functional) or the `@Boundary()` class decorator (OOP). It configures CORS, headers, DI providers, timeout, and exclusion rules.
-2. **Pipeline** — real code, auto-detected by function signature. No manual pipeline registration is needed.
+1. **Configuration**: Pure declarative options declared via `defineBoundary()` (functional) or `@Boundary()` (OOP). It sets CORS, response headers, timeout limits, exclusion patterns, probe blackholing, and DI providers.
+2. **Pipeline Handlers**: Functions and lifecycle hooks that run before, during, or after request execution:
 
-| Signature | Detected as | Execution timing |
-|---|---|---|
-| `(req, res, next)` | Chain Step | Runs in file/declaration order, before the route |
-| `beforeHandle(req, res)` | Boundary Guard Hook | Immediately before the route handler. Short-circuits on `false` or when sending headers |
-| `afterHandle(req, res, data)` | Response Hook | Immediately after the route handler. Mutates returned payload or logs audit data |
-| `(ctx, next)` — default export (functional) or class method `handle(ctx, next)` (OOP) | Request Wrapper | Wraps around all chain steps and the nested route/boundary |
+| Handler Type | Signature | Description |
+| :--- | :--- | :--- |
+| **Chain Step** | `(req, res, next)` | Standard middleware step running in declaration order before route handlers |
+| **Guard Hook** | `beforeHandle(req, res)` | Runs immediately before route handler execution; aborts if returning `false` |
+| **Audit Hook** | `afterHandle(req, res, data)` | Runs immediately after route handler returns; can transform response data |
+| **Pipeline Wrapper** | `(ctx, next)` / `handle(ctx, next)` | Onion-style wrapper around all steps and downstream routes in the boundary |
 
 ---
 
 ## 1. Functional Paradigm
 
-In functional style, export `config = defineBoundary(...)`, export named middleware functions `(req, res, next)` for chain steps, and optionally provide a `default export` function `(ctx, next)` as an onion-style wrapper. You can also configure `beforeHandle` and `afterHandle` hooks directly inside `defineBoundary({ ... })`.
+Export `config = defineBoundary(...)`, named middleware functions `(req, res, next)`, and optionally a default export `(ctx, next)` as a request wrapper:
 
 ```typescript filename="src/http/admin/boundary.ts"
 import { defineBoundary } from 'exisjs/router'
 import type { Request, Response, Next, BoundaryContext } from 'exisjs/router'
 import { UnauthorizedError } from 'exisjs/error'
 
-// 1. Configuration (CORS, Headers, Exclusions, Hooks, DI Providers)
+// 1. Declarative Boundary Configuration
 export const config = defineBoundary({
   cors: {
-    origin: ['https://admin.yourdomain.com'],
+    origin: ['https://admin.example.com'],
     credentials: true,
   },
   headers: {
-    'X-Admin-Api-Version': '2.0',
+    'X-Admin-Scope': 'active',
   },
   exclude: [
     '/admin/health',
-    { path: '/admin/public/*', method: 'GET' }
+    { path: '/admin/public/*', method: 'GET' },
   ],
 
-  // Pre-handler hook: Return false to reject with 403, or send custom response
+  // Pre-handler guard hook
   beforeHandle(req, res) {
     if (!req.headers['x-admin-token']) {
       res.status(401).json({ error: 'Missing admin access token' })
-      return false
+      return false // Aborts downstream execution
     }
   },
 
-  // Post-handler hook: Transform outgoing response payload or perform async audit
+  // Post-handler response transformation hook
   afterHandle(req, res, data) {
-    res.setHeader('X-Audited', 'true')
-    return { ...data, auditedAt: Date.now() }
+    res.setHeader('X-Audited-At', new Date().toISOString())
+    return { ...data, audited: true }
   },
 })
 
-// 2. Chain Step (auto-detected by (req, res, next) signature)
-export function requireAuth(req: Request, res: Response, next: Next) {
+// 2. Named Chain Step Middleware
+export function verifyApiKey(req: Request, res: Response, next: Next) {
   if (!req.headers['x-api-key']) {
-    throw new UnauthorizedError('Missing API key')
+    throw new UnauthorizedError('Missing required API key')
   }
   next()
 }
 
-// 3. Wrapper (auto-detected as default export with (ctx, next) signature)
+// 3. Pipeline Wrapper (Default Export)
 export default async function (ctx: BoundaryContext, next: Next) {
   const start = Date.now()
   try {
     const result = await next()
     const duration = Date.now() - start
     ctx.res.setHeader('X-Response-Time', `${duration}ms`)
-    return { success: true, data: result }
+    return result
   } catch (err: any) {
     return {
       success: false,
@@ -94,7 +96,7 @@ export default async function (ctx: BoundaryContext, next: Next) {
 
 ## 2. Class-Based (OOP) Paradigm
 
-In OOP style, decorate a class with `@Boundary(...)`. Named methods taking `(req, res, next)` are auto-detected as chain steps, `beforeHandle(req, res)` and `afterHandle(req, res, data)` act as lifecycle hooks, and a method named `handle(ctx, next)` serves as the request wrapper.
+Decorate a class with `@Boundary(...)`. Class methods taking `(req, res, next)` become chain steps, `beforeHandle` / `afterHandle` serve as lifecycle hooks, and a method named `handle(ctx, next)` acts as the pipeline wrapper:
 
 ```typescript filename="src/http/admin/boundary.ts"
 import { Boundary } from 'exisjs/decorators'
@@ -103,11 +105,11 @@ import { UnauthorizedError } from 'exisjs/error'
 
 @Boundary({
   cors: {
-    origin: ['https://admin.yourdomain.com'],
+    origin: ['https://admin.example.com'],
     credentials: true,
   },
   headers: {
-    'X-Admin-Api-Version': '2.0',
+    'X-Admin-Scope': 'active',
   },
   exclude: ['/admin/health'],
 })
@@ -122,19 +124,19 @@ export default class AdminBoundary {
 
   // Post-handler hook
   afterHandle(req: Request, res: Response, data: any) {
-    res.setHeader('X-Audited', 'true')
-    return { ...data, auditedAt: Date.now() }
+    res.setHeader('X-Audited-At', new Date().toISOString())
+    return { ...data, audited: true }
   }
 
-  // Chain step
-  requireAuth(req: Request, res: Response, next: Next) {
+  // Named chain step
+  verifyApiKey(req: Request, res: Response, next: Next) {
     if (!req.headers['x-api-key']) {
-      throw new UnauthorizedError('Missing API key')
+      throw new UnauthorizedError('Missing required API key')
     }
     next()
   }
 
-  // Wrapper
+  // Pipeline wrapper
   async handle(ctx: BoundaryContext, next: Next) {
     const start = Date.now()
     const result = await next()
@@ -146,44 +148,110 @@ export default class AdminBoundary {
 
 ---
 
-## Cascading & Inheritance
+## Boundary Cascading & Execution Order
 
-Boundaries cascade down the directory tree. For instance:
+Boundaries cascade top-down through the folder structure:
 
 ```text
 src/http/
-├── boundary.ts       # Root Boundary (applies to /api/*)
+├── boundary.ts          # Root Boundary (applies to all routes)
 └── admin/
-    ├── boundary.ts   # Admin Boundary (applies to /api/admin/*)
+    ├── boundary.ts      # Admin Boundary (applies to /admin/*)
     └── users/
-        └── route.ts  # Handled by both Root Boundary and Admin Boundary
+        └── route.ts     # Handled by both Root Boundary and Admin Boundary
 ```
 
-1. **Wrappers & Chain Steps**: Outer boundaries execute first. Root wrappers wrap nested wrappers, and root chain steps run before nested chain steps top-down.
-2. **CORS Precedence & Inheritance**:
-   - **Innermost Boundary Wins**: If a nested boundary specifies `cors`, it overrides any CORS configuration set in parent boundaries or `exis.config.ts`.
-   - **Inheritance**: If a sub-boundary omits `cors`, it seamlessly inherits the parent boundary's CORS configuration (or global config).
-   - **Per-Route Overrides**: A `route.ts` handler can define its own `cors` setting to override boundary settings for that single endpoint.
-   - **Disabling CORS**: Setting `cors: false` on a boundary or route explicitly disables CORS headers and preflight handling for that sub-tree or route.
-3. **Headers Merging**: Headers are deep-merged from root to child. Child headers override parent headers if keys collide.
-4. **Exclusions**: When a route matches an exclusion pattern (e.g. `/admin/health` in `exclude`), that boundary's chain steps and wrappers are bypassed for the request.
+### Execution Order
+
+1. **Wrappers**: Outer wrappers wrap inner wrappers (onion architecture).
+2. **Chain Steps**: Root chain steps run before nested boundary chain steps.
+3. **Guard Hooks (`beforeHandle`)**: Run immediately before the route handler, evaluated from root boundary down to the innermost boundary.
+4. **Response Hooks (`afterHandle`)**: Run in reverse order (innermost boundary up to root boundary).
+
+---
+
+## CORS Inheritance & Precedence
+
+CORS configuration follows a 4-tier hierarchy:
+
+| Priority | Level | Where Defined | Description |
+| :---: | :--- | :--- | :--- |
+| 1 | **Route Override** | `route.get('/', { cors: ... })` or `@Cors(...)` | Specific to a single endpoint; overrides all boundaries and global configs |
+| 2 | **Innermost Boundary** | `src/http/admin/boundary.ts` | Scoped to subfolder tree; overrides parent boundaries |
+| 3 | **Parent / Root Boundary** | `src/http/boundary.ts` | Scoped to all routes in `src/http/`; overrides global defaults |
+| 4 | **Global Configuration** | `exis.config.ts` (`cors`) | Fallback baseline for endpoints without boundary or route CORS |
+
+> [!NOTE]
+> If a sub-boundary omits `cors`, it inherits the CORS settings of the nearest ancestor boundary (or `exis.config.ts`). Setting `cors: false` on a boundary explicitly disables CORS for that entire subtree.
+
+---
+
+## Headers Merging
 
-### CORS Resolution Hierarchy
+Response headers defined across boundaries are deep-merged from root to child. If header keys conflict, the innermost boundary value takes precedence:
 
-ExisJS resolves CORS in a 3-tier precedence order:
+```typescript
+// src/http/boundary.ts (Root)
+export const config = defineBoundary({
+  headers: { 'X-Framework': 'ExisJS', 'X-Environment': 'production' },
+})
+
+// src/http/v2/boundary.ts (Nested)
+export const config = defineBoundary({
+  headers: { 'X-Api-Version': 'v2', 'X-Environment': 'v2-canary' },
+})
 
-| Level | Where to Define | Priority | Description |
-|---|---|---|---|
-| **Route** | `route.get('/', { cors: ... })` or `@Cors(...)` | 🥇 **Highest** | Specific to a single endpoint. Overrides boundary and global config. |
-| **Nested Boundary** | `src/http/admin/boundary.ts` | 🥈 **High** | Scoped to the subfolder tree. Overrides parent boundaries and global config. |
-| **Parent / Root Boundary** | `src/http/boundary.ts` | 🥉 **Medium** | Scoped to all API routes under the folder. Overrides global config. |
-| **Global Config** | `exis.config.ts` (`defineConfig({ cors })`) | **Base** | Fallback baseline for any route not covered by a boundary or route override. |
+// Endpoints under /v2 receive:
+// X-Framework: ExisJS
+// X-Api-Version: v2
+// X-Environment: v2-canary (overwritten by nested boundary)
+```
 
 ---
 
-## Dependency Injection via Providers
+## Route Exclusion Rules
+
+To bypass boundary middleware for specific routes (e.g. public webhooks or health checks), add rules to `exclude`:
+
+```typescript filename="src/http/boundary.ts"
+import { defineBoundary } from 'exisjs/router'
+
+export const config = defineBoundary({
+  exclude: [
+    // 1. Exact path string
+    '/health',
 
-Boundaries also act as IoC module scopes. You can scope providers to a directory tree using `providers`:
+    // 2. Wildcard pattern matching any HTTP method
+    '/public/*',
+
+    // 3. Path with specific HTTP method restriction
+    { path: '/webhooks/stripe', method: 'POST' },
+    { path: '/docs/*', methods: ['GET', 'HEAD'] },
+  ],
+})
+```
+
+When an incoming request matches an exclusion rule, the boundary's chain steps and `beforeHandle` hooks are bypassed.
+
+---
+
+## Noise Suppression & Exploit Probe Blackholing
+
+ExisJS can automatically intercept and drop automated vulnerability scanner probes (e.g. `/.env`, `/.git`, `/.DS_Store`, `/wp-admin`) at the boundary level without flooding application logs:
+
+```typescript filename="src/http/boundary.ts"
+import { defineBoundary } from 'exisjs/router'
+
+export const config = defineBoundary({
+  blockSuspiciousProbes: true, // Blackholes malicious probe paths immediately
+})
+```
+
+---
+
+## Dependency Injection Scoping
+
+Boundaries can register scoped providers into the IoC container for all routes within their sub-tree:
 
 ```typescript filename="src/http/users/boundary.ts"
 import { defineBoundary } from 'exisjs/router'
@@ -195,3 +263,12 @@ export const config = defineBoundary({
   ],
 })
 ```
+
+---
+
+## Next Steps
+
+- **[Validation Guide](/docs/validation)**: Building request schemas with `tex`.
+- **[Dependency Injection](/docs/providers)**: IoC containers, tokens, and provider lifecycles.
+- **[Routing](/docs/routing)**: File-system route parameters and handler definitions.
+- **[Controllers](/docs/controllers)**: Class-based routing and parameter decorators.