exisjs 0.5.10 → 0.5.12

package/dist/docs/content/middleware.mdx

@@ -0,0 +1,441 @@
+---
+nextUrl: "/docs/modules"
+nextTitle: "Modules & Plugins"
+---
+
+# Middleware
+
+ExisJS comes with a collection of built-in middleware out of the box. 
+
+ExisJS provides first-party implementations for features like CORS, Request Logging, Backpressure, and Deduplication.
+
+All middleware can be imported directly from the `exisjs/middleware` package.
+
+---
+
+## Where to Apply Middleware
+
+ExisJS gives you granular control over where your middleware executes:
+
+1. **Globally (`server.ts`)**: Applies to every request hitting your server.
+2. **Folder-Scoped (`gateway.ts`)**: Applies only to routes inside that specific folder.
+3. **Route-Scoped (`route.ts`)**: Applies only to a specific endpoint.
+
+```typescript filename="src/http/admin/gateway.ts"
+import { defineGateway } from 'exisjs/router'
+import { requestLogger } from 'exisjs/middleware'
+
+// This logger will ONLY run for requests to /admin/*
+export default defineGateway({
+  middlewares: [
+    requestLogger({ level: 'debug' })
+  ]
+})
+```
+
+### Middleware vs Inline Execution
+
+It is critical to understand that middleware executes **before** your route handler. If you are using [Custom Typed Contexts](/docs/requests#strongly-typed-context--native-destructuring) to destructure variables (e.g., `async handle({ user })`), you **must** use middleware to populate `req.user`.
+
+If you try to call an authentication function *inline* inside the handler, the `user` variable will be `undefined` because destructuring occurs at the moment the handler is invoked—before the inline function has a chance to execute!
+
+```typescript
+// ❌ BAD: Destructuring happens before requireAuth mutates the request
+create: route.post('/', {
+  async handle({ user, req }) {
+    requireAuth(req); 
+    console.log(user); // undefined
+  }
+})
+
+// ✅ GOOD: Middleware runs first, so `user` is fully populated and strongly typed
+create: route.post('/', {
+  middleware: [requireAuth],
+  async handle({ user }) {
+    console.log(user); // Populated and typed
+  }
+})
+```
+
+#### Functional Paradigm
+
+```typescript filename="src/http/route.ts"
+import { controller, route } from 'exisjs/router'
+import { validate } from 'exisjs/middleware'
+
+export default controller({
+  // This middleware ONLY runs for this specific endpoint
+  create: route.post('/', {
+    middlewares: [validate(mySchema)],
+    handle(req, res) {
+      return { ok: true }
+    }
+  })
+})
+```
+
+#### Class-Based (OOP) Paradigm
+
+```typescript filename="src/http/route.ts"
+import { Controller, Post, Use } from 'exisjs/decorators'
+import { validate } from 'exisjs/middleware'
+
+@Controller()
+export default class MyController {
+  // This middleware ONLY runs for this specific endpoint
+  @Use(validate(mySchema))
+  @Post('/')
+  async create() {
+    return { ok: true }
+  }
+}
+```
+
+---
+
+## 1. CORS
+
+The `cors` middleware handles Cross-Origin Resource Sharing. It is configurable and optimized for low overhead on preflight requests.
+
+The recommended practice in ExisJS is to configure CORS globally in your **`exis.config.ts`** file (the Single Source of Truth). The framework will automatically merge and apply it globally for you.
+
+```typescript filename="exis.config.ts"
+import { defineConfig } from 'exisjs/config'
+
+export default async () => defineConfig({
+  cors: {
+    origin: ['https://myapp.com', /localhost:\d+/],
+    methods: ['GET', 'POST', 'OPTIONS'],
+    credentials: true,
+    maxAge: 86400,
+    preflightContinue: true // Set this to true if you want OPTIONS requests to hit your custom route.options() handlers!
+  }
+})
+```
+
+By default, ExisJS intercepts `OPTIONS` requests at the middleware level and responds with a `204 No Content` (and the appropriate CORS headers) to save server resources. However, if you need to run custom logic on preflight requests—such as hitting a specific `route.options('/', ...)` handler or a `@Options()` decorated controller method—you can set `preflightContinue: true`. 
+
+You can also configure CORS locally per-route by passing it to your controller config or gateway.
+
+---
+
+## 2. Request Logger
+
+ExisJS uses **Pino** under the hood. The `requestLogger` injects a request-scoped logger instance (`req.log`) and times response cycles automatically.
+
+```typescript filename="src/http/server.ts"
+import { requestLogger } from 'exisjs/middleware'
+
+app.use(requestLogger({
+  level: 'debug',
+  pretty: true // Enable beautiful CLI formatting
+}))
+```
+
+#### Functional Paradigm
+
+```typescript filename="src/http/route.ts"
+import { controller, route } from 'exisjs/router'
+
+export default controller({
+  index: route.get('/', {
+    handle(req, res) {
+      req.log.info({ userId: 123 }, "User hit the index route")
+      return { ok: true }
+    }
+  })
+})
+```
+
+#### Class-Based (OOP) Paradigm
+
+```typescript filename="src/http/route.ts"
+import { Controller, Get, Req } from 'exisjs/decorators'
+
+@Controller()
+export default class MyController {
+  @Get('/')
+  async index(@Req() req: any) {
+    req.log.info({ userId: 123 }, "User hit the index route")
+    return { ok: true }
+  }
+}
+```
+
+---
+
+## 3. Request ID
+
+Injects a unique `X-Request-Id` into every incoming request and outgoing response header. It natively supports distributed tracing headers (`traceparent`, `x-b3-traceid`).
+
+```typescript filename="src/http/server.ts"
+import { requestId } from 'exisjs/middleware'
+
+app.use(requestId())
+```
+
+#### Functional Paradigm
+
+```typescript filename="src/http/route.ts"
+import { controller, route } from 'exisjs/router'
+
+export default controller({
+  index: route.get('/', {
+    handle(req, res) {
+      console.log("Trace ID:", req.requestId)
+      return { ok: true }
+    }
+  })
+})
+```
+
+#### Class-Based (OOP) Paradigm
+
+```typescript filename="src/http/route.ts"
+import { Controller, Get, Req } from 'exisjs/decorators'
+
+@Controller()
+export default class MyController {
+  @Get('/')
+  async index(@Req() req: any) {
+    console.log("Trace ID:", req.requestId)
+    return { ok: true }
+  }
+}
+```
+
+---
+
+## 4. Static File Serving
+
+A static file server that resolves MIME types, streams files, and provides Cache-Control configuration out of the box.
+
+```typescript
+import { serveStatic } from 'exisjs/middleware'
+import path from 'node:path'
+
+app.use('/public', serveStatic(path.join(process.cwd(), 'public'), {
+  maxAge: 31536000 // Cache for 1 year
+}))
+```
+
+---
+
+## 5. Security Middlewares
+
+ExisJS bundles several security middlewares. (We will cover these in the Security documentation, but here is a preview):
+
+- **`helmet()`**: Automatically sets 14+ secure HTTP headers.
+- **`hpp()`**: Prevents HTTP Parameter Pollution attacks.
+- **`dbSanitize()`**: A universal scraper that protects against NoSQL injection patterns (`$where` and other malicious operators).
+- **`timeout(ms)`**: Kills requests that hang longer than a specified duration.
+- **`ipFilter()`**: Restricts access based on IP Whitelists/Blacklists.
+
+```typescript
+import { helmet, timeout, dbSanitize } from 'exisjs/middleware'
+
+app.use(helmet())
+app.use(dbSanitize({ mongo: true }))
+app.use(timeout(5000)) // 5 second timeout
+```
+
+---
+
+## 6. Advanced Performance Middlewares
+
+These middlewares provide additional scaling and performance capabilities.
+
+- **`cache()`**: An in-memory route caching engine. Requires a `keyGenerator` to prevent data leaks.
+- **`dedupe()`**: Request deduplication (In-flight request collapsing). If 1,000 users hit a heavy `/stats` route at the exact same millisecond, ExisJS will only compute it **once**, and send the same response to all 1,000 users simultaneously. Requires a `keyGenerator`.
+- **`backpressure()`**: Protects your server from traffic spikes by shedding load or queuing requests when the Node.js Event Loop lags.
+
+> [!WARNING]
+> **Authentication Leak Hazard**: When using `cache()` or `dedupe()` on authenticated routes, you **must** include the user's ID or session token in your `keyGenerator`. Failing to do so will result in User B receiving a cached/deduped response generated for User A.
+
+---
+
+## 7. Interceptors & Error Filters
+
+As covered in our [Error Handling](/docs/errors) guide, you can centrally mutate responses or catch specific Exception classes using `intercept()` and `catchError()`.
+
+```typescript
+import { intercept, catchError } from 'exisjs/middleware'
+
+// Wrap all responses in { data: ... }
+app.use(intercept((data) => ({ data })))
+
+// Catch specific errors
+app.use(catchError(DatabaseError, (err, req, res) => {
+  res.status(503).json({ error: 'Database Offline' })
+}))
+```
+
+---
+
+## 8. Schema Validation
+
+ExisJS includes a validation engine. You can validate `body`, `query`, or `params` directly at the middleware layer. If validation fails, it automatically rejects the request with a structured HTTP 400 JSON response.
+
+#### Functional Paradigm
+
+```typescript filename="src/http/users/route.ts"
+import { controller, route } from 'exisjs/router'
+import { validate } from 'exisjs/middleware'
+import { tex } from 'exisjs/validator'
+
+const createUserSchema = {
+  body: tex.object({
+    email: tex.email(),
+    age: tex.number({ min: 18 })
+  })
+}
+
+export default controller({
+  // Automatically rejects invalid payloads with 400 Bad Request
+  create: route.post('/', {
+    middlewares: [validate(createUserSchema)],
+    handle(req, res) {
+      // req.body is fully validated, but we also type-cast it safely
+      const body = req.body as { email: string, age: number }
+      
+      return { success: true, email: body.email }
+    }
+  })
+})
+```
+
+#### Class-Based (OOP) Paradigm
+
+```typescript filename="src/http/users/route.ts"
+import { Controller, Post, Use, Body } from 'exisjs/decorators'
+import { validate } from 'exisjs/middleware'
+import { tex } from 'exisjs/validator'
+
+const createUserSchema = {
+  body: tex.object({
+    email: tex.email(),
+    age: tex.number({ min: 18 })
+  })
+}
+
+@Controller()
+export default class UsersController {
+  // Automatically rejects invalid payloads with 400 Bad Request
+  @Use(validate(createUserSchema))
+  @Post('/')
+  async create(@Body() body: { email: string, age: number }) {
+    return { success: true, email: body.email }
+  }
+}
+```
+
+---
+
+## 9. Idempotency
+
+Idempotency ensures that retrying an identical request multiple times (e.g., due to network timeouts) will not result in duplicate operations on the server. ExisJS provides a Redis-backed (or in-memory) idempotency engine.
+
+#### Functional Paradigm
+
+```typescript
+import { controller, route } from 'exisjs/router'
+import { IdempotentMiddleware } from 'exisjs/middleware'
+
+export default controller({
+  checkout: route.post('/checkout', {
+    middlewares: [IdempotentMiddleware({ ttl: 86400, headerName: 'Idempotency-Key' })],
+    handle(req, res) {
+      return { success: true }
+    }
+  })
+})
+```
+
+#### Class-Based (OOP) Paradigm
+
+```typescript
+import { Controller, Post, Idempotent } from 'exisjs/decorators'
+
+@Controller()
+export default class CheckoutController {
+  @Idempotent({ ttl: 86400 }) // Caches the response for 24 hours based on the Idempotency-Key header
+  @Post('/checkout')
+  async checkout() {
+    return { success: true }
+  }
+}
+```
+
+---
+
+## 10. Cache Engine
+
+ExisJS provides a built-in Cache Engine for `GET` requests. It allows you to reduce database load and response times for frequently requested data.
+
+#### Functional Paradigm
+
+```typescript
+import { controller, route } from 'exisjs/router'
+import { cache } from 'exisjs/middleware'
+
+export default controller({
+  popular: route.get('/popular', {
+    middlewares: [
+      cache({
+        ttlMs: 60000,
+        keyGenerator: (req) => req.url // Critical: Define how cache keys are built
+      })
+    ], 
+    handle(req, res) {
+      return { success: true, books: [] }
+    }
+  })
+})
+```
+
+#### Class-Based (OOP) Paradigm
+
+```typescript
+import { Controller, Get, Cache } from 'exisjs/decorators'
+
+@Controller()
+export default class BooksController {
+  @Cache({ ttlMs: 60000, keyGenerator: (req) => req.url }) // Caches the response for 60 seconds
+  @Get('/popular')
+  async getPopular() {
+    return { success: true, books: [] }
+  }
+}
+```
+
+---
+
+## 11. Compression (Gzip / Brotli / Deflate)
+
+ExisJS includes a stream-based Compression middleware. It natively hooks into the `uWebSockets` core and compresses JSON, streams, and text on-the-fly, reducing your outbound network bandwidth.
+
+The best practice is to configure Compression globally in your **`exis.config.ts`**. By default, if `compression: true` is passed, the framework will add the `compress` middleware for you automatically.
+
+```typescript filename="exis.config.ts"
+import type { ExisConfig } from 'exisjs/config'
+
+const config: ExisConfig = {
+  // Enables Gzip, Brotli, and Deflate compression globally for all routes
+  compression: true, 
+}
+
+export default config
+```
+
+If you prefer to manually apply it to specific routes or gateways instead of globally, you can import it:
+
+```typescript filename="src/http/api/gateway.ts"
+import { defineGateway } from 'exisjs/router'
+import { compress } from 'exisjs/middleware'
+
+export default defineGateway({
+  middlewares: [
+    compress() // Only compress responses within this Gateway
+  ]
+})
+```

package/dist/docs/content/modules.mdx

@@ -0,0 +1,144 @@
+---
+nextUrl: "/docs/cache"
+nextTitle: "Caching"
+---
+
+# Modules & Plugins
+
+ExisJS provides a modular architecture. The framework is built on a Plugin Engine that allows you to encapsulate functionality, inject dependencies, and distribute reusable packages across your organization.
+
+ExisJS offers two distinct primitives for extension:
+1. **Modules (`defineModule`)**: Used for grouping domain-level business logic (e.g., `AuthModule`, `UsersModule`).
+2. **Plugins (`definePlugin`)**: Used for building framework-level extensions that often require configuration options (e.g., `StripePlugin({ apiKey })`).
+
+---
+
+## 1. Domain Modules (`defineModule`)
+
+When building large-scale applications, you should avoid placing all your logic into a single file. Modules allow you to encapsulate related dependencies (Providers), sub-modules (Imports), and Routes into a single unit.
+
+### Defining a Module
+
+Let's build an `AuthModule` that encapsulates an authentication provider:
+
+```typescript filename="src/modules/auth.module.ts"
+import { defineModule } from 'exisjs/module'
+
+export const AuthModule = defineModule({
+  name: 'auth-module',
+  
+  // 1. Inject Dependencies
+  providers: [
+    ['AuthService', { useClass: class AuthService { login() {} } }]
+  ],
+
+  // 2. Import other modules
+  imports: [
+    DatabaseModule
+  ],
+
+  // 3. Register lifecycle hooks
+  async onStart(app) {
+    console.log("AuthModule has initialized")
+  }
+})
+```
+
+### Registering Modules
+
+Once your module is defined, you can register it globally. The recommended place to register core modules is inside your `exis.config.ts` file, ensuring they boot up synchronously before your server starts accepting traffic.
+
+```typescript filename="exis.config.ts"
+import { defineExisConfig } from 'exisjs/config'
+import { AuthModule } from './src/modules/auth.module'
+
+export default defineExisConfig({
+  plugins: [
+    AuthModule
+  ]
+})
+```
+
+Alternatively, you can register it manually inside your `src/http/server.ts`:
+
+#### Functional Paradigm
+
+```typescript filename="src/http/server.ts"
+import { exis } from 'exisjs'
+import { AuthModule } from '../modules/auth.module'
+
+export default exis({
+  async onStart(app) {
+    await app.register(AuthModule)
+  }
+})
+```
+
+#### Class-Based (OOP) Paradigm
+
+```typescript filename="src/http/server.ts"
+import { Server } from 'exisjs/decorators'
+import { AuthModule } from '../modules/auth.module'
+import type { App } from 'exisjs'
+
+@Server({
+  plugins: [AuthModule]
+})
+export default class RootServer {
+  async onStart(app: App) {
+    console.log("Server with AuthModule booted")
+  }
+}
+```
+
+---
+
+## 2. Framework Plugins (`definePlugin`)
+
+While `defineModule` is great for internal business logic, `definePlugin` is designed for building distributable, third-party packages that require configuration options.
+
+When you use `definePlugin`, ExisJS returns a **Hybrid Object**. This means the plugin can be registered directly if it doesn't need options, or it can be called as a function if you need to pass a configuration object.
+
+### Building a Plugin
+
+Let's build a `StripePlugin` that requires an API key:
+
+```typescript filename="src/plugins/stripe.plugin.ts"
+import { definePlugin } from 'exisjs/plugin'
+
+interface StripeOptions {
+  apiKey: string
+}
+
+export const StripePlugin = definePlugin<StripeOptions>({
+  name: 'stripe-plugin',
+  
+  async register(app, options) {
+    if (!options?.apiKey) {
+      throw new Error("Stripe API Key is required")
+    }
+
+    // Initialize Stripe client and inject it globally
+    const stripeClient = new Stripe(options.apiKey)
+    
+    app.provide('StripeClient', { useValue: stripeClient })
+  }
+})
+```
+
+### Using the Plugin
+
+Because we used `definePlugin`, the framework allows us to pass configuration options directly:
+
+```typescript filename="exis.config.ts"
+import { defineExisConfig } from 'exisjs/config'
+import { StripePlugin } from './src/plugins/stripe.plugin'
+import { env } from './src/env'
+
+export default defineExisConfig({
+  plugins: [
+    // We call the plugin as a function to pass options
+    StripePlugin({ apiKey: env.STRIPE_SECRET_KEY })
+  ]
+})
+```