cron-explain-now

Convert cron expressions into clear, human-readable text — zero dependencies.

Ever stared at 0 2 * * 1-5 and had no idea what it actually does? cron-explain-now turns cron syntax into plain English (and other languages) instantly — no website lookup needed.

explain('0 0 * * *')
// → "Runs every day at midnight"

explain('*/15 9-17 * * 1-5')
// → "Runs every 15 minutes, between 09:00 and 17:00, Monday through Friday"

Table of Contents

• Why cron-explain-now?
• Installation
• Usage
• API
• Supported Syntax
• Examples
• CLI Usage
• Localization
• Comparison
• Contributing
• Good First Issues
• Roadmap
• License

Why cron-explain-now?

• Zero dependencies — lightweight, fast install, no supply-chain bloat.
• Beginner-friendly API — one function, predictable output.
• Readable output — designed for humans, not just developers.
• TypeScript support — full type definitions included out of the box.
• Works everywhere — Node.js, browser bundlers, and CLI.

Installation

npm install cron-explain-now

yarn add cron-explain-now

pnpm add cron-explain-now

Usage

JavaScript (CommonJS)

const { explain } = require('cron-explain-now');

console.log(explain('30 4 * * *'));
// → "Runs every day at 04:30"

ES Modules / TypeScript

import { explain } from 'cron-explain-now';

console.log(explain('0 9 * * 1-5'));
// → "Runs at 09:00, Monday through Friday"

API

explain(cronExpression: string, options?: ExplainOptions): string

Converts a cron expression into a human-readable string.

| Parameter | Type | Description | |---|---|---| | cronExpression | string | A standard 5-field cron expression (minute hour day month weekday) | | options | ExplainOptions | Optional configuration object |

ExplainOptions

| Option | Type | Default | Description | |---|---|---|---| | locale | string | 'en' | Output language (see Localization) | | use24HourTime | boolean | true | Use 24-hour or 12-hour time format | | verbose | boolean | false | Include extra detail in the explanation |

explain('0 18 * * 5', { use24HourTime: false });
// → "Runs at 6:00 PM, on Friday"

isValidCron(cronExpression: string): boolean

Validates whether a string is a syntactically correct cron expression.

isValidCron('* * * * *'); // → true
isValidCron('99 * * * *'); // → false

Supported Syntax

| Field | Allowed Values | Special Characters | |---|---|---| | Minute | 0-59 | * , - / | | Hour | 0-23 | * , - / | | Day of Month | 1-31 | * , - / | | Month | 1-12 (or JAN-DEC) | * , - / | | Day of Week | 0-6 (or SUN-SAT) | * , - / |

Special shortcut strings are also supported:

| Shortcut | Equivalent | Meaning | |---|---|---| | @yearly / @annually | 0 0 1 1 * | Once a year | | @monthly | 0 0 1 * * | Once a month | | @weekly | 0 0 * * 0 | Once a week | | @daily / @midnight | 0 0 * * * | Once a day | | @hourly | 0 * * * * | Once an hour |

Examples

explain('* * * * *');
// → "Runs every minute"

explain('*/5 * * * *');
// → "Runs every 5 minutes"

explain('0 */2 * * *');
// → "Runs every 2 hours"

explain('0 0 1 * *');
// → "Runs on the 1st of every month at midnight"

explain('0 0 * * 0');
// → "Runs every Sunday at midnight"

explain('15 14 1 * *');
// → "Runs at 14:15, on the 1st of every month"

explain('0 22 * * 1-5');
// → "Runs at 22:00, Monday through Friday"

explain('@daily');
// → "Runs once a day, at midnight"

CLI Usage

cron-explain-now also ships with a small command-line tool.

npx cron-explain-now "0 0 * * *"
# Runs every day at midnight

npx cron-explain-now "*/10 8-18 * * 1-5" --no-24h
# Runs every 10 minutes, between 8:00 AM and 6:00 PM, Monday through Friday

Localization

Currently supported locales:

| Code | Language | |---|---| | en | English (default) | | es | Spanish | | hi | Hindi |

explain('0 9 * * 1-5', { locale: 'hi' });
// → "सोमवार से शुक्रवार, सुबह 09:00 बजे चलता है"

More locales are welcome — see Contributing.

Comparison

| Feature | cron-explain-now | cronstrue | |---|---|---| | Zero dependencies | ✅ | ✅ | | Bundle size | Small | Larger | | TypeScript types included | ✅ | ✅ | | CLI included | ✅ | ❌ | | Beginner-friendly source code | ✅ | Moderate |

cron-explain-now aims to be a lightweight, easy-to-read alternative — great if you want a smaller footprint or want to study/contribute to a simple, approachable codebase.

Contributing

Contributions are very welcome, including from first-time open-source contributors!

1. Fork the repository
2. Clone your fork: git clone https://github.com/mayank8025/cron-explain-now.git
3. Install dependencies: npm install
4. Create a branch: git checkout -b feature/my-feature
5. Make your changes and add tests
6. Run tests: npm test
7. Commit and push, then open a Pull Request

Please read CONTRIBUTING.md for full guidelines.

Good First Issues

These are great entry points if you're new to the project or to open source in general:

• Add support for @reboot shortcut
• Add a new locale (French, German, Portuguese, etc.)
• Improve error messages for invalid cron strings
• Add support for Quartz-style 6/7-field cron expressions
• Write additional unit tests for edge cases (e.g. 30-59/10)
• Add a toJSON() method that returns a structured breakdown instead of a string

Look for issues tagged good first issue on GitHub.

Roadmap

• [ ] Quartz cron format support (6/7 fields)
• [ ] Timezone-aware explanations
• [ ] Browser playground / demo site
• [ ] More locales (French, German, Portuguese, Japanese)
• [ ] toJSON() structured output mode
• [ ] VS Code extension for inline cron explanations

License

MIT © Mayank Sardhara