cron-human 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Akin Ibitoye
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,282 @@
+# cron-human
+
+> A command-line tool that converts cron expressions into human-readable English and calculates the next scheduled run times.
+
+[![npm version](https://img.shields.io/npm/v/cron-human.svg)](https://www.npmjs.com/package/cron-human)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## What is this?
+
+If you've ever looked at a cron expression like `0 12 * * MON-FRI` and wondered "when does this actually run?", this tool is for you. It translates cryptic cron syntax into plain English and shows you exactly when the job will execute next.
+
+Perfect for:
+- 🔍 **Debugging cron jobs** - Verify your cron expressions do what you expect
+- � **Understanding existing schedules** - Decode cron expressions in config files
+- ✅ **Validating syntax** - Catch errors before deploying to production
+- 🌐 **Timezone conversions** - See execution times in different timezones
+
+## Features
+
+- �🗣 **Human readable** - Converts `*/5 * * * *` to "Every 5 minutes"
+- 📅 **Next run times** - Calculates exact dates for upcoming executions
+- 🌍 **Timezone aware** - Supports IANA timezone identifiers (e.g., `America/New_York`, `Asia/Tokyo`)
+- 🤖 **JSON output** - Machine-readable format for scripting and automation
+- ✅ **Strict validation** - Catches invalid expressions and provides clear error messages
+- ⏱️ **Seconds support** - Handle 6-field cron expressions with `--seconds` flag
+- 🏷️ **Macro shortcuts** - Supports `@daily`, `@hourly`, `@weekly`, etc.
+
+## Installation
+
+### One-time use with npx
+
+No installation needed - run directly with npx:
+
+```bash
+npx cron-human "*/5 * * * *"
+```
+
+### Global installation
+
+Install once, use anywhere:
+
+```bash
+npm install -g cron-human
+```
+
+Then use it directly:
+
+```bash
+cron-human "0 12 * * MON-FRI"
+```
+
+## Usage
+
+### Basic Usage
+
+```bash
+cron-human "<cron-expression>"
+```
+
+**Example:**
+```bash
+$ cron-human "30 4 * * *"
+At 04:30
+
+Next 5 runs:
+- 2026-01-22 04:30:00
+- 2026-01-23 04:30:00
+- 2026-01-24 04:30:00
+- 2026-01-25 04:30:00
+- 2026-01-26 04:30:00
+```
+
+### Options
+
+| Option | Alias | Description | Default |
+|---|---|---|---|
+| `--next <number>` | `-n` | Number of upcoming run times to show (max 100) | 5 |
+| `--tz <timezone>` | | IANA timezone for output dates (e.g., `America/New_York`) | System local time |
+| `--json` | | Output in JSON format for scripting | false |
+| `--quiet` | `-q` | Print only the human description (no next runs) | false |
+| `--seconds` | | Enable 6-field cron format (includes seconds) | false |
+| `--help` | `-h` | Show help message | |
+| `--version` | `-v` | Show installed version | |
+
+## Examples
+
+### Common Cron Patterns
+
+**Every 5 minutes:**
+```bash
+$ cron-human "*/5 * * * *"
+Every 5 minutes
+```
+
+**Daily at midnight:**
+```bash
+$ cron-human "0 0 * * *"
+At 00:00
+```
+
+**Weekdays only at 9 AM:**
+```bash
+$ cron-human "0 9 * * MON-FRI"
+At 09:00, Monday through Friday
+```
+
+**First day of every month:**
+```bash
+$ cron-human "0 0 1 * *"
+At 00:00, on day 1 of the month
+```
+
+### Using Macros
+
+Cron macros are shortcuts for common schedules:
+
+```bash
+$ cron-human "@daily"
+At 00:00
+
+$ cron-human "@hourly"
+Every hour
+
+$ cron-human "@weekly"
+At 00:00, only on Sunday
+```
+
+**Supported macros:**
+- `@yearly` or `@annually` - Run once a year: `0 0 1 1 *`
+- `@monthly` - Run once a month: `0 0 1 * *`
+- `@weekly` - Run once a week: `0 0 * * 0`
+- `@daily` - Run once a day: `0 0 * * *`
+- `@hourly` - Run once an hour: `0 * * * *`
+
+### Timezone Examples
+
+**New York time:**
+```bash
+$ cron-human "0 9 * * *" --tz America/New_York
+At 09:00
+
+Next 5 runs:
+- 2026-01-22 09:00:00
+- 2026-01-23 09:00:00
+- ...
+```
+
+**Tokyo time:**
+```bash
+$ cron-human "30 14 * * *" --tz Asia/Tokyo --next 3
+At 14:30
+
+Next 3 runs:
+- 2026-01-22 14:30:00
+- 2026-01-23 14:30:00
+- 2026-01-24 14:30:00
+```
+
+### JSON Output for Scripting
+
+Perfect for parsing in scripts or CI/CD pipelines:
+
+```bash
+$ cron-human "*/15 * * * *" --json --next 2
+{
+  "expression": "*/15 * * * *",
+  "description": "Every 15 minutes",
+  "nextRuns": [
+    "2026-01-22 12:15:00",
+    "2026-01-22 12:30:00"
+  ]
+}
+```
+
+### Quiet Mode
+
+Get just the description without the run times:
+
+```bash
+$ cron-human "0 */6 * * *" --quiet
+Every 6 hours
+```
+
+### Seconds-Precision Cron
+
+Some systems (like certain schedulers) support 6-field cron with seconds:
+
+```bash
+$ cron-human "*/30 * * * * *" --seconds
+Every 30 seconds
+```
+
+## Supported Cron Format
+
+### Standard 5-field format:
+```
+* * * * *
+│ │ │ │ │
+│ │ │ │ └─── Day of week (0-6, SUN-SAT)
+│ │ │ └───── Month (1-12)
+│ │ └─────── Day of month (1-31)
+│ └───────── Hour (0-23)
+└─────────── Minute (0-59)
+```
+
+### 6-field format (with `--seconds`):
+```
+* * * * * *
+│ │ │ │ │ │
+│ │ │ │ │ └─── Day of week (0-6)
+│ │ │ │ └───── Month (1-12)
+│ │ │ └─────── Day of month (1-31)
+│ │ └───────── Hour (0-23)
+│ └─────────── Minute (0-59)
+└───────────── Second (0-59)
+```
+
+### Special characters:
+- `*` - Any value
+- `,` - List (e.g., `1,3,5`)
+- `-` - Range (e.g., `1-5`)
+- `/` - Step (e.g., `*/10` = every 10)
+
+## Troubleshooting
+
+### Invalid cron expression error
+
+Make sure your expression has the correct number of fields:
+- **5 fields** for standard cron (default)
+- **6 fields** with `--seconds` flag
+
+### Timezone not recognized
+
+Use valid IANA timezone identifiers. Common examples:
+- `UTC`
+- `America/New_York`
+- `Europe/London`
+- `Asia/Tokyo`
+
+Find your timezone: [IANA Timezone Database](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)
+
+### Expression accepted but results look wrong
+
+Use `--tz UTC` to see results in UTC and verify the pattern:
+
+```bash
+cron-human "0 12 * * *" --tz UTC --next 7
+```
+
+## Development
+
+Want to contribute or run locally?
+
+1. **Clone the repository:**
+   ```bash
+   git clone https://github.com/yourusername/cron-human.git
+   cd cron-human
+   ```
+
+2. **Install dependencies:**
+   ```bash
+   npm install
+   ```
+
+3. **Run tests:**
+   ```bash
+   npm test
+   ```
+
+4. **Build:**
+   ```bash
+   npm run build
+   ```
+
+5. **Run locally:**
+   ```bash
+   npm run dev "*/5 * * * *"
+   ```
+
+## License
+
+MIT © Akin Ibitoye

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import { createRequire } from 'module';
+import { DateTime } from 'luxon';
+import { explainCron, getNextRuns, validateCron } from './lib.js';
+const require = createRequire(import.meta.url);
+const pkg = require('../package.json');
+const program = new Command();
+program
+    .name('cron-human')
+    .description('Converts cron expressions to human-readable English and prints next run times.')
+    .version(pkg.version, '-v, --version')
+    .argument('<expression>', 'Cron expression to parse')
+    .option('-n, --next <number>', 'how many upcoming run times to print', '5')
+    .option('--tz <timezone>', 'timezone for output (default: system timezone)')
+    .option('--json', 'output machine-readable JSON', false)
+    .option('-q, --quiet', 'only print the one-line human explanation (no next runs)', false)
+    .option('--seconds', 'support 6-field cron expressions with seconds', false)
+    .action((expression, options) => {
+    if (options.tz) {
+        const test = DateTime.now().setZone(options.tz);
+        if (!test.isValid) {
+            console.error(`Error: invalid timezone "${options.tz}" (use IANA like "Europe/London")`);
+            process.exit(1);
+        }
+    }
+    let nextCount = 5;
+    if (options.next) {
+        const count = parseInt(options.next, 10);
+        if (!Number.isFinite(count) || count < 1 || count > 100) {
+            console.error("Error: --next must be a number between 1 and 100");
+            process.exit(1);
+        }
+        nextCount = count;
+    }
+    const error = validateCron(expression, {
+        timezone: options.tz,
+        allowSeconds: options.seconds
+    });
+    if (error) {
+        console.error(error);
+        process.exit(1);
+    }
+    try {
+        let description = '';
+        try {
+            description = explainCron(expression);
+        }
+        catch (e) {
+            console.error(`Error: Could not generate description. ${e?.message ?? e}`);
+            process.exit(1);
+        }
+        const output = {
+            expression,
+            description,
+        };
+        if (!options.quiet) {
+            output.nextRuns = getNextRuns(expression, nextCount, options.tz);
+        }
+        if (options.json) {
+            console.log(JSON.stringify(output, null, 2));
+        }
+        else {
+            console.log(description);
+            if (output.nextRuns && output.nextRuns.length > 0) {
+                console.log(`\nNext ${output.nextRuns.length} runs:`);
+                output.nextRuns.forEach((run) => console.log(`- ${run}`));
+            }
+        }
+    }
+    catch (err) {
+        console.error(`Error: ${err.message}`);
+        process.exit(1);
+    }
+});
+program.parse();

package/dist/lib.d.ts

@@ -0,0 +1,7 @@
+export interface ValidateOptions {
+    timezone?: string;
+    allowSeconds?: boolean;
+}
+export declare function validateCron(expression: string, options?: ValidateOptions): string | null;
+export declare function explainCron(expression: string): string;
+export declare function getNextRuns(expression: string, count: number, timezone?: string): string[];

package/dist/lib.js

@@ -0,0 +1,118 @@
+import cronstrue from 'cronstrue';
+import { DateTime } from 'luxon';
+import { CronExpressionParser } from 'cron-parser';
+const MACROS = {
+    "@yearly": "0 0 0 1 1 *",
+    "@annually": "0 0 0 1 1 *",
+    "@monthly": "0 0 0 1 * *",
+    "@weekly": "0 0 0 * * 0",
+    "@daily": "0 0 0 * * *",
+    "@hourly": "0 0 * * * *",
+    "@minutely": "0 * * * * *",
+    "@secondly": "* * * * * *",
+    "@weekdays": "0 0 0 * * 1-5",
+    "@weekends": "0 0 0 * * 0,6",
+};
+function normalizeForParse(expr) {
+    const t = expr.trim();
+    if (!t.startsWith("@"))
+        return t;
+    const key = t.toLowerCase();
+    // for parsing, use expanded cron if known, otherwise keep original (will error)
+    return MACROS[key] ?? t;
+}
+function fieldCount(expr) {
+    return expr.trim().split(/\s+/).length;
+}
+function toJSDate(x) {
+    if (x instanceof Date)
+        return x;
+    if (x && typeof x.toDate === 'function')
+        return x.toDate();
+    if (x && typeof x.toJSDate === 'function')
+        return x.toJSDate();
+    if (x && typeof x.valueOf === 'function')
+        return new Date(x.valueOf());
+    const d = new Date(String(x));
+    if (isNaN(d.getTime())) {
+        throw new Error('cron-parser returned an invalid date iterator result.');
+    }
+    return d;
+}
+export function validateCron(expression, options = {}) {
+    if (expression.length > 1000) {
+        return 'Error: Cron expression too long (max 1000 chars).';
+    }
+    if (expression.match(/[\x00-\x08\x0E-\x1F\x7F]/)) {
+        return 'Error: Invalid control characters in expression.';
+    }
+    if (expression.match(/[\n\r]/)) {
+        return 'Error: Invalid cron expression (newlines not allowed).';
+    }
+    const normalized = normalizeForParse(expression);
+    if (expression.trim().startsWith("@")) {
+        try {
+            const parseOpts = {};
+            if (options.timezone)
+                parseOpts.tz = options.timezone;
+            CronExpressionParser.parse(normalized, parseOpts);
+            return null;
+        }
+        catch (err) {
+            return `Invalid cron expression: ${err.message}`;
+        }
+    }
+    const fields = fieldCount(normalized);
+    if (!options.allowSeconds && fields === 6) {
+        return 'Error: 6-field cron detected. Use --seconds for seconds support.';
+    }
+    if (fields < 5 || fields > 6) {
+        return 'Error: cron must have 5 fields (or 6 with --seconds).';
+    }
+    try {
+        const parseOpts = {};
+        if (options.timezone)
+            parseOpts.tz = options.timezone;
+        CronExpressionParser.parse(normalized, parseOpts);
+        return null;
+    }
+    catch (err) {
+        return `Invalid cron expression: ${err.message}`;
+    }
+}
+export function explainCron(expression) {
+    const normalized = normalizeForParse(expression);
+    return cronstrue.toString(normalized, {
+        use24HourTimeFormat: true,
+        throwExceptionOnParseError: true,
+        verbose: false,
+    });
+}
+export function getNextRuns(expression, count, timezone) {
+    const options = {};
+    if (!Number.isFinite(count) || count < 0 || count > 1000) {
+        throw new Error("Invalid count: must be between 0 and 1000.");
+    }
+    if (timezone) {
+        const test = DateTime.now().setZone(timezone);
+        if (!test.isValid)
+            throw new Error(`Invalid timezone "${timezone}". Use IANA like "Europe/London".`);
+        options.tz = timezone;
+    }
+    try {
+        const interval = CronExpressionParser.parse(normalizeForParse(expression), options);
+        const dates = [];
+        for (let i = 0; i < count; i++) {
+            const obj = interval.next();
+            const jsDate = toJSDate(obj);
+            const dt = timezone
+                ? DateTime.fromJSDate(jsDate).setZone(timezone)
+                : DateTime.fromJSDate(jsDate);
+            dates.push(dt.toFormat('yyyy-MM-dd HH:mm:ss'));
+        }
+        return dates;
+    }
+    catch (err) {
+        throw new Error(`Failed to calculate next runs: ${err.message}`);
+    }
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "cron-human",
+  "version": "1.0.0",
+  "description": "A CLI that converts cron expressions to human-readable English and prints next run times",
+  "main": "dist/lib.js",
+  "types": "dist/lib.d.ts",
+  "bin": {
+    "cron-human": "./dist/cli.js"
+  },
+  "type": "module",
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "start": "node dist/cli.js",
+    "dev": "tsx src/cli.ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint src tests",
+    "format": "prettier --write ."
+  },
+  "keywords": [
+    "cron",
+    "cli",
+    "human-readable",
+    "schedule"
+  ],
+  "author": "Akin Ibitoye",
+  "license": "MIT",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "commander": "^14.0.2",
+    "cron-parser": "^5.5.0",
+    "cronstrue": "^3.9.0",
+    "luxon": "^3.7.2"
+  },
+  "devDependencies": {
+    "@types/luxon": "^3.7.1",
+    "@types/node": "^25.0.10",
+    "@typescript-eslint/eslint-plugin": "^8.53.1",
+    "@typescript-eslint/parser": "^8.53.1",
+    "eslint": "^9.39.2",
+    "eslint-config-prettier": "^10.1.8",
+    "prettier": "^3.8.1",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.17"
+  }
+}