exisjs 0.7.5 → 0.7.7

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

@@ -68,6 +68,10 @@ Parameter decorators automatically extract data from the incoming request and in
 - `@Param(nameOrPipe?)`: Injects a URL path parameter (e.g., `id` from `/:id`).
 - `@Headers(nameOrPipe?)`: Injects an HTTP header by name.
 - `@QueryParam(nameOrPipe?)` / `@Query(nameOrPipe?)`: Injects a URL query parameter (e.g., `?search=term`).
+- `@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()`: Injects the uploaded file (`req.file`) into the method argument.
 - `@UploadedFiles()`: Injects the uploaded files array or dictionary (`req.files`) into the method argument.
 - `@HostParam(nameOrPipe?)`: Injects a subdomain parameter.
@@ -83,8 +87,14 @@ Parameter decorators automatically extract data from the incoming request and in
 
 - `@Use(...middlewaresOrGuardsOrInterceptorsOrFilters)`: Unified decorator that binds middlewares, guards (`canActivate`), interceptors (`intercept`), or exception filters (`catch`) to a controller class or method.
 - `@Upload(fieldName, options?)` / `@UseUpload(...)`: Configures multipart file upload handling for a method, populating `@UploadedFile()` or `@UploadedFiles()`.
-- `@Timeout(ms: number | TimeoutOptions)`: Overrides the request timeout for this method (e.g. `@Timeout(120000)`). Passing `0` disables timeouts for long-running streaming or exports.
-- `@Idempotent(options?)`: Caches responses based on the `Idempotency-Key` header using native in-memory off-heap storage.
+- `@Timeout(ms: number | TimeoutOptions)`: Overrides the request timeout for a class or method (e.g. `@Timeout(120000)`). Passing `0` disables timeouts for long-running streaming or exports.
+- `@Idempotent(options?)`: Caches responses based on the `Idempotency-Key` header using native in-memory off-heap storage. Works at class and method level.
+- `@RateLimit(options?)`: Enforces rate limits (e.g. `@RateLimit({ max: 100, windowMs: 60000 })`) at class or method level.
+- `@Cors(options?)`: Enforces Cross-Origin Resource Sharing rules at class or method level.
+- `@IpFilter(options)`: Enforces CIDR and IP allow/deny lists at class or method level.
+- `@Compress()`: Enables automatic Gzip and Brotli compression on responses.
+- `@Dedupe(options)`: Deduplicates concurrent identical requests sharing the same key.
+- `@BlockProbes(options?)`: Intercepts vulnerability scanner probes (`.env`, `/.git`, `/.DS_Store`) and blackholes them without triggering log noise.
 
 ---
 
@@ -108,8 +118,16 @@ Parameter decorators automatically extract data from the incoming request and in
 
 - `@Module({ imports?, controllers?, providers?, exports? })`: OOP class decorator equivalent to `defineModule()` for structuring application modules.
 - `@Injectable(options?)`: Marks a service class as an IoC provider managed by the container. Supports `{ scope: 'singleton' | 'request' | 'transient' }`.
-- `@Inject(token)`: Constructor parameter decorator for injecting dependencies by class, string, or symbol token.
-- `@Optional()`: Constructor parameter decorator resolving missing dependencies to `undefined` without throwing.
+- `@Inject(token)`: Constructor parameter decorator from `exisjs/di` for injecting dependencies by class, string, or symbol token.
+- `@Optional()`: Constructor parameter decorator from `exisjs/di` resolving missing dependencies to `undefined` without throwing.
 - `@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)`. 
@@ -170,3 +214,47 @@ app.use((err, req, res, next) => {
 ExisJS natively intercepts and handles Promise rejections at the core routing level. 
 
 Unlike Express, you do **not** need to wrap your routes in an `asyncHandler`. However, for strict compatibility with older Express middleware ecosystems, `exisjs/error` does export an `asyncHandler` wrapper. Note that using it in ExisJS is entirely redundant and merely adds unnecessary Promise allocations.
+
+---
+
+## Developer Error Formatting & Overlay Utilities
+
+`exisjs/error` also exports powerful error diagnostic utilities that you can use in custom error handlers, CLI scripts, background workers, and testing:
+
+```typescript
+import {
+  formatDevError,
+  renderDevErrorToString,
+  categorizeError,
+  generateErrorHint,
+  buildCodeFrame,
+  stripInternalStackFrames,
+  devErrorResponse,
+  type ParsedError,
+} from 'exisjs/error'
+```
+
+### Utility Functions
+
+| Function | Signature | Description |
+| :--- | :--- | :--- |
+| `formatDevError` | `(err: Error, optionsOrFile?: string \| { routeFile?: string; title?: string }) => void` | Prints a formatted terminal error envelope with code frames and actionable hints |
+| `renderDevErrorToString` | `(err: Error, optionsOrFile?: ...) => string` | Returns the formatted terminal error envelope string |
+| `categorizeError` | `(err: Error) => string` | Intelligently classifies errors into domain categories (`Validation Schema Error`, `Environment Configuration Error`, etc.) |
+| `generateErrorHint` | `(err: Error) => string \| null` | Generates actionable hints for common coding mistakes |
+| `buildCodeFrame` | `(filePath: string, line: number, col?: number) => string` | Builds a source code snippet visualizer with gutter line numbers and caret indicator |
+| `stripInternalStackFrames` | `(stack?: string) => string[]` | Strips internal Node.js and framework runtime stack frames |
+| `devErrorResponse` | `(err: Error, routeFile?: string) => object` | Generates a structured developer error envelope payload for JSON API responses |
+
+### Example: Custom Worker or Script Error Handling
+
+```typescript filename="src/workers/import-csv.ts"
+import { formatDevError, categorizeError } from 'exisjs/error'
+
+try {
+  await processCsvImport(filePath)
+} catch (err: any) {
+  // Prints a clean code frame with line numbers and actionable hints directly in terminal
+  formatDevError(err, { routeFile: filePath, title: categorizeError(err) })
+}
+```