exisjs 0.6.0 → 0.7.0

package/dist/docs/integrations/observability.mdx

@@ -1,125 +0,0 @@
----
-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

@@ -1,108 +0,0 @@
----
-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 automatically 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
-    })
-  }
-})
-```

package/dist/docs/integrations/postgres.mdx

@@ -1,190 +0,0 @@
----
-nextUrl: "/docs/integrations/mongo"
-nextTitle: "Database (NoSQL)"
----
-
-# Database (SQL)
-
-ExisJS provides native integrations for SQL databases and ORMs in the Node.js ecosystem. Instead of writing boilerplate connection logic, ExisJS manages your connection pools using the `DATABASE_URL` environment variable.
-
-Because these plugins manage their own state, you do **NOT** need to register them in your `server.ts` file. They lazily initialize their connection pools when you first query them.
-
-The framework provides first-class plugins for **Drizzle ORM**, **Prisma**, and raw **PostgreSQL** (`postgres.js`).
-
----
-
-## Environment Variables
-
-All SQL plugins securely read your connection string from your `.env` file. 
-Before using any of the plugins below, ensure you have your Postgres connection string set:
-
-```bash filename=".env"
-# Your PostgreSQL connection string
-DATABASE_URL="postgres://user:password@localhost:5432/my_database"
-```
-
----
-
-## 1. Drizzle ORM (Recommended)
-
-[Drizzle ORM](https://orm.drizzle.team/) is the recommended database solution for ExisJS. It provides type safety and performance.
-
-### Installation
-
-```bash
-npm install drizzle-orm postgres
-npm install -D drizzle-kit
-```
-
-### Usage
-
-Simply define your schema and call the native `drizzle()` integration helper. ExisJS will initialize a `postgres.js` connection pool using your `DATABASE_URL` environment variable.
-
-```typescript filename="src/db/index.ts"
-import { drizzle } from 'exisjs/drizzle'
-import { pgTable, serial, text, varchar } from 'drizzle-orm/pg-core'
-
-// 1. Define your schema
-export const users = pgTable('users', {
-  id: serial('id').primaryKey(),
-  fullName: text('full_name'),
-  phone: varchar('phone', { length: 256 }),
-})
-
-const schema = { users }
-
-// 2. Initialize the client
-// ExisJS automatically reads process.env.DATABASE_URL
-export const db = drizzle(schema)
-```
-
-Now you can use `db` in your routes:
-
-#### Functional Paradigm
-
-```typescript filename="src/http/users/route.ts"
-import { controller, route } from 'exisjs/router'
-import { db, users } from '../../db'
-
-export default controller({
-  listUsers: route.get('/', {
-    async handle() {
-      return await db.select().from(users)
-    }
-  })
-})
-```
-
-#### Class-Based (OOP) Paradigm
-
-```typescript filename="src/http/users/route.ts"
-import { Controller, Get } from 'exisjs/decorators'
-import { db, users } from '../../db'
-
-@Controller()
-export default class UsersController {
-  @Get('/')
-  async listUsers() {
-    return await db.select().from(users)
-  }
-}
-```
-
----
-
-## 2. Prisma ORM
-
-If you prefer a schema-first approach, ExisJS includes a wrapper for Prisma.
-
-### Installation
-
-```bash
-npm install @prisma/client
-npm install -D prisma
-```
-
-Initialize your schema:
-```bash
-npx prisma init
-```
-
-### Usage
-
-Use the native `prisma()` helper to instantiate a singleton `PrismaClient` that manages the connection.
-
-```typescript filename="src/db/index.ts"
-import { prisma } from 'exisjs/prisma'
-
-// Singleton initialization
-export const db = prisma()
-```
-
----
-
-## 3. Raw PostgreSQL (`postgres.js`)
-
-If you don't want to use an ORM and prefer writing raw SQL, ExisJS provides an integration for the `postgres.js` driver.
-
-### Installation
-
-```bash
-npm install postgres
-```
-
-### Usage
-
-Import the tagged template literal `sql` from `exisjs/postgres`. The first time you use it, ExisJS will boot up a connection pool using `DATABASE_URL`.
-
-#### Functional Paradigm
-
-```typescript filename="src/http/users/route.ts"
-import { controller, route } from 'exisjs/router'
-import { sql } from 'exisjs/postgres'
-
-export default controller({
-  getUser: route.get('/:id', {
-    async handle(req) {
-      // Write raw SQL with native parameterization.
-      const users = await sql`SELECT * FROM users WHERE id = ${req.params.id}`
-      return users[0]
-    }
-  })
-})
-```
-
-#### Class-Based (OOP) Paradigm
-
-```typescript filename="src/http/users/route.ts"
-import { Controller, Get, Param } from 'exisjs/decorators'
-import { sql } from 'exisjs/postgres'
-
-@Controller()
-export default class UsersController {
-  @Get('/:id')
-  async getUser(@Param('id') id: string) {
-    // Write raw SQL with native parameterization!
-    const users = await sql`SELECT * FROM users WHERE id = ${id}`
-    return users[0]
-  }
-}
-```
-
-### Customizing Connection Options
-
-If you need to pass custom options to the Postgres connection pool (like SSL config or max pool sizes), call `configurePostgres(options)` before you run your first query (e.g. inside your `server.ts` `onStart` hook).
-
-```typescript filename="src/http/server.ts"
-import { exis } from 'exisjs'
-import { configurePostgres } from 'exisjs/postgres'
-
-export default exis({
-  async onStart() {
-    // Initialize with custom connection limits
-    configurePostgres({
-      max: 20,
-      idle_timeout: 30000,
-      ssl: process.env.NODE_ENV === 'production' ? 'require' : false
-    })
-  }
-})
-```

package/dist/docs/integrations/posthog.mdx

@@ -1,122 +0,0 @@
----
-nextUrl: "/docs/integrations/observability"
-nextTitle: "Observability"
----
-
-# PostHog Integration
-
-ExisJS provides an integration for PostHog, an open-source product analytics platform. 
-
-This enables you to capture server-side events, identify users, and evaluate feature flags directly inside your route handlers.
-
----
-
-## Environment Variables
-
-The PostHog plugin securely reads your project API key directly from your `.env` file. 
-
-Before using the plugin, ensure you have your API key set. You can optionally define a custom host if you are self-hosting PostHog (it defaults to `https://app.posthog.com`).
-
-```bash filename=".env"
-POSTHOG_API_KEY="phc_123456789"
-POSTHOG_HOST="https://eu.posthog.com" # Optional (For EU Cloud or Self-Hosted)
-```
-
----
-
-## Installation
-
-ExisJS wraps the official `posthog-node` SDK as an optional peer dependency.
-
-```bash
-npm install posthog-node
-```
-
----
-
-## Usage
-
-Simply import the `posthog` proxy from `exisjs/posthog`. ExisJS will boot the client behind the scenes the first time you track an event.
-
-#### Functional Paradigm
-
-```typescript filename="src/http/auth/route.ts"
-import { controller, route } from 'exisjs/router'
-import { posthog } from 'exisjs/posthog'
-
-export default controller({
-  login: route.post('/login', {
-    async handle(req) {
-      const { email, userId } = req.body
-
-      // Your auth logic here...
-
-      // The posthog client lazy-loads here
-      posthog.identify({
-        distinctId: userId,
-        properties: { email }
-      })
-
-      posthog.capture({
-        distinctId: userId,
-        event: 'user_logged_in'
-      })
-
-      return { success: true }
-    }
-  })
-})
-```
-
-#### Class-Based (OOP) Paradigm
-
-```typescript filename="src/http/auth/route.ts"
-import { Controller, Post, Body } from 'exisjs/decorators'
-import { posthog } from 'exisjs/posthog'
-
-@Controller('/auth')
-export default class AuthController {
-  
-  @Post('/login')
-  async login(@Body() body: any) {
-    const { email, userId } = body
-
-    // Your auth logic here...
-
-    // The posthog client lazy-loads here
-    posthog.identify({
-      distinctId: userId,
-      properties: { email }
-    })
-
-    posthog.capture({
-      distinctId: userId,
-      event: 'user_logged_in'
-    })
-
-    return { success: true }
-  }
-}
-```
-
----
-
-## Graceful Shutdown (Flushing)
-
-PostHog queues events in memory and sends them in batches for high performance. 
-
-When your application shuts down, you must ensure all pending events are successfully flushed to PostHog before the Node.js process exits so you don't lose analytics data.
-
-Simply await `posthog.shutdown()` in your `onStop` hook.
-
-```typescript filename="src/http/server.ts"
-import { exis } from 'exisjs'
-import { posthog } from 'exisjs/posthog'
-
-export default exis({
-  async onStop() {
-    // Ensures all pending events are flushed before the server exits
-    await posthog.shutdown()
-  }
-})
-```

package/dist/docs/integrations/redis.mdx

@@ -1,141 +0,0 @@
----
-nextUrl: "/docs/integrations/jwt"
-nextTitle: "JWT Auth"
----
-
-# Redis Integration
-
-ExisJS provides an integration for Redis via the `ioredis` package. You do **NOT** need to register Redis in your `server.ts` file. The connection pool is lazily initialized when you execute your first command.
-
----
-
-## Environment Variables
-
-The Redis plugin securely reads your connection string from your `.env` file. It automatically looks for either `REDIS_URL` or `KV_URL` (compatible with Vercel KV).
-
-Before using the plugin, ensure you have your Redis URI set:
-
-```bash filename=".env"
-# Your Redis connection string
-REDIS_URL="redis://default:password@localhost:6379"
-```
-
----
-
-## Installation
-
-ExisJS wraps the `ioredis` client.
-
-```bash
-npm install ioredis
-```
-
----
-
-## Usage
-
-Import the `redis` proxy from `exisjs/redis`. ExisJS will connect to your Redis instance behind the scenes.
-
-#### Functional Paradigm
-
-```typescript filename="src/http/cache/route.ts"
-import { controller, route } from 'exisjs/router'
-import { redis } from 'exisjs/redis'
-
-export default controller({
-  getCache: route.get('/:key', {
-    async handle(req) {
-      const value = await redis.get(req.params.key)
-      return { key: req.params.key, value }
-    }
-  }),
-
-  setCache: route.post('/:key', {
-    async handle(req) {
-      // Set key with an expiration of 60 seconds
-      await redis.set(req.params.key, JSON.stringify(req.body), 'EX', 60)
-      return { success: true }
-    }
-  })
-})
-```
-
-#### Class-Based (OOP) Paradigm
-
-```typescript filename="src/http/cache/route.ts"
-import { Controller, Get, Post, Param, Body } from 'exisjs/decorators'
-import { redis } from 'exisjs/redis'
-
-@Controller('/cache')
-export default class CacheController {
-  @Get('/:key')
-  async getCache(@Param('key') key: string) {
-    const value = await redis.get(key)
-    return { key, value }
-  }
-
-  @Post('/:key')
-  async setCache(@Param('key') key: string, @Body() body: any) {
-    // Set key with an expiration of 60 seconds
-    await redis.set(key, JSON.stringify(body), 'EX', 60)
-    return { success: true }
-  }
-}
-```
-
----
-
-## Redis as a Job Queue
-
-ExisJS's native distributed Job Queue can run on top of Redis. This is a common approach for production environments to process background jobs across multiple server instances.
-
-To enable the Redis queue driver, configure it either in `server.ts` or centrally in your `exis.config.ts` file:
-
-### `exis.config.ts`
-
-```typescript filename="exis.config.ts"
-import { defineConfig } from 'exisjs/config'
-
-export default defineConfig({
-  queue: {
-    driver: 'redis',
-    // ExisJS will automatically use process.env.REDIS_URL.
-    // If you need a custom URL just for the queue, you can specify it:
-    // redisUrl: process.env.CUSTOM_QUEUE_REDIS_URL
-  }
-})
-```
-
-### `src/http/server.ts`
-
-```typescript filename="src/http/server.ts"
-import { exis } from 'exisjs'
-
-export default exis({
-  queue: {
-    driver: 'redis',
-  }
-})
-```
-
----
-
-## Customizing Connection Options
-
-If you need to pass custom options to the Redis connection pool (like custom retry strategies, lazy connections, or TLS settings), call `configureRedis(options)` inside your `server.ts` `onStart` hook.
-
-```typescript filename="src/http/server.ts"
-import { exis } from 'exisjs'
-import { configureRedis } from 'exisjs/redis'
-
-export default exis({
-  async onStart() {
-    // Initialize with custom connection options
-    configureRedis({
-      maxRetriesPerRequest: 3,
-      connectTimeout: 10000,
-      lazyConnect: true
-    })
-  }
-})
-```