Skill: openlark/node-cron (version 1.0.0)

--- name: node-cron description: Node.js cron job scheduling with the `cron` npm package. Use when the user needs to schedule recurring tasks, create cron jobs, validate cron expressions, set up timed callbacks, or work with cron syntax in a Node.js/TypeScript project. --- # Node Cron Use the `cron` npm package (`npm install cron`) for second-precision scheduled tasks in Node.js. ## Triggers cron job, node-cron, schedule task, cron expression, cron pattern, scheduled job, npm install cron, CronJob, CronTime. ## Quick Start ```ts import { CronJob } from 'cron'; const job = new CronJob( '0 */5 * * * *', // every 5 minutes () => console.log('Running every 5 minutes'), null, // onComplete true, // start immediately 'Asia/Shanghai' // timeZone ); ``` Or use the object form: ```ts const job = CronJob.from({ cronTime: '0 0 9 * * 1', // 9am every Monday onTick: () => sendReport(), start: true, timeZone: 'Asia/Shanghai' }); job.stop(); // halt job.start(); // resume ``` ## Cron Patterns The library uses **6 fields** (second-precision), unlike standard 5-field Unix cron: ``` second minute hour day-of-month month day-of-week 0-59 0-59 0-23 1-31 1-12 0-7 ``` ### Syntax | Token | Meaning | |-------|---------| | `*` | Any value (every second/minute/etc.) | | `1,3,5` | List of values | | `1-5` | Range (inclusive) | | `*/5` | Every N steps | ### Names Use first 3 letters for month/day-of-week (case-insensitive): `"jan,mar,dec"`, `"mon,wed,fri"` Day-of-week: `0` or `7` is Sunday. ### Common Examples | Expression | Meaning | |------------|---------| | `*/10 * * * * *` | Every 10 seconds | | `0 * * * * *` | Every minute on the second | | `0 0 * * * *` | Every hour | | `0 0 9 * * *` | Daily at 9:00 AM | | `0 30 9 * * 1-5` | 9:30 AM Mon-Fri | | `0 0 0 1 * *` | Midnight on the 1st of every month | ## CronJob Class ### Constructor Parameters | Param | Required | Description | |-------|----------|-------------| | `cronTime` | [OK] | Cron pattern string, `Date`, or Luxon `DateTime` | | `onTick` | [OK] | Callback function | | `onComplete` | | Called when job stops via `job.stop()` | | `start` | | Auto-start. Default `false` | | `timeZone` | | IANA zone string (e.g. `'Asia/Shanghai'`) | | `context` | | `this` context for `onTick` | | `runOnInit` | | Fire `onTick` immediately on init | | `waitForCompletion` | | If `true`, skip ticks while callback is still running | | `errorHandler` | | Catch exceptions in `onTick` | | `name` | | Job identifier for debugging | | `threshold` | | Missed-deadline tolerance in ms. Default `250` | Do NOT pass `utcOffset` together with `timeZone` -- they conflict. ### Key Methods - **`CronJob.from(obj)`** (static) -- Create with named params - **`job.start()` / `job.stop()`** -- Start/stop - **`job.nextDate()`** -- Next execution as Luxon DateTime - **`job.nextDates(n)`** -- Array of next N dates - **`job.lastDate()`** -- Last execution date - **`job.setTime(cronTime)`** -- Change schedule - **`job.addCallback(fn)`** -- Add another onTick callback ### Read-Only Properties - **`job.isActive`** -- Whether job is running - **`job.isCallbackRunning`** -- Whether onTick is currently executing ## Standalone Utilities ```ts import * as cron from 'cron'; // When will this cron expression fire next? const dt = cron.sendAt('0 0 * * *'); console.log(dt.toISO()); // How many ms until next execution? const ms = cron.timeout('0 0 * * *'); // Validate an expression const { valid, error } = cron.validateCronExpression('0 0 * * *'); ``` ## Gotchas - **Month is 1-12**, not 0-11. Upgrade from v2 needs `+1` on all month values. - **Day-of-week 0 = Sunday** (7 also works). - **6 fields** (with seconds) -- unlike standard 5-field Unix cron. - Use `waitForCompletion: true` for async callbacks to prevent overlap. ## Async onTick Wrap async work directly -- `waitForCompletion` prevents overlapping runs: ```ts const job = CronJob.from({ cronTime: '*/30 * * * * *', onTick: async () => { await fetchData(); await processData(); }, waitForCompletion: true, start: true }); ``` ## Full API Reference See [references/api_reference.md](references/api_reference.md) for the complete API documentation including `CronTime` class, all method signatures, and migration notes.


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)