exisjs 0.7.5 → 0.7.7

package/dist/docs/content/cron.mdx

@@ -0,0 +1,196 @@
+---
+nextUrl: "/docs/queues"
+nextTitle: "Queues & Background Jobs"
+---
+
+# Cron & Task Scheduling
+
+ExisJS includes a built-in Cron and Task Scheduling system designed for reliability and developer ergonomic efficiency. It resolves common Node.js scheduling challenges such as timer drift, concurrent execution overlap, unhandled exceptions crashing the process, timezone/DST inaccuracies, and zombie timers during hot reload or process shutdown.
+
+Both **Functional** and **Class-Based (OOP)** paradigms are fully supported with complete feature parity.
+
+---
+
+## File Conventions & Auto-Discovery
+
+ExisJS auto-mounts cron jobs using two straightforward conventions:
+
+1. **Single-File Management (`src/http/cron.ts` or `src/http/cron.js`)**:
+   Define and manage all your scheduled tasks in a single file located at `src/http/cron.ts` (or inside route slices such as `src/http/admin/cron.ts`). Multiple jobs can be exported using named exports, a default export, or an array of jobs.
+
+2. **Dedicated Directory (`src/cron/*`)**:
+   Organize distinct tasks into separate files inside `src/cron/` (e.g. `src/cron/sync.ts`, `src/cron/reports.ts`). Every file inside `src/cron/` is automatically registered upon application boot.
+
+---
+
+## 1. Functional Paradigm (`cron`)
+
+Import `cron` from `exisjs/cron` to define scheduled tasks.
+
+### Single-File Multi-Job Example
+
+Manage multiple jobs within `src/http/cron.ts`:
+
+```typescript filename="src/http/cron.ts"
+import { cron, CronExpression } from 'exisjs/cron'
+
+// Job 1: Nightly synchronization
+export const syncJob = cron({
+  name: 'nightly-sync',
+  schedule: CronExpression.EVERY_DAY_AT_MIDNIGHT,
+  timezone: 'UTC',
+  preventOverlap: true,
+  retries: 2,
+  retryDelayMs: 3000,
+  async run({ app, log }) {
+    log.info('Executing nightly sync...')
+  },
+  onError(err, { log }) {
+    log.error({ err }, 'Nightly sync failed after retries')
+  }
+})
+
+// Job 2: Frequent polling using human-readable duration
+export const pollJob = cron.every('5 minutes', async ({ log }) => {
+  log.info('Checking external queue...')
+})
+
+// Job 3: Recurring millisecond interval
+export const heartbeat = cron.interval(30_000, async ({ log }) => {
+  log.info('System heartbeat active')
+})
+
+// Job 4: Startup delayed task (runs 5 seconds after server boots)
+export const warmup = cron.timeout(5_000, async ({ app, log }) => {
+  log.info('Pre-warming cache...')
+})
+```
+
+### Dedicated File Example
+
+```typescript filename="src/cron/cleanup.ts"
+import { cron, CronExpression } from 'exisjs/cron'
+
+export default cron({
+  name: 'db-cleanup',
+  schedule: CronExpression.EVERY_DAY_AT_2AM,
+  timezone: 'America/New_York',
+  preventOverlap: true,
+  async run({ log }) {
+    log.info('Purging stale database records...')
+  }
+})
+```
+
+---
+
+## 2. Class-Based (OOP) Paradigm (`@Cron`)
+
+In the OOP paradigm, methods on any `@Injectable()` service or class can be scheduled using decorators from `exisjs/decorators` with full **Dependency Injection** support.
+
+```typescript filename="src/cron/cleanup.ts"
+import { Injectable, Cron, Interval, TimeoutTask, CronExpression } from 'exisjs/decorators'
+import { DatabaseService } from '../services/database.service'
+import { LoggerService } from '../services/logger.service'
+
+@Injectable()
+export default class CleanupService {
+  constructor(
+    private db: DatabaseService,
+    private logger: LoggerService
+  ) {}
+
+  @Cron(CronExpression.EVERY_DAY_AT_MIDNIGHT, {
+    name: 'nightly-purge',
+    timezone: 'UTC',
+    preventOverlap: true,
+  })
+  async purgeOldSessions() {
+    this.logger.info('Purging expired user sessions...')
+    await this.db.deleteExpiredSessions()
+  }
+
+  @Interval(60_000, { name: 'health-ping' })
+  async checkDatabaseHealth() {
+    await this.db.ping()
+  }
+
+  @TimeoutTask(5_000, { name: 'cache-warmup' })
+  async warmupCache() {
+    this.logger.info('Pre-warming cache...')
+  }
+}
+```
+
+---
+
+## 3. Core Reliability Features
+
+### Overlap Prevention (`preventOverlap: true`)
+Standard timers trigger subsequent ticks even if the current execution is stalled, leading to connection exhaustion and database lock contention. With `preventOverlap: true` (default: `true`), ExisJS locks execution during active jobs and skips overlapping executions until the current run completes.
+
+### Error Isolation Sandbox
+Exceptions thrown inside cron handlers are caught within an isolated execution boundary. An error in a background task will never crash the HTTP server or stop subsequent cron triggers. Errors are logged and forwarded to an optional `onError(err, context)` hook for monitoring integration (e.g. Sentry, Datadog).
+
+### IANA Timezones & Daylight Saving Time (DST)
+Supports standard IANA timezones (e.g. `'America/New_York'`, `'Asia/Kolkata'`, `'Europe/London'`, `'UTC'`). Next execution dates are computed accurately across DST transitions using cached native `Intl.DateTimeFormat` evaluations.
+
+---
+
+## 4. Programmatic Runtime Management (`app.cron`)
+
+You can inspect, pause, resume, or trigger jobs dynamically at runtime via `app.cron`:
+
+```typescript filename="src/http/admin/cron/route.ts"
+import { controller, route } from 'exisjs/router'
+
+export default controller({
+  // Query status and metrics of all registered jobs
+  listJobs: route.get('/', async ({ app }) => {
+    return {
+      jobs: app.cron.status()
+    }
+  }),
+
+  // Manually trigger a scheduled job on demand
+  triggerJob: route.post('/:name/trigger', async ({ app, params }) => {
+    const result = await app.cron.trigger(params.name)
+    return { success: true, result }
+  }),
+
+  // Pause a job
+  pauseJob: route.post('/:name/pause', async ({ app, params }) => {
+    app.cron.pause(params.name)
+    return { success: true, message: `Job ${params.name} paused` }
+  }),
+
+  // Resume a paused job
+  resumeJob: route.post('/:name/resume', async ({ app, params }) => {
+    app.cron.resume(params.name)
+    return { success: true, message: `Job ${params.name} resumed` }
+  }),
+})
+```
+
+---
+
+## 5. Graceful Shutdown & Draining
+
+When the application receives a shutdown signal (`SIGINT`, `SIGTERM`, or `app.close()`):
+1. The scheduler stops scheduling future ticks immediately.
+2. Active timers are unreferenced (`unref()`).
+3. Running tasks are allowed to finish within the configured drain window (default: 5000ms) before the process terminates.
+
+---
+
+## 6. CLI Scaffolding
+
+Generate cron job files using the ExisJS CLI:
+
+```bash
+# Functional Job (generates src/cron/cleanup.ts)
+npx exis generate cron cleanup
+
+# Class-Based Job (generates src/cron/cleanup.ts with @Injectable & @Cron)
+npx exis generate cron cleanup --oop
+```

package/dist/docs/content/decorators.mdx

@@ -134,6 +134,12 @@ export default class UsersController {
 - `@Param(nameOrPipe?)` — Extracts a route path param (e.g. `:id`).
 - `@QueryParam(nameOrPipe?)` / `@Query(nameOrPipe?)` — Extracts a query parameter from the URL query string.
 - `@Headers(nameOrPipe?)` — Extracts a request header by name.
+- `@Cookies(nameOrPipe?)` / `@Cookie(nameOrPipe?)` — Injects incoming parsed cookies or a specific cookie value.
+- `@State(keyOrPipe?)` — Injects request state from execution context or middleware.
+- `@AppCtx()` — Injects the root ExisJS Application instance.
+- `@Fields(nameOrPipe?)` — Injects non-file multipart form fields.
+- `@UploadedFile(nameOrPipe?)` — Injects a single uploaded file.
+- `@UploadedFiles(nameOrPipe?)` — Injects multiple uploaded files.
 - `@HostParam(nameOrPipe?)` — Extracts a host subdomain parameter.
 - `@Req()` — Injects the raw request object.
 - `@Res(options?)` — Injects the response object (e.g. `{ passthrough: true }`).
@@ -150,16 +156,19 @@ export default class UsersController {
 
 ## 4. Middleware & Pipeline Decorators
 
-You can bind middlewares, guards, interceptors, and exception filters to controllers or route methods using the unified `@Use()` decorator:
+You can bind middlewares, guards, interceptors, and exception filters to controllers or route methods using first-class decorators:
 
 ```typescript filename="src/http/checkout/route.ts"
-import { Controller, Post, Use, Idempotent } from 'exisjs/decorators'
+import { Controller, Post, Use, Idempotent, RateLimit, Cors, Timeout } from 'exisjs/decorators'
 import { requireAuth } from '../../middleware/auth'
 
 @Controller('/checkout')
 @Use(requireAuth) // Applies to all routes in this controller
+@Cors({ origin: 'https://app.yourdomain.com' })
+@RateLimit({ max: 10, windowMs: 60000 })
 export default class CheckoutController {
   @Post('/')
+  @Timeout(30000)
   @Idempotent({ ttlMs: 86400000 }) // In-memory off-heap idempotency protection
   async processPayment() {
     return { success: true }
@@ -169,7 +178,15 @@ export default class CheckoutController {
 
 ### Available Lifecycle & Middleware Decorators
 - `@Use(...items)` — Unified decorator that attaches middlewares, guards (`canActivate`), interceptors (`intercept`), or exception filters (`catch`) to a class or method.
-- `@Idempotent(options?)` — Caches responses based on the `Idempotency-Key` header using off-heap native memory.
+- `@Timeout(ms: number | TimeoutOptions)` — Overrides the request timeout for a class or method.
+- `@Idempotent(options?)` — Caches responses based on the `Idempotency-Key` header using native in-memory off-heap storage.
+- `@RateLimit(options?)` — Enforces request rate limits on a controller class or route method.
+- `@Cors(options?)` — Configures Cross-Origin Resource Sharing rules on a controller class or route method.
+- `@IpFilter(options)` — Enforces IP/CIDR allowlist and denylist.
+- `@Compress()` — Enables automatic response compression (Gzip/Brotli).
+- `@Dedupe(options)` — Deduplicates concurrent identical requests sharing the same key.
+- `@UseUpload(options)` / `@Upload(options)` — Configures multipart file upload handling.
+- `@BlockProbes(options?)` — Intercepts scanner exploit probes (`.env`, `/.git`, `/.DS_Store`) and blackholes them without log noise.
 
 ---
 
@@ -229,7 +246,8 @@ export class UserService {
 You can inject dependencies using tokens or classes, and mark optional dependencies with `@Optional()`:
 
 ```typescript filename="src/http/users/route.ts"
-import { Controller, Get, Param, Inject, Optional } from 'exisjs/decorators'
+import { Controller, Get, Param } from 'exisjs/decorators'
+import { Inject, Optional } from 'exisjs/di'
 import { UserService } from './service'
 
 @Controller('/users')

package/dist/docs/content/errors.mdx

@@ -163,40 +163,89 @@ ExisJS provides mechanisms for granular and centralized error handling.
 
 ### 1. Framework-Level Exception Handler (`src/http/error.ts`)
 
-Instead of writing manual `try/catch` blocks in every route or calling `app.onError` inside `server.ts`, ExisJS natively discovers and auto-mounts `src/http/error.ts` (or `error.js`).
+Instead of writing manual `try/catch` blocks in every route or wiring `app.onError` inside `server.ts`, ExisJS provides a dedicated file convention: **`src/http/error.ts`** (or `src/http/*.error.ts`).
 
-Export an `onError(err, req, res)` function to centrally format, log, and respond to all unhandled exceptions and validation errors:
+When `src/http/error.ts` is present, ExisJS automatically discovers and mounts it during application boot as the global exception interceptor. Any uncaught exception, thrown `HttpError`, or validation failure anywhere in your application is routed to this file.
+
+#### Functional Paradigm
 
 ```typescript filename="src/http/error.ts"
 import type { Request, Response } from 'exisjs'
+import { isDev } from 'exisjs/config'
 
 /**
- * Global Exception Handler for ExisJS
- * Auto-mounted at startup to intercept all unhandled exceptions.
+ * Global Framework Exception Handler
+ * Auto-mounted at startup to intercept all unhandled exceptions and validation errors.
  */
 export function onError(err: any, req: Request, res: Response) {
   const status = err.statusCode || err.status || 500
+  const isOperational = Boolean(err.isOperational || err.statusCode < 500)
+
+  // 1. Log unexpected crashes in production to external APM (Sentry, Datadog, Axiom)
+  if (!isOperational && !isDev) {
+    // e.g. Sentry.captureException(err, { extra: { path: req.path, method: req.method } })
+    req.log.error({ err }, '[Fatal] Unhandled Server Exception')
+  }
 
-  // Centralized structured error response
+  // 2. Format a unified, standard error envelope for client applications
   res.status(status).json({
     success: false,
     error: {
-      code: err.code || 'INTERNAL_ERROR',
+      code: err.code || (status === 500 ? 'INTERNAL_SERVER_ERROR' : 'ERROR'),
       message: err.message || 'Internal Server Error',
+      ...(err.details ? { details: err.details } : {}),
+      ...(err.errors ? { errors: err.errors } : {}),
       path: req.path,
+      timestamp: new Date().toISOString(),
     },
   })
 }
 ```
 
+#### Class-Based (OOP) Paradigm
+
+```typescript filename="src/http/error.ts"
+import type { Request, Response } from 'exisjs'
+import { isDev } from 'exisjs/config'
+
+export default class GlobalErrorHandler {
+  onError(err: any, req: Request, res: Response) {
+    const status = err.statusCode || err.status || 500
+    const isOperational = Boolean(err.isOperational || err.statusCode < 500)
+
+    if (!isOperational && !isDev) {
+      req.log.error({ err }, '[Fatal] Unhandled Server Exception')
+    }
+
+    res.status(status).json({
+      success: false,
+      error: {
+        code: err.code || (status === 500 ? 'INTERNAL_SERVER_ERROR' : 'ERROR'),
+        message: err.message || 'Internal Server Error',
+        ...(err.details ? { details: err.details } : {}),
+        path: req.path,
+        timestamp: new Date().toISOString(),
+      },
+    })
+  }
+}
+```
+
 > [!TIP]
-> You can also scaffold this file instantly via the CLI:
+> **Scaffold with CLI**: You can generate this file instantly using the ExisJS CLI:
 > ```bash
-> exis generate error
+> npx exis generate error
 > # or shorthand:
-> exis g error
+> npx exis g error
 > ```
 
+#### What `src/http/error.ts` Intercepts:
+- **`HttpError` instances**: (e.g. `throw HttpError.notFound()`, `throw HttpError.unauthorized()`).
+- **Validation failures**: Zod, Tex, or Yup validation rejections automatically pass structured `err.errors` and `err.details`.
+- **Database / Network exceptions**: Postgres connection failures, timeout rejections, and third-party API errors.
+- **Syntax errors**: Malformed JSON bodies or bad request payloads.
+
+
 ### 2. Exception Filters (`catchError`)
 
 ExisJS allows you to create **Exception Filters** to globally intercept specific types of errors. 

package/dist/docs/content/introduction.mdx

@@ -20,7 +20,7 @@ Exis aims to provide that out-of-the-box application architecture for backends:
 The fastest way to start is the Exis CLI, which scaffolds a new project directory with the core files and a conventional base structure already in place. This is the recommended path for first-time users.
 
 <div className="my-6 max-w-lg">
-  <CopyCommand command="npx @exisjs/create@latest my-backend" />
+  <CopyCommand command="npm create exisjs@latest my-backend" />
 </div>
 
 <Hint>
@@ -43,12 +43,12 @@ export default controller({
   getUsers: route.get('/', {
     handle(req) {
       // Return a realistic response structure
-      return { 
+      return {
         data: [
           { id: 1, name: 'Alice' },
-          { id: 2, name: 'Bob' }
+          { id: 2, name: 'Bob' },
         ],
-        total: 2 
+        total: 2,
       }
     },
   }),
@@ -66,12 +66,12 @@ export default class UsersController {
   @Get('/')
   getUsers(@Req() req: Request) {
     // Return a realistic response structure
-    return { 
+    return {
       data: [
         { id: 1, name: 'Alice' },
-        { id: 2, name: 'Bob' }
+        { id: 2, name: 'Bob' },
       ],
-      total: 2 
+      total: 2,
     }
   }
 }