exisjs 0.5.10 → 0.5.11

package/dist/docs/content/controllers.mdx

@@ -0,0 +1,241 @@
+---
+nextUrl: "/docs/providers"
+nextTitle: "Providers"
+---
+
+# Controllers
+
+Controllers are responsible for handling incoming requests and sending responses back to the client.
+
+A controller's purpose is to handle specific requests for the application. The routing mechanism determines which controller will handle each request. Often, a controller has multiple routes, and each route can perform a different action.
+
+While ExisJS natively supports Functional Routing, developers coming from enterprise backgrounds often prefer Object-Oriented patterns. To create a basic OOP controller, we use classes and decorators. Decorators link classes with the necessary metadata, allowing ExisJS to automatically route requests.
+
+## Routing & Prefixes
+
+In the following example, we'll use the `@Controller()` decorator, which is required to define a basic OOP controller. We'll specify an optional route path prefix of `users`. Using a path prefix helps group related routes together.
+
+```typescript filename="src/http/users/route.ts"
+import { Controller, Get } from 'exisjs/decorators'
+
+@Controller('users')
+export default class UsersController {
+  @Get()
+  findAll(): any[] {
+    return [
+      { id: 1, name: 'Alice' },
+      { id: 2, name: 'Bob' }
+    ]
+  }
+}
+```
+
+The `@Get()` HTTP request method decorator placed before the `findAll()` method tells ExisJS to create a handler for GET requests. Because the controller has a prefix of `users`, this endpoint maps to `GET /users`. If we used `@Get('active')`, it would map to `GET /users/active`.
+
+## Request Object
+
+Handlers often need access to the client’s request details. You can access the request object by injecting it using the `@Req()` decorator.
+
+```typescript filename="src/http/users/route.ts"
+import { Controller, Get, Req } from 'exisjs/decorators'
+import type { Request } from 'exisjs/router'
+
+@Controller('users')
+export default class UsersController {
+  @Get()
+  findAll(@Req() request: Request): any[] {
+    console.log(request.ip, request.headers)
+    return []
+  }
+}
+```
+
+In most cases, you don't need to manually access the entire request object. Instead, you can use dedicated decorators provided out of the box:
+
+<div className="overflow-x-auto mb-6">
+  <table className="w-full text-sm text-left border border-border/50 rounded-lg overflow-hidden">
+    <thead className="bg-muted/50 text-foreground">
+      <tr>
+        <th className="px-4 py-3 border-b border-border/50 font-semibold w-1/3">Decorator</th>
+        <th className="px-4 py-3 border-b border-border/50 font-semibold">Represents</th>
+      </tr>
+    </thead>
+    <tbody className="divide-y divide-border/50">
+      <tr className="bg-background hover:bg-muted/30 transition-colors">
+        <td className="px-4 py-3 font-mono text-xs"><span className="text-primary">@</span>Req()</td>
+        <td className="px-4 py-3 text-muted-foreground">The raw HTTP Request object</td>
+      </tr>
+      <tr className="bg-background hover:bg-muted/30 transition-colors">
+        <td className="px-4 py-3 font-mono text-xs"><span className="text-primary">@</span>Res()</td>
+        <td className="px-4 py-3 text-muted-foreground">The raw HTTP Response object</td>
+      </tr>
+      <tr className="bg-background hover:bg-muted/30 transition-colors">
+        <td className="px-4 py-3 font-mono text-xs"><span className="text-primary">@</span>Param(key?)</td>
+        <td className="px-4 py-3 text-muted-foreground">URL Path Parameters (e.g. req.params.id)</td>
+      </tr>
+      <tr className="bg-background hover:bg-muted/30 transition-colors">
+        <td className="px-4 py-3 font-mono text-xs"><span className="text-primary">@</span>Body(key?)</td>
+        <td className="px-4 py-3 text-muted-foreground">Parsed Request Body</td>
+      </tr>
+      <tr className="bg-background hover:bg-muted/30 transition-colors">
+        <td className="px-4 py-3 font-mono text-xs"><span className="text-primary">@</span>Query(key?)</td>
+        <td className="px-4 py-3 text-muted-foreground">URL Query Parameters</td>
+      </tr>
+      <tr className="bg-background hover:bg-muted/30 transition-colors">
+        <td className="px-4 py-3 font-mono text-xs"><span className="text-primary">@</span>Headers(name?)</td>
+        <td className="px-4 py-3 text-muted-foreground">Specific HTTP Header</td>
+      </tr>
+      <tr className="bg-background hover:bg-muted/30 transition-colors">
+        <td className="px-4 py-3 font-mono text-xs"><span className="text-primary">@</span>HostParam(name?)</td>
+        <td className="px-4 py-3 text-muted-foreground">Subdomain / Host route parameter</td>
+      </tr>
+      <tr className="bg-background hover:bg-muted/30 transition-colors">
+        <td className="px-4 py-3 font-mono text-xs"><span className="text-primary">@</span>Session()</td>
+        <td className="px-4 py-3 text-muted-foreground">The request session object</td>
+      </tr>
+      <tr className="bg-background hover:bg-muted/30 transition-colors">
+        <td className="px-4 py-3 font-mono text-xs"><span className="text-primary">@</span>Next()</td>
+        <td className="px-4 py-3 text-muted-foreground">Next middleware function in pipeline</td>
+      </tr>
+      <tr className="bg-background hover:bg-muted/30 transition-colors">
+        <td className="px-4 py-3 font-mono text-xs"><span className="text-primary">@</span>Ip()</td>
+        <td className="px-4 py-3 text-muted-foreground">The client's IP address</td>
+      </tr>
+      <tr className="bg-background hover:bg-muted/30 transition-colors">
+        <td className="px-4 py-3 font-mono text-xs"><span className="text-primary">@</span>UploadedFile()</td>
+        <td className="px-4 py-3 text-muted-foreground">A single uploaded file (multipart/form-data)</td>
+      </tr>
+      <tr className="bg-background hover:bg-muted/30 transition-colors">
+        <td className="px-4 py-3 font-mono text-xs"><span className="text-primary">@</span>UploadedFiles()</td>
+        <td className="px-4 py-3 text-muted-foreground">Array of uploaded files</td>
+      </tr>
+    </tbody>
+  </table>
+</div>
+
+## Payloads & Validation
+
+For POST and PUT endpoints, you need to read the incoming JSON payload. Use the `@Body()` decorator to inject it.
+
+```typescript filename="src/http/users/route.ts"
+import { Controller, Post, Body } from 'exisjs/decorators'
+
+export class CreateUserDto {
+  name: string;
+  email: string;
+  role: string;
+}
+
+@Controller('users')
+export default class UsersController {
+  @Post()
+  async create(@Body() createUserDto: CreateUserDto) {
+    return { id: 3, ...createUserDto }
+  }
+}
+```
+
+## Status Codes & Headers
+
+By default, responses have a `200 OK` status (except POST which uses `201`). You can change this declaratively using the `@HttpCode()` and `@Header()` decorators.
+
+```typescript filename="src/http/users/route.ts"
+import { Controller, Post, HttpCode, Header } from 'exisjs/decorators'
+
+@Controller('users')
+export default class UsersController {
+  @Post()
+  @HttpCode(204)
+  @Header('Cache-Control', 'no-store')
+  create() {
+    return null // No Content
+  }
+}
+```
+
+## Advanced Features
+
+ExisJS provides routing enhancements like Subdomain Routing, Redirects, and Passthrough Responses. These are supported across both paradigms.
+
+### Functional Paradigm
+
+```typescript filename="src/http/advanced/route.ts"
+import { controller, route } from 'exisjs/router'
+
+export default controller({
+  // 1. Subdomain Routing
+  ping: route.get('/ping', {
+    host: ':sub.exis.local',
+    handle({ req }) {
+      return { subdomain: (req.params as any).sub }
+    }
+  }),
+  // 2. Redirect
+  redirect: route.get('/redirect', {
+    handle({ res }) {
+      res.redirect('https://google.com')
+    }
+  }),
+  // 3. Passthrough Response
+  manual: route.get('/manual', {
+    handle({ res }) {
+      res.setHeader('X-Custom', 'true')
+      return { msg: 'This is auto-serialized with custom headers!' }
+    }
+  })
+})
+```
+
+### Class-Based (OOP) Paradigm
+
+```typescript filename="src/http/advanced/route.ts"
+import { Controller, Get, HostParam, Redirect, Res } from 'exisjs/decorators'
+import type { Response } from 'exisjs/router'
+
+// 1. Subdomain Routing
+@Controller({ host: ':sub.exis.local' })
+export class SubdomainController {
+  @Get('/ping')
+  ping(@HostParam('sub') sub: string) {
+    return { subdomain: sub }
+  }
+}
+
+@Controller('users')
+export class AdvancedController {
+  // 2. Redirect
+  @Get('/redirect')
+  @Redirect('https://google.com')
+  redirect() {}
+
+  // 3. Passthrough Response
+  @Get('/manual')
+  manual(@Res({ passthrough: true }) res: Response) {
+    res.setHeader('X-Custom', 'true')
+    return { msg: 'This is auto-serialized with custom headers!' }
+  }
+}
+```
+
+## Registration & Library-Specific Response
+
+Unlike frameworks where controllers must be registered manually in a module file, ExisJS uses Folder-Based Routing. To register a controller, you export default the class inside a `route.ts` file.
+
+If you need low-level control over the response, you can inject the native `@Res()` object.
+
+```typescript filename="src/http/users/route.ts"
+import { Controller, Get, Res } from 'exisjs/decorators'
+import type { Response } from 'exisjs/router'
+
+@Controller('users')
+export default class UsersController {
+  @Get()
+  findAll(@Res() res: Response) {
+    res.status(200).json({ data: [] })
+  }
+}
+```
+
+<Info title="Tip: Safely Returning with @Res">
+In some frameworks, injecting the `@Res()` object disables auto-serialization, causing the request to hang if you forget to call `res.send()`. ExisJS handles this differently: if you return a value from your handler, ExisJS will still safely auto-serialize it to JSON even if you injected `@Res()` to set a custom header.
+</Info>

package/dist/docs/content/cron.mdx

@@ -0,0 +1,109 @@
+---
+nextUrl: "/docs/rpc"
+nextTitle: "RPC Client"
+---
+
+# Cron Jobs
+
+ExisJS ships with a distributed Cron Scheduler. Because the cron engine is integrated with the [Job Queue](/docs/queues) system, you can turn any standard background job into a recurring cron task with a single line of code.
+
+---
+
+## 1. Defining a Cron Job
+
+To schedule a recurring task, add the `cron` property to any Job definition (`defineJob`) or inline `queue()` handler using standard 5-part cron syntax (`minute hour day month day-of-week`).
+
+### Using `defineJob`
+```typescript filename="src/jobs/cleanup.ts"
+import { defineJob } from 'exisjs/queue'
+
+export default defineJob({
+  name: 'database-cleanup',
+  // Run this job at exactly 2:00 AM every single day
+  cron: '0 2 * * *', 
+  
+  async handler(job) {
+    console.log("Running daily database cleanup...")
+    await db.users.deleteInactive()
+  }
+})
+```
+
+### Using Inline Handlers (`queue`)
+If you prefer functional programming, you can define recurring jobs right alongside your application setup:
+
+```typescript filename="src/http/server.ts"
+import { queue } from 'exisjs/queue'
+
+queue('sync-metrics', async () => {
+  console.log("Syncing metrics to data warehouse...")
+}, {
+  cron: '*/15 * * * *', // Run every 15 minutes
+  defaultOptions: { attempts: 3 }
+})
+```
+
+---
+
+## 2. Distributed Locking (Cluster Safe)
+
+In modern web architecture, you rarely run a single NodeJS process. If you run your application across 10 load-balanced servers, a traditional `setInterval` or standard node-cron library would execute your scheduled task 10 times simultaneously.
+
+ExisJS solves this natively through **Distributed Locking**.
+
+When you configure your Queue system to use the `redis` driver, the ExisJS Cron Scheduler automatically utilizes a `SETNX` (Set if Not Exists) Redis lock.
+
+### How it works:
+1. Every 60 seconds, all 10 of your servers will attempt to trigger the cron job.
+2. The *very first* server to hit Redis acquires a 55-second lock for that specific minute.
+3. The other 9 servers see the lock and silently skip execution.
+4. The winning server instantly enqueues the job into the standard ExisJS Queue.
+
+This guarantees that **your cron job will only execute exactly once per minute**, regardless of how many servers or Docker containers you spin up.
+
+---
+
+## 3. Supported Cron Syntax
+
+ExisJS implements a zero-dependency cron parser that supports all standard operations:
+
+- `*` - Any value (e.g., run every minute)
+- `,` - Value list (e.g., `1,15,30` to run on the 1st, 15th, and 30th minute)
+- `-` - Value range (e.g., `1-5` to run from Monday to Friday)
+- `/` - Step values (e.g., `*/10` to run every 10 minutes)
+
+**Examples:**
+- `* * * * *`: Every minute
+- `*/5 * * * *`: Every 5 minutes
+- `0 0 * * *`: Every day at midnight
+- `0 9 * * 1-5`: At 9:00 AM on Monday through Friday
+- `0 12 1,15 * *`: At 12:00 PM on the 1st and 15th of every month
+
+---
+
+## 4. Important Considerations
+
+### Empty Payloads
+Because cron jobs are triggered by the system clock rather than a user action, they are always dispatched with an empty payload (`{}`). Your job handler should not expect dynamic data to be passed into the `data` property when triggered via cron.
+
+### Retries & Error Handling
+Cron jobs are standard background jobs under the hood. This means they fully support your `defaultOptions`. If a cron job throws an error, it will automatically be retried according to the `attempts` and `backoff` settings defined in the job.
+
+```typescript filename="src/jobs/cleanup.ts"
+export default defineJob({
+  name: 'database-cleanup',
+  cron: '0 2 * * *', 
+  defaultOptions: {
+    attempts: 3,
+    backoff: { type: 'exponential', delay: 5000 }
+  },
+  async handler(job) {
+    // If this fails, it will retry 3 times, backing off exponentially
+  }
+})
+```
+
+### Redis Requirement
+Because ExisJS is designed for cluster-safe, distributed deployments, **the Cron Scheduler strictly requires the `redis` queue driver**. 
+
+If you attempt to run a cron job while using the `memory` driver, ExisJS will skip execution and log an error. This is a deliberate design choice to prevent you from accidentally triggering scheduled jobs multiple times simultaneously across a load-balanced cluster.

package/dist/docs/content/database.mdx

@@ -0,0 +1,209 @@
+---
+title: "Database Layer"
+description: "ExisJS includes a built-in, high-performance database layer with native support for PostgreSQL, MySQL, SQLite, and MongoDB, plus a powerful query builder and migration system."
+---
+
+# Database Layer
+
+Unlike other Node.js frameworks that rely entirely on third-party ORMs like Prisma or TypeORM, **ExisJS ships with a fully integrated, high-performance Database Layer.** 
+
+This provides a massive advantage in developer experience and reliability, as connections, query generation, and migrations are orchestrated directly by the framework.
+
+<Info title="Functional vs OOP">
+ExisJS natively supports both a **Functional Paradigm** and a **Class-Based OOP Paradigm** (for dependency injection and decorators). The database layer is seamlessly accessible through both approaches.
+</Info>
+
+## Setup and Connection
+
+You configure your database connections directly in your application entry point (`server.ts`). ExisJS manages their lifecycle (including graceful shutdown) automatically.
+
+#### Functional Paradigm
+```typescript filename="src/http/server.ts"
+import { exis, db, createDatabase } from 'exisjs'
+
+export default exis({
+  async onStart(app) {
+    const database = createDatabase({
+      dialect: 'postgres',
+      url: process.env.DATABASE_URL,
+    })
+    
+    // Connect on boot
+    await database.connect()
+  }
+})
+```
+
+#### Class-Based (OOP) Paradigm
+```typescript filename="src/http/server.ts"
+import { Server } from 'exisjs/decorators'
+import { createDatabase } from 'exisjs'
+
+@Server()
+export default class RootServer {
+  async onStart(app: App) {
+    const database = createDatabase({
+      dialect: 'postgres',
+      url: process.env.DATABASE_URL,
+    })
+    
+    // Connect on boot
+    await database.connect()
+  }
+}
+```
+
+## Using the Query Builder in Routes
+
+ExisJS includes a powerful, chainable Query Builder that automatically generates the correct, parameterized SQL for your chosen dialect. Here is how you use it in your route controllers or services.
+
+#### Functional Paradigm
+In functional routes, you can easily use the global `db` object to fetch data directly, or use the `resolve` function to inject a dedicated Service that wraps the database calls.
+
+```typescript filename="src/http/users/route.ts"
+import { controller, route } from 'exisjs/router'
+import { db } from 'exisjs'
+
+export default controller({
+  list: route.get('/', {
+    async handle() {
+      // Query multiple rows
+      const users = await db.table('users')
+        .select('id', 'name', 'email')
+        .where('role', '=', 'admin')
+        .orderBy('created_at', 'desc')
+        .limit(10)
+        .rows()
+        
+      return users
+    }
+  }),
+
+  create: route.post('/', {
+    async handle({ req }) {
+      const { name, email } = req.body
+      
+      // Insert a new row
+      const result = await db.table('users').insert({
+        name,
+        email,
+        role: 'user'
+      }).execute()
+      
+      return { id: result.insertId, name, email }
+    }
+  })
+})
+```
+
+#### Class-Based (OOP) Paradigm
+In the OOP paradigm, it is highly recommended to abstract database calls into `@Injectable()` services and inject them into your `@Controller()`.
+
+```typescript filename="src/http/users/service.ts"
+import { Injectable } from 'exisjs/decorators'
+import { db } from 'exisjs'
+
+@Injectable()
+export class UsersService {
+  async getAdmins() {
+    return await db.table('users')
+      .select('id', 'name', 'email')
+      .where('role', '=', 'admin')
+      .orderBy('created_at', 'desc')
+      .limit(10)
+      .rows()
+  }
+
+  async createUser(data: { name: string, email: string }) {
+    const result = await db.table('users').insert({
+      ...data,
+      role: 'user'
+    }).execute()
+    
+    return { id: result.insertId, ...data }
+  }
+}
+```
+
+```typescript filename="src/http/users/route.ts"
+import { Controller, Get, Post, Body } from 'exisjs/decorators'
+import { UsersService } from './service'
+
+@Controller()
+export default class UsersController {
+  // ExisJS automatically injects the service!
+  constructor(private usersService: UsersService) {}
+
+  @Get('/')
+  async list() {
+    return await this.usersService.getAdmins()
+  }
+
+  @Post('/')
+  async create(@Body() body: any) {
+    return await this.usersService.createUser(body)
+  }
+}
+```
+
+## Transactions
+
+ExisJS makes it trivial to perform safe database transactions. If the callback throws an error, the transaction is automatically rolled back.
+
+```typescript
+import { db } from 'exisjs'
+
+await db.transaction(async (tx) => {
+  // Deduct from inventory
+  await tx.execute(
+    'UPDATE inventory SET stock = stock - ? WHERE id = ?', 
+    [1, itemId]
+  )
+  
+  // Create order record
+  await tx.execute(
+    'INSERT INTO orders (user_id, item_id) VALUES (?, ?)', 
+    [userId, itemId]
+  )
+})
+```
+
+## Built-in Migrations
+
+Managing database schema changes is critical. ExisJS includes a built-in migration system that tracks applied migrations in your database automatically.
+
+```typescript
+import { db } from 'exisjs'
+
+const migrator = db.getMigrator({ directory: './migrations' })
+
+// Apply all pending migrations
+await migrator.up()
+
+// Rollback the last batch of migrations
+await migrator.down()
+
+// Check the status of all migrations
+const status = await migrator.status()
+```
+
+### Creating a Migration
+A migration file simply exports `up` and `down` methods. You write raw SQL inside them for ultimate control.
+
+```typescript filename="migrations/001_create_users.ts"
+module.exports = {
+  name: '001_create_users',
+  async up(db) {
+    await db.execute(`
+      CREATE TABLE users (
+        id SERIAL PRIMARY KEY,
+        name VARCHAR(255) NOT NULL,
+        email VARCHAR(255) UNIQUE NOT NULL
+      )
+    `)
+  },
+  async down(db) {
+    await db.execute('DROP TABLE users')
+  },
+}
+```