cRonstrue

cronstrue is a zero-dependency JavaScript/TypeScript library that parses a cron expression and outputs a plain-English (or localized) description of the schedule — for example, */5 * * * * becomes “Every 5 minutes”. It supports standard 5-field cron, plus 6- and 7-field variants with seconds and year, Quartz Job Scheduler syntax (#, L, W, ?), and the common @daily/@weekly/@yearly-style shorthand nicknames.

It ships as a UMD module so it works identically in Node/CommonJS, bundlers (ESM/webpack/TypeScript), or a plain browser <script> tag via the unpkg CDN, and includes a small CLI (npx cronstrue "*/5 * * * *") for ad-hoc use from a terminal. Beyond English, cronstrue bundles translations for 30+ languages, selectable per call via the locale option, either all at once (cronstrue/i18n) or as individually tree-shakeable locale modules (cronstrue/locales/[locale]).

What You Get

• A single toString(expression, options) API that returns a natural-language description of any cron expression
• Support for 5-field standard cron, 6/7-field variants with seconds and year, and Quartz-specific characters (#, L, W)
• Recognition of @yearly/@monthly/@weekly/@daily/@hourly/@reboot shorthand expressions
• 30+ bundled language translations, selectable per call or loaded individually to keep bundle size down
• A zero-dependency runtime — nothing pulled into consuming projects’ node_modules at install time
• A bundled CLI (cronstrue) for describing expressions directly from a terminal or scripts
• Configurable output via options: verbose mode, 24-hour time, day/month start-index, leading-zero trimming, and AND vs OR combination of day-of-month/day-of-week

Common Use Cases

• Rendering the human-readable schedule text next to a cron field in an admin dashboard or job-scheduling UI
• Validating and previewing a user-entered cron expression before saving a scheduled task
• Generating changelogs, tooltips, or documentation that explain what a deployed cron job actually does
• Building CLI tools or scripts that need to print an expression’s meaning for logging or debugging
• Displaying localized schedule descriptions in multi-language SaaS admin panels

Under The Hood

Architecture

cronstrue follows a small, cleanly layered pipeline: CronParser (src/cronParser.ts) takes the raw expression, expands @-prefixed shorthand syntax (@daily, @yearly, @reboot, etc.) via parseSpecial(), splits it into fields with extractParts(), then normalizes and validates each field, delegating range checks to RangeValidator (rangeValidator.ts). The normalized parts are handed to ExpressionDescriptor (src/expressionDescriptor.ts), a static-factory class (ExpressionDescriptor.toString() / .initialize()) that walks the parsed fields and assembles a human-readable sentence, drawing vocabulary from a Locale object supplied by a LocaleLoader (enLocaleLoader.ts for the default English-only build, allLocalesLoader.ts for the full i18n bundle). StringUtilities centralizes small string-formatting helpers shared across the descriptor. The two entry modules (cronstrue.ts, cronstrue-i18n.ts) exist only to wire a specific LocaleLoader into ExpressionDescriptor.initialize() before exporting toString, so the two npm entry points (cronstrue vs cronstrue/i18n) are the same descriptor logic with a different locale set injected at import time. Options (options.ts) is a plain interface threaded through every layer rather than mutable shared state, keeping parsing and description generation stateless per call.

Tech Stack

cronstrue is written entirely in TypeScript with a genuinely zero-dependency runtime — the dependencies field in package.json is empty, and the library only pulls in TypeScript, ts-loader, and webpack 5 with terser-webpack-plugin as devDependencies to compile the UMD bundle into dist/. Tests run on Mocha with Chai assertions via ts-node/register, executing directly against the TypeScript sources without a separate compile step. The docs site is a static demo page (docs/index.html) built with Handlebars templates, using pixl-xml/xml2js/marked as devDependencies to generate locale-comparison tables. Publishing is scripted through a webpack-cli build in prepublishOnly, producing a UMD bundle that works unmodified in Node (CommonJS), bundlers (ESM/webpack), or a plain <script> tag via the unpkg CDN. A thin CLI (bin/cli.js) wraps the compiled dist/cronstrue module for npx cronstrue "<expr>" usage.

Code Quality

Test coverage is broad rather than superficial: test/cronstrue.ts alone runs a large number of individual cron-expression assertions grouped by feature (every/interval, day-of-week, Quartz #/L/W, @-shorthand, verbose mode), plus dedicated suites for i18n (test/i18n.ts, test/i18n-fr.ts), the parser (test/cronParser.ts), and string helpers (test/stringUtilities.ts). CI (.github/workflows/build.yml) runs npm test across multiple Node versions on every push and PR to main, though it stops at the test step — there’s no separate lint or type-check job wired into CI beyond what the TypeScript compiler catches during test execution. Prettier is configured inline in package.json but isn’t enforced as a CI gate. Types are used consistently throughout (strict interfaces for Options, Locale, LocaleLoader), and error handling favors throwing descriptive parse errors (via the throwExceptionOnParseError option) over silently swallowing malformed input. The small module count under src/ keeps the codebase easy to hold in your head.

What Makes It Unique

cronstrue’s differentiator isn’t cron-to-English translation itself — several JavaScript libraries do that — but the combination of Quartz Job Scheduler syntax support (7-field expressions with seconds and year, plus #, L, W special characters that many cron-to-English tools skip) with genuine internationalization depth: 30+ bundled locales, selectable per call, with two distinct import strategies (cronstrue/i18n for all locales at once versus cronstrue/locales/[locale] for tree-shaking a single one). It was originally ported from a C# implementation (cron-expression-descriptor), and that lineage carries through to a family of ports in other languages the project links to — making cronstrue effectively the reference JavaScript implementation of a translation algorithm shared across a small ecosystem of language ports, rather than a one-off library.