exisjs 0.5.9 → 0.5.11

package/dist/docs/content/dataloader.mdx

@@ -0,0 +1,170 @@
+---
+nextUrl: "/docs/security"
+nextTitle: "Security & Auth"
+---
+
+# Dataloader (N+1 Queries)
+
+The **N+1 problem** is a common performance issue in backend development. It occurs when your code executes one query to fetch a list of items (e.g. 100 Posts), and then executes $N$ additional queries to fetch related data (e.g. 100 separate queries for each Post's Author).
+
+ExisJS ships with a native `Dataloader` implementation (inspired by GraphQL/Facebook's DataLoader) built directly into the core framework. It automatically **batches** and **caches** requests over a single tick of the Node.js event loop.
+
+---
+
+## 1. Defining Loaders
+
+The best practice in ExisJS is to define a central registry of Dataloaders that are **securely scoped to the current HTTP Request** (to prevent data leaking between different users). 
+
+ExisJS provides `defineLoaders` to create this context-aware registry.
+
+```typescript filename="src/loaders.ts"
+import { Dataloader, defineLoaders } from 'exisjs/dataloader'
+import { getRequest } from 'exisjs/router'
+import { db } from './db'
+
+export const { loaderMiddleware, getLoaders } = defineLoaders({
+  // 1. Author Loader
+  authorLoader: () => new Dataloader<number, any>(async (keys) => {
+    // You can access the current HTTP Request anywhere using getRequest()
+    const req = getRequest()
+    const authToken = req.headers.authorization
+    
+    // This function will only be called ONCE per event-loop tick,
+    // receiving an array of all requested Author IDs: e.g. [1, 2, 3]
+    const authors = await db.authors.findMany({
+      where: { id: { in: keys } }
+    })
+    
+    // You MUST return an array of results in the EXACT same order as the keys
+    return keys.map(key => authors.find(a => a.id === key) || new Error('Not found'))
+  }),
+
+  // 2. Comments Loader
+  commentsLoader: () => new Dataloader<number, any[]>(async (keys) => {
+    const comments = await db.comments.findMany({
+      where: { postId: { in: keys } }
+    })
+    
+    // Group comments by postId
+    return keys.map(key => comments.filter(c => c.postId === key))
+  })
+})
+```
+
+---
+
+## 2. Registering the Middleware
+
+`defineLoaders` returns a `loaderMiddleware`. You must register this middleware so that ExisJS can securely inject a fresh, isolated instance of your Dataloaders into every incoming request.
+
+Because ExisJS uses lazy-initialization, there is **zero performance penalty** for routes that don't actually use the loaders.
+
+#### Functional Paradigm
+
+```typescript filename="src/http/server.ts"
+import { exis } from 'exisjs'
+import { loaderMiddleware } from '../loaders'
+
+export default exis({
+  async onStart(app) {
+    // Register globally for all routes
+    app.use(loaderMiddleware)
+  }
+})
+```
+
+#### Class-Based (OOP) Paradigm
+
+```typescript filename="src/http/server.ts"
+import { Server } from 'exisjs/decorators'
+import { loaderMiddleware } from '../loaders'
+import type { App } from 'exisjs'
+
+@Server()
+export default class RootServer {
+  async onStart(app: App) {
+    // Register globally for all routes
+    app.use(loaderMiddleware)
+  }
+}
+```
+
+---
+
+## 3. Using Dataloader in Routes
+
+Anywhere in your application (Routes, Controllers, Services), you can call `getLoaders()` to retrieve the securely isolated loaders for the *current* request.
+
+#### Functional Paradigm
+
+```typescript filename="src/http/posts/route.ts"
+import { controller, route } from 'exisjs/router'
+import { getLoaders } from '../../loaders'
+
+export default controller({
+  list: route.get('/', {
+    async handle() {
+      // 1. Fetch 100 posts (1 Query)
+      const posts = await db.posts.findMany()
+
+      const { authorLoader } = getLoaders()
+
+      // 2. Loop through 100 posts and call .load()
+      const postsWithAuthors = await Promise.all(
+        posts.map(async (post) => {
+          // Instead of firing 100 queries to the database,
+          // Dataloader queues them up and fires exactly ONE batched query.
+          const author = await authorLoader.load(post.authorId)
+          return { ...post, author }
+        })
+      )
+
+      return postsWithAuthors
+      // Total Queries: 2 (Not 101)
+    }
+  })
+})
+```
+
+#### Class-Based (OOP) Paradigm
+
+```typescript filename="src/http/posts/route.ts"
+import { Controller, Get } from 'exisjs/decorators'
+import { getLoaders } from '../../loaders'
+
+@Controller()
+export default class PostsController {
+  @Get('/')
+  async list() {
+    // 1. Fetch 100 posts (1 Query)
+    const posts = await db.posts.findMany()
+
+    const { authorLoader } = getLoaders()
+
+    // 2. Loop through 100 posts and call .load()
+    const postsWithAuthors = await Promise.all(
+      posts.map(async (post) => {
+        // Instead of firing 100 queries to the database,
+        // Dataloader queues them up and fires exactly ONE batched query.
+        const author = await authorLoader.load(post.authorId)
+        return { ...post, author }
+      })
+    )
+
+    return postsWithAuthors
+    // Total Queries: 2 (Not 101)
+  }
+}
+```
+
+---
+
+## API Reference (`exisjs/dataloader`)
+
+The `Dataloader` class exposes the standard, battle-tested API:
+
+- **`load(key: K): Promise<V>`**: Queues a key to be fetched and returns a Promise.
+- **`loadMany(keys: K[]): Promise<V[]>`**: Equivalent to calling `Promise.all(keys.map(k => load(k)))`.
+- **`clear(key: K): this`**: Clears the cached result for a specific key.
+- **`clearAll(): this`**: Clears the entire cache for this dataloader instance.
+- **`prime(key: K, value: V): this`**: Primes the cache with a predefined value, preventing the batch function from being called for that key.

package/dist/docs/content/decorators.mdx

@@ -0,0 +1,204 @@
+# Decorators
+
+ExisJS provides standard ES6 decorators for developers who prefer the Object-Oriented Programming (OOP) paradigm (inspired by NestJS). 
+
+Because ExisJS does not rely on reflection libraries like `reflect-metadata`, these decorators are fast and memory-efficient.
+
+All decorators can be imported directly from `exisjs/decorators`.
+
+---
+
+## 1. Servers & Gateways
+
+ExisJS allows you to configure your root application and directory-scoped gateways using decorators, replacing the need for functional `exis()` and `defineGateway()` wrappers if you prefer OOP.
+
+### `@Server(config)`
+Used exclusively in your `src/http/server.ts` file to bootstrap the application.
+
+```typescript filename="src/http/server.ts"
+import { Server } from 'exisjs/decorators'
+import { metricsPlugin } from './plugins/metrics'
+import type { App } from 'exisjs'
+
+@Server({
+  plugins: [metricsPlugin],
+  providers: [['Logger', { useValue: console }]]
+})
+export default class RootServer {
+  async onStart(app: App) {
+    console.log('Server started')
+  }
+}
+```
+
+### `@Gateway(config)`
+Used inside any folder (e.g. `src/http/admin/gateway.ts`) to act as a gatekeeper for all routes within that directory and its subdirectories.
+
+```typescript filename="src/http/admin/gateway.ts"
+import { Gateway } from 'exisjs/decorators'
+import { requireAuth } from '../../middleware/auth'
+
+@Gateway({
+  middleware: [requireAuth],
+  cors: { origin: 'https://admin.com' },
+  timeout: 10000,
+  metadata: { openapi: { tags: ['Admin'] } }
+})
+export default class AdminGateway {}
+```
+
+---
+
+## 1. Controllers & Routing
+
+To map a class to a route prefix, use the `@Controller()` decorator. You can then use HTTP Method decorators to map class methods to specific endpoints.
+
+```typescript filename="src/http/users/route.ts"
+import { Controller, Get, Post, Put, Delete } from 'exisjs/decorators'
+
+@Controller('/users')
+export default class UsersController {
+  
+  @Get('/')
+  async listUsers() {
+    return { users: [] }
+  }
+
+  @Post('/create')
+  async createUser() {
+    return { success: true }
+  }
+  
+  @Delete('/:id')
+  async deleteUser() {}
+}
+```
+
+### Available Method Decorators
+- `@Get(path?, schema?)`
+- `@Post(path?, schema?)`
+- `@Put(path?, schema?)`
+- `@Patch(path?, schema?)`
+- `@Delete(path?, schema?)`
+- `@Options(path?, schema?)`
+- `@Head(path?, schema?)`
+- `@All(path?, schema?)`
+- `@Ws(path?, schema?)` (For WebSockets)
+- `@Sse(path?, schema?)` (For Server-Sent Events)
+
+---
+
+## 2. Request Parameters
+
+Instead of manually digging through the `req` object, ExisJS allows you to inject request properties directly into your method parameters.
+
+```typescript filename="src/http/users/route.ts"
+import { Controller, Post, Body, Param, Headers, Req, Res } from 'exisjs/decorators'
+
+@Controller('/users')
+export default class UsersController {
+  
+  @Post('/:id')
+  async update(
+    @Param('id') id: string,
+    @Body() payload: any,
+    @Headers('authorization') token: string,
+    @Req() req: any,
+    @Res() res: any
+  ) {
+    return { success: true, id, payload }
+  }
+}
+```
+
+### Available Parameter Decorators
+- `@Body(key?)` - Extracts `req.body` or a specific key.
+- `@Param(key?)` - Extracts `req.params` or a specific key.
+- `@Query(key?)` - Extracts `req.query` or a specific key.
+- `@Headers(key?)` - Extracts `req.headers` or a specific key.
+- `@Req()` - Injects the underlying `ExisRequest` object.
+- `@Res({ passthrough?: boolean })` - Injects the underlying `ExisResponse` object.
+- `@Ip()` - Extracts the client IP address.
+- `@Next()` - Injects the `next()` function for middleware bypass.
+- `@Session()` - Injects `req.session` (if a session plugin is active).
+- `@Socket()` - Injects the `ExisWebSocket` (only valid in `@Ws` routes).
+- `@Stream()` - Injects the `ExisSSE` stream (only valid in `@Sse` routes).
+- `@UploadedFile()` / `@UploadedFiles()` - Automatically extracts multipart form-data files.
+
+---
+
+## 3. Middleware & Lifecycles
+
+You can bind Middleware, Guards, Exception Filters, and Interceptors directly to your Controllers or individual methods using decorators.
+
+```typescript filename="src/http/admin/route.ts"
+import { Controller, Get, Use, UseGuards, UseFilters } from 'exisjs/decorators'
+import { requireAuth } from '../../middleware/auth'
+import { RoleGuard } from '../../guards/role'
+import { AdminErrorFilter } from '../../filters/admin'
+
+@Controller('/admin')
+@Use(requireAuth) // Applies to the entire class
+@UseFilters(AdminErrorFilter) // Applies to the entire class
+export default class AdminController {
+  
+  @Get('/dashboard')
+  @UseGuards(RoleGuard) // Applies ONLY to this method
+  async getDashboard() {
+    return { secret: 'data' }
+  }
+}
+```
+
+### Available Lifecycle Decorators
+- `@Use(...middlewares)` - Binds standard Express-style middleware.
+- `@UseGuards(...guards)` - Binds ExisJS authorization Guards.
+- `@UseInterceptors(...interceptors)` - Binds response Interceptors.
+- `@UseFilters(...filters)` - Binds Exception Filters.
+
+---
+
+## 4. Response Modifiers
+
+Sometimes you need to modify the HTTP Response (like changing the status code or adding a header) without injecting the raw `@Res()` object. 
+
+```typescript filename="src/http/api/route.ts"
+import { Controller, Post, HttpCode, Header, Redirect } from 'exisjs/decorators'
+
+@Controller('/api')
+export default class ApiController {
+  
+  @Post('/create')
+  @HttpCode(201) // Forces the response status to 201 Created
+  @Header('X-Custom-Version', '2.0') // Appends a custom header
+  async create() {
+    return { success: true }
+  }
+  
+  @Get('/legacy')
+  @Redirect('/new-api', 301) // Automatically redirects the client
+  async legacy() {}
+}
+```
+
+### Available Response & Metadata Decorators
+- `@HttpCode(code: number)`
+- `@Header(name: string, value: string)`
+- `@Redirect(url: string, statusCode?: number)`
+- `@Hosts(...hosts: string[])` - Restricts a route/controller to a specific Host header (e.g. `api.example.com`).
+- `@Permissions(...permissions: string[])` - Restricts a route/controller to users with specific permissions.
+
+---
+
+## 5. Dependency Injection
+
+To mark a class as a service that can be injected into your controllers, use the `@Injectable()` decorator.
+
+```typescript filename="src/services/db.ts"
+import { Injectable } from 'exisjs/decorators'
+
+@Injectable({ scope: 'singleton' })
+export class DatabaseService {
+  async findUser() { ... }
+}
+```