cron-task-manager

A production-ready, dependency-free cron job scheduler and manager for Node.js. It features overlap protection, detailed runtime metrics, custom error callbacks, manual execution, and support for standard 5-field cron patterns.

Features

• 🚀 Zero dependencies — extremely fast, lightweight, and reliable.
• 🔀 Overlap Protection — prevents a job from running again if the previous execution is still running (highly critical for async database tasks, sync scripts, etc.).
• 📊 Detailed Execution Stats — tracks total runs, success/failure counts, skipped executions, last run timestamp, and last execution duration.
• 🪝 Custom Error Hooks — register a callback to handle task exceptions gracefully.
• ⚡ Manual Triggering — run any registered task programmatically on-demand.
• 📅 5-Field Cron Support — supports standard cron matching: minute, hour, day-of-month, month, day-of-week. (Supports *, steps */n, lists a,b, and ranges a-b).

Installation

npm install cron-task-manager

Quick Start

const { CronTaskManager } = require('cron-task-manager');
const scheduler = new CronTaskManager();

// 1. Add an async task running every minute
scheduler.add(
  'syncData', 
  '* * * * *', 
  async () => {
    console.log('Syncing data with remote server...');
    await new Promise(resolve => setTimeout(resolve, 2000));
  },
  {
    allowOverlap: false, // Prevent starting again if previous execution is still running
    onError: (err) => console.error('Error in syncData task:', err)
  }
);

// 2. Start the scheduler loop
scheduler.start();

// Get statistics
console.log(scheduler.list());

Advanced Usage

Manual Triggering

You can run any task immediately by name without waiting for its scheduled time:

await scheduler.runTask('syncData');

Checking Task Metrics

const tasks = scheduler.list();
console.log(tasks[0].stats);
/* Output:
{
  totalRuns: 5,
  successRuns: 4,
  failedRuns: 1,
  skippedRuns: 0,
  lastRunTime: '2026-06-28T01:50:00.000Z',
  lastDurationMs: 2045,
  lastError: 'Database timeout'
}
*/

Cron Patterns Support

The scheduler parses standard 5-field expressions:

┌────────────── minute (0 - 59)
│ ┌──────────── hour (0 - 23)
│ │ ┌────────── day of month (1 - 31)
│ │ │ ┌──────── month (1 - 12)
│ │ │ │ ┌────── day of week (0 - 6) (0 is Sunday)
│ │ │ │ │
* * * * *

• */5 * * * *: Every 5 minutes.
• 0 9 * * 1-5: At 9:00 AM, Monday through Friday.
• 0,30 9-17 * * *: At minute 0 and 30, between 9 AM and 5 PM daily.

License

MIT