CROOT 🕐

Cron Root - A robust cron expression parser and job scheduler for Node.js

Installation

npm install croot

Quick Start

import { CronJob } from 'croot';

// Create a job that runs every 5 minutes
const job = new CronJob('0 */5 * * * *', () => {
  console.log('Running every 5 minutes!');
});

job.start();

// Stop when needed
// job.stop();

Features

• ✅ Full cron expression support (6 fields with seconds)
• ✅ Human-readable explanations
• ✅ Robust validation and error handling
• ✅ Retry mechanisms for failed jobs
• ✅ Timezone support
• ✅ Event-driven architecture
• ✅ Zero dependencies

Usage Examples

Basic Job Scheduling

import { CronJob } from 'croot';

const job = new CronJob('0 9 * * 1-5', () => {
  console.log('Running at 9 AM on weekdays');
}, {
  retries: 3,
  retryDelay: 1000,
  immediate: true
});

job.start();

Expression Parsing & Validation

import { parseCron, explainCronExpression, validateCronExpression } from 'croot';

// Parse expression
const schedule = parseCron('0 */15 * * * *');

// Get human-readable explanation
const explanation = explainCronExpression('0 0 12 * * 0');
console.log(explanation.description);
// "At second 0 of minute 0 hour 12 every day of month every month day of week 0"

// Validate expressions
const result = validateCronExpression('invalid-expression');
if (!result.valid) {
  console.error(result.error);
}

Check Schedule Times

import { isScheduledTime, getNextRunTime } from 'croot';

const schedule = parseCron('0 0 * * *');
const now = new Date();

// Check if now matches schedule
if (isScheduledTime(schedule, now)) {
  console.log('Time to run!');
}

// Get next execution time
const nextRun = getNextRunTime(schedule);
console.log('Next run:', nextRun);

API Reference

CronJob

const job = new CronJob(expression, handler, options);

Options:

• retries (number): Number of retry attempts (default: 0)
• retryDelay (number): Delay between retries in ms (default: 2000)
• immediate (boolean): Run immediately on start (default: false)
• timezone (string): Timezone for scheduling (default: 'UTC')

Methods:

• start() - Start the job scheduler
• stop() - Stop the job completely
• runOnce() - Execute immediately (returns Promise)
• pause() - Pause scheduling
• resume() - Resume after pause
• explain() - Get human-readable description
• getNextSchedule() - Get next scheduled run

Events:

• start - Job started
• stop - Job stopped
• tick - Job executed successfully
• error - Job execution failed
• retry - Retry attempt started
• failed - All retries exhausted

Parser Functions

• parseCron(expression) - Parse cron expression into object
• validateCronExpression(expression) - Validate and return result
• explainCronExpression(expression) - Get human-readable explanation
• isScheduledTime(schedule, date) - Check if date matches schedule
• getNextRunTime(schedule, fromDate) - Calculate next execution time
• getRunTimesBetween(schedule, start, end, limit) - Get all runs in date range

Cron Expression Format

CROOT supports 6-field cron expressions (with seconds):

*    *    *    *    *    *
-    -    -    -    -    -
|    |    |    |    |    |
|    |    |    |    |    +----- Day of week (0 - 7) (0 and 7 = Sunday)
|    |    |    |    +---------- Month (1 - 12)
|    |    |    +--------------- Day of month (1 - 31)
|    |    +-------------------- Hour (0 - 23)
|    +------------------------- Minute (0 - 59)
+------------------------------ Second (0 - 59)

Special Characters:

• * - Any value
• , - Value list separator
• - - Range of values
• / - Step values

Examples

// Every minute
'* * * * *'

// Every 5 minutes
'0 */5 * * * *'

// Daily at 9:30 AM
'0 30 9 * * *'

// Weekdays at 6 PM
'0 0 18 * * 1-5'

// Every Sunday at midnight
'0 0 0 * * 0'

// Complex: Every 15 minutes from 9 AM to 5 PM on weekdays
'0 */15 9-17 * * 1-5'

License

MIT