exisjs 0.5.9 → 0.5.11

package/dist/docs/integrations/swagger.mdx

@@ -0,0 +1,113 @@
+---
+nextUrl: "/docs/integrations/s3"
+nextTitle: "AWS S3"
+---
+
+# Swagger OpenAPI
+
+ExisJS comes with a native **Swagger UI & OpenAPI 3.0** generator built directly into the framework. It parses your routes, path parameters, and schema validations to generate an API explorer.
+
+You do **not** need to maintain OpenAPI YAML files or write decorators.
+
+---
+
+## Usage
+
+To enable Swagger UI, simply import `serveSwagger` and call it inside the `onStart` hook in your `server.ts`.
+
+```typescript filename="src/http/server.ts"
+import { exis } from 'exisjs'
+import { serveSwagger } from 'exisjs/swagger'
+
+export default exis({
+  async onStart(app) {
+    // Generate and mount Swagger UI
+    serveSwagger(app, {
+      path: '/api-docs', // Defaults to '/docs'
+      title: 'My Startup API',
+      version: '1.0.0',
+      components: {
+        securitySchemes: {
+          bearerAuth: {
+            type: 'http',
+            scheme: 'bearer',
+            bearerFormat: 'JWT'
+          }
+        }
+      }
+    })
+  }
+})
+```
+
+Once your server starts, navigate to `http://localhost:4000/api-docs` to see your auto-generated Swagger UI. The raw OpenAPI JSON payload will be available at `/api-docs/json`.
+
+---
+
+## Automatic Schema Generation
+
+ExisJS integrates with its internal `v` validator. Any validation schemas attached to your routes (whether Functional or OOP) are automatically translated into OpenAPI specifications.
+
+#### Functional Paradigm
+
+```typescript filename="src/http/users/route.ts"
+import { controller, route } from 'exisjs/router'
+import { tex } from 'exisjs/validator'
+
+export default controller({
+  createUser: route.post('/', {
+    // This schema is automatically translated to OpenAPI request body definitions
+    body: tex.object({
+      name: tex.string(),
+      age: tex.number({ optional: true })
+    }),
+    async handle(req) {
+      return { success: true, name: req.body.name }
+    }
+  })
+})
+```
+
+#### Class-Based (OOP) Paradigm
+
+```typescript filename="src/http/users/route.ts"
+import { Controller, Post, Body } from 'exisjs/decorators'
+import { tex } from 'exisjs/validator'
+
+const CreateUserSchema = tex.object({
+  name: tex.string(),
+  age: tex.number({ optional: true })
+})
+
+@Controller('/users')
+export default class UsersController {
+  @Post('/', { body: CreateUserSchema })
+  async createUser(@Body() body: any) {
+    return { success: true, name: body.name }
+  }
+}
+```
+
+When you view Swagger UI, the `POST /users` endpoint will show the JSON body required, properly displaying the string/number types and required/optional flags.
+
+---
+
+## Gateway Cascading Metadata
+
+If you want to apply OpenAPI tags or security schemas to an entire folder of routes without decorating every endpoint, you can use ExisJS Gateways.
+
+```typescript filename="src/http/admin/gateway.ts"
+import { defineGateway } from 'exisjs/router'
+
+export default defineGateway({
+  // Every route in the /admin folder automatically inherits these OpenAPI tags
+  metadata: {
+    openapi: { 
+      tags: ['Admin Management API'], 
+      security: ['bearerAuth'] 
+    }
+  }
+})
+```
+
+Now, every route under `/admin/*` will be grouped under the "Admin Management API" section in your Swagger UI.

package/dist/docs/reference/README.md

@@ -0,0 +1,3 @@
+# Reference
+
+This folder contains detailed API references, configuration options (`exis.config.ts`), and advanced framework capabilities for Exis JS.

package/dist/docs/reference/adapters.mdx

@@ -0,0 +1,130 @@
+---
+title: "Adapters"
+description: "Strict API Reference for all Serverless and Edge adapters."
+---
+
+# Adapters (`exisjs/adapters`)
+
+This document provides the strict API signatures and TypeScript interfaces exported by the `exisjs/adapters` module. For high-level deployment guides, see the [Adapters Guide](/docs/adapters).
+
+---
+
+## `aws`
+
+Converts API Gateway events into a native Node.js HTTP stream.
+
+```typescript
+function aws(app: App): (event: APIGatewayEvent) => Promise<APIGatewayResult>
+```
+
+### `APIGatewayEvent`
+```typescript
+interface APIGatewayEvent {
+  httpMethod: string;
+  path: string;
+  headers: Record<string, string | undefined>;
+  body: string | null;
+  isBase64Encoded: boolean;
+  queryStringParameters?: Record<string, string | undefined>;
+}
+```
+
+### `APIGatewayResult`
+```typescript
+interface APIGatewayResult {
+  statusCode: number;
+  headers: Record<string, string>;
+  body: string;
+  isBase64Encoded: boolean;
+}
+```
+
+---
+
+## `vercel`
+
+Provides a bridge between Vercel's Node.js Serverless runtime and ExisJS.
+
+```typescript
+function vercel(
+  app: App, 
+  options?: { cwd?: string }
+): (req: VercelRequest, res: VercelResponse) => void | Promise<void>
+```
+
+### `VercelRequest` & `VercelResponse`
+These are re-exported from `@vercel/node`. The adapter intercepts these and patches the internal socket state to satisfy the ExisJS pipeline.
+
+---
+
+## `fetch`
+
+The universal Web Standard adapter. Converts standard Web `Request` objects into internal HTTP pipelines and resolves back to a Web `Response`.
+
+```typescript
+function fetch(
+  app: App
+): (request: Request, env?: any, ctx?: any) => Promise<Response>
+```
+
+*Note: The `env` and `ctx` arguments are seamlessly injected into the ExisJS routing context, allowing you to access platform-specific bindings (e.g. Cloudflare KV).*
+
+---
+
+## `cloudflare`
+
+A dedicated wrapper for Cloudflare Workers that returns the expected ES Module format.
+
+```typescript
+function cloudflare(
+  app: App
+): { fetch: (request: Request, env: any, ctx: ExecutionContext) => Promise<Response> }
+```
+
+---
+
+## `bun`
+
+A dedicated wrapper for the `Bun.serve()` configuration object.
+
+```typescript
+function bun(
+  app: App
+): { fetch: (request: Request) => Promise<Response> }
+```
+
+---
+
+## `deno`
+
+A dedicated wrapper for `Deno.serve()`.
+
+```typescript
+function deno(
+  app: App
+): (request: Request) => Promise<Response>
+```
+
+---
+
+## `netlify`
+
+A dedicated wrapper for Netlify Edge Functions.
+
+```typescript
+function netlify(
+  app: App
+): (request: Request, context: NetlifyContext) => Promise<Response>
+```
+
+---
+
+## `fastly`
+
+A dedicated wrapper for Fastly Compute@Edge which binds to the global `addEventListener` fetch event.
+
+```typescript
+function fastly(
+  app: App
+): (event: FetchEvent) => void
+```

package/dist/docs/reference/auth.mdx

@@ -0,0 +1,183 @@
+---
+title: "Authentication"
+description: "API Reference for ExisJS Authentication utilities (`exisjs/auth`)."
+---
+
+# Authentication (`exisjs/auth`)
+
+ExisJS ships with a completely native, dependency-free `auth` module that covers the most critical security implementations: Scrypt Password Hashing, JWT (JSON Web Tokens), Session Management, and Role-Based Access Control (RBAC).
+
+---
+
+## 1. Password Hashing (Scrypt)
+
+ExisJS natively uses Node's highly secure `scrypt` algorithm to hash passwords. It automatically generates a cryptographically secure salt and stores the parameters in a single string format (`scrypt:N:r:p:keylen:salt:hash`) so you never have to manage them separately.
+
+```typescript filename="src/services/AuthService.ts"
+import { Password } from 'exisjs/auth'
+
+// Hashing a new password
+const hashedPassword = await Password.hashPassword('my-super-secret-password', {
+  cost: 16384, // Higher cost = harder to brute force, but slower to compute
+})
+
+// Verifying a login attempt
+const isValid = await Password.verifyPassword('my-super-secret-password', hashedPassword)
+```
+
+---
+
+## 2. JSON Web Tokens (JWT)
+
+You can instantly sign and verify JWTs without needing third-party libraries like `jsonwebtoken`.
+
+```typescript
+import { JWT } from 'exisjs/auth'
+
+// Sign a token valid for 2 hours
+const token = JWT.signJWT(
+  { userId: '123', role: 'admin' }, 
+  process.env.JWT_SECRET,
+  { expiresIn: 2 * 60 * 60 } 
+)
+
+try {
+  // Verifying token returns the exact typed payload
+  const payload = JWT.verifyJWT<{ userId: string, role: string }>(token, process.env.JWT_SECRET)
+  console.log(payload.userId)
+} catch (err) {
+  if (err.name === 'TokenExpiredError') {
+    // Handle expired token
+  }
+}
+```
+
+---
+
+## 3. Session Middleware
+
+If you prefer stateful authentication, ExisJS provides extremely robust session middleware out of the box. It leverages signed HTTP-only cookies to track users and automatically synchronizes session state back to the store (Memory, Redis, etc.) when the request ends.
+
+### Global Setup via Plugin (`exis.config.ts`)
+
+Because ExisJS utilizes a file-based architecture with no manual server entry point, global middlewares like `session` should be attached using a Plugin.
+
+```typescript filename="src/plugins/session.ts"
+import { definePlugin } from 'exisjs/plugin'
+import { session } from 'exisjs/auth'
+
+export const sessionPlugin = definePlugin({
+  name: 'global-session',
+  register(app) {
+    app.use(session({
+      secret: process.env.SESSION_SECRET || 'fallback-secret-minimum-32-chars-long!',
+      cookieName: 'exis_sid',
+      ttl: 86400 * 1000, // 1 day in milliseconds
+      // store: new RedisSessionStore(...) 
+    }))
+  }
+})
+```
+
+Then, natively register your plugin in `exis.config.ts`:
+
+```typescript filename="exis.config.ts"
+import { defineConfig } from 'exisjs/config'
+import { sessionPlugin } from './src/plugins/session'
+
+export default defineConfig({
+  plugins: [
+    sessionPlugin()
+  ]
+})
+```
+
+Once registered, you can read and write to `req.session` anywhere in your application!
+
+### Functional Example
+
+```typescript filename="src/http/auth/route.ts"
+import { controller, route } from 'exisjs/router'
+import { HttpError } from 'exisjs/error'
+
+export default controller({
+  login: route.post('/login', {
+    async handle(ctx) {
+      const user = await db.users.findByEmail(ctx.body.email)
+      if (!user) throw HttpError.unauthorized('Invalid credentials')
+
+      // Login the user by attaching data to the session
+      ctx.req.session.userId = user.id
+      ctx.req.session.role = user.role
+      
+      return { success: true }
+    }
+  })
+})
+```
+
+### Class-Based (OOP) Example
+
+```typescript filename="src/http/auth/route.ts"
+import { Controller, Post, Body, Req } from 'exisjs/decorators'
+import type { Request } from 'exisjs'
+
+@Controller('/auth')
+export default class AuthController {
+  
+  @Post('/login')
+  async login(@Body() body: any, @Req() req: Request) {
+    const user = await db.users.findByEmail(body.email)
+    
+    // Attach to session
+    req.session.userId = user.id
+    req.session.role = user.role
+    
+    return { success: true }
+  }
+}
+```
+
+---
+
+## 4. Role-Based Access Control (RBAC)
+
+The `requireRole` middleware checks if the current authenticated user has the necessary permissions to access a route.
+
+*Note: This middleware expects that `req.user.role` was populated by an earlier authentication middleware (like a JWT Verifier or a Session Restorer).*
+
+### Functional Example
+
+```typescript filename="src/http/admin/route.ts"
+import { controller, route } from 'exisjs/router'
+import { requireRole } from 'exisjs/auth'
+
+export default controller({
+  getDashboard: route.get('/dashboard', {
+    middleware: [
+      // Only users with 'admin' or 'superadmin' roles can access this route
+      requireRole(['admin', 'superadmin'])
+    ],
+    async handle() {
+      return { metrics: [] }
+    }
+  })
+})
+```
+
+### Class-Based (OOP) Example
+
+```typescript filename="src/http/admin/route.ts"
+import { Controller, Get, Use } from 'exisjs/decorators'
+import { requireRole } from 'exisjs/auth'
+
+@Controller('/admin')
+export default class AdminController {
+  
+  @Get('/dashboard')
+  @Use(requireRole(['admin', 'superadmin']))
+  async getDashboard() {
+    return { metrics: [] }
+  }
+}
+```

package/dist/docs/reference/cache.mdx

@@ -0,0 +1,132 @@
+---
+title: "Caching"
+description: "API Reference for ExisJS Caching and Revalidation (`exisjs/cache`)."
+---
+
+# Caching (`exisjs/cache`)
+
+ExisJS comes with a highly sophisticated built-in caching system that natively supports **stale-while-revalidate** semantics, intelligent `tags`-based cache invalidation, and multiple backing stores (Memory, FileSystem, and Redis).
+
+---
+
+## `cacheMiddleware(options)`
+
+The primary way to use the cache is by attaching the `cacheMiddleware` directly to your GET routes. It intercepts responses, stores them in the cache, and serves them blazingly fast on subsequent identical requests.
+
+ExisJS automatically injects an `X-Exis-Cache: HIT` or `X-Exis-Cache: MISS` header into the HTTP response so you can debug your cache behavior instantly!
+
+**Class-Based (OOP)**
+```typescript filename="src/http/stats/route.ts"
+import { Controller, Get, Use } from 'exisjs/decorators'
+import { cacheMiddleware } from 'exisjs/cache'
+
+@Controller('/stats')
+export default class StatsController {
+  
+  @Get('/')
+  @Use(
+    cacheMiddleware({
+      ttlMs: 60 * 1000, // 60 seconds
+      keyGenerator: (req) => `stats:${req.query.period || 'all'}`
+    })
+  )
+  async getStats() {
+    return db.queryHeavyStats() 
+  }
+}
+```
+
+**Functional**
+```typescript filename="src/http/stats/route.ts"
+import { controller, route } from 'exisjs/router'
+import { cacheMiddleware } from 'exisjs/cache'
+
+export default controller({
+  getStats: route.get('/', {
+    middleware: [
+      cacheMiddleware({
+        ttlMs: 60 * 1000, // 60 seconds
+        
+        // You MUST provide a keyGenerator to prevent data leaking between users!
+        keyGenerator: (req) => `stats:${req.query.period || 'all'}`
+      })
+    ],
+    async handle() {
+      // This heavy query only runs once every 60 seconds per period
+      return db.queryHeavyStats() 
+    }
+  })
+})
+```
+
+### Options
+
+- **`keyGenerator`** `(req => string)`: **Required.** Generates a unique cache key for the request. Never use a static key if the response varies by User ID or Query Parameters.
+- **`ttlMs`** `(number)`: Time to live in milliseconds. If omitted, the cache never inherently expires based on time (relies on manual tags instead).
+- **`tags`** `(string[] | function)`: A list of tags to associate with this cache entry, used for Next.js-style on-demand revalidation.
+
+---
+
+## Tag-Based Cache Invalidation
+
+Instead of waiting for a TTL to expire, you can invalidate caches instantly using tags. This is exactly how Next.js App Router caching works.
+
+When you cache a route, assign it a tag:
+
+```typescript filename="src/http/products/route.ts"
+import { cacheMiddleware } from 'exisjs/cache'
+
+route.get('/:id', {
+  middleware: [
+    cacheMiddleware({
+      // We tag this cache entry with the specific product ID
+      tags: (req) => [`product-${req.params.id}`, 'all-products'],
+      keyGenerator: (req) => `product:${req.params.id}`
+    })
+  ],
+  async handle(ctx) {
+    return db.products.find(ctx.params.id)
+  }
+})
+```
+
+Later, when a user updates the product via a `POST` or `PUT` route, you can instantly bust all caches tied to that tag using `revalidateTag()`!
+
+```typescript filename="src/http/products/route.ts"
+import { revalidateTag } from 'exisjs/cache'
+
+route.put('/:id', {
+  async handle(ctx) {
+    await db.products.update(ctx.params.id, ctx.body)
+    
+    // Instantly purge the cache across the entire cluster!
+    await revalidateTag(`product-${ctx.params.id}`)
+    
+    return { success: true }
+  }
+})
+```
+
+---
+
+## Cache Drivers
+
+ExisJS natively provides three driver implementations:
+
+1. **`FileSystemCacheStore`**: (Default). Writes cache data to `.exis/cache/*.json` on the disk. Extremely fast for static data and survives server reboots.
+2. **`MemoryCacheStore`**: Keeps caches purely in RAM. Perfect for development or extremely high-throughput, short-TTL data. (Includes automatic broadcast sync if running in an ExisJS Cluster).
+3. **`RedisCacheStore`**: The standard for production. Uses a minimal Redis client to handle distributed caching across massive fleets of servers.
+
+### Switching Stores Globally
+
+While you can pass a `store` option directly into `cacheMiddleware()`, it is usually better to set the global cache store during application boot:
+
+```typescript filename="src/server.ts"
+import { exis } from 'exisjs'
+import { setCacheStore, RedisCacheStore } from 'exisjs/cache'
+
+const app = exis()
+
+// Use Redis instead of the default FileSystem cache
+setCacheStore(new RedisCacheStore(myRedisClient))
+```

package/dist/docs/reference/circuit-breaker.mdx

@@ -0,0 +1,71 @@
+---
+title: "Circuit Breaker"
+description: "Strict API Reference for the Circuit Breaker resilience utility."
+---
+
+# Circuit Breaker (`exisjs/app`)
+
+This document provides the strict API signatures and TypeScript interfaces exported for the `CircuitBreaker` utility. For high-level resilience guides, see the [Circuit Breaker Guide](/docs/circuit-breaker).
+
+---
+
+## `CircuitBreaker` Class
+
+The `CircuitBreaker` class is a state machine that monitors the execution of async actions to prevent cascading failures.
+
+```typescript
+import { CircuitBreaker } from 'exisjs/app'
+
+class CircuitBreaker {
+  constructor(options?: CircuitBreakerOptions)
+  
+  // The current state of the breaker
+  public state: CircuitState
+  
+  // Executes the provided async action through the breaker
+  fire<T>(action: () => Promise<T>): Promise<T>
+}
+```
+
+### `CircuitBreakerOptions`
+
+```typescript
+interface CircuitBreakerOptions {
+  /** Maximum number of sequential failures before the breaker transitions to OPEN */
+  failureThreshold?: number // Default: 5
+  
+  /** Time to wait (in ms) before transitioning from OPEN to HALF_OPEN to test recovery */
+  resetTimeoutMs?: number   // Default: 10000 (10 seconds)
+}
+```
+
+---
+
+## `CircuitState` Enum
+
+The circuit breaker operates in one of three states.
+
+```typescript
+enum CircuitState {
+  // Normal operation, all requests pass
+  CLOSED = 'CLOSED',
+  
+  // Failing, all requests are instantly rejected
+  OPEN = 'OPEN',
+  
+  // Testing recovery, exactly ONE request is allowed through
+  HALF_OPEN = 'HALF_OPEN',
+}
+```
+
+---
+
+## `CircuitBreakerError`
+
+If `fire()` is called while the breaker is `OPEN` (or if it is `HALF_OPEN` and a probe is already in flight), the breaker will instantly reject the promise with a `CircuitBreakerError`.
+
+```typescript
+class CircuitBreakerError extends Error {
+  constructor(message: string)
+}
+```