exisjs 0.6.1 → 0.7.1

package/dist/docs/content/oauth.mdx

@@ -1,179 +0,0 @@
----
-title: "OAuth Provider System"
-description: "ExisJS includes a fully-featured, built-in OAuth 2.0 and OpenID Connect system with native providers for Google, GitHub, Microsoft, Discord, and Facebook."
----
-
-# OAuth Provider System
-
-Implementing secure, compliant OAuth flows is notoriously difficult. ExisJS solves this by providing a unified, built-in OAuth system. It handles PKCE (Proof Key for Code Exchange), state generation for CSRF protection, and normalizes user profiles automatically.
-
-<Info title="Functional vs OOP">
-ExisJS natively supports both a **Functional Paradigm** and a **Class-Based OOP Paradigm** (for dependency injection and decorators). The OAuth middleware helpers can easily be used in either paradigm.
-</Info>
-
-## Configuration
-
-Configure your providers globally using the `OAuthManager`. You typically do this once in your application entry point (`server.ts`).
-
-```typescript filename="src/http/server.ts"
-import { exis } from 'exisjs'
-import { OAuth } from 'exisjs/auth'
-
-export default exis({
-  async onStart(app) {
-    OAuth.configure({
-      google: {
-        clientId: process.env.GOOGLE_CLIENT_ID!,
-        clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
-        redirectUri: 'http://localhost:3000/auth/google/callback',
-      },
-      github: {
-        clientId: process.env.GITHUB_CLIENT_ID!,
-        clientSecret: process.env.GITHUB_CLIENT_SECRET!,
-        redirectUri: 'http://localhost:3000/auth/github/callback',
-      },
-    })
-  }
-})
-```
-
-## Routing & Middleware
-
-ExisJS provides Express-style middleware (`oauthRedirect` and `oauthCallback`) that makes securing your routes trivial. It securely stores state/PKCE verifiers in sessions or signed cookies.
-
-Here is how you handle the login flow using both paradigms.
-
-#### Functional Paradigm
-In functional routes, you wrap your handlers using standard middleware chaining techniques.
-
-```typescript filename="src/http/auth/route.ts"
-import { controller, route } from 'exisjs/router'
-import { oauthRedirect, oauthCallback } from 'exisjs/auth'
-
-export default controller({
-  // 1. Redirect user to Google
-  login: route.get('/google', {
-    middlewares: [oauthRedirect('google')],
-    handle() {
-      // Never reached, the middleware handles the redirect
-    }
-  }),
-
-  // 2. Handle the callback from Google
-  callback: route.get('/google/callback', {
-    middlewares: [
-      oauthCallback('google', {
-        onSuccess: async (req, res, profile, tokens) => {
-          // profile contains the normalized user data
-          console.log(profile.email, profile.name)
-          
-          // Log the user into your system
-          req.session.userId = profile.id
-          res.redirect('/dashboard')
-        },
-        onError: async (req, res, error) => {
-          res.redirect(`/login?error=${encodeURIComponent(error.message)}`)
-        }
-      })
-    ],
-    handle() {
-      // Handled by the onSuccess callback above
-    }
-  })
-})
-```
-
-#### Class-Based (OOP) Paradigm
-In OOP routes, you can use the `@Use()` decorator to apply the exact same middleware helpers.
-
-```typescript filename="src/http/auth/route.ts"
-import { Controller, Get, Use } from 'exisjs/decorators'
-import { oauthRedirect, oauthCallback } from 'exisjs/auth'
-
-@Controller()
-export default class AuthController {
-  
-  // 1. Redirect user to Google
-  @Get('/google')
-  @Use(oauthRedirect('google'))
-  login() {
-    // Never reached, the middleware handles the redirect
-  }
-
-  // 2. Handle the callback from Google
-  @Get('/google/callback')
-  @Use(
-    oauthCallback('google', {
-      onSuccess: async (req, res, profile, tokens) => {
-        // Log the user into your system
-        req.session.userId = profile.id
-        res.redirect('/dashboard')
-      },
-      onError: async (req, res, error) => {
-        res.redirect(`/login?error=${encodeURIComponent(error.message)}`)
-      }
-    })
-  )
-  callback() {
-    // Handled by the onSuccess callback above
-  }
-}
-```
-
-## Route Guards
-
-Once authenticated, use the built-in `requireAuth` middleware to protect your endpoints.
-
-#### Functional Paradigm
-```typescript filename="src/http/dashboard/route.ts"
-import { controller, route } from 'exisjs/router'
-import { requireAuth } from 'exisjs/auth'
-
-export default controller({
-  view: route.get('/', {
-    middlewares: [requireAuth({ redirectTo: '/login' })],
-    handle({ req }) {
-      return { message: 'Welcome to the secure dashboard!' }
-    }
-  })
-})
-```
-
-#### Class-Based (OOP) Paradigm
-```typescript filename="src/http/dashboard/route.ts"
-import { Controller, Get, Use } from 'exisjs/decorators'
-import { requireAuth } from 'exisjs/auth'
-
-@Controller()
-@Use(requireAuth({ redirectTo: '/login' })) // Protects the whole controller!
-export default class DashboardController {
-  @Get('/')
-  view() {
-    return { message: 'Welcome to the secure dashboard!' }
-  }
-}
-```
-
-## Creating Custom Providers
-
-If you need to connect to an internal identity provider or a service not included by default, use the generic custom provider adapter anywhere in your `server.ts` configuration:
-
-```typescript
-OAuth.custom({
-  name: 'keycloak',
-  authUrl: 'https://keycloak.example.com/auth',
-  tokenUrl: 'https://keycloak.example.com/token',
-  userInfoUrl: 'https://keycloak.example.com/userinfo',
-  clientId: process.env.KC_CLIENT_ID!,
-  clientSecret: process.env.KC_CLIENT_SECRET!,
-  redirectUri: 'http://localhost:3000/auth/keycloak/callback',
-  scopes: ['openid', 'profile', 'email'],
-  
-  // Optionally map the raw response to standard profile fields
-  mapProfile: (raw) => ({
-    id: raw.sub,
-    email: raw.email,
-    name: raw.preferred_username,
-  }),
-})
-```

package/dist/docs/content/queues.mdx

@@ -1,177 +0,0 @@
----
-nextUrl: "/docs/cron"
-nextTitle: "Cron Jobs"
----
-
-# Job Queues
-
-ExisJS provides a built-in Job Queue system designed to handle background processing, delayed tasks, and high-concurrency workloads.
-
-Key features include:
-- **Native Worker Threads**: File-based jobs are processed in isolated Node.js Worker Threads (`ThreadPool`) so heavy tasks do not block the main HTTP event loop.
-- **Type-Safe Payloads**: Built-in schema validation for queue payloads.
-- **Driver Agnostic**: Swap between `memory` (for dev) and `redis` (for production) without changing business logic.
-
----
-
-## 1. Configuration
-
-You can configure the Queue engine globally in your main `exis.config.ts` or directly in the `exis({ ... })` initializer.
-
-```typescript filename="exis.config.ts"
-export default {
-  queue: {
-    driver: process.env.NODE_ENV === 'production' ? 'redis' : 'memory',
-    redisUrl: process.env.REDIS_URL,
-    concurrency: 5,
-    maxQueue: 10000,
-    prefix: 'myapp:jobs'
-  }
-}
-```
-
-### Configuration Properties
-
-Here are all the properties you can pass to the `queue` configuration object:
-
-- **`driver`**: (`'redis' | 'memory'`) The backend storage engine for the queue. Defaults to `'memory'`.
-- **`redisUrl`**: (`string`) The connection string for your Redis instance if using the redis driver.
-- **`redis`**: (`Redis`) An already instantiated `ioredis` client instance.
-- **`concurrency`** (or **`maxConcurrent`**): (`number`) The maximum number of jobs the worker will process concurrently in the thread pool. Defaults to `1`.
-- **`maxQueue`**: (`number`) Maximum number of pending jobs allowed in the queue. If this limit is hit, `enqueue()` will throw a Backpressure error to protect the system.
-- **`prefix`**: (`string`) A namespace prefix for all queue keys in the backend store (e.g., in Redis). Defaults to `'exis:queue'`.
-- **`enableWorkers`**: (`boolean`) Explicitly enable or disable the background worker on this specific Node process (useful for splitting HTTP servers and Worker servers).
-
----
-
-## 2. Defining Jobs (Two Approaches)
-
-ExisJS provides two distinctly different ways to define and process background jobs, depending on whether the task is CPU-intensive or just a quick asynchronous action.
-
-### Approach 1: Auto-Mounted File-Based Jobs (Multi-Threaded)
-If you place a job definition inside the `src/jobs/` directory, ExisJS automatically mounts it using **File-Based Routing**.
-
-ExisJS will run these files off the main thread in a dedicated V8 isolate (`ThreadPool`). You do not need to write `worker_threads` boilerplate. Define the job, and ExisJS prevents the HTTP server from being blocked by heavy CPU tasks (like image processing or large calculations).
-
-```typescript filename="src/jobs/process-image.ts"
-import { defineJob } from 'exisjs/queue'
-import { tex } from 'exisjs/validator'
-
-export default defineJob({
-  name: 'process-image',
-  
-  schema: tex.object({
-    imageId: tex.string(),
-    resize: tex.boolean()
-  }),
-  
-  // ExisJS automatically runs this handler in a separate Worker Thread!
-  async handler({ data }) {
-    console.log(`[Worker Thread] Processing image ${data.imageId}...`)
-    const result = heavyImageProcessing(data);
-    return result;
-  }
-})
-```
-
-### Approach 2: Inline Handlers (Main Thread)
-If you have an IO-bound task (like sending an email or calling an external API) and you do not want to create a new file, you can use the global `queue()` helper. 
-
-Jobs defined this way run functionally in the **main thread** (alongside your HTTP server).
-
-```typescript filename="src/http/server.ts"
-import { queue } from 'exisjs/queue'
-
-// Define a job inline! Runs in the main event loop.
-queue<{ email: string }>('send-welcome-email', async ({ data }) => {
-  console.log(`Sending email to ${data.email}...`)
-}, { 
-  defaultOptions: { attempts: 3 }
-})
-```
-
----
-
-## 3. Enqueuing Jobs
-
-Regardless of which approach you used to define the job, you dispatch them the exact same way using the global `enqueue` helper.
-
-#### Functional Paradigm
-
-```typescript filename="src/http/users/route.ts"
-import { controller, route } from 'exisjs/router'
-import { enqueue } from 'exisjs/queue'
-
-export default controller({
-  register: route.post('/register', {
-    async handle({ req, res }) {
-      const user = await db.users.create(req.body)
-      
-      // Enqueue the job
-      await enqueue('send-welcome-email', {
-        email: user.email
-      }, {
-        // You can override job options at dispatch time
-        delay: 5000 // Wait 5 seconds before processing
-      })
-      
-      res.json({ success: true, user })
-    }
-  })
-})
-```
-
-#### Class-Based (OOP) Paradigm
-
-```typescript filename="src/http/users/route.ts"
-import { Controller, Post, Body } from 'exisjs/decorators'
-import { enqueue } from 'exisjs/queue'
-
-@Controller()
-export default class UsersController {
-  @Post('/register')
-  async register(@Body() body: any) {
-    const user = await db.users.create(body)
-    
-    // Enqueue the job
-    await enqueue('send-welcome-email', {
-      email: user.email
-    }, {
-      // You can override job options at dispatch time
-      delay: 5000 // Wait 5 seconds before processing
-    })
-    
-    return { success: true, user }
-  }
-}
-```
-
-## Extended Options
-
-When enqueuing a job, or setting `defaultOptions` in your job definitions, you can configure:
-
-- **`attempts`**: How many times to retry a failed job.
-- **`delay`**: How many milliseconds to wait before the job is processing.
-- **`backoff`**: If a job fails, how to wait before retrying (e.g., `{ type: 'exponential', delay: 1000 }` waits 1s, 2s, 4s, etc.).
-- **`visibilityTimeout`**: How long a job stays in the "processing" state before it is considered stuck and gets re-queued by the Sweeper (default: `30000`ms).
-
----
-
-## 4. Queue Drivers & Internals
-
-ExisJS comes with two native queue drivers. Both drivers implement atomic operations and strict visibility timeouts to ensure jobs are not processed twice and are safely retried if a worker crashes.
-
-### The Memory Driver (`memory`)
-The in-memory driver is designed for development, testing, or simple single-node deployments. 
-- It uses ES6 `Map` and `Array.sort` to keep jobs sorted by their execution score (`Date.now() + delay`).
-- Does not require any external infrastructure.
-
-### The Redis Driver (`redis`)
-Designed for horizontal scale, the Redis driver powers distributed clusters.
-- **Atomic Operations**: Uses Lua scripts (`EVAL`) to atomically pop jobs from a pending `ZSET` (sorted set) into a processing state.
-- **integrated Core**: It dynamically requires `ioredis` only if used, keeping the core framework lightweight.
-- **Cluster Safe**: All jobs for a specific topic map to consistent Redis hash slots.
-
-### The Sweeper
-ExisJS runs a background **Sweeper** every 10 seconds.
-If a worker crashes mid-job, or a job takes longer than its `visibilityTimeout`, the Sweeper detects the stalled job in the processing list and re-queues it back into the pending list so another worker can pick it up.

package/dist/docs/content/rpc.mdx

@@ -1,146 +0,0 @@
----
-nextUrl: "/docs/decorators"
-nextTitle: "Custom Decorators"
----
-
-# RPC Client (End-to-End Type Safety)
-
-ExisJS comes with a native RPC (Remote Procedure Call) client designed to give you **end-to-end type safety** without needing code generation (like OpenAPI/Swagger) or GraphQL. 
-
-Because ExisJS infers the types of your backend routes natively, you can share those types directly with your frontend (React, Vue, React Native) and get autocomplete, payload validation, and response typing.
-
----
-
-## 1. Exporting the AppRouter Type
-
-To use the strictly typed client, you simply need to export the inferred type of your ExisJS application from your main backend entry point.
-
-```typescript filename="backend/src/http/server.ts"
-import { exis } from 'exisjs'
-
-const app = exis({
-  async onStart(app) {
-    // Backend boot logic...
-  }
-})
-
-// Export the inferred router type for the frontend
-export type AppRouter = typeof app
-
-export default app
-```
-
-*(Note: Because this is just a TypeScript `type` export, no backend code gets compiled into your frontend bundle.)*
-
----
-
-## 2. Initializing the Client
-
-On your frontend (React, Vue, Svelte, etc.), install the lightweight client package:
-
-```bash
-npm install @exisjs/client
-```
-
-Then, initialize the client using the `AppRouter` type from your backend:
-
-```typescript filename="frontend/src/api.ts"
-import { createClient } from '@exisjs/client'
-import type { AppRouter } from '../../backend/src/http/server'
-
-export const client = createClient<AppRouter>({
-  baseUrl: 'http://localhost:3000',
-  
-  // Optionally provide default headers (like Auth tokens)
-  headers: () => ({
-    'Authorization': `Bearer ${localStorage.getItem('token')}`
-  }),
-
-  // Global error handler
-  onError: (err) => {
-    if (err.status === 401) {
-      window.location.href = '/login'
-    }
-  }
-})
-```
-
----
-
-## 3. Using the Client
-
-Because ExisJS uses an ES6 `Proxy` under the hood, the client dynamically maps your chained object calls into HTTP requests. It mirrors your backend's folder structure.
-
-If you have a backend route at `src/http/api/users/route.ts` with a `get` handler:
-
-```typescript filename="frontend/src/components/UserProfile.tsx"
-import { client } from '../api'
-
-async function fetchUser() {
-  // 1. Autocomplete for .api.users.get
-  // 2. Strong typing for the payload (e.g. { id: string })
-  // 3. The `user` variable is strictly typed to whatever the backend returns
-  const user = await client.api.users.get({
-    id: "123"
-  })
-  
-  console.log(user.name) 
-}
-```
-
-### Passing Query Parameters
-
-If you need to pass HTTP query parameters (like `?sort=desc`), you can use the `options` argument (the second parameter):
-
-```typescript filename="frontend/src/components/UserList.tsx"
-const users = await client.api.users.get(
-  // The first argument is the JSON payload (Body/Params)
-  {}, 
-  // The second argument configures the Request Options
-  { 
-    query: { sort: 'desc', limit: 10 },
-    headers: { 'X-Custom-Override': 'true' }
-  }
-)
-```
-
----
-
-## 4. Advanced Configuration
-
-The `createClient` function accepts configuration options to intercept requests and responses globally.
-
-```typescript
-export interface ClientConfig {
-  // The base URL of your ExisJS backend
-  baseUrl: string
-  
-  // Static headers, or a dynamic function evaluated per-request
-  headers?: Record<string, string> | (() => Record<string, string>)
-  
-  // Provide a custom fetch implementation (useful for testing or Polyfills)
-  fetch?: typeof fetch
-  
-  // A global hook that runs BEFORE the request is dispatched
-  onRequest?: (req: RequestInit, url: string) => void | Promise<void>
-  
-  // A global hook that runs AFTER the request successfully completes
-  onResponse?: (res: Response, url: string) => void | Promise<void>
-  
-  // A global hook that catches any failed requests
-  onError?: (err: Error) => void | Promise<void>
-}
-```
-
-### ExisClientError
-
-If an HTTP request fails (e.g., the backend returns a `400 Bad Request` or `500 Internal Server Error`), the client throws an `ExisClientError`. This error attaches the status code and parsed JSON response.
-
-```typescript
-try {
-  await client.api.users.post({ email: "invalid-email" })
-} catch (err) {
-  console.log(err.status) // 400
-  console.log(err.data) // { success: false, error: "Validation Failed..." }
-}
-```

package/dist/docs/content/sse.mdx

@@ -1,159 +0,0 @@
----
-nextUrl: "/docs/websockets"
-nextTitle: "WebSockets"
----
-
-# Server-Sent Events (SSE)
-
-Server-Sent Events (SSE) is a server push technology enabling a client to receive automatic updates from a server via an HTTP connection. Unlike WebSockets, SSE is unidirectional (server-to-client) and works over standard HTTP without requiring complex handshake protocols or specialized load balancer configurations.
-
-SSE is the industry standard for Large Language Model (LLM) streaming (e.g., OpenAI, Anthropic) and real-time dashboard updates. ExisJS provides native SSE support.
-
----
-
-## 1. Creating an SSE Stream
-
-When you declare a route as an SSE endpoint using `route.sse()` or `@Sse()`, ExisJS automatically configures the correct HTTP headers (`Content-Type: text/event-stream`, `Cache-Control: no-cache`, `Connection: keep-alive`) and provides an `ExisSSE` stream object.
-
-### Functional Paradigm
-
-```typescript filename="src/http/chat/route.ts"
-import { controller, route } from 'exisjs/router'
-import Groq from 'groq-sdk'
-
-export default controller({
-  chat: route.sse('/api/chat', {
-    async handle({ stream: sse, req }) {
-      const groq = new Groq({ apiKey: process.env.GROQ_API_KEY })
-      const message = req.query.message as string
-      
-      if (!message) {
-        sse.send({ error: 'Message is required' }, 'error')
-        sse.close()
-        return
-      }
-
-      try {
-        const aiStream = await groq.chat.completions.create({
-          messages: [{ role: 'user', content: message }],
-          model: 'llama-3.1-8b-instant',
-          stream: true,
-        })
-
-        // Iterate over the async generator provided by the AI SDK
-        for await (const chunk of aiStream) {
-          // Prevent writing to a closed socket if the client disconnects early
-          if (!sse.connected) break
-          
-          const content = chunk.choices[0]?.delta?.content || ''
-          if (content) {
-            sse.send({ text: content }, 'chunk')
-          }
-        }
-        
-        sse.send({ text: '' }, 'done')
-      } finally {
-        // Ensure the connection is always closed when processing completes
-        sse.close()
-      }
-    }
-  })
-})
-```
-
-### Class-Based (OOP) Paradigm
-
-```typescript filename="src/http/chat/route.ts"
-import { Controller, Sse, Stream, Req } from 'exisjs/decorators'
-import type { ExisSSE } from 'exisjs/router'
-import Groq from 'groq-sdk'
-
-@Controller()
-export default class AIChatController {
-  @Sse('/api/chat')
-  async handleChat(@Stream() sse: ExisSSE, @Req() req: any) {
-    const groq = new Groq({ apiKey: process.env.GROQ_API_KEY })
-    const message = req.query.message as string
-    
-    if (!message) {
-      sse.send({ error: 'Message is required' }, 'error')
-      sse.close()
-      return
-    }
-
-    try {
-      const aiStream = await groq.chat.completions.create({
-        messages: [{ role: 'user', content: message }],
-        model: 'llama-3.1-8b-instant',
-        stream: true,
-      })
-
-      for await (const chunk of aiStream) {
-        if (!sse.connected) break
-        
-        const content = chunk.choices[0]?.delta?.content || ''
-        if (content) {
-          sse.send({ text: content }, 'chunk')
-        }
-      }
-      sse.send({ text: '' }, 'done')
-    } finally {
-      sse.close()
-    }
-  }
-}
-```
-
----
-
-## 2. The `ExisSSE` API
-
-The injected `sse` object gives you full control over the streaming connection:
-
-- **`sse.send(data: string | Record<string, any>, eventName?: string)`**: Serializes the data (if it is an object) to JSON and sends it down the wire. You can optionally tag it with a specific `eventName`.
-- **`sse.connected`**: A boolean that evaluates to `true` while the connection is alive. You should always check this inside long-running `for await` or `while` loops to prevent throwing "Socket Closed" errors when the client disconnects unexpectedly.
-- **`sse.close()`**: Safely closes the stream and terminates the HTTP connection.
-
-```typescript
-// Sending a plain text message
-sse.send("Processing your request...")
-
-// Sending a JSON object tagged with a specific event type (e.g., 'metrics')
-sse.send({ cpu_usage: 95, mem_usage: 60 }, 'metrics')
-```
-
----
-
-## 3. Client-Side Consumption
-
-To consume the SSE stream from the frontend (e.g., in React, Vue, or Vanilla JS), use the native browser `EventSource` API.
-
-```javascript filename="frontend/app.js"
-// Connect to the ExisJS SSE endpoint
-const eventSource = new EventSource('/api/chat?message=Hello')
-
-// Listen for the default 'message' event (when no eventName is specified in sse.send)
-eventSource.onmessage = (event) => {
-  const data = JSON.parse(event.data)
-  console.log("Standard message:", data)
-}
-
-// Listen for a custom event type, such as 'chunk'
-eventSource.addEventListener('chunk', (event) => {
-  const data = JSON.parse(event.data)
-  // Append the streamed text to the DOM
-  document.getElementById('output').textContent += data.text
-})
-
-// Listen for the 'done' event to close the connection from the client side
-eventSource.addEventListener('done', () => {
-  console.log("Stream finished.")
-  eventSource.close()
-})
-
-// Handle connection errors
-eventSource.onerror = (error) => {
-  console.error("SSE Connection Error:", error)
-  eventSource.close()
-}
-```