exisjs 0.5.10 → 0.5.11

package/dist/docs/reference/config.mdx

@@ -0,0 +1,118 @@
+---
+title: "Configuration"
+description: "API Reference for the global exis.config.ts file (`exisjs/config`)."
+---
+
+# Configuration (`exisjs/config`)
+
+ExisJS is designed to be highly zero-config out of the box. However, for advanced tuning, security, and clustering, you can define an `exis.config.ts` file in the root of your project.
+
+This configuration file deeply integrates with the framework's core, managing everything from global middleware (like CORS and Helmet) to underlying Server backends and Worker Threads.
+
+---
+
+## 1. Standard Configuration
+
+For most applications, you can simply export a static configuration object typed with `ExisConfig`.
+
+```typescript filename="exis.config.ts"
+import type { ExisConfig } from 'exisjs/config'
+
+const config: ExisConfig = {
+  port: Number(process.env.PORT) || 4000,
+  host: '0.0.0.0',
+
+  cors: {
+    origin: process.env.CORS_ORIGIN || '*',
+    credentials: true,
+  },
+
+  logger: {
+    level: 'debug',
+    pretty: process.env.NODE_ENV !== 'production',
+  },
+
+  queue: {
+    driver: 'memory',
+  },
+
+  helmet: { enabled: true },
+  compression: true,
+
+  test: {
+    include: ['tests/**/*.test.ts'],
+  },
+}
+
+export default config
+```
+
+---
+
+## 2. Advanced Configuration (Phases)
+
+If you need dynamic configuration (such as spawning worker threads only in production or altering middleware depending on the environment), you can use `defineConfig()` and Phase execution.
+
+```typescript filename="exis.config.ts"
+import { defineConfig, PHASE_DEVELOPMENT_SERVER } from 'exisjs/config'
+
+export default async (phase: string, { defaultConfig }) => {
+  const isDev = phase === PHASE_DEVELOPMENT_SERVER
+
+  return defineConfig({
+    port: Number(process.env.PORT) || 4000,
+    
+    // Auto-spawn Worker threads based on CPU cores!
+    workers: isDev ? 1 : 'safe', 
+    
+    // Globally configure native middleware
+    cors: {
+      origin: isDev ? '*' : 'https://myapp.com',
+      credentials: true
+    },
+    helmet: { enabled: true },
+    logger: isDev ? { level: 'debug', pretty: true } : false,
+    
+    // Native plugin registration
+    plugins: [
+      // ... your plugins here
+    ]
+  })
+}
+```
+
+---
+
+## Configuration Phases
+
+If you export a function from `exis.config.ts`, ExisJS will inject the current "Phase" string as the first argument, allowing you to dynamically adjust settings based on whether you are running a dev server, running tests, or building for production.
+
+- `PHASE_DEVELOPMENT_SERVER`: Emitted during `exis dev`
+- `PHASE_PRODUCTION_BUILD`: Emitted during `exis build`
+- `PHASE_PRODUCTION_SERVER`: Emitted during `exis start`
+- `PHASE_TEST`: Emitted during test runs
+
+---
+
+## Configuration Options
+
+Here is the full list of options supported natively by the ExisJS configuration engine:
+
+### Server & Network
+- **`port`** *(number)*: The port the server listens on (default: `4000`).
+- **`host`** *(string)*: The host interface to bind to (default: `'0.0.0.0'`).
+- **`server`** *(`'node' | 'uws' | 'auto'`)*: ExisJS supports running on standard Node `http`, or incredibly fast C++ `uWebSockets.js` (`uws`). Default is `'auto'` (uses `uws` if installed, falls back to `node`).
+- **`workers`** *(number | `'safe'` | `'max'`)*: Number of Node.js Cluster workers to spawn. `'max'` uses all CPU cores. `'safe'` uses all cores minus 1 (to leave room for the OS).
+- **`trustProxy`** *(boolean)*: Enable if running behind a reverse proxy (like Nginx or AWS ALB) to trust the `X-Forwarded-For` headers.
+
+### Security & Middlewares
+- **`cors`** *(boolean | object)*: Enable and configure Cross-Origin Resource Sharing globally.
+- **`helmet`** *(boolean | object)*: Enable strict security headers. Enabled by default.
+- **`logger`** *(boolean | object)*: Configure the high-performance Pino request logger.
+- **`compression`** *(boolean | object)*: Enable gzip/brotli response compression.
+- **`bodyLimit`** *(number)*: Maximum JSON/URL-encoded payload size in bytes (default: `1MB`).
+
+### Advanced Integrations
+- **`queue`**: Define your background queue driver (`memory` or `redis`) and configure `maxConcurrent` processing limits.
+- **`plugins`**: An array of `ExisPlugin` instances to register natively into the framework.
+- **`test`**: Configure testing environments (`include`, `exclude`, `setupFiles`, `coverage`).

package/dist/docs/reference/context.mdx

@@ -0,0 +1,168 @@
+---
+title: "Context & Requests"
+description: "API Reference for ExisJS Context, Requests, and Async Hooks."
+---
+
+# Context & Requests
+
+ExisJS leverages Node.js `AsyncLocalStorage` to provide request-scoped state without needing to manually pass request objects down through your entire service layer. This enables globally accessible contextual data anywhere in your application lifecycle.
+
+---
+
+## Global Request & Response
+
+In deeply nested utilities (like DataLoaders or generic services), it is often cumbersome to pass the `req` object through every function call. ExisJS allows you to pull the active HTTP Request and Response objects directly from the asynchronous context.
+
+### `getRequest()`
+
+Returns the active ExisJS `Request` object.
+
+```typescript filename="src/loaders/index.ts"
+import { defineLoaders, Dataloader } from 'exisjs/dataloader'
+import { getRequest } from 'exisjs/router'
+
+export const { loaderMiddleware, getLoaders } = defineLoaders({
+  user: () => new Dataloader(
+    async (keys: readonly string[]) => {
+      // Access the request deep inside the dataloader!
+      const req = getRequest()
+      console.log(`Batch fetching users for RequestId: ${req.requestId}`)
+      
+      return keys.map(key => db.users.find(key))
+    }
+  )
+})
+```
+
+### `getResponse()`
+
+Returns the active ExisJS `Response` object.
+
+```typescript filename="src/utils/auth.ts"
+import { getResponse } from 'exisjs/router'
+
+export function forceLogout() {
+  const res = getResponse()
+  res.clearCookie('session_id')
+}
+```
+
+### `getActiveApp()`
+
+Returns the active ExisJS `App` instance processing the request. This is useful for resolving dependencies or accessing the application logger from deep within a service.
+
+```typescript filename="src/services/billing.ts"
+import { getActiveApp } from 'exisjs/app'
+
+export function processRefund(transactionId: string) {
+  const app = getActiveApp()
+  const stripe = app.resolve('StripeClient')
+  
+  app.log.info(`Processing refund for ${transactionId}`)
+  return stripe.refunds.create({ charge: transactionId })
+}
+```
+
+---
+
+## Async Context API
+
+The core context API allows you to read and write arbitrary state associated with the current HTTP request. 
+
+### `setContext(key, value)`
+
+Sets a value in the current request's state object. This is typically used by middleware to attach parsed data, user sessions, or tenant IDs.
+
+```typescript filename="src/middleware/tenant.ts"
+import { setContext } from 'exisjs/router'
+
+export async function tenantMiddleware(req, res, next) {
+  const tenantId = req.headers['x-tenant-id']
+  
+  // Store the tenant ID in the async context
+  setContext('tenantId', tenantId)
+  next()
+}
+```
+
+### `getContext<T>()`
+
+Retrieves the current request's state object.
+
+```typescript filename="src/services/database.ts"
+import { getContext } from 'exisjs/router'
+
+function getTenantDatabase() {
+  // Retrieve the state set by the middleware!
+  const state = getContext<{ tenantId: string }>()
+  
+  return new DatabaseConnection({ schema: state.tenantId })
+}
+```
+
+---
+
+## Background Tasks
+
+### `after(callback)`
+
+Queues a function to execute in the background **after** the response has been completely sent to the client. This is the perfect place to put non-blocking tasks like sending welcome emails, flushing analytics, or writing audit logs.
+
+```typescript filename="src/http/users/route.ts"
+import { controller, route } from 'exisjs/router'
+import { after } from 'exisjs/router'
+import { tex } from 'exisjs/validator'
+
+export default controller({
+  createUser: route.post('/', {
+    body: tex.object({ email: tex.email() }),
+    async handle({ body }) {
+      
+      // Respond to the client immediately
+      after(async () => {
+        // This runs after the client has received the HTTP response
+        await emailService.sendWelcome(body.email)
+      })
+
+      return { success: true, email: body.email }
+    }
+  })
+})
+```
+
+
+> [!NOTE]
+> Tasks queued with `after()` do not block the HTTP request. If the task throws an error, it will be logged by the application logger, but it will not crash the server or affect the already-completed client response.
+
+---
+
+## Class-Based Context (OOP)
+
+If you are using the Object-Oriented paradigm, ExisJS provides dedicated decorators to inject the request and response directly into your controller methods. This removes the need to manually call `getRequest()` or `getResponse()` in the controller layer.
+
+### `@Req()` & `@Res()`
+
+Inject the raw ExisJS request or response objects.
+
+```typescript filename="src/http/users/route.ts"
+import { Controller, Get, Req, Res } from 'exisjs/decorators'
+import type { Request, Response } from 'exisjs/router'
+
+@Controller('/users')
+export default class UserController {
+  
+  @Get('/ip')
+  getIp(@Req() req: Request) {
+    return { ip: req.ip }
+  }
+
+  @Get('/logout')
+  logout(@Res() res: Response) {
+    res.clearCookie('session_id')
+    res.json({ success: true })
+  }
+}
+```
+
+> [!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!

package/dist/docs/reference/dataloader.mdx

@@ -0,0 +1,91 @@
+---
+title: "Data Loader"
+description: "Strict API Reference for the N+1 batching utility."
+---
+
+# Data Loader (`exisjs/dataloader`)
+
+This document provides the strict API signatures and TypeScript interfaces exported by the `exisjs/dataloader` module. For high-level guides on solving N+1 query problems, see the [Data Loader Guide](/docs/dataloader).
+
+---
+
+## `Dataloader<K, V, C>` Class
+
+The `Dataloader` class batches and caches requests to a backend data source.
+
+```typescript
+import { Dataloader } from 'exisjs/dataloader'
+
+class Dataloader<K, V, C = K> {
+  constructor(batchFn: BatchLoadFn<K, V>, options?: DataloaderOptions<K, C>)
+
+  // Enqueues a key to be batched, returning a Promise that resolves to the value
+  load(key: K): Promise<V>
+
+  // Loads multiple keys, returning an array of Promises
+  loadMany(keys: readonly K[]): Promise<V[]>
+
+  // Clears the value at `key` from the cache
+  clear(key: K): this
+
+  // Clears all values from the cache
+  clearAll(): this
+
+  // Primes the cache with a predefined value or Error for a specific key
+  prime(key: K, value: V | Error): this
+}
+```
+
+### `BatchLoadFn<K, V>`
+
+The function responsible for loading the batched keys. **It must return an array of values (or Errors) that are precisely the same length and in the exact same order as the provided keys array.**
+
+```typescript
+type BatchLoadFn<K, V> = (
+  keys: readonly K[]
+) => Promise<readonly (V | Error)[]>
+```
+
+### `DataloaderOptions<K, C>`
+
+```typescript
+interface DataloaderOptions<K, C = K> {
+  // Whether to cache resolved keys within this Dataloader instance. Default: true
+  cache?: boolean
+
+  // The maximum number of keys to include in a single batch. Default: 1000
+  maxBatchSize?: number
+
+  // A function to generate a unique cache key from the provided load key
+  cacheKeyFn?: (key: K) => C
+}
+```
+
+---
+
+## Context Registry (`defineLoaders`)
+
+Because `Dataloader` instances are inherently stateful (they cache data), they **must not** be shared across different HTTP requests, or else users might read each other's cached data.
+
+The `defineLoaders` function securely isolates Dataloader instances per-request by binding them to the ExisJS asynchronous context.
+
+```typescript
+import { defineLoaders } from 'exisjs/dataloader'
+
+function defineLoaders<
+  T extends Record<string, () => Dataloader<any, any>>
+>(factories: T): {
+  // Middleware to register onto your router/app
+  loaderMiddleware: (req, res, next) => void;
+  
+  // Hook to retrieve the isolated loaders anywhere in the request lifecycle
+  getLoaders: () => { [K in keyof T]: ReturnType<T[K]> }
+}
+```
+
+### Usage Signature
+```typescript
+const { loaderMiddleware, getLoaders } = defineLoaders({
+  userLoader: () => new Dataloader(async (keys) => { /* ... */ })
+})
+```

package/dist/docs/reference/decorators.mdx

@@ -0,0 +1,293 @@
+---
+title: "Decorators"
+description: "API Reference for ExisJS Class-Based Routing and Decorators."
+---
+
+# Decorators (OOP)
+
+ExisJS provides a robust Object-Oriented Programming (OOP) paradigm via the `exisjs/decorators` module. 
+
+Unlike many other frameworks (such as NestJS or TypeDI), ExisJS decorators are built completely on standard ECMAScript decorators and **do not require `reflect-metadata`**. This makes them incredibly lightweight, extremely fast, and completely free of legacy metadata bloat.
+
+---
+
+## 1. Controller & Routing
+
+### `@Controller(prefixOrOptions?)`
+
+Marks a class as a Controller. All route handler methods within the class will be grouped under the specified prefix.
+
+```typescript filename="src/http/users/route.ts"
+import { Controller } from 'exisjs/decorators'
+
+// Routes will be mounted at /api/users
+@Controller('/api/users')
+export default class UserController {
+  // ...
+}
+```
+
+### HTTP Methods
+Defines an HTTP route handler on a class method. You can optionally pass a schema to validate incoming requests.
+
+- `@Get(path?, schema?)`
+- `@Post(path?, schema?)`
+- `@Put(path?, schema?)`
+- `@Patch(path?, schema?)`
+- `@Delete(path?, schema?)`
+- `@Options(path?, schema?)`
+- `@Head(path?, schema?)`
+- `@Connect(path?, schema?)`
+- `@Trace(path?, schema?)`
+- `@All(path?, schema?)`
+- `@Query(path?, schema?)`: Can be used as a method decorator to handle custom `QUERY` method requests (e.g., RPC or GraphQL-like endpoints).
+
+```typescript filename="src/http/users/route.ts"
+import { Controller, Get, Post } from 'exisjs/decorators'
+import { tex } from 'exisjs/validator'
+
+@Controller('/users')
+export default class UserController {
+  @Get('/:id')
+  getUser() {
+    return { id: 1 }
+  }
+
+  @Post('/', { body: tex.object({ name: tex.string() }) })
+  createUser() {
+    return { success: true }
+  }
+}
+```
+
+### Real-Time Methods
+- `@Ws(path?, schema?)`: Maps the handler to a WebSocket connection.
+- `@Sse(path?, schema?)`: Maps the handler to a Server-Sent Events stream.
+
+---
+
+## 2. Parameter Injection
+
+Parameter decorators automatically extract data from the incoming request and inject them directly into your method arguments, drastically reducing boilerplate.
+
+- `@Body()`: Parses and injects the JSON request body.
+- `@Param(name?)`: Injects a URL path parameter (e.g., `id` from `/:id`).
+- `@Query(name?)`: Injects a query string parameter. (Note: `@Query` doubles as a route decorator if used on a method).
+- `@Headers(name?)`: Injects an HTTP header by name.
+- `@HostParam(name?)`: Injects a subdomain parameter (e.g., extracted from `@Hosts(':tenant.example.com')`).
+- `@Req()`: Injects the raw ExisJS Request object.
+- `@Res(options?)`: Injects the raw ExisJS Response object. Use `@Res({ passthrough: true })` if you want ExisJS to still handle the final response serialization.
+- `@Ip()`: Injects the client's IP address.
+- `@Session()`: Injects the active session object (requires session middleware).
+- `@Next()`: Injects the Next function.
+- `@Socket()`: Injects the active WebSocket instance (for `@Ws`).
+- `@Stream()`: Injects the active SSE instance (for `@Sse`).
+- `@UploadedFile() / @UploadedFiles()`: Injects multipart/form-data files.
+
+```typescript filename="src/http/users/route.ts"
+import { Controller, Get, Post, Param, Body, Ip } from 'exisjs/decorators'
+
+@Controller('/users')
+export default class UserController {
+  @Get('/:id')
+  getUser(@Param('id') id: string, @Ip() ip: string) {
+    return { id, requestedBy: ip }
+  }
+
+  @Post('/')
+  createUser(@Body() body: { email: string }) {
+    return { email: body.email }
+  }
+}
+```
+
+---
+
+## 3. Middleware & Configuration
+
+### `@Use(...middlewares)`
+Applies Express-style middleware functions to a specific route handler or an entire controller class.
+
+```typescript filename="src/http/secure/route.ts"
+import { Controller, Get, Use } from 'exisjs/decorators'
+import { authMiddleware } from '../middleware/auth'
+
+@Controller('/secure')
+@Use(authMiddleware)
+export default class SecureController {
+  @Get('/')
+  getSecureData() {
+    return { secure: true }
+  }
+}
+```
+
+### `@Cache(options)`
+Automatically caches `GET` responses in memory or Redis.
+
+### `@Idempotent(options)`
+Enforces idempotency based on the `Idempotency-Key` header, preventing duplicate mutations (e.g., duplicate payments).
+
+```typescript filename="src/http/payments/route.ts"
+import { Controller, Post, Idempotent } from 'exisjs/decorators'
+
+@Controller('/payments')
+export default class PaymentController {
+  @Post('/checkout')
+  @Idempotent()
+  checkout() {
+    return { status: 'processing' }
+  }
+}
+```
+
+---
+
+## 4. Responses & Metadata
+
+### `@HttpCode(code)`
+Forces a specific HTTP status code for successful responses.
+
+### `@Header(name, value)`
+Automatically injects a specific response header before sending the response.
+
+### `@Redirect(url, statusCode?)`
+Redirects the request to the specified URL.
+
+### `@Returns(schema)`
+Explicitly defines the response schema for OpenAPI (Swagger) generation.
+
+```typescript filename="src/http/documents/route.ts"
+import { Controller, Post, HttpCode, Header } from 'exisjs/decorators'
+
+@Controller('/documents')
+export default class DocumentController {
+  @Post('/')
+  @HttpCode(201)
+  @Header('X-Custom-Status', 'Processed')
+  createDoc() {
+    return { created: true }
+  }
+}
+```
+
+---
+
+## 5. Security & Lifecycle
+
+These decorators allow you to attach ExisJS lifecycle hooks to your OOP routes.
+
+- `@Permissions(...flags)`: Restricts the route to users with specific permission flags.
+- `@Hosts(...hosts)`: Restricts the route to a specific subdomain/host.
+- `@UseGuards(...guards)`: Attaches Guards (authentication/authorization checks).
+- `@UseInterceptors(...interceptors)`: Attaches Interceptors (request/response mutation).
+- `@UseFilters(...filters)`: Attaches Exception Filters (custom error handling).
+
+---
+
+## 6. Global Setup
+
+### `@Server(options?)`
+Marks a class as the root Server entry point. Used to register global configuration and dependencies.
+
+**Options Interface:**
+```typescript
+interface ServerConfig {
+  plugins?: any[]
+  providers?: any[]
+  cron?: any[]
+  queue?: any[]
+}
+```
+
+```typescript filename="src/http/server.ts"
+import { Server } from 'exisjs/decorators'
+import { corsPlugin } from 'exisjs/middleware'
+
+@Server({
+  plugins: [corsPlugin]
+})
+export default class RootServer {
+  async onStart(app) {
+    app.log.info("App booted!")
+  }
+}
+```
+
+### `@Gateway(options?)`
+Marks a class as a Gateway module. Gateways are used to apply massive configuration blocks across an entire directory of routes (e.g., applying an auth guard to all routes inside `src/http/admin`).
+
+**Options Interface:**
+```typescript
+interface GatewayConfig {
+  exclude?: any[]
+  middleware?: any[]
+  filters?: any[]
+  guards?: any[]
+  interceptors?: any[]
+  timeout?: number | ((req: any) => number)
+  metadata?: Record<string, any>
+  cors?: any
+  headers?: Record<string, string>
+  imports?: any[]
+  providers?: any[]
+}
+```
+
+```typescript filename="src/http/gateway.ts"
+import { Gateway } from 'exisjs/decorators'
+import { helmet, hpp } from 'exisjs/middleware'
+
+/**
+ * Root Gateway (gatekeeper for the entire application)
+ *
+ * Gateways apply configuration to all routes within their directory and subdirectories.
+ * This acts as the global security and infrastructure layer.
+ */
+@Gateway({
+  // 1. Cross-Origin Resource Sharing (CORS)
+  cors: {
+    origin: ['https://myapp.com', /localhost:\d+/],
+    credentials: true,
+  },
+
+  // 2. Global Headers
+  headers: {
+    'X-Powered-By': 'ExisJS',
+    'X-Application-Version': '1.0.0',
+  },
+
+  // 3. Global Middleware
+  middleware: [
+    helmet(), // Sets secure HTTP headers
+    hpp(),    // Prevents HTTP Parameter Pollution
+  ],
+
+  // 4. Exclude Paths
+  exclude: [{ path: '/health', method: 'GET' }],
+
+  // 5. Dependency Injection Providers
+  providers: [
+    ['ConfigService', { useValue: { apiKey: process.env.API_KEY || 'default' } }],
+  ],
+
+  // 6. Global Metadata
+  metadata: {
+    tenant: 'root',
+  },
+
+  // 7. Request Timeout
+  timeout: 10000,
+})
+export default class RootGateway {}
+```
+
+### `@Injectable(options?)`
+Marks a class as a provider for Dependency Injection, meaning it can be automatically injected into controllers or other services by the IoC container.
+
+**Options Interface:**
+```typescript
+interface InjectableOptions {
+  scope?: 'singleton' | 'request'
+}
+```