@venizia/ignis-docs 0.2.0 → 0.2.1-0

package/content/extensions/helpers/cron/index.md

@@ -1,27 +1,14 @@
-# Cron
-
-Schedule and manage recurring tasks using cron expressions, with support for dynamic rescheduling and job duplication.
-
-## Quick Reference
-
-| Item | Value |
-|------|-------|
-| **Package** | `@venizia/ignis-helpers` |
-| **Class** | `CronHelper` |
-| **Extends** | `BaseHelper` |
-| **Peer Dependency** | `cron` (^4.3.3, optional) |
-| **Runtimes** | Both |
+---
+title: Cron
+description: Schedule recurring tasks with cron expressions, plus runtime rescheduling and job duplication
+difficulty: beginner
+---
 
-#### Import Paths
-
-```typescript
-import { CronHelper } from '@venizia/ignis-helpers/cron';
-import type { ICronHelperOptions } from '@venizia/ignis-helpers/cron';
-```
+# Cron
 
-## Creating an Instance
+`CronHelper` wraps the `cron` package's `CronJob` with scoped logging and convenience methods for rescheduling and duplicating jobs.
 
-`CronHelper` wraps the `cron` package's `CronJob` class, adding scoped logging via `BaseHelper` and convenience methods for rescheduling and duplication.
+## In one example
 
 ```typescript
 import { CronHelper } from '@venizia/ignis-helpers/cron';
@@ -32,193 +19,97 @@ const job = new CronHelper({
     console.log('Running scheduled task');
   },
   autoStart: true,
-  tz: 'America/New_York',
-  errorHandler: (error) => {
-    console.error('Cron job failed:', error);
-  },
+  tz: 'Asia/Ho_Chi_Minh',
 });
 ```
 
-> [!TIP]
-> You can also use the static factory method `CronHelper.newInstance(opts)` which is equivalent to `new CronHelper(opts)`.
-
-#### ICronHelperOptions
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `cronTime` | `string` | -- | Cron pattern defining when the job runs (e.g., `'0 */1 * * * *'`). Required, must be non-empty. |
-| `onTick` | `() => void \| Promise<void>` | -- | Function executed each time the cron job triggers. Required. |
-| `onCompleted` | `CronOnCompleteCommand \| null` | `undefined` | Callback executed when the job is stopped via `stop()`. |
-| `autoStart` | `boolean` | `false` | If `true`, the job starts running immediately after construction. |
-| `tz` | `string` | `undefined` | IANA timezone for the schedule (e.g., `'Asia/Ho_Chi_Minh'`). Uses server timezone if omitted. |
-| `errorHandler` | `(error: unknown) => void \| null` | `undefined` | Handler invoked if `onTick` throws during execution. |
-
-#### Common Cron Patterns
+`autoStart: true` starts the job immediately. Leave it `false` (the default) and call `job.start()` when you are ready.
 
-| Pattern | Description |
-|---------|-------------|
-| `'0 */1 * * * *'` | Every minute |
-| `'0 */5 * * * *'` | Every 5 minutes |
-| `'0 0 * * * *'` | Every hour |
-| `'0 0 0 * * *'` | Every day at midnight |
-| `'0 0 9 * * 1-5'` | Weekdays at 9 AM |
-| `'0 0 0 * * 1'` | Every Monday at midnight |
+## How it works
 
-## Usage
+- **The constructor builds the job synchronously.** `buildInstance()` runs inside the constructor and creates a `CronJob` via `CronJob.from(...)`. An empty `cronTime` or a malformed cron expression throws immediately - `getError` never lets the object come back into your hands half-built.
+- **`start()` and `stop()` guard against a missing instance.** If `buildInstance()` never produced a `CronJob` (a prior `configure()` failure), `start()` logs `'Invalid cron instance to start cronjob!'` and returns without throwing. `stop()` is `async` because the underlying `CronJob.stop()` resolves only once an in-flight tick finishes - awaiting it prevents a replacement job from starting while the old handler is still running.
+- **`modifyCronTime()` reschedules in place.** It builds a new `CronTime`, calls `instance.setTime(...)`, and updates the stored `cronTime` - the same `CronJob` keeps running, it just fires on the new schedule.
+- **`duplicate()` clones configuration, not state.** The new instance shares `onTick`, `onCompleted`, `autoStart`, `tz`, and `errorHandler` with a different `cronTime`. It is fully independent - stopping or modifying one does not touch the other.
+- **The `instance` property is the raw `CronJob`.** Use it for anything the wrapper does not expose - `isActive`, `lastDate()`, `fireOnTick()` - from the [`cron`](https://github.com/kelektiv/node-cron) package (an optional peer dependency, `^4.3.3`).
 
-### Scheduling Jobs
+**`ICronHelperOptions`**
 
-Create a job with `autoStart: true` to begin execution immediately, or leave it as `false` (default) and call `start()` when ready.
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `cronTime` | `string` | -- (required) | Cron pattern defining when the job runs, e.g. `'0 */1 * * * *'` |
+| `onTick` | `() => void \| Promise<void>` | -- (required) | Runs on every trigger |
+| `onCompleted` | `CronOnCompleteCommand \| null` | `undefined` | Runs when the job is stopped via `stop()` |
+| `autoStart` | `boolean` | `false` | Starts the job immediately after construction |
+| `tz` | `string` | `undefined` | IANA timezone, e.g. `'Asia/Ho_Chi_Minh'`. Uses server timezone if omitted |
+| `errorHandler` | `(error: unknown) => void \| null` | `undefined` | Runs if `onTick` throws |
 
-```typescript
-// Auto-start: begins running on schedule immediately
-const autoJob = new CronHelper({
-  cronTime: '0 */1 * * * *',
-  onTick: () => {
-    console.log('Runs every minute');
-  },
-  autoStart: true,
-});
-```
+## Common tasks
 
-### Starting Jobs Manually
+### Start a job manually
 
-When `autoStart` is `false`, the job is created but does not run until `start()` is called. This is useful when you need to set up dependencies before the job begins firing.
+Leave `autoStart` unset (`false`) and call `start()` once dependencies are ready.
 
 ```typescript
 const job = new CronHelper({
   cronTime: '0 0 * * * *', // Every hour
-  onTick: () => {
-    console.log('Hourly task executed');
-  },
+  onTick: () => runHourlyTask(),
 });
 
-// Start later when conditions are met
 job.start();
 ```
 
-If the internal `CronJob` instance does not exist (e.g., `configure()` failed), `start()` logs an error and returns without throwing.
-
-### Modifying the Schedule
+### Reschedule at runtime
 
-Change a job's cron schedule at runtime with `modifyCronTime()`. The job continues running with the new schedule.
+`modifyCronTime()` swaps the cron pattern without recreating the job. Set `shouldFireOnTick: true` to fire once immediately after the change (fire-and-forget - errors are logged, not thrown).
 
 ```typescript
-modifyCronTime(opts: { cronTime: string; shouldFireOnTick?: boolean }): void
-```
-
-| Parameter | Type | Default | Description |
-|-----------|------|---------|-------------|
-| `cronTime` | `string` | -- | The new cron pattern to apply. |
-| `shouldFireOnTick` | `boolean` | `false` | If `true`, immediately fires the `onTick` function after changing the schedule. |
-
-```typescript
-// Change the job to run every 5 minutes instead
-job.modifyCronTime({ cronTime: '0 */5 * * * *' });
-
-// Change schedule and immediately fire onTick
 job.modifyCronTime({ cronTime: '0 */10 * * * *', shouldFireOnTick: true });
 ```
 
-### Duplicating Jobs
+### Duplicate a job onto a new schedule
 
-Create a new `CronHelper` instance that copies the current job's configuration (`onTick`, `onCompleted`, `autoStart`, `tz`, `errorHandler`) but uses a different `cronTime`.
-
-```typescript
-duplicate(opts: { cronTime: string }): CronHelper
-```
+Reuse the same `onTick` logic on a second cron pattern.
 
 ```typescript
 const dailyJob = new CronHelper({
   cronTime: '0 0 0 * * *', // Daily at midnight
-  onTick: async () => {
-    await generateReport();
-  },
-  tz: 'America/New_York',
+  onTick: async () => generateReport(),
+  tz: 'Asia/Ho_Chi_Minh',
 });
 
-// Same logic, different schedule
 const hourlyJob = dailyJob.duplicate({ cronTime: '0 0 * * * *' });
 hourlyJob.start();
 ```
 
-> [!NOTE]
-> `duplicate()` copies all configuration except `cronTime`. The new instance is independent -- stopping or modifying one does not affect the other.
-
-### Accessing the Underlying CronJob
+### Handle tick errors without crashing the process
 
-The `instance` property exposes the underlying `CronJob` from the `cron` package, giving access to the full API (e.g., `stop()`, `isActive`, `lastDate()`).
+Pass `errorHandler` so a throwing `onTick` does not take down the job silently.
 
 ```typescript
 const job = new CronHelper({
   cronTime: '0 */1 * * * *',
-  onTick: () => { /* ... */ },
-});
-
-job.start();
-
-// Access the underlying CronJob directly
-console.log(job.instance.isActive);  // true
-job.instance.stop();
-```
-
-## Troubleshooting
-
-### "[CronHelper][configure] Invalid cronTime to configure application cron!"
-
-**Cause:** The `cronTime` option is empty, undefined, or not provided.
-
-**Fix:** Provide a valid, non-empty cron pattern string:
-
-```typescript
-const job = new CronHelper({
-  cronTime: '0 */1 * * * *', // Must be a non-empty cron pattern
-  onTick: () => { /* ... */ },
+  onTick: async () => riskyTask(),
+  errorHandler: error => logger.for('cron').error('Tick failed: %s', error),
 });
 ```
 
-### "Invalid cron instance to start cronjob!"
-
-**Cause:** `start()` was called but the internal `CronJob` instance was not created. This typically means `configure()` threw an error during construction.
-
-**Fix:** Ensure the constructor completed without errors before calling `start()`. Wrap creation in a try/catch to detect configuration failures:
+### Reach the underlying `CronJob`
 
 ```typescript
-try {
-  const job = new CronHelper({
-    cronTime: '0 */1 * * * *',
-    onTick: () => { /* ... */ },
-  });
-  job.start();
-} catch (error) {
-  console.error('Failed to create cron job:', error);
-}
-```
-
-### Job does not fire at expected times
-
-**Cause:** The `tz` option is not set or uses an incorrect timezone identifier, causing the job to fire based on the server's local timezone.
-
-**Fix:** Set `tz` to the correct [IANA timezone identifier](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones):
-
-```typescript
-const job = new CronHelper({
-  cronTime: '0 0 9 * * *', // 9 AM
-  onTick: () => { /* ... */ },
-  tz: 'America/New_York', // Explicit timezone
-});
+console.log(job.instance.isActive); // true
+job.instance.stop();
 ```
 
-## See Also
+## See also
 
-- **Related Concepts:**
-  - [Services](/guides/core-concepts/services) -- Scheduling jobs within services
-  - [Application](/guides/core-concepts/application/) -- Scheduling on application startup
+- [Services](/guides/core-concepts/services) - scheduling jobs inside services
+- [Application](/guides/core-concepts/application/) - scheduling on application startup
+- [Helpers Overview](/extensions/helpers/) - all available helpers
+- [Queue Helper](/extensions/helpers/queue/) - message queue processing
+- [Cron Expression Guide](https://crontab.guru/) - interactive cron syntax reference
 
-- **Other Helpers:**
-  - [Helpers Index](../index) -- All available helpers
-  - [Queue Helper](../queue/) -- Message queue processing
+**Files:**
 
-- **External Resources:**
-  - [Cron Expression Guide](https://crontab.guru/) -- Interactive cron syntax reference
-  - [`cron` npm package](https://github.com/kelektiv/node-cron) -- Underlying cron library
+- [`packages/helpers/src/modules/cron/cron.helper.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/helpers/src/modules/cron/cron.helper.ts) - `CronHelper` class
+- [`packages/helpers/src/modules/cron/index.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/helpers/src/modules/cron/index.ts) - module barrel