exisjs 0.7.6 → 0.7.8

package/dist/decorators/routing.d.ts

@@ -1,37 +1,102 @@
 import type { HttpMethod, RouteSchema } from '../types';
 export declare function createMethodDecorator(method: HttpMethod): (path?: string, schema?: RouteSchema<any, any, any, any>) => any;
 /**
- * Marks a method as a GET route handler.
+ * Marks a controller method as an HTTP GET route handler.
  *
- * Example:
+ * @param path Optional route path relative to controller prefix
+ * @param schema Optional validation schema
  *
- *     @Get('/:id')
- *     getUser(@Param('id') id: string) { return { id }; }
- *
- * @param {string} [path] The route path
- * @param {RouteSchema} [schema] Optional validation schema
- * @public
+ * @example
+ * ```ts
+ * @Controller('/users')
+ * export class UserController {
+ *   @Get('/:id')
+ *   getUser(@Param('id') id: string) {
+ *     return { id }
+ *   }
+ * }
+ * ```
  */
 export declare const Get: (path?: string, schema?: RouteSchema<any, any, any, any>) => any;
 /**
- * Marks a method as a POST route handler.
- *
- * Example:
+ * Marks a controller method as an HTTP POST route handler.
  *
- *     @Post('/', { body: tex.object({ name: tex.string() }) })
- *     createUser(@Body() body: any) { return body; }
+ * @param path Optional route path relative to controller prefix
+ * @param schema Optional validation schema
  *
- * @param {string} [path] The route path
- * @param {RouteSchema} [schema] Optional validation schema
- * @public
+ * @example
+ * ```ts
+ * @Controller('/users')
+ * export class UserController {
+ *   @Post('/')
+ *   createUser(@Body() body: CreateUserDto) {
+ *     return { created: body.name }
+ *   }
+ * }
+ * ```
  */
 export declare const Post: (path?: string, schema?: RouteSchema<any, any, any, any>) => any;
+/**
+ * Marks a controller method as an HTTP PUT route handler.
+ *
+ * @param path Optional route path relative to controller prefix
+ * @param schema Optional validation schema
+ *
+ * @example
+ * ```ts
+ * @Controller('/users')
+ * export class UserController {
+ *   @Put('/:id')
+ *   updateUser(@Param('id') id: string, @Body() body: UpdateUserDto) {
+ *     return { updated: id }
+ *   }
+ * }
+ * ```
+ */
 export declare const Put: (path?: string, schema?: RouteSchema<any, any, any, any>) => any;
+/**
+ * Marks a controller method as an HTTP PATCH route handler.
+ *
+ * @param path Optional route path relative to controller prefix
+ * @param schema Optional validation schema
+ */
 export declare const Patch: (path?: string, schema?: RouteSchema<any, any, any, any>) => any;
+/**
+ * Marks a controller method as an HTTP DELETE route handler.
+ *
+ * @param path Optional route path relative to controller prefix
+ * @param schema Optional validation schema
+ *
+ * @example
+ * ```ts
+ * @Controller('/users')
+ * export class UserController {
+ *   @Delete('/:id')
+ *   deleteUser(@Param('id') id: string) {
+ *     return { deleted: true }
+ *   }
+ * }
+ * ```
+ */
 export declare const Delete: (path?: string, schema?: RouteSchema<any, any, any, any>) => any;
+/**
+ * Marks a controller method as an HTTP OPTIONS route handler.
+ */
 export declare const Options: (path?: string, schema?: RouteSchema<any, any, any, any>) => any;
+/**
+ * Marks a controller method as an HTTP HEAD route handler.
+ */
 export declare const Head: (path?: string, schema?: RouteSchema<any, any, any, any>) => any;
+/**
+ * Marks a controller method to handle any HTTP method (GET, POST, PUT, DELETE, PATCH, etc.).
+ */
 export declare const All: (path?: string, schema?: RouteSchema<any, any, any, any>) => any;
+/**
+ * Marks a controller method as an HTTP CONNECT route handler.
+ */
 export declare const Connect: (path?: string, schema?: RouteSchema<any, any, any, any>) => any;
+/**
+ * Marks a controller method as an HTTP TRACE route handler.
+ */
 export declare const Trace: (path?: string, schema?: RouteSchema<any, any, any, any>) => any;
 //# sourceMappingURL=routing.d.ts.map

package/dist/decorators/routing.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"routing.d.ts","sourceRoot":"","sources":["../../src/decorators/routing.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,UAAU,CAAA;AAKvD,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,UAAU,IACrC,aAAS,EAAE,SAAS,WAAW,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,KAAG,GAAG,CAoC3E;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,GAAG,2BAlDuB,WAAW,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,KAAG,GAkD1B,CAAA;AAE/C;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,IAAI,2BAhEsB,WAAW,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,KAAG,GAgExB,CAAA;AACjD,eAAO,MAAM,GAAG,2BAjEuB,WAAW,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,KAAG,GAiE1B,CAAA;AAC/C,eAAO,MAAM,KAAK,2BAlEqB,WAAW,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,KAAG,GAkEtB,CAAA;AACnD,eAAO,MAAM,MAAM,2BAnEoB,WAAW,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,KAAG,GAmEpB,CAAA;AACrD,eAAO,MAAM,OAAO,2BApEmB,WAAW,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,KAAG,GAoElB,CAAA;AACvD,eAAO,MAAM,IAAI,2BArEsB,WAAW,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,KAAG,GAqExB,CAAA;AACjD,eAAO,MAAM,GAAG,2BAtEuB,WAAW,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,KAAG,GAsE1B,CAAA;AAC/C,eAAO,MAAM,OAAO,2BAvEmB,WAAW,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,KAAG,GAuElB,CAAA;AACvD,eAAO,MAAM,KAAK,2BAxEqB,WAAW,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,KAAG,GAwEtB,CAAA"}
+{"version":3,"file":"routing.d.ts","sourceRoot":"","sources":["../../src/decorators/routing.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,UAAU,CAAA;AAKvD,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,UAAU,IACrC,aAAS,EAAE,SAAS,WAAW,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,KAAG,GAAG,CAoC3E;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,GAAG,2BAvDuB,WAAW,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,KAAG,GAuD1B,CAAA;AAE/C;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,IAAI,2BA1EsB,WAAW,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,KAAG,GA0ExB,CAAA;AAEjD;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,GAAG,2BA7FuB,WAAW,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,KAAG,GA6F1B,CAAA;AAE/C;;;;;GAKG;AACH,eAAO,MAAM,KAAK,2BArGqB,WAAW,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,KAAG,GAqGtB,CAAA;AAEnD;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,MAAM,2BAxHoB,WAAW,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,KAAG,GAwHpB,CAAA;AAErD;;GAEG;AACH,eAAO,MAAM,OAAO,2BA7HmB,WAAW,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,KAAG,GA6HlB,CAAA;AAEvD;;GAEG;AACH,eAAO,MAAM,IAAI,2BAlIsB,WAAW,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,KAAG,GAkIxB,CAAA;AAEjD;;GAEG;AACH,eAAO,MAAM,GAAG,2BAvIuB,WAAW,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,KAAG,GAuI1B,CAAA;AAE/C;;GAEG;AACH,eAAO,MAAM,OAAO,2BA5ImB,WAAW,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,KAAG,GA4IlB,CAAA;AAEvD;;GAEG;AACH,eAAO,MAAM,KAAK,2BAjJqB,WAAW,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,KAAG,GAiJtB,CAAA"}

package/dist/decorators/routing.js

@@ -36,37 +36,102 @@ function createMethodDecorator(method) {
     };
 }
 /**
- * Marks a method as a GET route handler.
+ * Marks a controller method as an HTTP GET route handler.
  *
- * Example:
+ * @param path Optional route path relative to controller prefix
+ * @param schema Optional validation schema
  *
- *     @Get('/:id')
- *     getUser(@Param('id') id: string) { return { id }; }
- *
- * @param {string} [path] The route path
- * @param {RouteSchema} [schema] Optional validation schema
- * @public
+ * @example
+ * ```ts
+ * @Controller('/users')
+ * export class UserController {
+ *   @Get('/:id')
+ *   getUser(@Param('id') id: string) {
+ *     return { id }
+ *   }
+ * }
+ * ```
  */
 exports.Get = createMethodDecorator('GET');
 /**
- * Marks a method as a POST route handler.
- *
- * Example:
+ * Marks a controller method as an HTTP POST route handler.
  *
- *     @Post('/', { body: tex.object({ name: tex.string() }) })
- *     createUser(@Body() body: any) { return body; }
+ * @param path Optional route path relative to controller prefix
+ * @param schema Optional validation schema
  *
- * @param {string} [path] The route path
- * @param {RouteSchema} [schema] Optional validation schema
- * @public
+ * @example
+ * ```ts
+ * @Controller('/users')
+ * export class UserController {
+ *   @Post('/')
+ *   createUser(@Body() body: CreateUserDto) {
+ *     return { created: body.name }
+ *   }
+ * }
+ * ```
  */
 exports.Post = createMethodDecorator('POST');
+/**
+ * Marks a controller method as an HTTP PUT route handler.
+ *
+ * @param path Optional route path relative to controller prefix
+ * @param schema Optional validation schema
+ *
+ * @example
+ * ```ts
+ * @Controller('/users')
+ * export class UserController {
+ *   @Put('/:id')
+ *   updateUser(@Param('id') id: string, @Body() body: UpdateUserDto) {
+ *     return { updated: id }
+ *   }
+ * }
+ * ```
+ */
 exports.Put = createMethodDecorator('PUT');
+/**
+ * Marks a controller method as an HTTP PATCH route handler.
+ *
+ * @param path Optional route path relative to controller prefix
+ * @param schema Optional validation schema
+ */
 exports.Patch = createMethodDecorator('PATCH');
+/**
+ * Marks a controller method as an HTTP DELETE route handler.
+ *
+ * @param path Optional route path relative to controller prefix
+ * @param schema Optional validation schema
+ *
+ * @example
+ * ```ts
+ * @Controller('/users')
+ * export class UserController {
+ *   @Delete('/:id')
+ *   deleteUser(@Param('id') id: string) {
+ *     return { deleted: true }
+ *   }
+ * }
+ * ```
+ */
 exports.Delete = createMethodDecorator('DELETE');
+/**
+ * Marks a controller method as an HTTP OPTIONS route handler.
+ */
 exports.Options = createMethodDecorator('OPTIONS');
+/**
+ * Marks a controller method as an HTTP HEAD route handler.
+ */
 exports.Head = createMethodDecorator('HEAD');
+/**
+ * Marks a controller method to handle any HTTP method (GET, POST, PUT, DELETE, PATCH, etc.).
+ */
 exports.All = createMethodDecorator('ALL');
+/**
+ * Marks a controller method as an HTTP CONNECT route handler.
+ */
 exports.Connect = createMethodDecorator('CONNECT');
+/**
+ * Marks a controller method as an HTTP TRACE route handler.
+ */
 exports.Trace = createMethodDecorator('TRACE');
 //# sourceMappingURL=routing.js.map

package/dist/decorators/routing.js.map

@@ -1 +1 @@
-{"version":3,"file":"routing.js","sourceRoot":"","sources":["../../src/decorators/routing.ts"],"names":[],"mappings":";;;AAKA,sDAqCC;AAzCD,2CAAwD;AACxD,8CAAgD;AAChD,sCAAkC;AAElC,SAAgB,qBAAqB,CAAC,MAAkB;IACtD,OAAO,UAAU,IAAI,GAAG,EAAE,EAAE,MAAwC;QAClE,IAAI,MAAM,KAAK,KAAK,IAAI,MAAM,EAAE,IAAI,EAAE,CAAC;YACrC,eAAM,CAAC,IAAI,CACT,cAAc,IAAI,+DAA+D,CAClF,CAAA;QACH,CAAC;QAED,OAAO,UACL,MAAW,EACX,oBAA4C,EAC5C,UAAqC;YAErC,IACE,OAAO,oBAAoB,KAAK,QAAQ;gBACxC,oBAAoB,KAAK,IAAI;gBAC7B,MAAM,IAAI,oBAAoB,EAC9B,CAAC;gBACD,mCAAmC;gBACnC,yBAAc,CAAC,GAAG,CAAC,MAAM,EAAE,sBAAU,EAAE;oBACrC,MAAM;oBACN,IAAI;oBACJ,MAAM;iBACP,CAAC,CAAA;YACJ,CAAC;iBAAM,CAAC;gBACN,yCAAyC;gBACzC,MAAM,KAAK,GAAG,OAAO,MAAM,KAAK,UAAU,CAAC,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAA;gBACtE,MAAM,IAAI,GAAG,oBAAoB,IAAI,UAAU,EAAE,IAAI,CAAA;gBACrD,yBAAc,CAAC,IAAI,CAAC,KAAK,EAAE,0BAAc,EAAE;oBACzC,MAAM;oBACN,IAAI;oBACJ,MAAM;oBACN,WAAW,EAAE,IAAI;iBAClB,CAAC,CAAA;YACJ,CAAC;QACH,CAAC,CAAA;IACH,CAAC,CAAA;AACH,CAAC;AAED;;;;;;;;;;;GAWG;AACU,QAAA,GAAG,GAAG,qBAAqB,CAAC,KAAK,CAAC,CAAA;AAE/C;;;;;;;;;;;GAWG;AACU,QAAA,IAAI,GAAG,qBAAqB,CAAC,MAAM,CAAC,CAAA;AACpC,QAAA,GAAG,GAAG,qBAAqB,CAAC,KAAK,CAAC,CAAA;AAClC,QAAA,KAAK,GAAG,qBAAqB,CAAC,OAAO,CAAC,CAAA;AACtC,QAAA,MAAM,GAAG,qBAAqB,CAAC,QAAQ,CAAC,CAAA;AACxC,QAAA,OAAO,GAAG,qBAAqB,CAAC,SAAS,CAAC,CAAA;AAC1C,QAAA,IAAI,GAAG,qBAAqB,CAAC,MAAM,CAAC,CAAA;AACpC,QAAA,GAAG,GAAG,qBAAqB,CAAC,KAAK,CAAC,CAAA;AAClC,QAAA,OAAO,GAAG,qBAAqB,CAAC,SAAS,CAAC,CAAA;AAC1C,QAAA,KAAK,GAAG,qBAAqB,CAAC,OAAO,CAAC,CAAA"}
+{"version":3,"file":"routing.js","sourceRoot":"","sources":["../../src/decorators/routing.ts"],"names":[],"mappings":";;;AAKA,sDAqCC;AAzCD,2CAAwD;AACxD,8CAAgD;AAChD,sCAAkC;AAElC,SAAgB,qBAAqB,CAAC,MAAkB;IACtD,OAAO,UAAU,IAAI,GAAG,EAAE,EAAE,MAAwC;QAClE,IAAI,MAAM,KAAK,KAAK,IAAI,MAAM,EAAE,IAAI,EAAE,CAAC;YACrC,eAAM,CAAC,IAAI,CACT,cAAc,IAAI,+DAA+D,CAClF,CAAA;QACH,CAAC;QAED,OAAO,UACL,MAAW,EACX,oBAA4C,EAC5C,UAAqC;YAErC,IACE,OAAO,oBAAoB,KAAK,QAAQ;gBACxC,oBAAoB,KAAK,IAAI;gBAC7B,MAAM,IAAI,oBAAoB,EAC9B,CAAC;gBACD,mCAAmC;gBACnC,yBAAc,CAAC,GAAG,CAAC,MAAM,EAAE,sBAAU,EAAE;oBACrC,MAAM;oBACN,IAAI;oBACJ,MAAM;iBACP,CAAC,CAAA;YACJ,CAAC;iBAAM,CAAC;gBACN,yCAAyC;gBACzC,MAAM,KAAK,GAAG,OAAO,MAAM,KAAK,UAAU,CAAC,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAA;gBACtE,MAAM,IAAI,GAAG,oBAAoB,IAAI,UAAU,EAAE,IAAI,CAAA;gBACrD,yBAAc,CAAC,IAAI,CAAC,KAAK,EAAE,0BAAc,EAAE;oBACzC,MAAM;oBACN,IAAI;oBACJ,MAAM;oBACN,WAAW,EAAE,IAAI;iBAClB,CAAC,CAAA;YACJ,CAAC;QACH,CAAC,CAAA;IACH,CAAC,CAAA;AACH,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACU,QAAA,GAAG,GAAG,qBAAqB,CAAC,KAAK,CAAC,CAAA;AAE/C;;;;;;;;;;;;;;;;GAgBG;AACU,QAAA,IAAI,GAAG,qBAAqB,CAAC,MAAM,CAAC,CAAA;AAEjD;;;;;;;;;;;;;;;;GAgBG;AACU,QAAA,GAAG,GAAG,qBAAqB,CAAC,KAAK,CAAC,CAAA;AAE/C;;;;;GAKG;AACU,QAAA,KAAK,GAAG,qBAAqB,CAAC,OAAO,CAAC,CAAA;AAEnD;;;;;;;;;;;;;;;;GAgBG;AACU,QAAA,MAAM,GAAG,qBAAqB,CAAC,QAAQ,CAAC,CAAA;AAErD;;GAEG;AACU,QAAA,OAAO,GAAG,qBAAqB,CAAC,SAAS,CAAC,CAAA;AAEvD;;GAEG;AACU,QAAA,IAAI,GAAG,qBAAqB,CAAC,MAAM,CAAC,CAAA;AAEjD;;GAEG;AACU,QAAA,GAAG,GAAG,qBAAqB,CAAC,KAAK,CAAC,CAAA;AAE/C;;GAEG;AACU,QAAA,OAAO,GAAG,qBAAqB,CAAC,SAAS,CAAC,CAAA;AAEvD;;GAEG;AACU,QAAA,KAAK,GAAG,qBAAqB,CAAC,OAAO,CAAC,CAAA"}

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/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/structure.mdx

@@ -138,7 +138,7 @@ export const UserParamsSchema = tex.object({ id: tex.string() });
 ```
 
 `tex` is the only validation engine. Schemas here are also the source for
-OpenAPI generation once `@exisjs/swagger` is installed.
+OpenAPI generation via `exisjs/swagger`.
 
 ---