exisjs 0.7.12 → 0.7.14

package/dist/di/inject.js.map

@@ -1 +1 @@
-{"version":3,"file":"inject.js","sourceRoot":"","sources":["../../src/di/inject.ts"],"names":[],"mappings":";;AAoBA,wBAQC;AA5BD,+CAAoD;AAGpD;;;;;;;;;;;;;;;;GAgBG;AACH,SAAgB,MAAM,CAAI,KAAuB;IAC/C,MAAM,KAAK,GAAG,0BAAgB,CAAC,QAAQ,EAAE,CAAA;IACzC,IAAI,CAAC,KAAK,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC;QACzB,MAAM,IAAI,KAAK,CACb,4DAA4D,CAC7D,CAAA;IACH,CAAC;IACD,OAAO,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC,KAAK,EAAE,KAAK,CAAC,OAAO,CAAC,CAAA;AAChD,CAAC"}
+{"version":3,"file":"inject.js","sourceRoot":"","sources":["../../src/di/inject.ts"],"names":[],"mappings":";;AAqBA,wBAQC;AA7BD,+CAAoD;AAGpD;;;;;;;;;;;;;;;;;GAiBG;AACH,SAAgB,MAAM,CAAI,KAAuB;IAC/C,MAAM,KAAK,GAAG,0BAAgB,CAAC,QAAQ,EAAE,CAAA;IACzC,IAAI,CAAC,KAAK,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC;QACzB,MAAM,IAAI,KAAK,CACb,4DAA4D,CAC7D,CAAA;IACH,CAAC;IACD,OAAO,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC,KAAK,EAAE,KAAK,CAAC,OAAO,CAAC,CAAA;AAChD,CAAC"}

package/dist/docs/ARCHITECTURE.md

@@ -1,110 +1,162 @@
 # ExisJS Architecture Reference
 
-This document is the single source of truth for how the ExisJS core engine is built internally.
-
-ExisJS core is a minimal, ultra-high-performance web framework runtime: file-system routing, dependency injection, validation (`tex`), sanitization, and an HTTP request pipeline. Everything else — databases, external auth providers, cache stores, queues, websockets — is extracted into official `@exisjs/*` packages.
+This document serves as the architecture specification and technical reference for the internal subsystems, lifecycle execution pipeline, and design constraints of the ExisJS framework monorepo.
 
 ---
 
-## 1. File-System Routing 🟢
-
-**What it is:** Folder-based routing mapping HTTP routes to the file system (`route.ts`, `boundary.ts`, `server.ts`, `schema.ts`, `service.ts`).
-
-**How it's implemented:** At boot, `RouteScanner` walks the configured `src/http` directory (or a custom `apiDir`) and registers discovered routes into the `Router`'s matching engine powered by the Rust `NativeRadixTree`. Folder-naming conventions are translated during the scan:
-
-- `[param]` → `:param` dynamic segment
-- `[...param]` → `*param` catch-all
-- `(group)` → ignored entirely in the resulting URL, but still traversed for nested routes
-
-In development, routes are mounted dynamically and watched by `HotReloader`. In production, `exis build` pre-generates a route manifest (`.exis/routes-manifest.js`) for instant O(1) boot.
+## 1. Monorepo Organization & Subsystems
+
+ExisJS is architected as a modular TypeScript monorepo backed by a native Rust engine. Heavy compute tasks (path matching, memory LRU caching, rate limit buckets, and body sanitization) are handled by Rust native bindings via N-API (`@exisjs/rs`), with pure TypeScript fallbacks ensuring cross-platform stability.
+
+```text
+packages/
+├── exisjs/        # Core TypeScript framework, HTTP pipeline, router, DI, Swagger, Telemetry
+├── rs/            # Native Rust engine (radix routing, token bucket rate limiter, fast LRU cache)
+├── fetch/         # Lightweight, zero-dependency typed HTTP/RPC client
+└── create/        # Scaffolding CLI tool (create-exisjs)
+```
+
+### Framework Module Mapping
+
+| Subsystem | Source Path | Key Responsibilities |
+| :--- | :--- | :--- |
+| **Router Engine** | `packages/exisjs/src/router/` | File-system directory scanning, `NativeRadixTree` route compilation, route grouping `(group)`, wildcard/param segments. |
+| **Dependency Injection** | `packages/exisjs/src/di/` | Hierarchical IoC container, constructor injection reflection, custom providers (`useValue`, `useFactory`, `useExisting`, `useClass`), contextual `inject()`. |
+| **Validation (`tex`)** | `packages/exisjs/src/validator/` | Schema definition AST (`tex.*`), discriminated unions, coercion primitives (`tex.coerce.*`), transforms, OpenAPI 3.1 duck-typing. |
+| **HTTP Pipeline** | `packages/exisjs/src/server/` | `ExisRequest`, `ExisResponse`, lifecycle hooks (`onStart`, `onClose`), cookie parsing, proxy IP resolution. |
+| **Folder Boundaries** | `packages/exisjs/src/router/boundary.ts` | Cascading directory configuration, CORS headers, security middleware, and directory-scoped DI providers. |
+| **Decorators & OOP** | `packages/exisjs/src/decorators/` | `@Controller`, HTTP method decorators (`@Get`, `@Post`, `@RawBody`), `@Injectable`, `@Server`, `@Boundary`. |
+| **Security & Middleware** | `packages/exisjs/src/middleware/` | `helmet()`, signed CSRF cookies, `hpp()`, CIDR `ipFilter()`, native `rateLimit()`, LRU `idempotency()`, streaming `upload()`. |
+| **OpenAPI / Swagger** | `packages/exisjs/src/swagger/` | Interactive Swagger UI (`/docs`), OpenAPI 3.1 spec compiler from `tex` and Zod schemas. |
+| **Telemetry & Observability** | `packages/exisjs/src/telemetry/` | Built-in OpenTelemetry tracing, span processors, and Prometheus metrics. |
+| **Task Scheduling** | `packages/exisjs/src/cron/` | Drift-corrected background task scheduler (`cron()`, `@Cron()`). |
+| **Testing Harness** | `packages/exisjs/src/testing/` | In-memory and HTTP integration test runner (`createTestApp`, `createTestContext`). |
 
 ---
 
-## 2. Dual Paradigm: Functional & Class-Based (OOP) 🟢
-
-**What it is:** Two ways to define routing and handlers — `controller()`/`route.*()` factory functions, or `@Controller()`/`@Get()` class decorators — that compile down to the same internal `Route` representation.
-
-**How it's implemented:** Class decorators attach metadata to the class prototype via symbols (`Symbol.for('exisjs:...')`) without any `reflect-metadata` dependency. The router processes both paradigms through the exact same internal pipeline. Choose one paradigm per project.
+## 2. Request Lifecycle & Execution Pipeline
+
+Every HTTP request flows through a deterministic execution pipeline:
+
+```text
+Incoming HTTP Request (Node HTTP / uWS)
+  │
+  ▼
+1. Core Server Hook & Request Context Initialization (AsyncLocalStorage)
+  │
+  ▼
+2. Global Boundary & Middleware Pipeline (CORS, Helmet, Rate Limiter, IP Filter)
+  │
+  ▼
+3. Radix Tree Route Matching (NativeRadixTree with Rust fallback)
+  │
+  ▼
+4. Scoped Folder Boundaries (Cascading boundary.ts configurations)
+  │
+  ▼
+5. Parameter Extraction & Schema Validation / Coercion (tex.* on Body, Query, Params)
+  │
+  ▼
+6. Controller Handler Execution (Functional handler or OOP controller method)
+  │
+  ▼
+7. Response Interceptors & Formatting (Fast serialization, ETag, Status Codes)
+  │
+  ▼
+8. Post-Response Tasks (after() deferred execution callbacks)
+```
+
+### Context & AsyncLocalStorage
+
+The execution pipeline utilizes `AsyncLocalStorage` via `executionContext` (`packages/exisjs/src/di/inject.ts`). This provides request isolation across concurrent async operations, powering:
+- Contextual `inject(Token)` without parameter passing.
+- `req.buffer()` lazy memoization for streaming webhooks.
+- Deferred post-response cleanup tasks.
 
 ---
 
-## 3. The Context API & `AsyncLocalStorage` 🟢
-
-**What it is:** Access to the current request's `req`/`res`/app-scoped state from anywhere in the call graph without prop-drilling, plus `after()` for deferred post-response work.
-
-**How it's implemented:** `AsyncLocalStorage` maintains an active store per request containing `{ state, afterCallbacks, req, res, app, diCache }`. `inject()`, `getContext()`, and `after()` read from this store, guaranteeing request isolation across concurrent requests.
+## 3. Dual-Paradigm Architecture
+
+ExisJS maintains 100% feature parity between **Functional** and **Class-Based (OOP)** paradigms. An application chooses one paradigm consistently.
+
+```text
+┌─────────────────────────────────────────────────────────────┐
+│                      Unified Pipeline                       │
+│    (Validation Engine, Radix Dispatcher, OpenAPI Generator) │
+└──────────────┬───────────────────────────────┬──────────────┘
+               ▲                               ▲
+               │                               │
+    ┌──────────┴──────────┐         ┌──────────┴──────────┐
+    │     Functional      │         │     Class-Based     │
+    │  controller()       │         │  @Controller()      │
+    │  route.get()        │         │  @Get(), @Post()    │
+    │  defineBoundary()   │         │  @Boundary()        │
+    │  exis({ onStart })  │         │  @Server()          │
+    │  inject(Token)      │         │  @Inject(Token)     │
+    └─────────────────────┘         └─────────────────────┘
+```
+
+Both paradigms compile down to identical internal `RouteDescriptor` structures registered in the route table.
 
 ---
 
-## 4. Dependency Injection (`Container`) 🟢
-
-**What it is:** An IoC container supporting value, factory, and class providers, with singleton and request scoping.
-
-**How it's implemented:** `Container` holds provider definitions and a singleton cache. Inside request handlers, `inject(token)` resolves dependencies dynamically using the request's context store.
+## 4. The Graceful Fallback Pattern
 
----
-
-## 5. Folder-Scoped Boundaries (`boundary.ts`) 🟢
+Subsystems interfacing with `@exisjs/rs` (Radix router, LRU cache, rate limiting, and parameter validation) implement a strict fallback pattern. If N-API native binaries fail to load on non-standard architectures, the engine seamlessly activates pure TypeScript implementations:
 
-**What it is:** Folder-level configuration and auto-detected request pipelines that apply to a directory and all its subdirectories recursively.
+```typescript
+export class NativeSubsystemService {
+  private nativeEngine: any
+  private fallbackStore = new Map()
+  private isFallback = false
 
-**How it's implemented:**
-1. **Config:** Export `config = defineBoundary(...)` (functional) or `@Boundary(...)` (OOP) to define CORS, headers, exclusions, and DI providers for that directory tree.
-2. **Auto-Detected Pipeline:**
-   - Functions matching `(req, res, next)` are auto-detected as sequential chain steps.
-   - The default export `(ctx, next)` (functional) or class method `handle(ctx, next)` (OOP) is auto-detected as an onion wrapper around all inner steps and child routes.
+  constructor() {
+    try {
+      // eslint-disable-next-line @typescript-eslint/no-require-imports
+      const { NativeSubsystem } = require('@exisjs/rs')
+      this.nativeEngine = new NativeSubsystem()
+    } catch {
+      this.isFallback = true
+    }
+  }
+}
+```
 
 ---
 
-## 6. Native Validation Engine (`tex`) 🟢
-
-**What it is:** A dependency-free, high-performance schema validator powered by Rust (`@exisjs/rs`) with strict typing, auto-coercion, and structured error responses.
+## 5. Dependency Injection Architecture
 
-**How it's implemented:** `tex` provides primitives (`string`, `number`, `boolean`, `email`, `object`, `array`, `enum`) and integrates directly with `route.*()` configs and `@Body()`. Input sanitization via `exisjs/sanitize` can be chained synchronously via `.sanitize(...)` before validation occurs.
+The IoC container (`packages/exisjs/src/di/`) supports multiple provider token strategies:
 
----
-
-## 7. Production Build & Manifest Pipeline 🟢
+1. **Class Providers**: `@Injectable()` decorated classes resolved via constructor metadata (`design:paramtypes`).
+2. **Value Providers (`useValue`)**: Static configuration, database instances, or constants.
+3. **Factory Providers (`useFactory`)**: Dynamic factory functions with dependency injection (`inject: [TokenA, TokenB]`).
+4. **Alias Providers (`useExisting`)**: Token aliases mapping to an existing provider instance.
 
-- **esbuild Compilation:** `exis build` bundles and transpiles TypeScript rapidly using esbuild, resolving path aliases (`@/*`).
-- **Route Manifest Generation:** Scans routes and writes `.exis/routes-manifest.js` to enable O(1) boot in production without recursive filesystem scanning.
-- **Fast Serialization:** Validated route responses integrate with JIT fast serializers.
+```typescript
+// Custom Provider Registration
+app.provide('DATABASE_CLIENT', {
+  useFactory: (url: string) => createClient(url),
+  inject: ['DATABASE_URL'],
+})
+```
 
 ---
 
-## 8. Request & Response Engine 🟢
+## 6. Validation & Schema Engine (`tex`)
 
-- **Request:** Native JSON body parsing and cookie parsing delegated to Rust off-heap bindings in `@exisjs/rs`, busboy for multipart form data, and robust proxy trust resolution.
-- **Response:** Chainable status, header, and cookie APIs, automatic ETag generation (weak ETags), and JSON auto-serialization.
+The validation subsystem provides a zero-dependency schema builder and parser:
 
----
-
-## 9. Global Error Handling 🟢
-
-Structured `HttpError` hierarchy (`badRequest`, `unauthorized`, `forbidden`, `notFound`, etc.) with consistent JSON error envelopes and dev-mode formatting.
+- **Type AST**: `TexType` instances represent individual property constraints (`string`, `number`, `boolean`, `date`, `object`, `array`, `enum`, `discriminatedUnion`).
+- **Coercion**: String parameter conversion via `tex.coerce.*` for query and path parameters.
+- **Transformations**: Output reshaping using `.transform((val) => ...)` at the field and object level.
+- **OpenAPI 3.1 Extraction**: Recursive duck typing translates `tex` schemas and external validator schemas (e.g. Zod) directly into OpenAPI 3.1 JSON Schemas.
 
 ---
 
-## 10. Core Middleware Suite 🟢
-
-- **Security:** `helmet()`, `csrf()`, `hpp()`, `dbSanitize()`, `timeout()`.
-- **Traffic & Performance:** In-memory off-heap `rateLimit()`, `idempotent()` (keyed response caching in off-heap memory), `dedupe()`, and `backpressure()`.
-- **Utilities:** `cors()`, `requestId()`, `requestLogger()`, `serveStatic()`.
-
----
+## 7. Build Pipeline & Manifest Generation
 
-## 11. Core Boundary Contract
-
-| Subsystem | Location | Scope |
-|---|---|---|
-| Routing & Boundaries | `exisjs/router` | Core runtime |
-| Schema & Validation | `exisjs/validator` (`tex`) | Core runtime |
-| Data Sanitization | `exisjs/sanitize` | Core runtime |
-| Dependency Injection | `exisjs/di` | Core runtime |
-| Core Middleware | `exisjs/middleware` | Core runtime |
-| CLI & Scaffolding | `exisjs/cli` | Core tooling |
-| Database & ORM | `@exisjs/database` | Extracted package |
-| Cache & Redis | `@exisjs/cache` | Extracted package |
-| Background Queues | `@exisjs/queue` | Extracted package |
-| WebSockets | `@exisjs/websocket` | Extracted package |
-| Auth & OAuth | `@exisjs/auth` | Extracted package |
+In production mode:
+1. `exisjs build` compiles TypeScript files using `esbuild`, bundling path aliases (`@/*`).
+2. `RouteScanner` crawls `src/http/*` and writes a static route manifest to `.exis/routes-manifest.js`.
+3. In production (`exisjs start`), the server loads the precompiled manifest for $O(1)$ startup without directory traversals.

package/dist/docs/BENCHMARKS.md

@@ -18,10 +18,10 @@
 
 | Framework | Req/Sec (median) | Latency avg (ms) | Latency p50 (ms) | Latency p99 (ms) | Errors | Server backend |
 |---|---|---|---|---|---|---|
-| Express | 24778.91 | 3.41 | 3.00 | 5.00 | 0 | n/a |
-| Fastify | 41802.19 | 2.04 | 2.00 | 3.00 | 0 | n/a |
-| Hono | 43174.40 | 2.04 | 2.00 | 3.00 | 0 | n/a |
-| Exis JS | 51430.40 | 1.26 | 1.00 | 3.00 | 0 | uws |
+| Express | 24742.55 | 3.42 | 3.00 | 5.00 | 0 | n/a |
+| Fastify | 41237.82 | 2.06 | 2.00 | 3.00 | 0 | n/a |
+| Hono | 43640.73 | 2.01 | 2.00 | 3.00 | 0 | n/a |
+| Exis JS | 47436.80 | 1.48 | 1.00 | 3.00 | 0 | uws |
 
 ### Handler Parity Note
 

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