@catbee/cron-parser

⏱️ Cron expression parser for Node.js and TypeScript

A lightweight, timezone-aware cron expression parser with full support for seconds, DST transitions, iterators, randomized scheduling, and crontab file parsing. Built for production systems with clean TypeScript types and zero-config ESM/CJS support.

Installation

npm install @catbee/cron-parser

Cron Format

*    *    *    *    *    *
┬    ┬    ┬    ┬    ┬    ┬
│    │    │    │    │    │
│    │    │    │    │    └─ day of week (0-7, 1L-7L) (0 or 7 is Sun)
│    │    │    │    └────── month (1-12, JAN-DEC)
│    │    │    └─────────── day of month (1-31, L)
│    │    └──────────────── hour (0-23)
│    └───────────────────── minute (0-59)
└────────────────────────── second (0-59, optional)

Special Characters

| Character | Description | Example | | --------- | ------------------------- | ---------------------------------------------------------------------- | | * | Any value | * * * * * (every minute) | | ? | Any value (alias for *) | ? * * * * (every minute) | | , | Value list separator | 1,2,3 * * * * (1st, 2nd, and 3rd minute) | | - | Range of values | 1-5 * * * * (every minute from 1 through 5) | | / | Step values | */5 * * * * (every 5th minute) | | L | Last day of month/week | 0 0 L * * (midnight on last day of month) | | # | Nth day of month | 0 0 * * 1#1 (first Monday of month) | | H | Randomized value | H * * * * (random minute every hour) |

Predefined Expressions

| Expression | Description | Equivalent | | ----------- | ----------------------------------------- | --------------- | | @yearly | Once a year at midnight of January 1 | 0 0 0 1 1 * | | @monthly | Once a month at midnight of first day | 0 0 0 1 * * | | @weekly | Once a week at midnight on Sunday | 0 0 0 * * 0 | | @daily | Once a day at midnight | 0 0 0 * * * | | @hourly | Once an hour at the beginning of the hour | 0 0 * * * * | | @minutely | Once a minute | 0 * * * * * | | @secondly | Once a second | * * * * * * | | @weekdays | Every weekday at midnight | 0 0 0 * * 1-5 | | @weekends | Every weekend at midnight | 0 0 0 * * 0,6 |

Field Values

| Field | Values | Special Characters | Aliases | | ------------ | ------ | ------------------------------- | ------------------------------ | | second | 0-59 | * ? , - / H | | | minute | 0-59 | * ? , - / H | | | hour | 0-23 | * ? , - / H | | | day of month | 1-31 | * ? , - / H L | | | month | 1-12 | * ? , - / H | JAN-DEC | | day of week | 0-7 | * ? , - / H L # | SUN-SAT (0 or 7 is Sunday) |

Options

| Option | Type | Description | | ----------- | ------------------------ | --------------------------------------------------------------------------------------------------------------------------- | | currentDate | Date | string | number | Current date. Defaults to current local time in UTC. If not provided but startDate is set, startDate is used instead. | | endDate | Date | string | number | End date of iteration range. Sets the iteration range end point | | startDate | Date | string | number | Start date of iteration range. Sets the iteration range start point | | tz | string | Timezone (e.g. Europe/London) | | hashSeed | string | Seed used for H randomized field values | | strict | boolean | Enable strict validation for expression format and day-of-month/day-of-week rules |

Supported string date formats:

• ISO8601
• HTTP and RFC2822
• SQL

⚡ Quick Start

import CronExpressionParser, {
  CronExpressionOptions,
  CronFileParser,
  CronFileParserResult
} from '@catbee/cron-parser';

const options: CronExpressionOptions = {
  currentDate: '2023-01-01T00:00:00Z',
  tz: 'UTC',
  strict: false
};

const expression = CronExpressionParser.parse('*/5 * * * *', options);
console.log('Next:', expression.next().toString());

const nextThree = expression.take(3);
console.log('Next 3:', nextThree.map(date => date.toString()));

const includesNow = expression.includesDate(new Date());
console.log('Includes now?', includesNow);

Crontab File Operations

import { CronFileParser } from '@catbee/cron-parser';

const result = CronFileParser.parseFileSync('./crontab.txt');
console.log('Variables:', result.variables);
console.log('Expressions:', result.expressions.length);
console.log('Errors:', result.errors);

import { CronFileParser } from '@catbee/cron-parser';

const result = await CronFileParser.parseFile('/path/to/crontab');
console.log('Variables:', result.variables);
console.log('Expressions:', result.expressions.length);
console.log('Errors:', result.errors);

Advanced Features

Strict Mode

Strict mode enforces more explicit cron expressions by rejecting ambiguous forms.

• Prevents both dayOfMonth and dayOfWeek from being used together in strict mode
• Requires the full 6-field expression if strict mode is enabled
• Rejects empty expressions

import CronExpressionParser from '@catbee/cron-parser';

try {
  CronExpressionParser.parse('0 0 12 1-31 * 1', { strict: true });
} catch (err) {
  console.error(err.message);
}

Last Day of Month / Week Support

The parser supports L in day-of-month and day-of-week fields to represent the last occurrence.

const lastMonday = CronExpressionParser.parse('0 0 0 * * 1L');
const lastDayOfMonth = CronExpressionParser.parse('0 0 L * *');

Randomized Scheduling (H)

The H character produces deterministic jitter when used with the same hashSeed.

const interval = CronExpressionParser.parse('H * * * *', {
  currentDate: '2023-03-26T01:00:00Z',
  hashSeed: 'job-name'
});

console.log(interval.stringify());

Timezone Support

The parser handles timezone-aware scheduling and DST transitions with Luxon.

const interval = CronExpressionParser.parse('0 * * * *', {
  currentDate: '2023-03-26T01:00:00',
  tz: 'Europe/London'
});

console.log(interval.next().toString());
console.log(interval.next().toString());

📚 Documentation

Full documentation and examples are available at:

https://catbee.in/docs/@catbee/cron-parser/intro

🤝 Credits

Based on the original cron-parser library and extended under Catbee.

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for development setup, testing, and PR guidance.

📜 License

MIT © Catbee Technologies