cron-validator

cron-validator is a lightweight, zero-dependency TypeScript/JavaScript library that checks whether a string is a syntactically valid cron expression, without attempting to schedule or run anything. It validates each field (seconds, minutes, hours, day-of-month, month, day-of-week) independently against its legal range, catching malformed steps, inverted ranges, and stray wildcards that scheduling libraries like node-cron won’t reject on their own.

The library deliberately takes a naive, explicit-rule approach rather than a general cron-parsing grammar, trading some flexibility for code that’s easy to reason about and extend. Optional flags add support for seconds fields, three-letter month/weekday aliases (jan, mon), blank-day ’?’ notation, 7-as-Sunday, and Quartz-style nth-weekday-of-month expressions (mon#2), so teams can match the exact cron dialect their scheduler or job runner expects.

What You Get

• A single isValidCron(cron, options) function with no runtime dependencies to install or audit.
• Per-field range validation for seconds, minutes, hours, day-of-month, month, and day-of-week.
• Optional support for month/weekday aliases (jan, mon), blank-day ? notation, and 7-as-Sunday.
• Quartz-style nth-weekday-of-month syntax (e.g. mon#2 for the second Monday) via the allowNthWeekdayOfMonth flag.
• Published TypeScript type declarations for the Options object, so flags are checked at compile time.

Common Use Cases

• Validating a cron string entered into a UI form before saving a scheduled job.
• Rejecting malformed cron expressions in an API request body before they reach a scheduler.
• Enforcing a specific cron dialect (e.g. with seconds, or Quartz nth-weekday syntax) that an internal scheduling system expects.
• Guarding a database column or config file that stores cron expressions against silently-invalid values.

Under The Hood

Architecture cron-validator is a single-module functional library: all logic lives in src/index.ts, which composes small pure helper functions (safeParseInt, isWildcard, isQuestionMark, isInRange, isValidRange, isValidStep, validateForRange) into per-field validators (hasValidSeconds, hasValidMinutes, hasValidHours, hasValidDays, hasValidMonths, hasValidWeekdays) that the exported isValidCron entry point runs against space-split cron fields, accumulating a checks: boolean[] array and reducing it with Array.prototype.every. There are no classes, no dependency injection, and no I/O — the entire execution path is synchronous string parsing and array validation. Because every field validator is independent and stateless, changing the format of one field touches only that validator and the Options/WeekdayOptions type definitions that thread flags through the pipeline; the risk of a change is confined almost entirely to the isValidCron dispatch logic.

Tech Stack The package is authored in TypeScript (compiled via tsc to CommonJS under lib/, targeting ES5 per tsconfig.json) with zero runtime dependencies — the entire published surface is one function, isValidCron. Testing uses Jest 27 with ts-jest for direct TypeScript test execution (src/index.test.ts), and linting is configured through the now-legacy tslint (tslint:latest + tslint-config-standard) rather than ESLint. Node 16.13.2 is pinned via .nvmrc for local development, and there is no CI workflow file (no .github/workflows) — publishing runs test then build via the prepublishOnly npm script rather than a hosted pipeline.

Code Quality Test coverage is extensive relative to the codebase size: index.test.ts contains dozens of it blocks (plus parameterized it.each cases for nth-weekday syntax) exercising boundary values, aliases, ranges, steps, and combined-flag interactions, run via Jest with coverage collection. TypeScript’s strict mode is enabled (noUnusedLocals, noUnusedParameters, noImplicitReturns, noFallthroughCasesInSwitch) and the Options/WeekdayOptions types give call sites compile-time safety. Naming is consistent camelCase with descriptive is/has-prefixed predicate functions. There is no explicit error handling — invalid input simply returns false rather than throwing, which is appropriate for a boolean-returning validator. The main quality gap is the absence of a CI workflow to enforce tests and linting on every push.

API Design The public API is a single function, isValidCron(cron, options?), with sensibly-defaulted, additive boolean flags (seconds, alias, allowBlankDay, allowSevenAsSunday, allowNthWeekdayOfMonth) rather than a configuration object requiring upfront setup — callers can validate a plain 5-field cron string in one line and opt into extended syntax only as needed. Naming is self-explanatory and the README documents every flag with a runnable before/after example. There’s no builder pattern, no separate parse-then-validate step, and no thrown exceptions to catch — the tradeoff is that a caller gets a plain false with no explanation of which field failed (the README explicitly notes an ‘explain mode’ was considered and dropped). Compared to more feature-rich alternatives like cron-validate, the API is intentionally narrower and less configurable in exchange for being close to zero-ceremony to adopt.