exisjs 0.7.5 → 0.7.6

package/dist/docs/content/controllers.mdx

@@ -101,13 +101,29 @@ In most cases, you don't need to manually access the entire request object. Inst
         <td className="px-4 py-3 font-mono text-xs"><span className="text-primary">@</span>Ip()</td>
         <td className="px-4 py-3 text-muted-foreground">The client's IP address</td>
       </tr>
+      <tr className="bg-background hover:bg-muted/30 transition-colors">
+        <td className="px-4 py-3 font-mono text-xs"><span className="text-primary">@</span>Cookies(name?) / <span className="text-primary">@</span>Cookie(name?)</td>
+        <td className="px-4 py-3 text-muted-foreground">Incoming parsed cookies or specific cookie value</td>
+      </tr>
+      <tr className="bg-background hover:bg-muted/30 transition-colors">
+        <td className="px-4 py-3 font-mono text-xs"><span className="text-primary">@</span>State(key?)</td>
+        <td className="px-4 py-3 text-muted-foreground">Request state from execution context or middleware</td>
+      </tr>
+      <tr className="bg-background hover:bg-muted/30 transition-colors">
+        <td className="px-4 py-3 font-mono text-xs"><span className="text-primary">@</span>AppCtx()</td>
+        <td className="px-4 py-3 text-muted-foreground">The root ExisJS Application instance</td>
+      </tr>
+      <tr className="bg-background hover:bg-muted/30 transition-colors">
+        <td className="px-4 py-3 font-mono text-xs"><span className="text-primary">@</span>Fields(name?)</td>
+        <td className="px-4 py-3 text-muted-foreground">Non-file multipart form fields</td>
+      </tr>
       <tr className="bg-background hover:bg-muted/30 transition-colors">
         <td className="px-4 py-3 font-mono text-xs"><span className="text-primary">@</span>UploadedFile()</td>
         <td className="px-4 py-3 text-muted-foreground">A single uploaded file (multipart/form-data)</td>
       </tr>
       <tr className="bg-background hover:bg-muted/30 transition-colors">
         <td className="px-4 py-3 font-mono text-xs"><span className="text-primary">@</span>UploadedFiles()</td>
-        <td className="px-4 py-3 text-muted-foreground">Array of uploaded files</td>
+        <td className="px-4 py-3 text-muted-foreground">Array or dictionary of uploaded files</td>
       </tr>
     </tbody>
   </table>
@@ -115,22 +131,123 @@ In most cases, you don't need to manually access the entire request object. Inst
 
 ## Payloads & Validation
 
-For POST and PUT endpoints, you need to read the incoming JSON payload. Use the `@Body()` decorator to inject it.
+For POST, PUT, and PATCH endpoints, you can validate and read incoming payloads using either method-level schemas or parameter-level `@Body(Schema)` decorators:
 
 ```typescript filename="src/http/users/route.ts"
-import { Controller, Post, Body } from 'exisjs/decorators'
+import { Controller, Post, Body, HttpCode } from 'exisjs/decorators'
+import { tex } from 'exisjs/validator'
+import type { ResolveSchema } from 'exisjs/validator'
+
+export const CreateUserSchema = tex.object({
+  name: tex.string({ min: 2 }),
+  email: tex.email(),
+  role: tex.enum(['admin', 'user'], { default: 'user' }),
+})
 
-export class CreateUserDto {
-  name: string;
-  email: string;
-  role: string;
+export type CreateUserDto = ResolveSchema<typeof CreateUserSchema>
+
+@Controller('users')
+export default class UsersController {
+  // 1. Parameter-level validation schema
+  @Post('/')
+  @HttpCode(201)
+  async create(@Body(CreateUserSchema) dto: CreateUserDto) {
+    return { id: 3, ...dto }
+  }
+
+  // 2. Or method-level schema object
+  @Post('/raw', { body: CreateUserSchema })
+  async createWithMethodSchema(@Body() dto: CreateUserDto) {
+    return { id: 4, ...dto }
+  }
 }
+```
+
+## Dependency Injection in Controllers
+
+Controllers can inject services using either the ergonomic `inject()` helper or standard constructor injection:
+
+```typescript filename="src/http/users/route.ts"
+import { Controller, Get, Param } from 'exisjs/decorators'
+import { inject, Inject, Optional } from 'exisjs/di'
+import { UsersService } from './service'
 
 @Controller('users')
 export default class UsersController {
-  @Post()
-  async create(@Body() createUserDto: CreateUserDto) {
-    return { id: 3, ...createUserDto }
+  // Approach A: Property-level injection (Recommended)
+  private usersService = inject(UsersService)
+
+  // Approach B: Constructor injection
+  constructor(
+    @Inject('DATABASE_URL') private dbUrl: string,
+    @Optional() @Inject('METRICS') private metrics?: any
+  ) {}
+
+  @Get('/:id')
+  async getUser(@Param('id') id: string) {
+    return this.usersService.findById(id)
+  }
+}
+```
+
+## File Uploads
+
+You can process file uploads in OOP controllers using `@UseUpload` or `@Upload` decorators alongside `@UploadedFile()` and `@UploadedFiles()`:
+
+```typescript filename="src/http/users/route.ts"
+import { Controller, Post, UseUpload, UploadedFile, Body } from 'exisjs/decorators'
+import type { UploadedFile as IUploadedFile } from 'exisjs/router'
+
+@Controller('users')
+export default class UsersController {
+  @Post('/avatar')
+  @UseUpload({
+    field: 'avatar',
+    maxBytes: 5 * 1024 * 1024,
+    mimeTypes: ['image/jpeg', 'image/png', 'image/webp'],
+  })
+  async uploadAvatar(
+    @UploadedFile() file: IUploadedFile,
+    @Body() body: { caption?: string }
+  ) {
+    return {
+      success: true,
+      filename: file.filename,
+      size: file.size,
+      caption: body.caption,
+    }
+  }
+}
+```
+
+## Streaming & Downloads
+
+OOP controllers support all streaming features including Node.js `Readable` streams, Web `ReadableStream`, async generators, and file downloads:
+
+```typescript filename="src/http/files/route.ts"
+import { Controller, Get, Res } from 'exisjs/decorators'
+import type { Response } from 'exisjs/router'
+import fs from 'node:fs'
+
+@Controller('files')
+export default class FilesController {
+  // 1. Force file download
+  @Get('/download')
+  download(@Res() res: Response) {
+    res.download('./reports/annual.pdf', 'Annual-Report.pdf')
+  }
+
+  // 2. Stream Node.js Readable or auto-pipe return value
+  @Get('/stream')
+  streamCsv() {
+    return fs.createReadStream('./data/export.csv')
+  }
+
+  // 3. Server-Sent Events (SSE)
+  @Get('/events')
+  events(@Res() res: Response) {
+    const sse = res.sse()
+    sse.send({ event: 'ping', data: { time: Date.now() } })
   }
 }
 ```

package/dist/docs/content/decorators.mdx

@@ -134,6 +134,12 @@ export default class UsersController {
 - `@Param(nameOrPipe?)` — Extracts a route path param (e.g. `:id`).
 - `@QueryParam(nameOrPipe?)` / `@Query(nameOrPipe?)` — Extracts a query parameter from the URL query string.
 - `@Headers(nameOrPipe?)` — Extracts a request header by name.
+- `@Cookies(nameOrPipe?)` / `@Cookie(nameOrPipe?)` — Injects incoming parsed cookies or a specific cookie value.
+- `@State(keyOrPipe?)` — Injects request state from execution context or middleware.
+- `@AppCtx()` — Injects the root ExisJS Application instance.
+- `@Fields(nameOrPipe?)` — Injects non-file multipart form fields.
+- `@UploadedFile(nameOrPipe?)` — Injects a single uploaded file.
+- `@UploadedFiles(nameOrPipe?)` — Injects multiple uploaded files.
 - `@HostParam(nameOrPipe?)` — Extracts a host subdomain parameter.
 - `@Req()` — Injects the raw request object.
 - `@Res(options?)` — Injects the response object (e.g. `{ passthrough: true }`).
@@ -150,16 +156,19 @@ export default class UsersController {
 
 ## 4. Middleware & Pipeline Decorators
 
-You can bind middlewares, guards, interceptors, and exception filters to controllers or route methods using the unified `@Use()` decorator:
+You can bind middlewares, guards, interceptors, and exception filters to controllers or route methods using first-class decorators:
 
 ```typescript filename="src/http/checkout/route.ts"
-import { Controller, Post, Use, Idempotent } from 'exisjs/decorators'
+import { Controller, Post, Use, Idempotent, RateLimit, Cors, Timeout } from 'exisjs/decorators'
 import { requireAuth } from '../../middleware/auth'
 
 @Controller('/checkout')
 @Use(requireAuth) // Applies to all routes in this controller
+@Cors({ origin: 'https://app.yourdomain.com' })
+@RateLimit({ max: 10, windowMs: 60000 })
 export default class CheckoutController {
   @Post('/')
+  @Timeout(30000)
   @Idempotent({ ttlMs: 86400000 }) // In-memory off-heap idempotency protection
   async processPayment() {
     return { success: true }
@@ -169,7 +178,15 @@ export default class CheckoutController {
 
 ### Available Lifecycle & Middleware Decorators
 - `@Use(...items)` — Unified decorator that attaches middlewares, guards (`canActivate`), interceptors (`intercept`), or exception filters (`catch`) to a class or method.
-- `@Idempotent(options?)` — Caches responses based on the `Idempotency-Key` header using off-heap native memory.
+- `@Timeout(ms: number | TimeoutOptions)` — Overrides the request timeout for a class or method.
+- `@Idempotent(options?)` — Caches responses based on the `Idempotency-Key` header using native in-memory off-heap storage.
+- `@RateLimit(options?)` — Enforces request rate limits on a controller class or route method.
+- `@Cors(options?)` — Configures Cross-Origin Resource Sharing rules on a controller class or route method.
+- `@IpFilter(options)` — Enforces IP/CIDR allowlist and denylist.
+- `@Compress()` — Enables automatic response compression (Gzip/Brotli).
+- `@Dedupe(options)` — Deduplicates concurrent identical requests sharing the same key.
+- `@UseUpload(options)` / `@Upload(options)` — Configures multipart file upload handling.
+- `@BlockProbes(options?)` — Intercepts scanner exploit probes (`.env`, `/.git`, `/.DS_Store`) and blackholes them without log noise.
 
 ---
 
@@ -229,7 +246,8 @@ export class UserService {
 You can inject dependencies using tokens or classes, and mark optional dependencies with `@Optional()`:
 
 ```typescript filename="src/http/users/route.ts"
-import { Controller, Get, Param, Inject, Optional } from 'exisjs/decorators'
+import { Controller, Get, Param } from 'exisjs/decorators'
+import { Inject, Optional } from 'exisjs/di'
 import { UserService } from './service'
 
 @Controller('/users')

package/dist/docs/content/introduction.mdx

@@ -20,7 +20,7 @@ Exis aims to provide that out-of-the-box application architecture for backends:
 The fastest way to start is the Exis CLI, which scaffolds a new project directory with the core files and a conventional base structure already in place. This is the recommended path for first-time users.
 
 <div className="my-6 max-w-lg">
-  <CopyCommand command="npx @exisjs/create@latest my-backend" />
+  <CopyCommand command="npm create exisjs@latest my-backend" />
 </div>
 
 <Hint>
@@ -43,12 +43,12 @@ export default controller({
   getUsers: route.get('/', {
     handle(req) {
       // Return a realistic response structure
-      return { 
+      return {
         data: [
           { id: 1, name: 'Alice' },
-          { id: 2, name: 'Bob' }
+          { id: 2, name: 'Bob' },
         ],
-        total: 2 
+        total: 2,
       }
     },
   }),
@@ -66,12 +66,12 @@ export default class UsersController {
   @Get('/')
   getUsers(@Req() req: Request) {
     // Return a realistic response structure
-    return { 
+    return {
       data: [
         { id: 1, name: 'Alice' },
-        { id: 2, name: 'Bob' }
+        { id: 2, name: 'Bob' },
       ],
-      total: 2 
+      total: 2,
     }
   }
 }

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