exisjs 0.7.12 → 0.7.14

package/dist/docs/reference/cron.mdx

@@ -1,11 +1,51 @@
 ---
-title: "Cron & Scheduling"
-description: "API Reference for ExisJS Task Scheduling, Cron Expressions, and Job Management."
+title: "exisjs/cron"
+description: "API Reference for ExisJS task scheduling, cron expressions, interval timers, CronManager, and @Cron decorators."
+nextUrl: "/docs/reference/sanitize"
+nextTitle: "Sanitize Reference"
 ---
 
-# Cron & Scheduling (`exisjs/cron`, `exisjs/decorators`)
+# `exisjs/cron`
 
-The `exisjs/cron` module provides task scheduling, cron expression parsing, interval timers, and runtime job management.
+The `exisjs/cron` module provides background task scheduling, 5/6-field cron expression parsing, drift-corrected interval timers, retry backoff, and runtime job management.
+
+---
+
+## Module Exports
+
+```typescript
+import {
+  cron,
+  defineCron,
+  CronManager,
+  CronJob,
+  CronExpression,
+  every,
+} from 'exisjs/cron'
+
+import type {
+  CronSchedule,
+  CronJobOptions,
+  CronContext,
+  CronJobStats,
+  CronJobStatus,
+  OverlapPolicy,
+  IntervalOptions,
+  TimeoutOptions,
+} from 'exisjs/cron'
+```
+
+Decorators for class-based jobs are imported from `exisjs/decorators`:
+
+```typescript
+import {
+  Cron,
+  Interval,
+  TimeoutTask,
+  Scheduled,
+  ScheduledTimeout,
+} from 'exisjs/decorators'
+```
 
 ---
 
@@ -13,65 +53,115 @@ The `exisjs/cron` module provides task scheduling, cron expression parsing, inte
 
 ### `cron(scheduleOrOptions, handler?)`
 
-Defines a functional cron job.
+Defines a functional cron job for auto-discovery or dynamic registration.
 
 ```typescript
-import { cron, CronExpression } from 'exisjs/cron'
+function cron(
+  scheduleOrOptions: string | CronJobOptions,
+  handler?: (ctx: CronContext) => any
+): FunctionalCronDefinition
+```
 
-// 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 }) {
-    // ...
-  }
-})
+#### Overloads
+
+1. **Option Object**:
+   ```typescript filename="src/cron/sync.ts"
+   import { cron, CronExpression } from 'exisjs/cron'
+
+   export default cron({
+     name: 'sync-users',
+     schedule: CronExpression.EVERY_10_MINUTES,
+     timezone: 'UTC',
+     preventOverlap: true,
+     retries: 2,
+     retryDelayMs: 1000,
+     async run({ app, log, iteration }) {
+       log.info({ iteration }, 'Running user synchronization')
+     },
+   })
+   ```
+
+2. **Schedule Pattern & Handler**:
+   ```typescript filename="src/cron/cleanup.ts"
+   import { cron } from 'exisjs/cron'
+
+   export default cron('0 0 * * *', async ({ log }) => {
+     log.info('Running nightly purge')
+   })
+   ```
 
-// 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'`).
+Shorthand helper accepting natural language English duration strings (e.g., `'10 seconds'`, `'5 minutes'`, `'2 hours'`, `'1 day'`).
 
 ```typescript
+cron.every(
+  duration: string,
+  handler: (ctx: CronContext) => any,
+  options?: Omit<CronJobOptions, 'schedule' | 'run' | 'handle'>
+): FunctionalCronDefinition
+```
+
+#### Example
+
+```typescript filename="src/cron/heartbeat.ts"
 import { cron } from 'exisjs/cron'
 
-export const healthCheck = cron.every('30 seconds', async ({ log }) => {
-  log.info('Checking external dependencies...')
+export default cron.every('15 minutes', async ({ log }) => {
+  log.info('Heartbeat tick')
 }, {
-  name: 'ext-health-check'
+  name: 'health-heartbeat',
+  timezone: 'UTC',
 })
 ```
 
+---
+
 ### `cron.interval(ms, handler, options?)`
 
-Shorthand helper for millisecond recurring intervals.
+Shorthand helper for millisecond recurring intervals with timer unref and drift management.
 
 ```typescript
+cron.interval(
+  ms: number,
+  handler: (ctx: CronContext) => any,
+  options?: Omit<CronJobOptions, 'interval' | 'run' | 'handle'>
+): FunctionalCronDefinition
+```
+
+#### Example
+
+```typescript filename="src/cron/queue-poll.ts"
 import { cron } from 'exisjs/cron'
 
-export const heartbeat = cron.interval(60_000, async ({ log }) => {
-  log.info('Server heartbeat tick')
+export default cron.interval(30_000, async ({ log }) => {
+  log.info('Polling background job queue')
 })
 ```
 
+---
+
 ### `cron.timeout(ms, handler, options?)`
 
-Shorthand helper for one-time delayed startup tasks (executes once after application boot).
+Shorthand helper for one-time delayed startup tasks executed once after the server initializes.
 
 ```typescript
+cron.timeout(
+  ms: number,
+  handler: (ctx: CronContext) => any,
+  options?: Omit<CronJobOptions, 'timeout' | 'run' | 'handle'>
+): FunctionalCronDefinition
+```
+
+#### Example
+
+```typescript filename="src/cron/warmup.ts"
 import { cron } from 'exisjs/cron'
 
-export const cacheWarmup = cron.timeout(5_000, async ({ app, log }) => {
-  log.info('Warming up Redis cache after boot')
+export default cron.timeout(5_000, async ({ app, log }) => {
+  log.info('Warming up memory cache after application startup')
 })
 ```
 
@@ -81,102 +171,153 @@ export const cacheWarmup = cron.timeout(5_000, async ({ app, log }) => {
 
 ### `@Cron(schedule, options?)`
 
-Method decorator that marks a class method as a scheduled cron job. Can be used on any `@Injectable()` service.
+Method decorator that marks a class method on an `@Injectable()` service as a scheduled cron job.
+
+```typescript
+function Cron(
+  schedule: string,
+  options?: Omit<CronJobOptions, 'schedule' | 'run' | 'handle'>
+): MethodDecorator
+```
 
 | 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.). |
+| `options` | `CronJobOptions` | Optional job configuration (`name`, `timezone`, `preventOverlap`, `retries`, `retryDelayMs`). |
 
-```typescript
-import { Injectable, Cron, CronExpression } from 'exisjs/decorators'
+```typescript filename="src/services/report.service.ts"
+import { Injectable } from 'exisjs/di'
+import { Cron, CronExpression } from 'exisjs/decorators'
 
 @Injectable()
-export default class ReportService {
+export class ReportService {
   @Cron(CronExpression.EVERY_DAY_AT_MIDNIGHT, {
     name: 'nightly-report',
     timezone: 'UTC',
     preventOverlap: true,
   })
   async generateDailyReport() {
-    // ...
+    // Executes every day at 00:00 UTC
   }
 }
 ```
 
+---
+
 ### `@Interval(ms, options?)`
 
-Method decorator for recurring millisecond tasks.
+Method decorator that schedules a method to run at recurring millisecond intervals.
 
 ```typescript
-import { Injectable, Interval } from 'exisjs/decorators'
+function Interval(
+  ms: number,
+  options?: Omit<CronJobOptions, 'interval' | 'run' | 'handle'>
+): MethodDecorator
+```
+
+```typescript filename="src/services/monitor.service.ts"
+import { Injectable } from 'exisjs/di'
+import { Interval } from 'exisjs/decorators'
 
 @Injectable()
-export default class QueueMonitor {
-  @Interval(15_000, { name: 'queue-poll' })
-  async pollQueue() {
-    // ...
+export class MonitorService {
+  @Interval(60_000, { name: 'health-monitor' })
+  async pingExternalServices() {
+    // Runs every 60 seconds
   }
 }
 ```
 
-### `@TimeoutTask(ms, options?)` (alias `@ScheduledTimeout`)
+---
 
-Method decorator for one-time startup tasks executed after the specified millisecond delay.
+### `@TimeoutTask(ms, options?)`
+
+Method decorator for one-time startup tasks executed after the specified millisecond delay. Also aliased as `@ScheduledTimeout`.
 
 ```typescript
-import { Injectable, TimeoutTask } from 'exisjs/decorators'
+function TimeoutTask(
+  ms: number,
+  options?: Omit<CronJobOptions, 'timeout' | 'run' | 'handle'>
+): MethodDecorator
+```
+
+```typescript filename="src/services/bootstrap.service.ts"
+import { Injectable } from 'exisjs/di'
+import { TimeoutTask } from 'exisjs/decorators'
 
 @Injectable()
-export default class CacheBootstrap {
+export class BootstrapService {
   @TimeoutTask(3_000, { name: 'seed-cache' })
   async seedCache() {
-    // ...
+    // Runs once 3s after server boot
   }
 }
 ```
 
 ---
 
-## 3. Configuration & Options
+## 3. Configuration Interfaces
 
 ### `CronJobOptions`
 
-Configuration object passed to `cron()` or decorator options:
+Configuration object accepted by `cron()`, `app.cron.schedule()`, and cron decorators:
 
-| Property | Type | Default | Description |
+| Option | Type | Default | Description |
 | :--- | :--- | :--- | :--- |
-| `name` | `string` | `auto-generated` | Unique identifier for the job. Used in logs and runtime APIs. |
+| `name` | `string` | `job_<random>` | Unique identifier for the job. Used in logging, statistics, and runtime triggers. |
 | `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. |
+| `interval` | `number` | `undefined` | Interval in milliseconds for recurring execution. |
+| `timeout` | `number` | `undefined` | Delay in milliseconds for one-time execution. |
+| `timezone` | `string` | `'UTC'` | IANA timezone string (e.g. `'America/New_York'`, `'Asia/Kolkata'`). |
+| `preventOverlap` | `boolean` | `true` | When `true`, skips execution if the previous execution is still running. |
+| `onOverlap` | `'skip' \| 'queue'` | `'skip'` | Overlap policy when a job is triggered while already running. |
+| `autoStart` | `boolean` | `true` | Whether the job begins scheduling automatically upon registration. |
+| `retries` | `number` | `0` | Number of retry attempts if the handler throws an unhandled error. |
+| `retryDelayMs` | `number` | `1000` | Delay between retry attempts in milliseconds. |
+| `run` / `handle` | `(ctx: CronContext) => any` | `undefined` | Main execution callback function. |
+| `onError` | `(err: Error, ctx: CronContext) => void` | `undefined` | Error hook executed if the handler fails all retry attempts. |
+
+---
 
 ### `CronContext`
 
-The context object provided as the first argument to job execution handlers:
+Context object passed to cron 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. |
+| `app` | `App` | The active ExisJS application instance. |
+| `log` | `Logger` | Structured application logger instance. |
+| `jobName` | `string` | The unique name of the currently executing job. |
+| `startedAt` | `Date` | Timestamp when the current execution began. |
+| `iteration` | `number` | Monotonically increasing execution counter for this job instance. |
+| `signal` | `AbortSignal` | AbortSignal triggered during application graceful shutdown. |
+
+---
+
+### `CronJobStats`
+
+Statistics descriptor returned by `job.getStats()` and `app.cron.getStats()`:
+
+| Field | Type | Description |
+| :--- | :--- | :--- |
+| `name` | `string` | Unique job identifier. |
+| `status` | `'idle' \| 'running' \| 'paused' \| 'stopped'` | Current job execution status. |
+| `schedule` | `string \| undefined` | Configured cron schedule expression. |
+| `intervalMs` | `number \| undefined` | Configured interval in milliseconds. |
+| `timezone` | `string \| undefined` | Configured IANA timezone. |
+| `preventOverlap` | `boolean` | Overlap prevention status. |
+| `lastRun` | `Date \| undefined` | Timestamp of the most recent execution. |
+| `nextRun` | `Date \| undefined` | Calculated timestamp for the upcoming scheduled run. |
+| `executionCount` | `number` | Total number of executions attempted. |
+| `failureCount` | `number` | Total number of failed executions. |
+| `lastDurationMs` | `number \| undefined` | Duration in milliseconds of the last execution. |
+| `lastError` | `string \| undefined` | Last error message if execution failed. |
 
 ---
 
-## 4. `CronExpression` Presets
+## 4. `CronExpression` Constants
 
-ExisJS exports pre-validated standard cron expression constants:
+ExisJS exports pre-compiled cron patterns:
 
 | Constant | Value | Description |
 | :--- | :--- | :--- |
@@ -185,116 +326,89 @@ ExisJS exports pre-validated standard cron expression constants:
 | `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_2_MINUTES` | `*/2 * * * *` | Every 2 minutes |
+| `CronExpression.EVERY_3_MINUTES` | `*/3 * * * *` | Every 3 minutes |
 | `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_HOUR` | `0 * * * *` | At minute 0 of every hour |
 | `CronExpression.EVERY_2_HOURS` | `0 */2 * * *` | Every 2 hours |
+| `CronExpression.EVERY_3_HOURS` | `0 */3 * * *` | Every 3 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 |
+| `CronExpression.EVERY_WEEK` | `0 0 * * 0` | Every Sunday at 00:00 |
+| `CronExpression.EVERY_WEEKDAY` | `0 0 * * 1-5` | Monday through Friday at 00:00 |
+| `CronExpression.EVERY_WEEKEND` | `0 0 * * 6,0` | Saturday and Sunday at 00:00 |
+| `CronExpression.EVERY_MONTH` | `0 0 1 * *` | First day of every month at 00:00 |
+| `CronExpression.EVERY_QUARTER` | `0 0 1 1,4,7,10 *` | First day of every quarter at 00:00 |
+| `CronExpression.EVERY_YEAR` | `0 0 1 1 *` | January 1st at 00:00 |
 
 ---
 
-## 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')
-  }
-})
-```
+## 5. `every(duration)` Helper
 
-### `app.cron.get(name)`
-Returns the `CronJob` instance by name, or `undefined` if not found.
+Converts human-readable duration strings into standard 5 or 6 field cron patterns.
 
 ```typescript
-const job = app.cron.get('nightly-sync')
+function every(duration: string): string
 ```
 
-### `app.cron.has(name)`
-Returns `true` if a job with the specified name exists.
+| Input Example | Generated Cron Pattern |
+| :--- | :--- |
+| `every('10 seconds')` | `*/10 * * * * *` |
+| `every('5 minutes')` | `*/5 * * * *` |
+| `every('2 hours')` | `0 */2 * * *` |
+| `every('1 day')` | `0 0 * * *` |
+| `every('1 week')` | `0 0 * * 0` |
+| `every('1 month')` | `0 0 1 * *` |
 
-```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')
-```
+## 6. Runtime Management (`CronManager`)
 
-### `app.cron.pause(name)` / `app.cron.resume(name)`
-Pauses or resumes a job's automatic scheduling without unregistering it.
+Access the application cron manager instance via `app.cron`:
 
 ```typescript
-app.cron.pause('nightly-sync')
-app.cron.resume('nightly-sync')
+export class CronManager {
+  has(name: string): boolean
+  schedule(nameOrOptions: string | CronJobOptions, schedule?: string, handler?: (ctx: CronContext) => any, options?: Partial<CronJobOptions>): CronJob
+  interval(name: string, ms: number, handler: (ctx: CronContext) => any, options?: Partial<CronJobOptions>): CronJob
+  timeout(name: string, ms: number, handler: (ctx: CronContext) => any, options?: Partial<CronJobOptions>): CronJob
+  getJob(name: string): CronJob | undefined
+  getJobs(): Map<string, CronJob>
+  getStats(): CronJobStats[]
+  startAll(): void
+  pauseAll(): void
+  stopAll(): void
+  trigger(name: string): Promise<any>
+  drain(timeoutMs?: number): Promise<void>
+}
 ```
 
-### `app.cron.remove(name)`
-Stops and unregisters a job by name.
+### Examples
 
 ```typescript
-app.cron.remove('nightly-sync')
-```
+// Check if a job exists
+if (app.cron.has('sync-users')) {
+  // Retrieve execution metrics
+  const job = app.cron.getJob('sync-users')
+  console.log(job?.getStats())
+}
 
-### `app.cron.stopAll()`
-Stops all scheduled timers across all registered jobs.
+// Manually trigger immediate execution
+await app.cron.trigger('sync-users')
 
-```typescript
-app.cron.stopAll()
-```
+// Pause all jobs during maintenance
+app.cron.pauseAll()
 
-### `app.cron.drain(timeoutMs?)`
-Stops new ticks and awaits any currently running job executions to complete. Called automatically during graceful server shutdown.
+// Resume scheduling
+app.cron.startAll()
 
-```typescript
+// Gracefully drain in-flight jobs during shutdown
 await app.cron.drain(5000)
 ```