cron-parser-yomly

TypeScript package that parses basic 5-field cron expressions and a command.

Not a scheduler. It expands each field to its numeric values and returns them with the command string.

Features

• Supports lists (,), ranges (-), wildcards (*), and steps (*/n, a-b/n).
• Validates bounds per field: minutes 0–59, hours 0–23, day-of-month 1–31, month 1–12, day-of-week 0–6 (0 = Sunday).
• Calendar-aware validation: day-of-month must be feasible in at least one of the selected months. February allows up to 29.
• Errors use an enum code and human-readable message.

Install

Add to your project (library only). Build uses TypeScript.

Usage

import { parseCronExpression } from "cron-parser-yomly";

const res = parseCronExpression("*/15 0 1,2,3,15 */2 1-5 /usr/bin/find");
// {
//   minutes: [0, 15, 30, 45],
//   hours: [0],
//   days_of_month: [1, 2, 3, 15],
//   months: [1, 3, 5, 7, 9, 11],
//   days_of_week: [1, 2, 3, 4, 5],
//   command: "/usr/bin/find"
// }

API

parseCronExpression(input: string) → { minutes, hours, days_of_month, months, days_of_week, command }

Throws CronParseError with code from ErrorCode and a human-readable message when invalid.

Rules and Limits

• No named months/days (JAN, MON). Numeric only.
• Day-of-week 0–6 only (0 = Sunday). 7 is not accepted.
• No wrap-around ranges (e.g., 50-10) — invalid.
• Steps must be integers ≥ 1. */n expands the whole field; a-b/n expands inclusively inside the range.
• Command is everything after the five fields (trimmed).
• Calendar validation: if a day-of-month has no feasible month among the selected months (e.g., 31 while months are 4,6,9,11), it is invalid. If at least one month can contain the day (e.g., months * with day 31), it is accepted.

Dev

• Use appropriate node version: nvm use
• Install dependencies: npm i
• Build: npm run build
• Test: npm test (uses Vitest)

AI/LLM Usage

I can implement this codebase independently. I used an AI assistant (Codex CLI) to accelerate iteration — not to substitute for design or implementation. Not auto‑generated: I wrote the requirements, constrained the approach, reviewed diffs, and validated behavior with tests and manual edge cases. I understand every line and own the design/trade‑offs. No proprietary code was copied; dependencies are only those in package.json.

What was AI‑assisted (under my direction):

• Parser and field expansion
• Typed error model (ErrorCode + CronParseError)
• Calendar‑aware validation (e.g., DOM feasibility, February ≤ 29)
• Public API and TypeScript types
• Test suite (Vitest) and initial README/build config

Examples of my steering choices:

• Numeric‑only months/days; DOW 0–6 (reject 7)
• No wrap‑around ranges; inclusive ranges and */n step semantics
• Strict per‑field bounds with sorted, de‑duplicated outputs
• Command parsed as everything after five fields (trimmed)
• Stable error codes/messages for precise, testable failures

small change