exisjs 0.5.9 → 0.5.11

package/dist/docs/integrations/postgres.mdx

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

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

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

package/dist/docs/integrations/resend.mdx

@@ -0,0 +1,117 @@
+---
+nextUrl: "/docs/integrations/openai"
+nextTitle: "OpenAI"
+---
+
+# Resend (Email) Integration
+
+ExisJS provides an integration for Resend to send emails. 
+
+Just like all our other integrations, ExisJS treats the `resend` SDK as an optional dependency. You only install it if you need it, keeping your core application lightweight.
+
+---
+
+## Environment Variables
+
+The Resend 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"
+RESEND_API_KEY="re_123456789"
+```
+
+---
+
+## Installation
+
+ExisJS wraps the official `resend` Node.js SDK.
+
+```bash
+npm install resend
+```
+
+---
+
+## Usage
+
+Simply import the `resend` proxy from `exisjs/resend`. ExisJS will boot the client behind the scenes the first time you attempt to send an email.
+
+#### Functional Paradigm
+
+```typescript filename="src/http/emails/route.ts"
+import { controller, route } from 'exisjs/router'
+import { resend } from 'exisjs/resend'
+
+export default controller({
+  sendWelcomeEmail: route.post('/welcome', {
+    async handle(req) {
+      const { email, name } = req.body
+
+    // The resend client lazy-loads here
+      const { data, error } = await resend.emails.send({
+        from: 'Acme <onboarding@resend.dev>',
+        to: [email],
+        subject: 'Welcome to Acme!',
+        html: `<strong>Hello ${name}, welcome aboard!</strong>`
+      })
+
+      if (error) {
+        return { success: false, error }
+      }
+
+      return { success: true, data }
+    }
+  })
+})
+```
+
+#### Class-Based (OOP) Paradigm
+
+```typescript filename="src/http/emails/route.ts"
+import { Controller, Post, Body } from 'exisjs/decorators'
+import { resend } from 'exisjs/resend'
+
+@Controller('/emails')
+export default class EmailsController {
+  
+  @Post('/welcome')
+  async sendWelcomeEmail(@Body() body: any) {
+    // The resend client magically lazy-loads here!
+    const { data, error } = await resend.emails.send({
+      from: 'Acme <onboarding@resend.dev>',
+      to: [body.email],
+      subject: 'Welcome to Acme!',
+      html: `<strong>Hello ${body.name}, welcome aboard!</strong>`
+    })
+
+    if (error) {
+      return { success: false, error }
+    }
+
+    return { success: true, data }
+  }
+}
+```
+
+---
+
+## Customizing Connection Options
+
+If you need to pass custom options to the Resend Client, call `configureResend(options)` inside your `server.ts` `onStart` hook.
+
+```typescript filename="src/http/server.ts"
+import { exis } from 'exisjs'
+import { configureResend } from 'exisjs/resend'
+
+export default exis({
+  async onStart() {
+    // Inject custom fetch options or headers
+    configureResend({
+      headers: {
+        'X-Custom-Header': 'ExisJS'
+      }
+    })
+  }
+})
+```

package/dist/docs/integrations/s3.mdx

@@ -0,0 +1,122 @@
+---
+nextUrl: "/docs/integrations/resend"
+nextTitle: "Resend"
+---
+
+# AWS S3 Integration
+
+ExisJS provides an integration for AWS S3 via the official `@aws-sdk/client-s3` package. 
+
+You do **NOT** need to write boilerplate to initialize the AWS SDK. The S3 client is lazily initialized when you execute your first `PutObject` or `GetObject` command.
+
+---
+
+## Environment Variables
+
+The AWS S3 plugin securely reads your credentials directly from your `.env` file using the industry-standard AWS variable names.
+
+Before using the plugin, ensure you have your credentials set:
+
+```bash filename=".env"
+AWS_ACCESS_KEY_ID="your_access_key"
+AWS_SECRET_ACCESS_KEY="your_secret_key"
+AWS_REGION="us-east-1"
+```
+
+---
+
+## Installation
+
+ExisJS wraps the `@aws-sdk/client-s3` library.
+
+```bash
+npm install @aws-sdk/client-s3
+```
+
+---
+
+## Usage
+
+Simply import the `s3` proxy from `exisjs/s3` and use standard AWS SDK commands. ExisJS will boot the client behind the scenes.
+
+#### Functional Paradigm
+
+```typescript filename="src/http/uploads/route.ts"
+import { controller, route } from 'exisjs/router'
+import { s3 } from 'exisjs/s3'
+import { PutObjectCommand, GetObjectCommand } from '@aws-sdk/client-s3'
+
+export default controller({
+  // ExisJS parses multipart/form-data when you access req.files
+  uploadFile: route.post('/', {
+    async handle(req) {
+      // req.files is automatically populated natively by ExisJS
+      const file = req.files[0] 
+      
+      const command = new PutObjectCommand({
+        Bucket: 'my-exis-bucket',
+        Key: file.filename,
+        Body: file.data, // Buffer
+        ContentType: file.mimetype,
+      })
+
+    // The s3 client lazy-loads here
+      await s3.send(command)
+
+      return { success: true, url: `https://my-exis-bucket.s3.amazonaws.com/${file.filename}` }
+    }
+  })
+})
+```
+
+#### Class-Based (OOP) Paradigm
+
+```typescript filename="src/http/uploads/route.ts"
+import { Controller, Post, UploadedFile, type ExisFile } from 'exisjs/decorators'
+import { s3 } from 'exisjs/s3'
+import { PutObjectCommand } from '@aws-sdk/client-s3'
+
+@Controller('/uploads')
+export default class UploadsController {
+  
+  @Post('/')
+  async uploadFile(@UploadedFile('avatar') file: ExisFile) {
+    const command = new PutObjectCommand({
+      Bucket: 'my-exis-bucket',
+      Key: file.filename,
+      Body: file.data, // Buffer
+      ContentType: file.mimetype,
+    })
+
+    // The s3 client magically lazy-loads here!
+    await s3.send(command)
+
+    return { success: true, url: `https://my-exis-bucket.s3.amazonaws.com/${file.filename}` }
+  }
+}
+```
+
+---
+
+## Customizing Connection Options
+
+If you need to pass custom options to the S3 Client (like a custom Endpoint URL for Cloudflare R2 or DigitalOcean Spaces), call `configureS3(options)` inside your `server.ts` `onStart` hook.
+
+```typescript filename="src/http/server.ts"
+import { exis } from 'exisjs'
+import { configureS3 } from 'exisjs/s3'
+
+export default exis({
+  async onStart() {
+    // Compatible with S3 APIs like Cloudflare R2
+    configureS3({
+      endpoint: 'https://<ACCOUNT_ID>.r2.cloudflarestorage.com',
+      forcePathStyle: true
+    })
+  }
+})
+```
+
+<Hint>
+Because ExisJS uses the official AWS SDK under the hood, the S3 integration works with Cloudflare R2, DigitalOcean Spaces, MinIO, and any other S3-compatible storage provider.
+</Hint>