@bernierllc/validators-cron-syntax

Cron syntax validation - pattern validity, timezone, DST

Installation

npm install @bernierllc/validators-cron-syntax

Usage

Basic Validation

import { validateCronSyntax, isValidCron } from '@bernierllc/validators-cron-syntax';

// Validate a cron expression
const problems = await validateCronSyntax('0 12 * * *');
if (problems.length === 0) {
  console.log('Valid cron expression');
}

// Quick validation check
const valid = await isValidCron('0 12 * * *');
console.log(valid); // true

Advanced Validation

// Validate with timezone
const problems = await validateCronSyntax('0 12 * * * America/New_York', {
  validateTimezone: true,
  checkDSTTransitions: true
});

// Validate 6-field format (with seconds)
const problems2 = await validateCronSyntax('0 0 12 * * *', {
  allowSeconds: true
});

// Validate with frequency constraints
const problems3 = await validateCronSyntax('*/5 * * * *', {
  minIntervalMinutes: 10, // Error: too frequent
  maxIntervalHours: 24
});

Parsing Cron Expressions

import { parseCronExpression } from '@bernierllc/validators-cron-syntax';

const result = parseCronExpression('0 12 * * *');
if (result.success) {
  console.log(result.fields);
  // {
  //   minute: '0',
  //   hour: '12',
  //   dayOfMonth: '*',
  //   month: '*',
  //   dayOfWeek: '*'
  // }
}

// Parse with timezone
const result2 = parseCronExpression('0 12 * * * America/New_York');
console.log(result2.timezone); // 'America/New_York'

Human-Readable Descriptions

import { describeCronExpression } from '@bernierllc/validators-cron-syntax';

console.log(describeCronExpression('0 12 * * *'));
// "at minute 0 hour 12"

console.log(describeCronExpression('*/15 * * * *'));
// "every 15 minutes"

console.log(describeCronExpression('0 12 * * * America/New_York'));
// "at minute 0 hour 12 (America/New_York)"

API Reference

validateCronSyntax(cronExpression, options?, utils?)

Validates a cron expression and returns validation problems.

Parameters:

• cronExpression (string): The cron expression to validate
• options (CronSyntaxOptions): Validation options
• utils (SharedUtils): Optional shared utilities from validators-core

Returns: Promise<Problem[]> - Array of validation problems

Options:

interface CronSyntaxOptions {
  allowSeconds?: boolean;           // Allow 6-field format (default: false)
  allowYear?: boolean;              // Allow 7-field format (default: false)
  validateTimezone?: boolean;       // Validate timezone identifiers (default: true)
  checkDSTTransitions?: boolean;    // Check for DST issues (default: true)
  minIntervalMinutes?: number;      // Minimum interval between executions
  maxIntervalHours?: number;        // Maximum interval between executions
  checkOverlaps?: boolean;          // Check for overlapping schedules (default: false)
}

isValidCron(cronExpression, options?)

Quick check if a cron expression is valid (no errors).

Returns: Promise<boolean>

parseCronExpression(cronExpression, options?)

Parses a cron expression into its component fields.

Returns: CronParseResult

interface CronParseResult {
  success: boolean;
  fields?: {
    second?: string;
    minute: string;
    hour: string;
    dayOfMonth: string;
    month: string;
    dayOfWeek: string;
    year?: string;
  };
  timezone?: string;
  error?: string;
}

describeCronExpression(cronExpression, options?)

Returns a human-readable description of the cron expression.

Returns: string

Validation Rules

Cron Syntax (cron-syntax)

• Validates field count (5, 6, or 7 fields)
• Validates field value ranges
• Validates special characters (*, ?, -, /, ,)
• Validates ranges, steps, and lists

Timezone Validation (cron-timezone)

• Validates IANA timezone identifiers
• Warns about UTC and Etc/ timezones (DST issues)
• Suggests location-based timezones

DST Transition Safety (cron-dst-transition)

• Warns about 2 AM schedules (spring-forward skip)
• Warns about 1 AM schedules (fall-back duplicate)
• Errors on daily 2 AM during March/November
• Provides DST-safe alternatives

Frequency Validation (cron-frequency)

• Enforces minimum interval between executions
• Enforces maximum interval between executions
• Warns about very high frequencies (>1000/day)
• Provides frequency insights

Cron Format Support

Standard 5-field format

* * * * *
│ │ │ │ │
│ │ │ │ └── Day of week (0-7)
│ │ │ └──── Month (1-12)
│ │ └────── Day of month (1-31)
│ └──────── Hour (0-23)
└────────── Minute (0-59)

6-field format (with seconds)

* * * * * *
│ │ │ │ │ │
│ │ │ │ │ └── Day of week (0-7)
│ │ │ │ └──── Month (1-12)
│ │ │ └────── Day of month (1-31)
│ │ └──────── Hour (0-23)
│ └────────── Minute (0-59)
└──────────── Second (0-59)

7-field format (with seconds and year)

* * * * * * *
│ │ │ │ │ │ │
│ │ │ │ │ │ └── Year (1970-2099)
│ │ │ │ │ └──── Day of week (0-7)
│ │ │ │ └────── Month (1-12)
│ │ │ └──────── Day of month (1-31)
│ │ └────────── Hour (0-23)
│ └──────────── Minute (0-59)
└────────────── Second (0-59)

Examples

Basic Schedules

// Every minute
await validateCronSyntax('* * * * *');

// Every hour at minute 0
await validateCronSyntax('0 * * * *');

// Daily at noon
await validateCronSyntax('0 12 * * *');

// Every weekday at 9 AM
await validateCronSyntax('0 9 * * 1-5');

Advanced Schedules

// Every 15 minutes during business hours
await validateCronSyntax('*/15 9-17 * * 1-5');

// Multiple specific times
await validateCronSyntax('0 8,12,16,20 * * *');

// First day of month at midnight
await validateCronSyntax('0 0 1 * *');

// With timezone
await validateCronSyntax('0 12 * * * America/New_York');

DST-Safe Scheduling

// ❌ Risky: May skip during spring DST
await validateCronSyntax('0 2 * * *');
// Warning: Cron expression scheduled during DST transition hour (2 AM)

// ✅ Safe: Use 3 AM or UTC
await validateCronSyntax('0 3 * * *');
await validateCronSyntax('0 2 * * * UTC');

Frequency Controls

// Enforce minimum 5-minute interval
await validateCronSyntax('*/5 * * * *', {
  minIntervalMinutes: 5 // OK
});

await validateCronSyntax('* * * * *', {
  minIntervalMinutes: 5 // Error: too frequent
});

// Enforce maximum 12-hour interval
await validateCronSyntax('0 */6 * * *', {
  maxIntervalHours: 12 // OK
});

Error Handling

const problems = await validateCronSyntax('invalid cron');

problems.forEach(problem => {
  console.log(`[${problem.severity}] ${problem.message}`);
  if (problem.suggestion) {
    console.log(`  Suggestion: ${problem.suggestion}`);
  }
});

Problem Severity Levels:

• error: Invalid syntax or critical issues
• warn: Potential issues or best practice violations
• info: Informational messages

Integration Status

• Logger: not-applicable - Pure validation utility
• Docs-Suite: ready - Full API documentation available
• NeverHub: not-applicable - Stateless validator

Dependencies

• @bernierllc/validators-core - Core validation framework

See Also

• @bernierllc/validators-core - Core validation framework
• @bernierllc/validators-workflow-sla - Workflow SLA validation
• @bernierllc/validators-temporal-consistency - Temporal consistency checks

License

Copyright (c) 2025 Bernier LLC. All rights reserved.