exisjs 0.7.6 → 0.7.8

package/dist/docs/content/swagger.mdx

@@ -0,0 +1,289 @@
+---
+nextUrl: "/docs/reference/swagger"
+nextTitle: "Swagger API Reference"
+---
+
+# Swagger & OpenAPI 3.1 Documentation
+
+ExisJS comes with a native, built-in **Swagger & OpenAPI 3.1** documentation engine. It automatically discovers all registered routes, introspects **Tex** and **Zod** validation schemas, and serves interactive API documentation at `/docs`.
+
+---
+
+## Quick Start
+
+Enable Swagger documentation in your `exis.config.ts`:
+
+```typescript filename="exis.config.ts"
+import { defineConfig } from 'exisjs/config'
+
+export default defineConfig({
+  docs: {
+    enabled: true,              // Mounts UI at /docs and spec at /docs/json
+    title: 'Store API Documentation',
+    version: '1.0.0',
+    description: 'Auto-generated API documentation with native schema validation',
+    ui: 'swagger-ui',          // 'swagger-ui' | 'scalar'
+  }
+})
+```
+
+Once enabled:
+* Visit `http://localhost:3000/docs` to view the interactive documentation UI.
+* Visit `http://localhost:3000/docs/json` (or `/docs/openapi.json`) for the raw OpenAPI 3.1 specification.
+
+---
+
+## Interactive Documentation UIs
+
+ExisJS supports two built-in UI renderers:
+
+### 1. Swagger UI (`ui: 'swagger-ui'`, default)
+The industry-standard interactive Swagger explorer featuring **Try it out**, live request execution, and parameter inspection.
+
+### 2. Scalar API Reference (`ui: 'scalar'`)
+A modern, high-performance, dark-mode-first API reference documentation viewer with integrated code snippets and fast search.
+
+```typescript filename="exis.config.ts"
+import { defineConfig } from 'exisjs/config'
+
+export default defineConfig({
+  docs: {
+    enabled: true,
+    ui: 'scalar', // Switches UI to modern Scalar
+  }
+})
+```
+
+---
+
+## Documenting Functional Routes
+
+In ExisJS folder-based routing, each endpoint folder contains a `route.ts` file that exports a default `controller({ ... })`. You can add OpenAPI metadata directly to each route definition:
+
+```typescript filename="src/http/users/route.ts"
+import { controller, route } from 'exisjs/router'
+import { tex, getPaginationSkip } from 'exisjs/validator'
+
+export default controller({
+  list: route.get('/', {
+    summary: 'List active users',
+    description: 'Returns a paginated list of all active users in the system.',
+    tags: ['Users'],
+    query: tex.pagination({ defaultLimit: 25, maxLimit: 100 }),
+    responses: {
+      200: {
+        description: 'Paginated user list',
+        schema: tex.object({
+          data: tex.array(tex.object({ id: tex.uuid(), name: tex.string() })),
+          total: tex.number(),
+        }),
+      },
+      400: { description: 'Invalid query parameters' },
+    },
+    async handle({ query }) {
+      const { skip, limit } = getPaginationSkip(query)
+      return {
+        data: [
+          { id: '550e8400-e29b-41d4-a716-446655440000', name: 'Alice' },
+          { id: '550e8400-e29b-41d4-a716-446655440001', name: 'Bob' },
+        ],
+        total: 2,
+        skip,
+        limit,
+      }
+    },
+  }),
+
+  create: route.post('/', {
+    summary: 'Create a new user',
+    tags: ['Users'],
+    body: tex.object({
+      name: tex.string({ min: 2 }),
+      email: tex.email(),
+    }),
+    responses: {
+      201: { description: 'User successfully created' },
+      400: { description: 'Validation error' },
+    },
+    async handle({ body }) {
+      return { id: '550e8400-e29b-41d4-a716-446655440002', ...body }
+    },
+  }),
+
+  getById: route.get('/:id', {
+    summary: 'Get user by UUID',
+    tags: ['Users'],
+    params: tex.object({ id: tex.uuid() }),
+    responses: {
+      200: { description: 'User details found' },
+      404: { description: 'User not found' },
+    },
+    async handle({ params }) {
+      return { id: params.id, name: 'Alice' }
+    },
+  }),
+})
+```
+
+---
+
+## Documenting Class-Based Controllers (OOP)
+
+For class-based controllers in `route.ts`, use OpenAPI decorators from `exisjs/swagger` alongside standard routing decorators:
+
+```typescript filename="src/http/products/route.ts"
+import { Controller, Get, Post, Body, Param, Query } from 'exisjs/decorators'
+import {
+  ApiTags,
+  ApiOperation,
+  ApiResponse,
+  ApiBearerAuth,
+  ApiExclude,
+} from 'exisjs/swagger'
+
+@ApiTags('Products')
+@ApiBearerAuth()
+@Controller()
+export default class ProductsController {
+  @Get('/')
+  @ApiOperation({
+    summary: 'List products',
+    description: 'Fetches paginated list of catalog products',
+  })
+  @ApiResponse({ status: 200, description: 'List of products' })
+  async list(@Query('page') page: number = 1) {
+    return [
+      { id: 1, name: 'Mechanical Keyboard', price: 99 },
+      { id: 2, name: 'Ergonomic Mouse', price: 49 },
+    ]
+  }
+
+  @Post('/')
+  @ApiOperation({ summary: 'Create new product' })
+  @ApiResponse({ status: 201, description: 'Product created' })
+  async create(@Body() dto: { name: string; price: number }) {
+    return { id: 3, ...dto }
+  }
+
+  @Get('/:id')
+  @ApiOperation({ summary: 'Get product by ID' })
+  @ApiResponse({ status: 200, description: 'Product found' })
+  @ApiResponse({ status: 404, description: 'Product not found' })
+  async getById(@Param('id') id: string) {
+    return { id, name: 'Mechanical Keyboard', price: 99 }
+  }
+
+  @Get('/internal/metrics')
+  @ApiExclude() // Excluded from Swagger documentation
+  async metrics() {
+    return { uptime: process.uptime() }
+  }
+}
+```
+
+---
+
+## Cascading Boundary Metadata
+
+Cascading boundaries (`boundary.ts`) can assign shared tags, descriptions, or security requirements to all nested routes in the directory:
+
+```typescript filename="src/http/admin/boundary.ts"
+import { defineBoundary } from 'exisjs/router'
+
+export const config = defineBoundary({
+  tags: ['Admin Portal'],
+  security: [{ bearerAuth: [] }],
+})
+```
+
+---
+
+## Security Schemes & Authentication
+
+Define reusable security schemes (such as Bearer JWT, API Keys, or OAuth2) in `exis.config.ts`:
+
+```typescript filename="exis.config.ts"
+import { defineConfig } from 'exisjs/config'
+
+export default defineConfig({
+  docs: {
+    enabled: true,
+    securitySchemes: {
+      bearerAuth: {
+        type: 'http',
+        scheme: 'bearer',
+        bearerFormat: 'JWT',
+        description: 'Enter your JWT token: Bearer <token>',
+      },
+      apiKeyAuth: {
+        type: 'apiKey',
+        in: 'header',
+        name: 'X-API-KEY',
+      },
+    },
+    security: [
+      { bearerAuth: [] },
+    ],
+  },
+})
+```
+
+---
+
+## Advanced Configuration (`exis.config.ts`)
+
+For advanced customization, such as modifying the generated OpenAPI spec before serving or injecting custom styling:
+
+```typescript filename="exis.config.ts"
+import { defineConfig } from 'exisjs/config'
+
+export default defineConfig({
+  docs: {
+    enabled: true,
+    title: 'Enterprise API Gateway',
+    version: '2.0.0',
+    description: 'Internal and external microservices API reference',
+    ui: 'scalar', // 'swagger-ui' | 'scalar'
+    servers: [
+      { url: 'https://api.example.com', description: 'Production Server' },
+      { url: 'http://localhost:3000', description: 'Local Development' },
+    ],
+    transformSpec(spec) {
+      // Programmatically mutate or enrich OpenAPI specification
+      spec.info.contact = { name: 'API Support', email: 'support@example.com' }
+      return spec
+    },
+  },
+})
+```
+
+---
+
+## Server Lifecycle Hook (`server.ts`)
+
+You can also interact with the Swagger subsystem or application instance during server boot in `src/http/server.ts`:
+
+### Functional Paradigm
+```typescript filename="src/http/server.ts"
+import { exis } from 'exisjs'
+
+export default exis({
+  onStart(app) {
+    console.log('[API] Swagger documentation ready at /docs')
+  },
+})
+```
+
+### Class-Based (OOP) Paradigm
+```typescript filename="src/http/server.ts"
+import { Server } from 'exisjs/decorators'
+import type { App } from 'exisjs'
+
+@Server()
+export default class RootServer {
+  async onStart(app: App) {
+    console.log('[API] Swagger documentation ready at /docs')
+  }
+}
+```
+

package/dist/docs/reference/cron.mdx

@@ -0,0 +1,300 @@
+---
+title: "Cron & Scheduling"
+description: "API Reference for ExisJS Task Scheduling, Cron Expressions, and Job Management."
+---
+
+# Cron & Scheduling (`exisjs/cron`, `exisjs/decorators`)
+
+The `exisjs/cron` module provides task scheduling, cron expression parsing, interval timers, and runtime job management.
+
+---
+
+## 1. Functional Definition Helpers
+
+### `cron(scheduleOrOptions, handler?)`
+
+Defines a functional cron job.
+
+```typescript
+import { cron, CronExpression } from 'exisjs/cron'
+
+// Signature 1: Options object with inline run handler
+export default cron({
+  name: 'sync-users',
+  schedule: CronExpression.EVERY_10_MINUTES,
+  timezone: 'UTC',
+  preventOverlap: true,
+  retries: 2,
+  retryDelayMs: 1000,
+  async run({ app, log }) {
+    // ...
+  }
+})
+
+// Signature 2: Schedule string with handler
+export const purgeJob = cron('0 0 * * *', async ({ log }) => {
+  // ...
+})
+```
+
+### `cron.every(duration, handler, options?)`
+
+Shorthand helper accepting human-readable duration strings (e.g., `'10 seconds'`, `'5 minutes'`, `'2 hours'`).
+
+```typescript
+import { cron } from 'exisjs/cron'
+
+export const healthCheck = cron.every('30 seconds', async ({ log }) => {
+  log.info('Checking external dependencies...')
+}, {
+  name: 'ext-health-check'
+})
+```
+
+### `cron.interval(ms, handler, options?)`
+
+Shorthand helper for millisecond recurring intervals.
+
+```typescript
+import { cron } from 'exisjs/cron'
+
+export const heartbeat = cron.interval(60_000, async ({ log }) => {
+  log.info('Server heartbeat tick')
+})
+```
+
+### `cron.timeout(ms, handler, options?)`
+
+Shorthand helper for one-time delayed startup tasks (executes once after application boot).
+
+```typescript
+import { cron } from 'exisjs/cron'
+
+export const cacheWarmup = cron.timeout(5_000, async ({ app, log }) => {
+  log.info('Warming up Redis cache after boot')
+})
+```
+
+---
+
+## 2. OOP Decorators (`exisjs/decorators`)
+
+### `@Cron(schedule, options?)`
+
+Method decorator that marks a class method as a scheduled cron job. Can be used on any `@Injectable()` service.
+
+| Parameter | Type | Description |
+| :--- | :--- | :--- |
+| `schedule` | `string` | Standard 5 or 6 field cron expression or `CronExpression` constant. |
+| `options` | `CronJobOptions` | Optional job configuration (name, timezone, preventOverlap, retries, etc.). |
+
+```typescript
+import { Injectable, Cron, CronExpression } from 'exisjs/decorators'
+
+@Injectable()
+export default class ReportService {
+  @Cron(CronExpression.EVERY_DAY_AT_MIDNIGHT, {
+    name: 'nightly-report',
+    timezone: 'UTC',
+    preventOverlap: true,
+  })
+  async generateDailyReport() {
+    // ...
+  }
+}
+```
+
+### `@Interval(ms, options?)`
+
+Method decorator for recurring millisecond tasks.
+
+```typescript
+import { Injectable, Interval } from 'exisjs/decorators'
+
+@Injectable()
+export default class QueueMonitor {
+  @Interval(15_000, { name: 'queue-poll' })
+  async pollQueue() {
+    // ...
+  }
+}
+```
+
+### `@TimeoutTask(ms, options?)` (alias `@ScheduledTimeout`)
+
+Method decorator for one-time startup tasks executed after the specified millisecond delay.
+
+```typescript
+import { Injectable, TimeoutTask } from 'exisjs/decorators'
+
+@Injectable()
+export default class CacheBootstrap {
+  @TimeoutTask(3_000, { name: 'seed-cache' })
+  async seedCache() {
+    // ...
+  }
+}
+```
+
+---
+
+## 3. Configuration & Options
+
+### `CronJobOptions`
+
+Configuration object passed to `cron()` or decorator options:
+
+| Property | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `name` | `string` | `auto-generated` | Unique identifier for the job. Used in logs and runtime APIs. |
+| `schedule` | `string` | `undefined` | 5 or 6 field cron expression (e.g. `'0 0 * * *'`). |
+| `interval` | `number` | `undefined` | Millisecond interval for recurring execution. |
+| `timeout` | `number` | `undefined` | Millisecond delay for one-time execution. |
+| `timezone` | `string` | `'UTC'` | Valid IANA timezone string (e.g. `'America/New_York'`, `'Asia/Kolkata'`). |
+| `preventOverlap` | `boolean` | `true` | Skips execution if the previous tick is still running. |
+| `overlapPolicy` | `'skip' \| 'queue'` | `'skip'` | Action taken when execution overlap occurs. |
+| `retries` | `number` | `0` | Number of retry attempts upon failure. |
+| `retryDelayMs` | `number` | `1000` | Milliseconds to wait before executing a retry. |
+| `autoStart` | `boolean` | `true` | Whether the job automatically starts on application bootstrap. |
+| `run` / `handle` | `(ctx: CronContext) => Promise<any> \| any` | `undefined` | The execution callback function. |
+| `onError` | `(err: Error, ctx: CronContext) => void` | `undefined` | Hook called when the job fails after all retries. |
+
+### `CronContext`
+
+The context object provided as the first argument to job execution handlers:
+
+| Property | Type | Description |
+| :--- | :--- | :--- |
+| `name` | `string` | The unique name of the active job. |
+| `scheduledTime` | `Date` | The theoretical timestamp the job was scheduled to run. |
+| `executionTime` | `Date` | The actual timestamp execution began. |
+| `iteration` | `number` | Total number of executions completed by this job instance. |
+| `app` | `App` | Reference to the current ExisJS application instance. |
+| `log` | `Logger` | Scoped logger instance with `job: name` context. |
+
+---
+
+## 4. `CronExpression` Presets
+
+ExisJS exports pre-validated standard cron expression constants:
+
+| Constant | Value | Description |
+| :--- | :--- | :--- |
+| `CronExpression.EVERY_SECOND` | `* * * * * *` | Every second (6-field) |
+| `CronExpression.EVERY_5_SECONDS` | `*/5 * * * * *` | Every 5 seconds (6-field) |
+| `CronExpression.EVERY_10_SECONDS` | `*/10 * * * * *` | Every 10 seconds (6-field) |
+| `CronExpression.EVERY_30_SECONDS` | `*/30 * * * * *` | Every 30 seconds (6-field) |
+| `CronExpression.EVERY_MINUTE` | `* * * * *` | Every minute |
+| `CronExpression.EVERY_5_MINUTES` | `*/5 * * * *` | Every 5 minutes |
+| `CronExpression.EVERY_10_MINUTES` | `*/10 * * * *` | Every 10 minutes |
+| `CronExpression.EVERY_15_MINUTES` | `*/15 * * * *` | Every 15 minutes |
+| `CronExpression.EVERY_30_MINUTES` | `*/30 * * * *` | Every 30 minutes |
+| `CronExpression.EVERY_HOUR` | `0 * * * *` | Top of every hour |
+| `CronExpression.EVERY_2_HOURS` | `0 */2 * * *` | Every 2 hours |
+| `CronExpression.EVERY_6_HOURS` | `0 */6 * * *` | Every 6 hours |
+| `CronExpression.EVERY_12_HOURS` | `0 */12 * * *` | Every 12 hours |
+| `CronExpression.EVERY_DAY_AT_MIDNIGHT` | `0 0 * * *` | Daily at 00:00 (Midnight) |
+| `CronExpression.EVERY_DAY_AT_1AM` | `0 1 * * *` | Daily at 01:00 AM |
+| `CronExpression.EVERY_DAY_AT_2AM` | `0 2 * * *` | Daily at 02:00 AM |
+| `CronExpression.EVERY_DAY_AT_NOON` | `0 12 * * *` | Daily at 12:00 PM |
+| `CronExpression.EVERY_WEEK` | `0 0 * * 0` | Every Sunday at midnight |
+| `CronExpression.EVERY_MONTH` | `0 0 1 * *` | First day of every month at midnight |
+| `CronExpression.EVERY_YEAR` | `0 0 1 1 *` | January 1st at midnight |
+
+---
+
+## 5. Runtime Management API (`app.cron`)
+
+Access the cron manager via `app.cron`:
+
+### `app.cron.schedule(options)`
+Registers and schedules a new cron job dynamically.
+
+```typescript
+const job = app.cron.schedule({
+  name: 'dynamic-sync',
+  schedule: '0 */3 * * *',
+  run: async ({ log }) => {
+    log.info('Dynamic sync executed')
+  }
+})
+```
+
+### `app.cron.get(name)`
+Returns the `CronJob` instance by name, or `undefined` if not found.
+
+```typescript
+const job = app.cron.get('nightly-sync')
+```
+
+### `app.cron.has(name)`
+Returns `true` if a job with the specified name exists.
+
+```typescript
+if (app.cron.has('nightly-sync')) {
+  // ...
+}
+```
+
+### `app.cron.list()`
+Returns an array of all registered `CronJob` instances.
+
+```typescript
+const allJobs = app.cron.list()
+```
+
+### `app.cron.status()`
+Returns an array of status and metric descriptors for all registered jobs.
+
+```typescript
+const stats = app.cron.status()
+// [
+//   {
+//     name: 'nightly-sync',
+//     status: 'running',
+//     running: false,
+//     totalExecutions: 14,
+//     successCount: 14,
+//     failureCount: 0,
+//     lastExecution: '2026-09-22T00:00:00.000Z',
+//     nextExecution: '2026-09-23T00:00:00.000Z',
+//     lastDurationMs: 142
+//   }
+// ]
+```
+
+### `app.cron.trigger(name)`
+Manually triggers an immediate execution of the specified job, returning the handler result.
+
+```typescript
+const result = await app.cron.trigger('nightly-sync')
+```
+
+### `app.cron.pause(name)` / `app.cron.resume(name)`
+Pauses or resumes a job's automatic scheduling without unregistering it.
+
+```typescript
+app.cron.pause('nightly-sync')
+app.cron.resume('nightly-sync')
+```
+
+### `app.cron.remove(name)`
+Stops and unregisters a job by name.
+
+```typescript
+app.cron.remove('nightly-sync')
+```
+
+### `app.cron.stopAll()`
+Stops all scheduled timers across all registered jobs.
+
+```typescript
+app.cron.stopAll()
+```
+
+### `app.cron.drain(timeoutMs?)`
+Stops new ticks and awaits any currently running job executions to complete. Called automatically during graceful server shutdown.
+
+```typescript
+await app.cron.drain(5000)
+```

package/dist/docs/reference/decorators.mdx

@@ -123,3 +123,11 @@ Parameter decorators automatically extract data from the incoming request and in
 - `@Boundary(config)`: Marks a class as a folder-scoped Boundary configuring CORS, headers, exclusions, and pipeline steps.
 - `@Server(config)`: Marks a class as a root server definition.
 
+---
+
+## 6. Cron & Task Scheduling
+
+- `@Cron(schedule: string, options?: CronJobOptions)`: Schedules a class method as a recurring cron job on any `@Injectable()` service.
+- `@Interval(ms: number, options?: IntervalOptions)`: Schedules a class method to execute repeatedly every `ms` milliseconds.
+- `@TimeoutTask(ms: number, options?: TimeoutOptions)` (alias `@ScheduledTimeout`): Schedules a class method to execute once after `ms` milliseconds following application bootstrap.
+

package/dist/docs/reference/error.mdx

@@ -133,6 +133,50 @@ export class InsufficientFundsError extends HttpError {
 
 ---
 
+## Framework Exception File Convention (`src/http/error.ts`)
+
+ExisJS natively discovers and auto-mounts `src/http/error.ts` (or `src/http/*.error.ts`) during application bootstrap. It serves as the single source of truth for centralized exception filtering without requiring manual middleware registration in `server.ts`.
+
+### Handler Signatures
+
+**Functional (`export function onError`):**
+```typescript filename="src/http/error.ts"
+import type { Request, Response } from 'exisjs'
+
+export function onError(err: any, req: Request, res: Response): void | Promise<void> {
+  const status = err.statusCode || err.status || 500
+  res.status(status).json({
+    success: false,
+    error: {
+      code: err.code || 'ERROR',
+      message: err.message || 'Internal Server Error',
+      path: req.path,
+    },
+  })
+}
+```
+
+**Class-Based OOP (`export default class`):**
+```typescript filename="src/http/error.ts"
+import type { Request, Response } from 'exisjs'
+
+export default class GlobalErrorHandler {
+  onError(err: any, req: Request, res: Response): void | Promise<void> {
+    const status = err.statusCode || err.status || 500
+    res.status(status).json({
+      success: false,
+      error: {
+        code: err.code || 'ERROR',
+        message: err.message || 'Internal Server Error',
+        path: req.path,
+      },
+    })
+  }
+}
+```
+
+---
+
 ## Global Error Handler
 
 ExisJS uses a highly sophisticated global error handler out of the box, generated via `createErrorHandler(isDev)`.