exisjs 0.5.10 → 0.5.11

package/dist/docs/content/oauth.mdx

@@ -0,0 +1,179 @@
+---
+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/providers.mdx

@@ -0,0 +1,147 @@
+---
+nextUrl: "/docs/gateways"
+nextTitle: "Gateways"
+---
+
+# Providers
+
+Providers are a fundamental concept in ExisJS. Many of the basic classes may be treated as a provider: services, repositories, factories, helpers, and so on.
+
+The main idea of a provider is that it can be injected as a dependency; this means objects can create various relationships with each other, and the function of "wiring up" instances of objects can largely be delegated to the ExisJS runtime system.
+
+## Services
+
+Let's start by creating a simple `UsersService`. This service will be responsible for data storage and retrieval, and is designed to be used by the `UsersController`. 
+
+To mark a class as a provider that the ExisJS Inversion of Control (IoC) container can manage, we use the `@Injectable()` decorator.
+
+```typescript filename="src/http/users/service.ts"
+import { Injectable } from 'exisjs/decorators'
+
+export interface User {
+  id: string;
+  email: string;
+}
+
+@Injectable({ scope: 'singleton' })
+export class UsersService {
+  private readonly users: User[] = []
+
+  create(user: User) {
+    this.users.push(user)
+  }
+
+  findAll(): User[] {
+    return this.users
+  }
+}
+```
+
+Now that we have a service class to retrieve users, let's use it inside the `UsersController`. ExisJS provides a powerful `inject()` primitive that automatically resolves dependencies from the current context.
+
+```typescript filename="src/http/users/route.ts"
+import { Controller, Get, Post, Body } from 'exisjs/decorators'
+import { inject } from 'exisjs/di'
+import { UsersService, User } from './service'
+
+@Controller('users')
+export default class UsersController {
+  
+  // Clean, ergonomic dependency injection
+  private usersService = inject(UsersService)
+
+  @Post()
+  async create(@Body() user: User) {
+    this.usersService.create(user)
+    return { success: true }
+  }
+
+  @Get()
+  async findAll() {
+    return this.usersService.findAll()
+  }
+}
+```
+
+<Info title="Note on Dependency Injection">
+ExisJS utilizes a runtime container system. By default, ExisJS does not aggressively use `reflect-metadata` for automatic constructor injection (unlike NestJS) to maintain a minimal footprint. The `inject()` function is the primary and recommended way to resolve dependencies.
+</Info>
+
+### Advanced: Manual Resolution
+If you are operating completely outside of an ExisJS controller or route (for example, in a background worker, CRON job, or a raw script like a database seeder), you can manually resolve dependencies as an escape hatch via the app container:
+
+```typescript filename="scripts/seed.ts"
+import { getActiveApp } from 'exisjs/app'
+import { UsersService } from './service'
+
+const app = getActiveApp()
+const usersService = app.container.resolve(UsersService)
+```
+
+## Custom Providers
+
+ExisJS's DI container is flexible. By default, when you register a class, ExisJS instantiates it for you. However, you often need more control. You can register standard classes, raw values, factories, or aliased classes natively using `app.provide()`.
+
+### Functional Paradigm
+
+```typescript filename="src/http/server.ts"
+import exis from 'exisjs'
+import { UsersService } from './users/service'
+
+export default exis({
+  async onStart(app) {
+    // 1. Standard Class Provider
+    app.provide(UsersService, UsersService)
+
+    // 2. Value Provider
+    app.provide('DATABASE_URL', {
+      useValue: 'postgres://localhost:5432/mydb'
+    })
+
+    // 3. Factory Provider
+    app.provide('LoggerService', {
+      useFactory: () => {
+        return { log: (msg: string) => console.log(`[Logger]: ${msg}`) }
+      }
+    })
+
+    // 4. Aliased Class Provider
+    app.provide('AuthService', {
+      useClass: UsersService
+    })
+  }
+})
+```
+
+### Class-Based (OOP) Paradigm
+
+```typescript filename="src/http/server.ts"
+import { Server } from 'exisjs/decorators'
+import { UsersService } from './users/service'
+
+@Server({
+  providers: [
+    // 1. Standard Class Provider
+    UsersService,
+    // 2. Value Provider
+    ['DATABASE_URL', { useValue: 'postgres://localhost:5432/mydb' }],
+    // 3. Factory Provider
+    ['LoggerService', { useFactory: () => ({ log: (msg: string) => console.log(`[Logger]: ${msg}`) }) }],
+    // 4. Aliased Class Provider
+    ['AuthService', { useClass: UsersService }]
+  ]
+})
+export default class RootServer {}
+```
+
+## Injection Scopes
+
+For people coming from different programming language backgrounds, it might be unexpected to learn that in ExisJS, almost everything is shared across incoming requests. We have a connection pool to the database, singleton services with global state, etc. This is because Node.js doesn't follow the request/response Multi-Threaded Stateless Model.
+
+However, there are edge-cases when request-based lifetime may be the desired behavior (e.g., per-request caching in GraphQL, request tracking, multi-tenancy). ExisJS supports scopes directly in the `@Injectable()` decorator:
+
+- **Singleton (Default)**: A single instance of the provider is shared across the entire application.
+- **Request**: A new instance of the provider is created exclusively for each incoming request, and garbage collected afterward.
+
+> [!WARNING]
+> **Request Scope Constraints**: A provider marked as `scope: 'request'` **must** be resolved within the lifecycle of an active HTTP request. If you try to `inject()` or resolve a request-scoped provider during application startup, inside a background queue worker, or from a cron job, the container will throw a runtime error.

package/dist/docs/content/queues.mdx

@@ -0,0 +1,177 @@
+---
+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 }
+  }
+}
+```
+
+## Advanced 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.
+- **Zero-Dependency 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.