exisjs 0.7.5 → 0.7.7

package/dist/docs/content/middleware.mdx

@@ -32,9 +32,131 @@ export const config = defineBoundary({})
 export const logger = requestLogger({ level: 'debug' })
 ```
 
-### Middleware vs Inline Execution
+### Middleware Context Type Inference (`defineMiddleware`)
 
-Middleware executes **before** your route handler. If you are using custom typed contexts to destructure variables (e.g., `async handle({ user })`), you must use middleware to populate `req.user`.
+When custom middlewares attach data to `req` (such as authenticated user details, session data, or tenant tokens), ExisJS supports **End-to-End Middleware Context Type Inference**.
+
+By using `defineMiddleware<TContext>()`, downstream route handlers automatically inherit strongly typed properties on `req` with zero manual type casts (`as any`) or boilerplate.
+
+#### Local Route-Level Inference (Recommended)
+
+```typescript filename="src/http/route.ts"
+import { controller, route, defineMiddleware } from 'exisjs/router'
+
+// 1. Define your custom context shape
+interface AuthContext {
+  user: {
+    id: string
+    role: 'admin' | 'user'
+    email: string
+  }
+}
+
+// 2. Define the middleware with your context
+export const authMiddleware = defineMiddleware<AuthContext>((req, res, next) => {
+  req.user = {
+    id: 'usr_123',
+    role: 'admin',
+    email: 'alex@example.com'
+  }
+  next()
+})
+
+export default controller({
+  profile: route.get('/profile', {
+    middlewares: [authMiddleware],
+    handle({ req, res }) {
+      // ✨ req.user is automatically inferred directly from middlewares: [authMiddleware]!
+      // Full autocomplete and strict type safety:
+      return res.json({
+        userId: req.user.id,
+        role: req.user.role,
+        email: req.user.email
+      })
+    }
+  })
+})
+```
+
+#### Multi-Middleware Context Composition
+
+When passing multiple middlewares, ExisJS automatically merges all injected contexts:
+
+```typescript
+const authMw = defineMiddleware<{ user: { id: string } }>(...)
+const tenantMw = defineMiddleware<{ tenantId: string }>(...)
+
+export default controller({
+  data: route.get('/data', {
+    middlewares: [authMw, tenantMw],
+    handle({ req }) {
+      // req has both `req.user` and `req.tenantId` strictly typed!
+      return { userId: req.user.id, tenant: req.tenantId }
+    }
+  })
+})
+```
+
+#### Module-Scoped Context (`createRouter<TContext>()`)
+
+If an entire file or subsystem shares the same context, use `createRouter<TContext>()`:
+
+```typescript filename="src/http/admin/route.ts"
+import { createRouter } from 'exisjs/router'
+
+interface AdminContext {
+  user: { id: string; role: 'admin' }
+}
+
+const { route, controller } = createRouter<AdminContext>()
+
+export default controller({
+  settings: route.get('/settings', {
+    middlewares: [authMiddleware],
+    handle({ req }) {
+      return { adminId: req.user.id }
+    }
+  })
+})
+```
+
+#### Boundary-Scoped Context (`defineBoundary<TContext>()`)
+
+Propagate context types across all routes in a directory tree:
+
+```typescript filename="src/http/admin/boundary.ts"
+import { defineBoundary } from 'exisjs/router'
+
+export const config = defineBoundary<AdminContext>({
+  beforeHandle: async ({ req }) => {
+    console.log(`Admin action by: ${req.user.id}`)
+  }
+})
+```
+
+#### Class-Based (OOP) Context Usage
+
+In OOP controllers, you can attach typed middlewares via `@Use()` and type the injected `@Req()` object:
+
+```typescript filename="src/http/admin/route.ts"
+import { Controller, Get, Use, Req } from 'exisjs/decorators'
+import type { Request } from 'exisjs/router'
+import { authMiddleware } from '../../middleware/auth'
+import type { AuthContext } from '../../middleware/auth'
+
+@Controller('/admin')
+@Use(authMiddleware)
+export default class AdminController {
+  @Get('/profile')
+  getProfile(@Req() req: Request & AuthContext) {
+    return {
+      userId: req.user.id,
+      role: req.user.role,
+      email: req.user.email,
+    }
+  }
+}
+```
 
 #### Functional Paradigm
 
@@ -132,15 +254,42 @@ app.use(requestId())
 
 ExisJS provides high-performance rate limiting powered by Rust native memory:
 
-```typescript filename="src/http/boundary.ts"
+#### Functional Paradigm
+
+```typescript filename="src/http/auth/route.ts"
+import { controller, route } from 'exisjs/router'
 import { rateLimit } from 'exisjs/middleware'
 
-export const limiter = rateLimit({
-  windowMs: 60000,
-  max: 100,
+const authLimiter = rateLimit({ windowMs: 60000, max: 10 })
+
+export default controller({
+  login: route.post('/login', {
+    middlewares: [authLimiter],
+    handle({ req }) {
+      return { status: 'ok' }
+    }
+  })
 })
 ```
 
+#### Class-Based (OOP) Paradigm
+
+```typescript filename="src/http/auth/route.ts"
+import { Controller, Post, Use } from 'exisjs/decorators'
+import { rateLimit } from 'exisjs/middleware'
+
+const authLimiter = rateLimit({ windowMs: 60000, max: 10 })
+
+@Controller('/auth')
+export default class AuthController {
+  @Post('/login')
+  @Use(authLimiter)
+  async login() {
+    return { status: 'ok' }
+  }
+}
+```
+
 > [!NOTE]
 > Core rate limiting runs completely off-heap in-memory. For Redis-backed distributed rate limiting across clusters, use `@exisjs/cache`.
 
@@ -150,6 +299,24 @@ export const limiter = rateLimit({
 
 Idempotency caches responses based on the `Idempotency-Key` header, preventing duplicate mutations:
 
+#### Functional Paradigm
+
+```typescript filename="src/http/checkout/route.ts"
+import { controller, route } from 'exisjs/router'
+import { idempotent } from 'exisjs/middleware'
+
+export default controller({
+  checkout: route.post('/', {
+    middlewares: [idempotent({ ttlMs: 86400000 })],
+    async handle() {
+      return { success: true }
+    }
+  })
+})
+```
+
+#### Class-Based (OOP) Paradigm
+
 ```typescript filename="src/http/checkout/route.ts"
 import { Controller, Post, Idempotent } from 'exisjs/decorators'
 
@@ -169,6 +336,8 @@ export default class CheckoutController {
 
 If multiple clients request the exact same resource concurrently, `dedupe` collapses identical in-flight requests into a single operation:
 
+#### Functional Paradigm
+
 ```typescript filename="src/http/stats/route.ts"
 import { controller, route } from 'exisjs/router'
 import { dedupe } from 'exisjs/middleware'
@@ -183,6 +352,22 @@ export default controller({
 })
 ```
 
+#### Class-Based (OOP) Paradigm
+
+```typescript filename="src/http/stats/route.ts"
+import { Controller, Get, Use } from 'exisjs/decorators'
+import { dedupe } from 'exisjs/middleware'
+
+@Controller('/stats')
+export default class StatsController {
+  @Get('/')
+  @Use(dedupe({ ttlMs: 5000 }))
+  async getStats() {
+    return { activeUsers: 1000 }
+  }
+}
+```
+
 ---
 
 ## 7. Static File Serving
@@ -351,3 +536,81 @@ export default controller({
 })
 ```
 
+---
+
+## 10. Security Scanner Noise Suppression & Blackhole (`blockSuspiciousProbes`)
+
+In public production deployments, automated vulnerability scanners aggressively probe for `.env`, `/.git/HEAD`, `/.env.backup`, `/.DS_Store`, `wp-config.php`, etc.
+
+Each probe generates a `404` error log with structured JSON logging (`{"level":40,"statusCode":404}`), flooding log aggregators and triggering false security alerts.
+
+ExisJS provides `blockSuspiciousProbes` (alias `blockProbes`) to immediately intercept known exploit patterns, terminate the request with an empty response (blackhole), and suppress logger noise.
+
+### Global Usage (`server.ts` / `exis.config.ts`)
+
+```typescript filename="src/http/server.ts"
+import { exis } from 'exisjs'
+import { blockSuspiciousProbes } from 'exisjs/middleware'
+
+export default exis({
+  async onStart(app) {
+    // Intercept probes before downstream routes or loggers
+    app.use(blockSuspiciousProbes({
+      statusCode: 404, // or 403
+      silent: true,    // Suppresses level-40 warning logs in requestLogger
+    }))
+  }
+})
+```
+
+Or enable directly in `exis.config.ts`:
+
+```typescript filename="exis.config.ts"
+import { defineConfig } from 'exisjs/config'
+
+export default async () => defineConfig({
+  blockProbes: true, // or { statusCode: 404, silent: true }
+})
+```
+
+### Folder-Scoped Boundary (`boundary.ts`)
+
+```typescript filename="src/http/boundary.ts"
+import { defineBoundary } from 'exisjs/router'
+
+export default defineBoundary({
+  blockProbes: {
+    statusCode: 404,
+    silent: true,
+    exclude: ['/.well-known/security.txt'],
+  }
+})
+```
+
+### Class-Based (OOP) Decorator
+
+```typescript filename="src/http/api/route.ts"
+import { Controller, Get, BlockProbes } from 'exisjs/decorators'
+
+@Controller('/api')
+@BlockProbes({ statusCode: 404 })
+export default class ApiController {
+  @Get('/health')
+  health() {
+    return { status: 'healthy' }
+  }
+}
+```
+
+### Configuration Options
+
+| Option | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `statusCode` | `number` | `404` | HTTP status code to return for blocked probes |
+| `blackhole` | `boolean` | `true` | Immediately terminates connection with empty body without calling downstream middleware |
+| `silent` | `boolean` | `true` | Suppresses `requestLogger` warning logs for blocked probe requests |
+| `patterns` | `(string \| RegExp)[]` | `[]` | Additional custom probe patterns to block |
+| `exclude` | `(string \| RegExp)[]` | `[]` | Whitelist patterns to allow through without blocking |
+| `onProbe` | `(req, res, pattern) => void` | `undefined` | Callback hook when a probe is detected (for SIEM or IP reputation metrics) |
+
+

package/dist/docs/content/requests.mdx

@@ -97,7 +97,9 @@ Handling `multipart/form-data` in Node.js can be difficult. ExisJS provides mult
 
 ### A. Declarative Route Uploads (Recommended)
 
-You can declare file upload requirements directly inside your route schema. ExisJS automatically executes the multipart parser, validates MIME types, enforces byte caps, and populates `req.file` or `req.files` along with non-file fields in `req.body`:
+You can declare file upload requirements directly inside your route schema or decorators. ExisJS automatically executes the multipart parser, validates MIME types, enforces byte caps, and populates `req.file` or `req.files` along with non-file fields in `req.body`:
+
+#### Functional Paradigm
 
 ```typescript filename="src/http/upload/route.ts"
 import { controller, route } from 'exisjs/router'
@@ -128,10 +130,47 @@ export default controller({
 })
 ```
 
+#### Class-Based (OOP) Paradigm
+
+```typescript filename="src/http/upload/route.ts"
+import { Controller, Post, UseUpload, UploadedFile, Body } from 'exisjs/decorators'
+import { tex } from 'exisjs/validator'
+import type { UploadedFile as IUploadedFile } from 'exisjs/router'
+
+const TitleSchema = tex.object({
+  title: tex.string({ min: 1 }),
+})
+
+@Controller('/upload')
+export default class UploadController {
+  @Post('/')
+  @UseUpload({
+    field: 'photo',
+    maxBytes: 10 * 1024 * 1024,
+    mimeTypes: ['image/jpeg', 'image/png', 'image/webp'],
+  })
+  async uploadPhoto(
+    @UploadedFile() file: IUploadedFile,
+    @Body(TitleSchema) body: { title: string }
+  ) {
+    console.log(`Uploaded ${file.originalname} (${file.size} bytes)`)
+
+    return {
+      success: true,
+      filename: file.filename,
+      mimetype: file.mimetype,
+      title: body.title,
+    }
+  }
+}
+```
+
 ### B. First-Party `fileUpload` Middleware
 
 ExisJS exports a dedicated `fileUpload` middleware from `exisjs/middleware` supporting single, multiple, and multi-field uploads:
 
+#### Functional Paradigm
+
 ```typescript filename="src/http/documents/route.ts"
 import { controller, route } from 'exisjs/router'
 import { fileUpload } from 'exisjs/middleware'
@@ -173,10 +212,44 @@ export default controller({
 })
 ```
 
+#### Class-Based (OOP) Paradigm
+
+```typescript filename="src/http/documents/route.ts"
+import { Controller, Post, Use, UploadedFile, UploadedFiles } from 'exisjs/decorators'
+import { fileUpload } from 'exisjs/middleware'
+import type { UploadedFile as IUploadedFile } from 'exisjs/router'
+
+@Controller('/documents')
+export default class DocumentsController {
+  // Single file upload
+  @Post('/single')
+  @Use(fileUpload.single('document', { maxBytes: 15 * 1024 * 1024, dest: './uploads/docs' }))
+  async uploadSingle(@UploadedFile() file: IUploadedFile) {
+    return { file }
+  }
+
+  // Multiple files with the same field name
+  @Post('/gallery')
+  @Use(fileUpload.array('photos', 5, { mimeTypes: ['image/*'] }))
+  async uploadGallery(@UploadedFiles() files: IUploadedFile[]) {
+    return { count: files.length, files }
+  }
+
+  // Multiple distinct fields
+  @Post('/profile')
+  @Use(fileUpload.fields([{ name: 'avatar', maxCount: 1 }, { name: 'cover', maxCount: 1 }]))
+  async uploadProfile(@UploadedFiles() files: Record<string, IUploadedFile[]>) {
+    return { files }
+  }
+}
+```
+
 ### C. Integrating Express/Connect Middleware (e.g. Multer)
 
 If your enterprise project relies on existing Express middleware like **Multer** (for custom storage engines, S3 direct-to-cloud streams, or specialized filters), ExisJS provides the `fromExpress()` bridge:
 
+#### Functional Paradigm
+
 ```typescript filename="src/http/legacy/route.ts"
 import { controller, route } from 'exisjs/router'
 import { fromExpress } from 'exisjs/middleware'
@@ -199,10 +272,36 @@ export default controller({
 })
 ```
 
+#### Class-Based (OOP) Paradigm
+
+```typescript filename="src/http/legacy/route.ts"
+import { Controller, Post, Use, Req } from 'exisjs/decorators'
+import { fromExpress } from 'exisjs/middleware'
+import type { Request } from 'exisjs/router'
+import multer from 'multer'
+
+const upload = multer({
+  storage: multer.memoryStorage(),
+  limits: { fileSize: 10 * 1024 * 1024 },
+})
+
+@Controller('/legacy')
+export default class LegacyUploadController {
+  @Post('/upload')
+  @Use(fromExpress(upload.single('file')))
+  async upload(@Req() req: Request) {
+    const file = (req.raw as any).file || req.file
+    return { success: true, originalname: file?.originalname }
+  }
+}
+```
+
 ### D. Manual `req.formData()` & Streaming Uploads
 
 For manual control over incoming multipart streams without route middleware:
 
+#### Functional Paradigm
+
 ```typescript filename="src/http/upload/route.ts"
 import { controller, route } from 'exisjs/router'
 
@@ -225,6 +324,29 @@ export default controller({
 })
 ```
 
+#### Class-Based (OOP) Paradigm
+
+```typescript filename="src/http/upload/route.ts"
+import { Controller, Post, Req } from 'exisjs/decorators'
+import type { Request } from 'exisjs/router'
+
+@Controller('/upload')
+export default class ManualUploadController {
+  @Post('/avatar')
+  async uploadAvatar(@Req() req: Request) {
+    const { fields, files } = await req.formData()
+    const uploadedFile = files['profile_pic']
+
+    if (uploadedFile) {
+      const savedPath = await uploadedFile.saveToDisk('./uploads/avatars')
+      return { success: true, path: savedPath }
+    }
+
+    return { success: false, error: 'No file uploaded' }
+  }
+}
+```
+
 ---
 
 ## 4. Body Size Limits & HTTP 413
@@ -260,22 +382,24 @@ ExisJS ships with a **60-second default request timeout** in its `timeout()` mid
 
 ### Dynamic In-Handler Control
 
-Handlers can dynamically extend or cancel the active timeout on the fly using `req.setTimeout()` and `req.clearTimeout()`:
+Handlers can dynamically extend or cancel the active timeout on the fly using `req.setTimeout()` and `req.clearTimeout()`, or declaratively via `@Timeout(ms)`:
+
+#### Functional Paradigm
 
 ```typescript filename="src/http/ai/route.ts"
 import { controller, route } from 'exisjs/router'
 
 export default controller({
   generateVideo: route.post('/', {
+    timeoutMs: 180000, // 1. Declarative 3-minute timeout for this endpoint
     async handle({ req }) {
-      // 1. Extend timeout for heavy AI pass generation (e.g. 3 minutes)
-      req.setTimeout(180000)
+      // 2. Or dynamically adjust timeout during processing
+      req.setTimeout(240000)
 
       try {
         const result = await longRunningAiTask()
         return { success: true, result }
       } finally {
-        // 2. Clear timeout once work completes
         req.clearTimeout()
       }
     }
@@ -283,6 +407,30 @@ export default controller({
 })
 ```
 
+#### Class-Based (OOP) Paradigm
+
+```typescript filename="src/http/ai/route.ts"
+import { Controller, Post, Timeout, Req } from 'exisjs/decorators'
+import type { Request } from 'exisjs/router'
+
+@Controller('/ai')
+export default class AiTaskController {
+  @Post('/generate-video')
+  @Timeout(180000) // 1. Declarative 3-minute timeout
+  async generateVideo(@Req() req: Request) {
+    // 2. Or dynamically adjust on the fly
+    req.setTimeout(240000)
+
+    try {
+      const result = await longRunningAiTask()
+      return { success: true, result }
+    } finally {
+      req.clearTimeout()
+    }
+  }
+}
+```
+
 ---
 
 ## 6. HTTP Headers & Content Negotiation
@@ -321,7 +469,7 @@ ExisJS provides a first-class standard Web API `req.signal: AbortSignal` tied di
 
 When a client closes their browser tab, cancels a download, or aborts an HTTP request, `req.signal` immediately triggers an `abort` event. You can pass `req.signal` directly to ORMs, database drivers, and HTTP clients to cancel expensive in-flight operations and eliminate wasted server resources.
 
-#### Example: Passing to Database Queries & Upstream Fetches
+#### Functional Paradigm
 
 ```typescript filename="src/http/reports/route.ts"
 import { controller, route } from 'exisjs/router'
@@ -346,6 +494,32 @@ export default controller({
 })
 ```
 
+#### Class-Based (OOP) Paradigm
+
+```typescript filename="src/http/reports/route.ts"
+import { Controller, Get, Req } from 'exisjs/decorators'
+import type { Request } from 'exisjs/router'
+
+@Controller('/reports')
+export default class ReportsController {
+  @Get('/')
+  async heavyReport(@Req() req: Request) {
+    // 1. Pass req.signal to fetch()
+    const upstream = await fetch('https://api.external.com/data', {
+      signal: req.signal,
+    })
+    const payload = await upstream.json()
+
+    // 2. Pass req.signal to your database queries
+    const results = await db.query(sql`SELECT * FROM heavy_analytics`, {
+      signal: req.signal,
+    })
+
+    return { payload, results }
+  }
+}
+```
+
 ---
 
 ## 9. Context & Metadata