exisjs 0.5.9 → 0.5.11

package/dist/docs/integrations/jwt.mdx

@@ -0,0 +1,151 @@
+---
+nextUrl: "/docs/integrations/swagger"
+nextTitle: "Swagger OpenAPI"
+---
+
+# JWT Authentication
+
+ExisJS comes with a native JSON Web Token (JWT) integration. You do **not** need to install external dependencies like `jsonwebtoken`. It is built natively into the framework and optimized for edge environments.
+
+---
+
+## Environment Variables
+
+The JWT integration securely reads your secret key from your `.env` file. 
+Before using the plugin, ensure you have your JWT secret set:
+
+```bash filename=".env"
+# Your JWT signing secret
+JWT_SECRET="super_secret_key_123"
+```
+
+---
+
+## Usage
+
+Import the `JWT` object from `exisjs/auth` and use `JWT.signJWT()` or `JWT.verifyJWT()`. You will need to explicitly pass your secret key.
+
+#### Functional Paradigm
+
+```typescript filename="src/http/auth/route.ts"
+import { controller, route } from 'exisjs/router'
+import { JWT } from 'exisjs/auth'
+import { db, users } from '../../db'
+
+export default controller({
+  login: route.post('/login', {
+    async handle(req, res) {
+      const user = await db.select().from(users).where({ email: req.body.email })
+      
+      if (!user) {
+        res.status(401)
+        return { error: 'Invalid credentials' }
+      }
+
+      // Sign the token using process.env.JWT_SECRET
+      const token = JWT.signJWT({ userId: user.id }, process.env.JWT_SECRET!, { expiresIn: 604800 })
+      
+      return { token }
+    }
+  }),
+
+  verify: route.get('/me', {
+    async handle(req, res) {
+      try {
+        const token = req.headers.authorization?.split(' ')[1]
+        
+        // Verify using process.env.JWT_SECRET
+        const decoded = JWT.verifyJWT<{ userId: string }>(token, process.env.JWT_SECRET!)
+        
+        return { userId: decoded.userId }
+      } catch (err) {
+        res.status(401)
+        return { error: 'Invalid or expired token' }
+      }
+    }
+  })
+})
+```
+
+#### Class-Based (OOP) Paradigm
+
+```typescript filename="src/http/auth/route.ts"
+import { Controller, Post, Get, Body, Req, Res } from 'exisjs/decorators'
+import { JWT } from 'exisjs/auth'
+import { db, users } from '../../db'
+
+@Controller('/auth')
+export default class AuthController {
+  @Post('/login')
+  async login(@Body() body: any, @Res() res: any) {
+    const user = await db.select().from(users).where({ email: body.email })
+    
+    if (!user) {
+      res.status(401)
+      return { error: 'Invalid credentials' }
+    }
+
+    // Sign the token using process.env.JWT_SECRET
+    const token = JWT.signJWT({ userId: user.id }, process.env.JWT_SECRET!, { expiresIn: 604800 })
+    
+    return { token }
+  }
+
+  @Get('/me')
+  async verifyMe(@Req() req: any, @Res() res: any) {
+    try {
+      const token = req.headers.authorization?.split(' ')[1]
+      
+      // Verify using process.env.JWT_SECRET
+      const decoded = JWT.verifyJWT<{ userId: string }>(token, process.env.JWT_SECRET!)
+      
+      return { userId: decoded.userId }
+    } catch (err) {
+      res.status(401)
+      return { error: 'Invalid or expired token' }
+    }
+  }
+}
+```
+
+---
+
+## Using JWT in Middleware & Gateways
+
+While you can verify tokens directly in your routes, ExisJS's JWT integration works well inside Middlewares to protect entire folders using **Gateways**.
+
+First, create your middleware outside of your routing tree:
+
+```typescript filename="src/middlewares/auth.ts"
+import { JWT } from 'exisjs/auth'
+
+export function requireAuth(req: any, res: any, next: any) {
+  const token = req.headers.authorization?.split(' ')[1]
+  
+  if (!token) {
+    res.status(401).json({ error: 'Missing token' })
+    return
+  }
+
+  try {
+    const decoded = JWT.verifyJWT<{ userId: string }>(token, process.env.JWT_SECRET!)
+    // Attach the decoded payload to the request for the route to use
+    req.user = decoded
+    next()
+  } catch (err) {
+    res.status(401).json({ error: 'Unauthorized' })
+  }
+}
+```
+
+Now, apply it to an entire domain using a Gateway. This prevents you from having to protect every route manually.
+
+```typescript filename="src/http/api/gateway.ts"
+import { defineGateway } from 'exisjs/router'
+import { requireAuth } from '../../middlewares/auth'
+
+export default defineGateway({
+  // Intercepts and protects every route inside the /api folder
+  middleware: [requireAuth]
+})
+```

package/dist/docs/integrations/mongo.mdx

@@ -0,0 +1,183 @@
+---
+nextUrl: "/docs/integrations/redis"
+nextTitle: "Redis"
+---
+
+# Database (NoSQL)
+
+ExisJS provides native integrations for MongoDB. You do **NOT** need to register the database in your `server.ts` file. The connection pools are lazily initialized when you first execute a query.
+
+The framework provides first-class plugins for **Mongoose** (the ODM) and the raw **MongoDB Node.js Driver** (`mongodb`).
+
+---
+
+## Environment Variables
+
+Both MongoDB plugins securely read your connection string from your `.env` file. 
+Before using any of the plugins below, ensure you have your MongoDB URI set:
+
+```bash filename=".env"
+# Your MongoDB connection string
+MONGODB_URI="mongodb://localhost:27017/my_database"
+```
+
+---
+
+## Mongoose (ODM)
+
+The `@exisjs/mongoose` plugin automatically manages your database connection lifecycle.
+
+### Basic Setup
+In your `server.ts` file, simply call `configureMongoose({})`:
+
+```typescript filename="src/http/server.ts"
+import { exis } from "exisjs";
+import { configureMongoose } from "exisjs/mongoose";
+
+export default exis({
+  async onStart(app) {
+    configureMongoose({});
+  }
+});
+```
+
+### Serverless Deployments (Vercel, AWS Lambda)
+
+When deploying to serverless platforms, bundlers (like `@vercel/node`) can accidentally create multiple unconnected instances of Mongoose in memory. To guarantee stability in serverless functions, we recommend importing Mongoose directly and passing it as the `client`:
+
+```typescript filename="src/http/server.ts"
+import { exis } from "exisjs";
+import mongoose from "mongoose";
+import { configureMongoose } from "exisjs/mongoose";
+
+export default exis({
+  async onStart(app) {
+    configureMongoose({ client: mongoose });
+  }
+});
+```
+
+---
+## 1. Mongoose (Recommended)
+
+Mongoose provides a straight-forward, schema-based solution to model your application data. 
+
+### Installation
+
+```bash
+npm install mongoose
+```
+
+### Usage
+
+Import the `mongoose` proxy from `exisjs/mongoose`. ExisJS will connect to your database behind the scenes (Mongoose natively buffers operations until connected).
+
+```typescript filename="src/models/user.ts"
+import { mongoose } from 'exisjs/mongoose'
+
+const userSchema = new mongoose.Schema({
+  name: String,
+  email: { type: String, unique: true },
+})
+
+export const User = mongoose.model('User', userSchema)
+```
+
+Now you can use your `User` model in your routes:
+
+#### Functional Paradigm
+
+```typescript filename="src/http/users/route.ts"
+import { controller, route } from 'exisjs/router'
+import { User } from '../../models/user'
+
+export default controller({
+  getUsers: route.get('/', {
+    async handle() {
+      return await User.find({})
+    }
+  })
+})
+```
+
+#### Class-Based (OOP) Paradigm
+
+```typescript filename="src/http/users/route.ts"
+import { Controller, Get } from 'exisjs/decorators'
+import { User } from '../../models/user'
+
+@Controller()
+export default class UsersController {
+  @Get('/')
+  async getUsers() {
+    return await User.find({})
+  }
+}
+```
+
+---
+
+## 2. Raw MongoDB (`mongodb`)
+
+If you don't want to use an ODM and prefer working with raw BSON documents, ExisJS provides an integration for the native `mongodb` driver.
+
+### Installation
+
+```bash
+npm install mongodb
+```
+
+### Usage
+
+Import `mongo` from `exisjs/mongodb`. The first time you interact with it, ExisJS will boot up a MongoClient connection pool using your `MONGODB_URI`.
+
+#### Functional Paradigm
+
+```typescript filename="src/http/users/route.ts"
+import { controller, route } from 'exisjs/router'
+import { mongo } from 'exisjs/mongodb'
+
+export default controller({
+  getUsers: route.get('/', {
+    async handle() {
+      const db = mongo.db('my_database')
+      return await db.collection('users').find({}).toArray()
+    }
+  })
+})
+```
+
+#### Class-Based (OOP) Paradigm
+
+```typescript filename="src/http/users/route.ts"
+import { Controller, Get } from 'exisjs/decorators'
+import { mongo } from 'exisjs/mongodb'
+
+@Controller()
+export default class UsersController {
+  @Get('/')
+  async getUsers() {
+    const db = mongo.db('my_database')
+    return await db.collection('users').find({}).toArray()
+  }
+}
+```
+
+### Customizing Connection Options
+
+If you need to pass custom options to the MongoDB connection pool (like replica set configs or pool sizes), call `configureMongo(options)` or `configureMongoose(options)` inside your `server.ts` `onStart` hook.
+
+```typescript filename="src/http/server.ts"
+import { exis } from 'exisjs'
+import { configureMongoose } from 'exisjs/mongoose'
+
+export default exis({
+  async onStart() {
+    // Initialize with custom connection options
+    configureMongoose({
+      maxPoolSize: 50,
+      wtimeoutMS: 2500,
+    })
+  }
+})
+```

package/dist/docs/integrations/observability.mdx

@@ -0,0 +1,125 @@
+---
+nextUrl: "/docs/integrations/drizzle"
+nextTitle: "Drizzle ORM"
+---
+
+# Observability (Health, Metrics, Tracing)
+
+ExisJS includes Observability features out of the box.
+
+Instead of locking you into a specific vendor, ExisJS uses a "Bring Your Own Adapter" architecture. We provide middlewares for Health Checks, Metrics (Prometheus/StatsD), and Tracing (OpenTelemetry) that integrate with your vendor SDKs.
+
+---
+
+## 1. Advanced Health Checks
+
+ExisJS includes a `healthCheck` middleware that exposes a `/health` endpoint for Kubernetes liveness/readiness probes or load balancers.
+
+It supports parallel asynchronous dependency checks with built-in timeouts.
+
+```typescript filename="src/http/server.ts"
+import { exis } from 'exisjs'
+import { healthCheck } from 'exisjs/observability'
+import { db } from 'exisjs/postgres'
+import { redis } from 'exisjs/redis'
+
+export default exis({
+  middlewares: [
+    healthCheck({
+      path: '/healthz', // Defaults to '/health'
+      checks: [
+        {
+          name: 'postgres',
+          timeoutMs: 3000,
+          check: async () => await db`SELECT 1` 
+        },
+        {
+          name: 'redis',
+          timeoutMs: 2000,
+          check: async () => await redis.ping()
+        }
+      ]
+    })
+  ]
+})
+```
+
+When you ping `GET /healthz`, ExisJS will run all checks in parallel. 
+- If all checks pass, it returns HTTP `200 OK` with `{ status: "pass", dependencies: { postgres: { status: "up" }, ... } }`.
+- If any check times out or fails, it returns HTTP `503 Service Unavailable` with `{ status: "fail", ... }`.
+
+---
+
+## 2. Metrics (Prometheus / StatsD)
+
+Tracking HTTP request durations is a common requirement.
+
+ExisJS exposes a `metrics()` middleware adapter. It handles timing calculations and path normalization (e.g., aggregating `/users/1` and `/users/2` into `/users/:id` to prevent Prometheus cardinality explosions).
+
+```typescript filename="src/http/server.ts"
+import { exis } from 'exisjs'
+import { metrics } from 'exisjs/observability'
+import promClient from 'prom-client'
+
+// 1. Setup your external Prometheus registry
+const httpRequestDurationMicroseconds = new promClient.Histogram({
+  name: 'http_request_duration_ms',
+  help: 'Duration of HTTP requests in ms',
+  labelNames: ['method', 'route', 'code'],
+})
+
+export default exis({
+  middlewares: [
+    // 2. Plug it directly into the ExisJS adapter
+    metrics({
+      onRequestEnd: ({ method, path, statusCode, durationMs }) => {
+        httpRequestDurationMicroseconds
+          .labels(method, path, String(statusCode))
+          .observe(durationMs)
+      }
+    })
+  ]
+})
+```
+
+---
+
+## 3. Distributed Tracing (OpenTelemetry)
+
+Distributed tracing allows you to follow a single request across multiple microservices. 
+
+ExisJS provides a `tracing()` adapter designed for OpenTelemetry. It creates spans for every incoming request, injects HTTP statuses, and scrubs sensitive headers (like `authorization`, `cookie`, `session`) before they are sent to your observability platform.
+
+```typescript filename="src/http/server.ts"
+import { exis } from 'exisjs'
+import { tracing } from 'exisjs/observability'
+import { trace } from '@opentelemetry/api'
+
+// Grab your global OpenTelemetry tracer
+const otelTracer = trace.getTracer('exis-app')
+
+export default exis({
+  middlewares: [
+    tracing({
+      // ExisJS calls this hook automatically for every incoming request
+      startActiveSpan: (name, metadata, callback) => {
+        otelTracer.startActiveSpan(name, (span) => {
+          
+          // ExisJS automatically provides safe, scrubbed metadata
+          span.setAttribute('http.method', metadata.method)
+          span.setAttribute('http.route', metadata.path)
+          
+          for (const [key, val] of Object.entries(metadata.headers)) {
+            span.setAttribute(`http.header.${key}`, String(val))
+          }
+
+          // Pass the span back to ExisJS so it can automatically end it and attach status codes
+          callback(span)
+        })
+      }
+    })
+  ]
+})
+```
+
+With this middleware, your application is instrumented with OpenTelemetry spans.

package/dist/docs/integrations/openai.mdx

@@ -0,0 +1,108 @@
+---
+nextUrl: "/docs/integrations/posthog"
+nextTitle: "PostHog"
+---
+
+# OpenAI Integration
+
+ExisJS provides an integration for OpenAI to harness the power of LLMs.
+
+Following our framework philosophy, the `openai` SDK is an optional peer dependency. It remains uninstalled until you explicitly need it, ensuring your core application stays lightweight.
+
+---
+
+## Environment Variables
+
+The OpenAI plugin securely reads your API key directly from your `.env` file. 
+
+Before using the plugin, ensure you have your API key set:
+
+```bash filename=".env"
+OPENAI_API_KEY="sk-proj-123456789"
+```
+
+---
+
+## Installation
+
+ExisJS wraps the official `openai` Node.js SDK.
+
+```bash
+npm install openai
+```
+
+---
+
+## Usage
+
+Simply import the `openai` proxy from `exisjs/openai`. ExisJS will boot and cache the client connection the first time you generate a completion.
+
+#### Functional Paradigm
+
+```typescript filename="src/http/ai/route.ts"
+import { controller, route } from 'exisjs/router'
+import { openai } from 'exisjs/openai'
+
+export default controller({
+  generateJoke: route.post('/joke', {
+    async handle(req) {
+    // The openai client lazy-loads here
+      const completion = await openai.chat.completions.create({
+        messages: [{ role: 'user', content: 'Tell me a programming joke.' }],
+        model: 'gpt-4o-mini',
+      })
+
+      return { 
+        success: true, 
+        joke: completion.choices[0].message.content 
+      }
+    }
+  })
+})
+```
+
+#### Class-Based (OOP) Paradigm
+
+```typescript filename="src/http/ai/route.ts"
+import { Controller, Post } from 'exisjs/decorators'
+import { openai } from 'exisjs/openai'
+
+@Controller('/ai')
+export default class AIController {
+  
+  @Post('/joke')
+  async generateJoke() {
+    // The openai client magically lazy-loads here!
+    const completion = await openai.chat.completions.create({
+      messages: [{ role: 'user', content: 'Tell me a programming joke.' }],
+      model: 'gpt-4o-mini',
+    })
+
+    return { 
+      success: true, 
+      joke: completion.choices[0].message.content 
+    }
+  }
+}
+```
+
+---
+
+## Customizing Connection Options
+
+If you need to pass custom options to the OpenAI Client (e.g., overriding the `baseURL` to use an OpenAI-compatible open-source model via Ollama or vLLM), call `configureOpenAI(options)` inside your `server.ts` `onStart` hook.
+
+```typescript filename="src/http/server.ts"
+import { exis } from 'exisjs'
+import { configureOpenAI } from 'exisjs/openai'
+
+export default exis({
+  async onStart() {
+    // Override the baseURL to point to a local Ollama instance
+    configureOpenAI({
+      baseURL: 'http://localhost:11434/v1',
+      apiKey: 'ollama' // Local LLMs often just need a dummy key
+    })
+  }
+})
+```