exisjs 0.6.0 → 0.7.0

package/dist/docs/content/websockets.mdx

@@ -1,289 +0,0 @@
----
-nextUrl: "/docs/queues"
-nextTitle: "Job Queues"
----
-
-# WebSockets
-
-ExisJS provides a built-in WebSocket engine. It includes an integrated Pub/Sub system (rooms), automatic JSON serialization, Socket.io-style event emitters, and built-in presence tracking.
-
-You can handle WebSockets using either the **Functional API** or the **Class-Based (OOP) API**.
-
----
-
-## 1. Functional API
-
-For smaller applications or functional paradigms, you can define WebSocket routes directly on a router using `route.ws()`.
-
-```typescript filename="src/http/route.ts"
-import { controller, route } from 'exisjs/router'
-
-export default controller({
-  chatSocket: route.ws('/ws', {
-    handle({ socket }) {
-      console.log(`New connection: ${socket.id}`)
-
-      // Listen for incoming messages
-      socket.on('message', (rawData) => {
-        const data = JSON.parse(rawData.toString())
-
-        if (data.action === 'join') {
-          // Join a room (Pub/Sub)
-          socket.join(data.room)
-
-          // Emit a named event back to the socket
-          socket.emit('chat', {
-            type: 'system',
-            message: `You joined #${data.room}`,
-          })
-        } else if (data.action === 'message') {
-          // Publish a message to everyone in the room (excluding sender by default)
-          socket.publish(data.room, {
-            event: 'chat',
-            data: { message: data.message },
-          })
-        }
-      })
-
-      socket.on('close', () => {
-        console.log(`Disconnected: ${socket.id}`)
-        socket.leaveAll()
-      })
-    },
-  }),
-})
-```
-
----
-
-## 2. Class-Based (OOP) API
-
-For larger applications, ExisJS provides the `@Ws()` decorator to map WebSocket endpoints inside your Controllers.
-
-```typescript filename="src/http/chat/route.ts"
-import { Controller, Ws, Socket } from 'exisjs/decorators'
-import { ExisWebSocket } from 'exisjs/router'
-
-@Controller()
-export default class ChatController {
-  @Ws('/ws')
-  handleSocket(@Socket() socket: ExisWebSocket) {
-    // Enable auto-presence for this server
-    socket.server.enablePresence()
-
-    // Listen for custom JSON events
-    socket.onEvent('join', (data) => {
-      // Attach custom state to the socket
-      socket.data.userId = data.userId
-
-      // Unsubscribe from previous rooms
-      socket.leaveAll()
-      socket.join(data.room)
-
-      // Fetch the roster of active users in the room
-      const roster = socket.server.getRoomRoster(data.room)
-      socket.emit('roster', { roster })
-    })
-
-    socket.onEvent('message', (data) => {
-      // Socket.io style broadcasting!
-      socket.to(data.room).emit('chat', {
-        userId: socket.data.userId,
-        message: data.message,
-      })
-    })
-  }
-}
-```
-
----
-
-## The `ExisWebSocket` API
-
-ExisJS wraps the native WebSocket with an `ExisWebSocket` instance that provides Socket.io-like ergonomics without the heavy client-side dependencies.
-
-### Emitting & Sending
-
-- **`socket.send(data)`**: Sends raw data. Objects are automatically stringified.
-- **`socket.emit(event, data)`**: Emits a named JSON event (`{ event: "name", data: ... }`).
-- **`socket.emitWithAck(event, data, timeoutMs?)`**: Emits an event and returns a Promise that resolves when the client sends back an acknowledgment with the matching `ackId`.
-- **`socket.volatile.emit(event, data)`**: Emits an event that will be safely dropped if the connection is experiencing backpressure (network saturation).
-
-#### Example: Emitting Events
-
-**Functional API:**
-
-```typescript
-route.ws('/ws', {
-  handle({ socket }) {
-    // Send a standard named event
-    socket.emit('ping', { timestamp: Date.now() })
-
-    // Send a volatile event that drops if network is busy
-    socket.volatile.emit('stock-tick', { price: 100 })
-  },
-})
-```
-
-**Class-Based (OOP) API:**
-
-```typescript
-@Ws('/ws')
-handleSocket(@Socket() socket: ExisWebSocket) {
-  // Await an acknowledgment from the client
-  socket.onEvent('request-data', async () => {
-    try {
-      const response = await socket.emitWithAck('data-ready', { id: 1 }, 5000)
-      console.log('Client acknowledged:', response)
-    } catch (err) {
-      console.error('Client failed to ack in 5s')
-    }
-  })
-}
-```
-
-### Rooms (Pub/Sub)
-
-ExisJS has a built-in Pub/Sub engine that allows sockets to subscribe to topics (rooms).
-
-- **`socket.join(room)`** / **`socket.subscribe(room)`**: Subscribes the socket to a room.
-- **`socket.leave(room)`** / **`socket.unsubscribe(room)`**: Unsubscribes from a room.
-- **`socket.leaveAll()`** / **`socket.unsubscribeAll()`**: Unsubscribes from all joined rooms.
-- **`socket.publish(room, data, excludeSelf?)`**: Publishes data to all sockets in a room. By default, it excludes the sender.
-
-#### Example: Managing Rooms
-
-**Functional API:**
-
-```typescript
-route.ws('/chat', {
-  handle({ socket }) {
-    socket.onEvent('join-room', (data) => {
-      // Leave old rooms before joining a new one
-      socket.leaveAll()
-      socket.join(data.roomId)
-
-      socket.publish(data.roomId, {
-        event: 'system',
-        data: 'A new user joined',
-      })
-    })
-  },
-})
-```
-
-**Class-Based (OOP) API:**
-
-```typescript
-@Ws('/chat')
-handleSocket(@Socket() socket: ExisWebSocket) {
-  socket.onEvent('leave-room', (data) => {
-    socket.leave(data.roomId)
-  })
-}
-```
-
-### Broadcasting (Socket.io Style)
-
-If you prefer Socket.io's chainable broadcasting syntax, ExisJS fully supports it:
-
-- **`socket.to(room).emit(event, data)`**: Emits an event to everyone in the specified room _except_ the sender.
-- **`socket.broadcast.emit(event, data)`**: Emits to every connected socket on the server _except_ the sender.
-- **`socket.broadcast.to(room).emit(event, data)`**: Same as `socket.to()`.
-
-#### Example: Broadcasting
-
-**Functional API:**
-
-```typescript
-route.ws('/game', {
-  handle({ socket }) {
-    socket.onEvent('player-move', (position) => {
-      // Tell everyone ELSE in 'game-1' that this player moved
-      socket.to('game-1').emit('player-moved', { id: socket.id, position })
-    })
-  },
-})
-```
-
-**Class-Based (OOP) API:**
-
-```typescript
-@Ws('/global')
-handleSocket(@Socket() socket: ExisWebSocket) {
-  socket.onEvent('global-alert', (alert) => {
-    // Broadcast to EVERYONE on the server except the sender
-    socket.broadcast.emit('alert', alert)
-  })
-}
-```
-
-### Listening for Events
-
-- **`socket.on('message', cb)`**: Listens for raw WebSocket messages.
-- **`socket.onEvent(eventName, cb)`**: Automatically parses incoming JSON and triggers the callback _only_ if the JSON payload matches `{ event: "eventName" }`.
-
-#### Example: Event Listeners
-
-**Functional API:**
-
-```typescript
-route.ws('/data', {
-  handle({ socket }) {
-    // Handle raw buffer/string messages manually
-    socket.on('message', (raw) => {
-      console.log('Raw data received:', raw.toString())
-    })
-  },
-})
-```
-
-**Class-Based (OOP) API:**
-
-```typescript
-@Ws('/api')
-handleSocket(@Socket() socket: ExisWebSocket) {
-  // Handle specific JSON events
-  socket.onEvent('auth', (credentials) => {
-    console.log('Auth attempt:', credentials.username)
-  })
-}
-```
-
-### State & Presence
-
-- **`socket.data`**: An empty object `Record<string, any>` where you can safely attach custom user data (like user IDs, roles, etc.) for the duration of the connection.
-- **`socket.server.enablePresence()`**: Turns on automatic presence tracking. When a socket joins or leaves a room, ExisJS will automatically broadcast `room:join` and `room:leave` events to the room.
-- **`socket.server.getRoomRoster(room)`**: Returns an array of all connected sockets currently in a specific room.
-
-#### Example: State & Roster Tracking
-
-**Functional API:**
-
-```typescript
-route.ws('/collaboration', {
-  handle({ socket }) {
-    socket.server.enablePresence()
-
-    socket.onEvent('identify', (user) => {
-      // Safely store state on the socket instance
-      socket.data.userId = user.id
-      socket.data.role = 'editor'
-    })
-  },
-})
-```
-
-**Class-Based (OOP) API:**
-
-```typescript
-@Ws('/collaboration')
-handleSocket(@Socket() socket: ExisWebSocket) {
-  socket.onEvent('get-users', (room) => {
-    // Fetch everyone currently in the room
-    const roster = socket.server.getRoomRoster(room)
-
-    socket.emit('users-list', roster.map(s => s.data.userId))
-  })
-}
-```

package/dist/docs/integrations/README.md

@@ -1,23 +0,0 @@
-# ExisJS Integrations Blueprint
-
-This directory contains the documentation for integrating third-party services and tools with ExisJS. This `README.md` acts as a **blueprint** to help you understand what each integration guide covers.
-
-## 🗄️ Databases & Storage
-*   **`mongo.mdx`**: Connecting to MongoDB using Mongoose, leveraging the DI container, and data modeling.
-*   **`postgres.mdx`**: Connecting to PostgreSQL databases (e.g., via Prisma or Drizzle ORM) in a type-safe manner.
-*   **`redis.mdx`**: Using Redis for high-speed caching, rate limiting, and powering ExisJS queues.
-*   **`s3.mdx`**: Integrating with AWS S3 (or compatible services like Cloudflare R2) for file uploads and object storage.
-
-## 🔐 Auth & Security
-*   **`jwt.mdx`**: Implementing JSON Web Token (JWT) authentication, signing, and protecting routes via middleware.
-
-## 🤖 Artificial Intelligence
-*   **`openai.mdx`**: Integrating the OpenAI SDK, streaming LLM responses using ExisJS SSE (Server-Sent Events), and managing API keys securely.
-
-## 📧 Communications
-*   **`resend.mdx`**: Sending transactional emails (like password resets or welcome emails) using the Resend API, ideally triggered via background Queues.
-
-## 📊 Analytics & Observability
-*   **`posthog.mdx`**: Capturing user events, feature flags, and product analytics using PostHog inside your ExisJS controllers.
-*   **`observability.mdx`**: Setting up advanced monitoring, tracing (OpenTelemetry), and logging infrastructure.
-*   **`swagger.mdx`**: Automatic OpenAPI/Swagger generation for your endpoints based on your validation schemas and route definitions.

package/dist/docs/integrations/jwt.mdx

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

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