Multi-language Code Vault: Demonstrating cron-parser

cron-parser is not confined to a single ecosystem. Its utility is recognized across various programming languages, enabling diverse teams to leverage its capabilities. Below are examples showcasing how to use cron-parser in popular languages to generate human-readable insights.

JavaScript (Node.js)

The JavaScript implementation is one of the most widely used and feature-rich.

import { CronParser } from 'cron-parser';

const cronString = '0 2 * * 1'; // At 2:00 AM every Monday
const options = {
    tz: 'UTC'
};

try {
    const parser = new CronParser(cronString, options);

    // Get the next occurrence
    const nextOccurrence = parser.next().toDate();
    console.log(`Cron string: ${cronString}`);
    console.log(`Next occurrence (UTC): ${nextOccurrence.toISOString()}`);

    // To generate a human-readable description, we'd interpret the components.
    // This part often requires custom logic built around the parser's output.
    // For demonstration, let's simulate a simple description generator.
    function describeCron(cronString) {
        const components = cronString.split(' ');
        if (components.length !== 5) return "Invalid cron string format.";

        const minute = components[0];
        const hour = components[1];
        const dayOfMonth = components[2];
        const month = components[3];
        const dayOfWeek = components[4];

        let description = "Runs ";

        // Minute
        if (minute === '*') description += "every minute";
        else if (minute.includes('/')) description += `every ${minute.split('/')[1]} minutes`;
        else description += `at minute ${minute}`;

        // Hour
        if (hour === '*') description += ""; // already handled by "every minute" or specific minute
        else if (hour.includes('/')) description += `, every ${hour.split('/')[1]} hours`;
        else description += `, at hour ${hour}`;

        // Day of Month
        if (dayOfMonth !== '*' && month === '*') description += `, on day ${dayOfMonth} of the month`;
        else if (dayOfMonth !== '*' && month !== '*') description += `, on day ${dayOfMonth}`;

        // Month
        if (month !== '*' && dayOfMonth === '*') description += `, every month`;
        else if (month !== '*' && dayOfMonth !== '*') description += `, in month(s) ${month}`;

        // Day of Week
        if (dayOfWeek !== '*') {
            const days = ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'];
            let dayNames = dayOfWeek.split(',').map(d => {
                if (d === '*') return 'every day';
                const num = parseInt(d, 10);
                if (!isNaN(num)) return days[num % 7];
                return d; // Keep names like MON, TUE
            }).filter(d => d !== 'every day').join(', '); // Remove if already covered by dayOfMonth *

            if (dayNames) {
                // If dayOfMonth is '*', focus on dayOfWeek
                if (dayOfMonth === '*') {
                     description = `Runs on ${dayNames}`;
                } else {
                    // If both are specified, it's a specific day of the month AND day of week
                    description += `, on day(s) of the week ${dayNames}`;
                }
            }
        }

        // Adjust phrasing for better readability
        if (minute === '*' && hour === '*' && dayOfMonth === '*' && month === '*' && dayOfWeek === '*') {
            description = "Runs every minute of every hour of every day.";
        } else if (minute !== '*' && hour === '*' && dayOfMonth === '*' && month === '*' && dayOfWeek === '*') {
             description = `Runs every ${minute.includes('/') ? minute.split('/')[1] + ' minutes' : minute + ' minute'}.`;
        } else if (minute === '*' && hour !== '*' && dayOfMonth === '*' && month === '*' && dayOfWeek === '*') {
            description = `Runs at hour ${hour}.`;
        } else if (minute === '*' && hour === '*' && dayOfMonth !== '*' && month === '*' && dayOfWeek === '*') {
            description = `Runs on day ${dayOfMonth} of the month.`;
        } else if (minute === '*' && hour === '*' && dayOfMonth === '*' && month !== '*' && dayOfWeek === '*') {
            description = `Runs in month(s) ${month}.`;
        } else if (minute === '*' && hour === '*' && dayOfMonth === '*' && month === '*' && dayOfWeek !== '*') {
            const days = ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'];
            let dayNames = dayOfWeek.split(',').map(d => {
                if (d === '*') return 'every day';
                const num = parseInt(d, 10);
                if (!isNaN(num)) return days[num % 7];
                return d;
            }).join(', ');
            description = `Runs on ${dayNames}.`;
        } else {
            // Refine for common cases like "0 2 * * 1" -> "At 2:00 AM every Monday"
            let finalDescription = "";
            const minStr = minute === '0' ? '00' : minute; // Standardize minute formatting
            const hourNum = parseInt(hour, 10);
            const formattedHour = hourNum % 12 === 0 ? 12 : hourNum % 12;
            const ampm = hourNum >= 12 ? 'PM' : 'AM';
            const timePart = `${minStr} ${formattedHour}:${minStr} ${ampm}`;

            if (dayOfWeek !== '*') {
                 const days = ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'];
                 let dayNames = dayOfWeek.split(',').map(d => {
                     if (d === '*') return 'every day';
                     const num = parseInt(d, 10);
                     if (!isNaN(num)) return days[num % 7];
                     return d;
                 }).join(', ');
                 finalDescription = `At ${timePart}, ${dayNames}`;
            } else if (dayOfMonth !== '*') {
                 finalDescription = `At ${timePart}, on day ${dayOfMonth}`;
                 if (month !== '*') {
                     finalDescription += ` of month(s) ${month}`;
                 }
            } else {
                finalDescription = `At ${timePart}`;
            }
            description = finalDescription;
        }

        return description;
    }

    console.log(`Human-readable description: ${describeCron(cronString)}`);

} catch (err) {
    console.error(`Error parsing cron string: ${err.message}`);
}

// Example 2: */15 * * * * (Every 15 minutes)
try {
    const cronString2 = '*/15 * * * *';
    const parser2 = new CronParser(cronString2, options);
    console.log(`\nCron string: ${cronString2}`);
    console.log(`Human-readable description: ${describeCron(cronString2)}`);
} catch (err) {
    console.error(`Error parsing cron string: ${err.message}`);
}

// Example 3: 0 0 1 * * (At midnight on the first day of every month)
try {
    const cronString3 = '0 0 1 * *';
    const parser3 = new CronParser(cronString3, options);
    console.log(`\nCron string: ${cronString3}`);
    console.log(`Human-readable description: ${describeCron(cronString3)}`);
} catch (err) {
    console.error(`Error parsing cron string: ${err.message}`);
}
            

Python

Python offers excellent libraries for cron parsing.

from crontab import CronTab

def describe_cron_python(cron_string):
    try:
        job = CronTab(cron_string=cron_string)
        # The crontab library doesn't directly provide a human-readable string
        # but we can access its components to build one.
        # For simplicity, we'll simulate the description generation.

        minute = job.minute
        hour = job.hour
        day_of_month = job.day_of_month
        month = job.month
        day_of_week = job.day_of_week

        description = "Runs "
        
        if minute == "*":
            description += "every minute"
        elif "/" in str(minute):
            step = str(minute).split("/")[1]
            description += f"every {step} minutes"
        else:
            description += f"at minute {minute}"

        if hour == "*":
            pass # Already covered by "every minute" or specific minute
        elif "/" in str(hour):
            step = str(hour).split("/")[1]
            description += f", every {step} hours"
        else:
            description += f", at hour {hour}"

        if day_of_month != "*" and month == "*":
            description += f", on day {day_of_month} of the month"
        elif day_of_month != "*" and month != "*":
            description += f", on day {day_of_month}"

        if month != "*" and day_of_month == "*":
            description += ", every month"
        elif month != "*" and day_of_month != "*":
            description += f", in month(s) {month}"

        if day_of_week != "*":
            days = ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday']
            day_names_list = []
            for d in str(day_of_week).split(','):
                if d == '*':
                    day_names_list.append('every day')
                else:
                    try:
                        num = int(d)
                        day_names_list.append(days[num % 7])
                    except ValueError:
                        day_names_list.append(d) # Keep names like MON, TUE
            
            day_names = ', '.join([d for d in day_names_list if d != 'every day'])

            if day_names:
                if day_of_month == "*":
                    description = f"Runs on {day_names}"
                else:
                    description += f", on day(s) of the week {day_names}"
        
        # Refine for common cases like "0 2 * * 1" -> "At 2:00 AM every Monday"
        if minute == "0" and hour != "*" and day_of_month == "*" and month == "*" and day_of_week != "*":
            hour_num = int(hour)
            formatted_hour = hour_num % 12 if hour_num % 12 != 0 else 12
            ampm = "PM" if hour_num >= 12 else "AM"
            time_part = f"{formatted_hour}:{minute} {ampm}"

            days = ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday']
            day_names_list = []
            for d in str(day_of_week).split(','):
                if d == '*':
                    day_names_list.append('every day')
                else:
                    try:
                        num = int(d)
                        day_names_list.append(days[num % 7])
                    except ValueError:
                        day_names_list.append(d)
            day_names = ', '.join(day_names_list)
            description = f"At {time_part}, {day_names}"
        
        return description

    except Exception as e:
        return f"Error parsing cron string: {e}"

# Example 1: 0 2 * * 1 (At 2:00 AM every Monday)
cron_string1 = '0 2 * * 1'
print(f"Cron string: {cron_string1}")
print(f"Human-readable description: {describe_cron_python(cron_string1)}")

# Example 2: */15 * * * * (Every 15 minutes)
cron_string2 = '*/15 * * * *'
print(f"\nCron string: {cron_string2}")
print(f"Human-readable description: {describe_cron_python(cron_string2)}")

# Example 3: 0 0 1 * * (At midnight on the first day of every month)
cron_string3 = '0 0 1 * *'
print(f"\nCron string: {cron_string3}")
print(f"Human-readable description: {describe_cron_python(cron_string3)}")

            

Bash Scripting (with external parsing logic)

While Bash itself doesn't have a built-in cron parser, you can leverage external tools or simple pattern matching for basic descriptions.

#!/bin/bash

parse_cron_description() {
    local cron_string="$1"
    local components=($cron_string)

    if [ ${#components[@]} -ne 5 ]; then
        echo "Invalid cron string format."
        return 1
    fi

    local minute=${components[0]}
    local hour=${components[1]}
    local day_of_month=${components[2]}
    local month=${components[3]}
    local day_of_week=${components[4]}

    local description="Runs "

    # Minute
    if [[ "$minute" == "*" ]]; then
        description+="every minute"
    elif [[ "$minute" == */* ]]; then
        step=$(echo "$minute" | cut -d'/' -f2)
        description+="every $step minutes"
    else
        description+="at minute $minute"
    fi

    # Hour
    if [[ "$hour" != "*" ]]; then
        if [[ "$hour" == */* ]]; then
            step=$(echo "$hour" | cut -d'/' -f2)
            description+=", every $step hours"
        else
            description+=", at hour $hour"
        fi
    fi

    # Day of Month
    if [[ "$day_of_month" != "*" ]]; then
        if [[ "$month" == "*" ]]; then
            description+=", on day $day_of_month of the month"
        else
            description+=", on day $day_of_month"
        fi
    fi

    # Month
    if [[ "$month" != "*" ]]; then
        if [[ "$day_of_month" == "*" ]]; then
            description+=", every month"
        else
            description+=", in month(s) $month"
        fi
    fi

    # Day of Week
    if [[ "$day_of_week" != "*" ]]; then
        local days=("Sunday" "Monday" "Tuesday" "Wednesday" "Thursday" "Friday" "Saturday")
        local day_names_arr=()
        IFS=',' read -ra day_tokens <<< "$day_of_week"
        for d_token in "${day_tokens[@]}"; do
            if [[ "$d_token" == "*" ]]; then
                day_names_arr+=("every day")
            else
                # Attempt to convert to number for array lookup
                if [[ "$d_token" =~ ^[0-6]$ ]]; then
                    day_names_arr+=("${days[$d_token]}")
                else
                    day_names_arr+=("$d_token") # Keep names like MON, TUE
                fi
            fi
        done
        
        # Filter out "every day" if it's redundant (e.g., combined with day_of_month)
        local filtered_day_names=$(printf "%s," "${day_names_arr[@]}" | sed 's/,every day,//g' | sed 's/^,//' | sed 's/,$//')
        
        if [[ -n "$filtered_day_names" ]]; then
            if [[ "$day_of_month" == "*" ]]; then
                description="Runs on $filtered_day_names"
            else
                description+=", on day(s) of the week $filtered_day_names"
            fi
        fi
    fi

    # Refine for common cases like "0 2 * * 1" -> "At 2:00 AM every Monday"
    if [[ "$minute" == "0" && "$hour" != "*" && "$day_of_month" == "*" && "$month" == "*" && "$day_of_week" != "*" ]]; then
        local hour_num=$hour
        local formatted_hour=$((hour_num % 12))
        formatted_hour=$((formatted_hour == 0 ? 12 : formatted_hour))
        local ampm="AM"
        [[ "$hour_num" -ge 12 ]] && ampm="PM"
        local time_part="$formatted_hour:$minute $ampm"

        local days=("Sunday" "Monday" "Tuesday" "Wednesday" "Thursday" "Friday" "Saturday")
        local day_names_arr=()
        IFS=',' read -ra day_tokens <<< "$day_of_week"
        for d_token in "${day_tokens[@]}"; do
            if [[ "$d_token" == "*" ]]; then
                day_names_arr+=("every day")
            else
                if [[ "$d_token" =~ ^[0-6]$ ]]; then
                    day_names_arr+=("${days[$d_token]}")
                else
                    day_names_arr+=("$d_token")
                fi
            fi
        done
        local day_names=$(IFS=', '; echo "${day_names_arr[*]}")
        description="At $time_part, $day_names"
    fi

    echo "$description"
}

# Example 1: 0 2 * * 1 (At 2:00 AM every Monday)
cron_str1="0 2 * * 1"
echo "Cron string: $cron_str1"
echo "Human-readable description: $(parse_cron_description "$cron_str1")"

# Example 2: */15 * * * * (Every 15 minutes)
cron_str2="*/15 * * * *"
echo -e "\nCron string: $cron_str2"
echo "Human-readable description: $(parse_cron_description "$cron_str2")"

# Example 3: 0 0 1 * * (At midnight on the first day of every month)
cron_str3="0 0 1 * *"
echo -e "\nCron string: $cron_str3"
echo "Human-readable description: $(parse_cron_description "$cron_str3")"