exisjs 0.5.9 → 0.5.11

package/dist/docs/content/security.mdx

@@ -0,0 +1,294 @@
+---
+nextUrl: "/docs/circuit-breaker"
+nextTitle: "Circuit Breaker"
+---
+
+# Security & Authentication
+
+ExisJS includes native implementations for Cryptography, JWT generation, Role-Based Access Control (RBAC), and Edge Security.
+
+---
+
+## 1. Password Hashing (Scrypt)
+
+ExisJS includes a password hashing engine powered by Node.js's built-in `crypto.scrypt`. 
+
+It automatically generates a secure salt, derives the key, and formats the output into a single safely-storable string (`scrypt:cost:blockSize:parallelization:keyLength:salt:hash`).
+
+#### Functional Paradigm
+
+```typescript filename="src/http/auth/route.ts"
+import { controller, route } from 'exisjs/router'
+import { Password } from 'exisjs/auth'
+
+export default controller({
+  register: route.post('/register', {
+    async handle(req, res) {
+      const plaintext = req.body.password
+
+      // 1. Hash the password
+      // Uses secure defaults (cost: 16384, block: 8)
+      const hashedPassword = await Password.hashPassword(plaintext)
+
+      await db.users.create({ password: hashedPassword })
+      return { success: true }
+    }
+  }),
+
+  login: route.post('/login', {
+    async handle(req, res) {
+      const user = await db.users.findByEmail(req.body.email)
+      
+      // 2. Verify the hash (timing-safe)
+      const isValid = await Password.verifyPassword(req.body.password, user.password)
+      
+      if (!isValid) throw new Error("Invalid credentials")
+      return { success: true }
+    }
+  })
+})
+```
+
+#### Class-Based (OOP) Paradigm
+
+```typescript filename="src/http/auth/route.ts"
+import { Controller, Post, Body } from 'exisjs/decorators'
+import { Password } from 'exisjs/auth'
+
+@Controller()
+export default class AuthController {
+  @Post('/register')
+  async register(@Body() body: any) {
+    const plaintext = body.password
+
+    // 1. Hash the password
+    // Uses secure defaults (cost: 16384, block: 8)
+    const hashedPassword = await Password.hashPassword(plaintext)
+
+    await db.users.create({ password: hashedPassword })
+    return { success: true }
+  }
+
+  @Post('/login')
+  async login(@Body() body: any) {
+    const user = await db.users.findByEmail(body.email)
+    
+    // 2. Verify the hash (timing-safe)
+    const isValid = await Password.verifyPassword(body.password, user.password)
+    
+    if (!isValid) throw new Error("Invalid credentials")
+    return { success: true }
+  }
+}
+```
+
+---
+
+## 2. JSON Web Tokens (JWT)
+
+ExisJS provides a JWT engine using native `createHmac('sha256')`.
+
+```typescript filename="src/http/auth/route.ts"
+import { JWT } from 'exisjs/auth'
+
+// Generate a Token (Expires in 24 hours)
+const token = JWT.signJWT({ userId: 123, role: 'admin' }, process.env.JWT_SECRET, {
+  expiresIn: 86400
+})
+
+// Verify a Token
+// Automatically throws 401 Unauthorized or TokenExpiredError if invalid
+const payload = JWT.verifyJWT<{ userId: number, role: string }>(token, process.env.JWT_SECRET)
+```
+
+### Creating an Auth Middleware
+
+You can wrap this in a gateway middleware to protect entire folders:
+
+#### Functional Paradigm
+
+```typescript filename="src/http/admin/gateway.ts"
+import { defineGateway } from 'exisjs/router'
+import { JWT } from 'exisjs/auth'
+
+export default defineGateway({
+  middlewares: [
+    (req, res, next) => {
+      const token = req.headers.authorization?.split(' ')[1]
+      // Verifies the token and attaches the payload to the request
+      req.user = JWT.verifyJWT(token, process.env.JWT_SECRET)
+      next()
+    }
+  ]
+})
+```
+
+#### Class-Based (OOP) Paradigm
+
+```typescript filename="src/http/admin/gateway.ts"
+import { Gateway } from 'exisjs/decorators'
+import { JWT } from 'exisjs/auth'
+
+@Gateway({
+  middlewares: [
+    (req, res, next) => {
+      const token = req.headers.authorization?.split(' ')[1]
+      req.user = JWT.verifyJWT(token, process.env.JWT_SECRET)
+      next()
+    }
+  ]
+})
+export default class AdminGateway {}
+```
+
+---
+
+## 3. Role-Based Access Control (RBAC)
+
+Once your user is authenticated and their payload is attached to `req.user`, ExisJS provides native Role-Based Access Control right inside the route configuration. You don't need any custom middlewares for this.
+
+#### Functional Paradigm
+
+```typescript filename="src/http/admin/route.ts"
+import { controller, route } from 'exisjs/router'
+import { parseUser } from '../middlewares/auth.js'
+
+export default controller({
+  // Intercepts the request and checks req.user.permissions (or req.user.role) 
+  // before the handler even executes. Throws 403 Forbidden if missing.
+  deleteDatabase: route.delete('/db', {
+    permissions: ['superadmin'],
+    middleware: [parseUser()],
+    handle() {
+      return { success: true }
+    }
+  }),
+  
+  // Accepts an array of allowed permissions
+  viewDashboard: route.get('/dashboard', {
+    permissions: ['admin', 'superadmin', 'manager'],
+    middleware: [parseUser()],
+    handle() {
+      return { metrics: [] }
+    }
+  })
+})
+```
+
+#### Class-Based (OOP) Paradigm
+
+```typescript filename="src/http/admin/route.ts"
+import { Controller, Delete, Get, Use, Permissions } from 'exisjs/decorators'
+import { parseUser } from '../middlewares/auth.js'
+
+@Use(parseUser())
+@Controller()
+export default class AdminController {
+  // Only users with superadmin permission can access this
+  @Permissions('superadmin')
+  @Delete('/db')
+  async deleteDatabase() {
+    return { success: true }
+  }
+  
+  // Accepts an array of allowed permissions
+  @Permissions(['admin', 'superadmin', 'manager'])
+  @Get('/dashboard')
+  async viewDashboard() {
+    return { metrics: [] }
+  }
+}
+```
+
+---
+
+## 4. Stateful Sessions
+
+If you prefer stateful authentication over JWTs, ExisJS ships with a secure session middleware. It securely signs the session cookie (`exis_sid`) and automatically persists changes to `req.session` back to the active store.
+
+By default, it uses a `MemorySessionStore`, but you can plug in any distributed store (like Redis) by implementing the `SessionStore` interface.
+
+#### Functional Paradigm
+
+```typescript filename="src/http/server.ts"
+import { exis } from 'exisjs'
+import { session } from 'exisjs/auth'
+
+export default exis({
+  async onStart(app) {
+    // 1. Mount the session globally
+    app.use(session({ 
+      secret: process.env.SESSION_SECRET_KEY, // Must be 32+ chars
+      ttl: 86400 * 1000 // 1 day
+    }))
+  }
+})
+```
+
+#### Class-Based (OOP) Paradigm
+
+```typescript filename="src/http/server.ts"
+import { Server } from 'exisjs/decorators'
+import { session } from 'exisjs/auth'
+import type { App } from 'exisjs'
+
+@Server()
+export default class RootServer {
+  async onStart(app: App) {
+    // 1. Mount the session globally
+    app.use(session({ 
+      secret: process.env.SESSION_SECRET_KEY, // Must be 32+ chars
+      ttl: 86400 * 1000 // 1 day
+    }))
+  }
+}
+```
+
+#### Functional Paradigm
+
+```typescript filename="src/http/cart/route.ts"
+import { controller, route } from 'exisjs/router'
+
+export default controller({
+  addItem: route.post('/', {
+    handle(req, res) {
+      // 2. Read and Write natively to req.session
+      // ExisJS automatically saves this back to the Store when the request ends
+      if (!req.session.cart) req.session.cart = []
+      
+      req.session.cart.push(req.body.itemId)
+      return { cart: req.session.cart }
+    }
+  })
+})
+```
+
+#### Class-Based (OOP) Paradigm
+
+```typescript filename="src/http/cart/route.ts"
+import { Controller, Post, Req, Body } from 'exisjs/decorators'
+
+@Controller()
+export default class CartController {
+  @Post('/')
+  async addItem(@Req() req: any, @Body() body: any) {
+    // 2. Read and Write natively to req.session
+    // ExisJS automatically saves this back to the Store when the request ends
+    if (!req.session.cart) req.session.cart = []
+    
+    req.session.cart.push(body.itemId)
+    return { cart: req.session.cart }
+  }
+}
+```
+
+---
+
+## 5. Edge Security Middleware
+
+As mentioned in the [Middleware Guide](/docs/middleware), you should strongly consider registering the following global security middleware in your `server.ts`:
+
+- `helmet()`: Enforces Strict-Transport-Security (HSTS), X-Content-Type-Options (nosniff), and prevents Clickjacking (`X-Frame-Options: DENY`).
+- `dbSanitize({ mongo: true })`: A universal scraper that strips NoSQL operators (`$where`) to provide defense-in-depth for MongoDB databases.
+- `csrf({ secret })`: Enforces the Signed Double Submit Cookie pattern to protect state-changing requests (POST, PUT, DELETE) from Cookie Tossing attacks.
+- `hpp()`: HTTP Parameter Pollution protection (removes duplicate array keys).

package/dist/docs/content/sse.mdx

@@ -0,0 +1,159 @@
+---
+nextUrl: "/docs/websockets"
+nextTitle: "WebSockets"
+---
+
+# Server-Sent Events (SSE)
+
+Server-Sent Events (SSE) is a server push technology enabling a client to receive automatic updates from a server via an HTTP connection. Unlike WebSockets, SSE is unidirectional (server-to-client) and works over standard HTTP without requiring complex handshake protocols or specialized load balancer configurations.
+
+SSE is the industry standard for Large Language Model (LLM) streaming (e.g., OpenAI, Anthropic) and real-time dashboard updates. ExisJS provides native SSE support.
+
+---
+
+## 1. Creating an SSE Stream
+
+When you declare a route as an SSE endpoint using `route.sse()` or `@Sse()`, ExisJS automatically configures the correct HTTP headers (`Content-Type: text/event-stream`, `Cache-Control: no-cache`, `Connection: keep-alive`) and provides an `ExisSSE` stream object.
+
+### Functional Paradigm
+
+```typescript filename="src/http/chat/route.ts"
+import { controller, route } from 'exisjs/router'
+import Groq from 'groq-sdk'
+
+export default controller({
+  chat: route.sse('/api/chat', {
+    async handle({ stream: sse, req }) {
+      const groq = new Groq({ apiKey: process.env.GROQ_API_KEY })
+      const message = req.query.message as string
+      
+      if (!message) {
+        sse.send({ error: 'Message is required' }, 'error')
+        sse.close()
+        return
+      }
+
+      try {
+        const aiStream = await groq.chat.completions.create({
+          messages: [{ role: 'user', content: message }],
+          model: 'llama-3.1-8b-instant',
+          stream: true,
+        })
+
+        // Iterate over the async generator provided by the AI SDK
+        for await (const chunk of aiStream) {
+          // Prevent writing to a closed socket if the client disconnects early
+          if (!sse.connected) break
+          
+          const content = chunk.choices[0]?.delta?.content || ''
+          if (content) {
+            sse.send({ text: content }, 'chunk')
+          }
+        }
+        
+        sse.send({ text: '' }, 'done')
+      } finally {
+        // Ensure the connection is always closed when processing completes
+        sse.close()
+      }
+    }
+  })
+})
+```
+
+### Class-Based (OOP) Paradigm
+
+```typescript filename="src/http/chat/route.ts"
+import { Controller, Sse, Stream, Req } from 'exisjs/decorators'
+import type { ExisSSE } from 'exisjs/router'
+import Groq from 'groq-sdk'
+
+@Controller()
+export default class AIChatController {
+  @Sse('/api/chat')
+  async handleChat(@Stream() sse: ExisSSE, @Req() req: any) {
+    const groq = new Groq({ apiKey: process.env.GROQ_API_KEY })
+    const message = req.query.message as string
+    
+    if (!message) {
+      sse.send({ error: 'Message is required' }, 'error')
+      sse.close()
+      return
+    }
+
+    try {
+      const aiStream = await groq.chat.completions.create({
+        messages: [{ role: 'user', content: message }],
+        model: 'llama-3.1-8b-instant',
+        stream: true,
+      })
+
+      for await (const chunk of aiStream) {
+        if (!sse.connected) break
+        
+        const content = chunk.choices[0]?.delta?.content || ''
+        if (content) {
+          sse.send({ text: content }, 'chunk')
+        }
+      }
+      sse.send({ text: '' }, 'done')
+    } finally {
+      sse.close()
+    }
+  }
+}
+```
+
+---
+
+## 2. The `ExisSSE` API
+
+The injected `sse` object gives you full control over the streaming connection:
+
+- **`sse.send(data: string | Record<string, any>, eventName?: string)`**: Serializes the data (if it is an object) to JSON and sends it down the wire. You can optionally tag it with a specific `eventName`.
+- **`sse.connected`**: A boolean that evaluates to `true` while the connection is alive. You should always check this inside long-running `for await` or `while` loops to prevent throwing "Socket Closed" errors when the client disconnects unexpectedly.
+- **`sse.close()`**: Safely closes the stream and terminates the HTTP connection.
+
+```typescript
+// Sending a plain text message
+sse.send("Processing your request...")
+
+// Sending a JSON object tagged with a specific event type (e.g., 'metrics')
+sse.send({ cpu_usage: 95, mem_usage: 60 }, 'metrics')
+```
+
+---
+
+## 3. Client-Side Consumption
+
+To consume the SSE stream from the frontend (e.g., in React, Vue, or Vanilla JS), use the native browser `EventSource` API.
+
+```javascript filename="frontend/app.js"
+// Connect to the ExisJS SSE endpoint
+const eventSource = new EventSource('/api/chat?message=Hello')
+
+// Listen for the default 'message' event (when no eventName is specified in sse.send)
+eventSource.onmessage = (event) => {
+  const data = JSON.parse(event.data)
+  console.log("Standard message:", data)
+}
+
+// Listen for a custom event type, such as 'chunk'
+eventSource.addEventListener('chunk', (event) => {
+  const data = JSON.parse(event.data)
+  // Append the streamed text to the DOM
+  document.getElementById('output').textContent += data.text
+})
+
+// Listen for the 'done' event to close the connection from the client side
+eventSource.addEventListener('done', () => {
+  console.log("Stream finished.")
+  eventSource.close()
+})
+
+// Handle connection errors
+eventSource.onerror = (error) => {
+  console.error("SSE Connection Error:", error)
+  eventSource.close()
+}
+```

package/dist/docs/content/structure.mdx

@@ -0,0 +1,116 @@
+---
+nextUrl: "/docs/config"
+nextTitle: "Configuration"
+---
+
+# Project Structure
+
+When you bootstrap a new ExisJS project using `@exisjs/create`, it generates a clean, opinionated folder structure designed for scalability and maintainability.
+
+Unlike frameworks that force you into deeply nested architectural layers, ExisJS relies heavily on native File-System Routing and centralized configurations to keep your project lean.
+
+---
+
+## The Default Structure
+
+Here is a look at a standard ExisJS project structure:
+
+```text
+my-backend/
+├── .exis/                  # Internal framework cache and build artifacts
+├── src/
+│   └── http/
+│       ├── server.ts       # The main backend entry point
+│       ├── route.ts        # The root API routes (e.g. `GET /`)
+│       └── health/
+│           └── route.ts    # Healthcheck endpoints (e.g. `GET /health`)
+├── .env                    # Local environment variables
+├── env.ts                  # Type-safe environment variable schema
+├── exis.config.ts          # The ExisJS server configuration file
+├── package.json
+└── tsconfig.json
+```
+
+---
+
+## Key Files & Directories
+
+### 1. `exis.config.ts`
+This configures the global application infrastructure. Here, you define network ports, SSL certificates, global CORS policies, Helmet security, and register native framework Plugins (like GraphQL or Drizzle).
+
+[Read the full Configuration Guide](/docs/config)
+
+### 2. `env.ts`
+ExisJS strongly encourages type-safe environment variables. By defining an `env.ts` file using the built-in validator (`v.env()`), your application will gracefully crash at boot if a required environment variable (like `DATABASE_URL`) is missing.
+
+```typescript filename="env.ts"
+import { tex } from 'exisjs/validator'
+
+export const env = tex.object({
+  PORT: tex.number({ coerce: true, optional: true }),
+  NODE_ENV: tex.enum(['development', 'production', 'test']),
+  DATABASE_URL: tex.string()
+}).parse(process.env)
+```
+
+### 3. `src/http/server.ts`
+This is your application's bootstrap file. Instead of manually invoking `app.listen()`, you export your server configuration. The ExisJS CLI automatically reads this file, connects your plugins, mounts the file-system router, and starts the server.
+
+### Functional Server Setup
+
+```typescript filename="src/http/server.ts"
+import { exis } from 'exisjs'
+
+export default exis({
+  async onStart(app) {
+    // Connect to database, provide global DI services, etc.
+  },
+  async onClose(app) {
+    // Gracefully close connections
+  }
+})
+```
+
+### Class-Based (OOP) Server Setup
+
+```typescript filename="src/http/server.ts"
+import { Server } from 'exisjs/decorators'
+import type { App } from 'exisjs'
+
+@Server()
+export default class RootServer {
+  async onStart(app: App) {
+    // Connect to database, provide global DI services, etc.
+  }
+  async onClose(app: App) {
+    // Gracefully close connections
+  }
+}
+```
+
+### 4. `src/http/**/route.ts`
+ExisJS uses **File-System Routing** out of the box! Any file named `route.ts` inside the `src/http/` directory is automatically mapped to a URL based on its folder path. You can define routes functionally using `controller({...})` or with OOP classes using `@Controller()`.
+- `src/http/route.ts` maps to `/`
+- `src/http/health/route.ts` maps to `/health`
+- `src/http/users/settings/route.ts` maps to `/users/settings`
+
+### 5. `src/http/**/gateway.ts`
+Gateways allow you to apply configurations to entire folders. If you place a `gateway.ts` file inside `src/http/admin/`, the Guards, Middlewares, and Providers defined in that Gateway will automatically apply to every single route inside `/admin/*`. Like servers, these can be built using `defineGateway({...})` or the `@Gateway()` decorator.
+
+### 6. `.exis/`
+This is an internal, hidden directory generated by the ExisJS CLI. It holds compiled router mappings and runtime cache to skip filesystem scanning in production. You should add `.exis/` to your `.gitignore`.
+
+### 7. Custom Directories (e.g., `src/services/` or `src/models/`)
+ExisJS only enforces structure inside `src/http/` (for routing) and `src/jobs/` (for background queues). For the rest of your application logic, you are free to organize it however you see fit. A common pattern is to abstract database schemas into `src/models/` and reusable business logic into `src/services/`, and then inject them into your route controllers using the Dependency Injection container.
+
+---
+
+## The ExisJS CLI
+
+Your project is driven entirely by the `exis` CLI tool, which is typically mapped in your `package.json` scripts:
+
+- `exis dev`: Starts the development server with Hot-Module Replacement (HMR).
+- `exis build`: Compiles your TypeScript code to JavaScript for production.
+- `exis start`: Starts the production server using the compiled output.
+- `exis routes`: Prints a formatted table of every compiled API endpoint and WebSocket in your application.
+- `exis generate <type>`: Scaffolds new routes, plugins, or middleware boilerplate.