@lowdep/cron-explain 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rushabh Shah
+
+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,107 @@
+# cron-explain
+
+![Zero dependencies](https://img.shields.io/badge/dependencies-0-brightgreen) ![Node](https://img.shields.io/badge/node-%3E%3D14-blue) ![License: MIT](https://img.shields.io/badge/license-MIT-green) ![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-lightgrey)
+
+
+Translate a cron expression into plain English **and** compute its next run times — all locally. Zero dependencies.
+
+`cronstrue` explains but is a library, not a CLI, and doesn't tell you *when* the job actually runs next. `cron-explain` does both in one command.
+
+---
+
+## Install
+
+```bash
+npm install -g cron-explain
+```
+
+Or without installing:
+
+```bash
+npx cron-explain "0 9 * * 1-5"
+```
+
+---
+
+## Usage
+
+```bash
+cron-explain "*/15 * * * *"          # Every 15 minutes
+cron-explain "0 9 * * 1-5"           # 9am on weekdays
+cron-explain "0 0 1 * *" --next 3    # Monthly — show next 3 runs
+cron-explain "@daily"                # Macros
+cron-explain "30 14 * * mon" --utc   # Evaluate in UTC
+cron-explain "0 9 * * 1-5" --no-next # Explanation only
+```
+
+---
+
+## Example Output
+
+```
+cron-explain  0 9 * * 1-5
+
+  At 09:00, on weekdays (Mon–Fri).
+
+  Next 5 runs  (local time)
+    ▸ Mon 2026-06-01 09:00  in 2d
+    ▸ Tue 2026-06-02 09:00  in 3d
+    ▸ Wed 2026-06-03 09:00  in 4d
+    ▸ Thu 2026-06-04 09:00  in 5d
+    ▸ Fri 2026-06-05 09:00  in 6d
+```
+
+---
+
+## Supported Syntax
+
+| Feature | Example |
+|---|---|
+| Standard 5-field | `0 9 * * 1-5` |
+| Steps | `*/15 * * * *` |
+| Ranges | `0 9-17 * * *` |
+| Lists | `0 0,12 * * *` |
+| Month names | `0 0 1 jan,jul *` |
+| Weekday names | `30 9 * * mon-fri` |
+| Macros | `@daily @hourly @weekly @monthly @yearly @midnight` |
+
+Field order: `minute hour day-of-month month day-of-week`.
+
+---
+
+## The Day-of-Month / Day-of-Week Quirk
+
+Cron has a well-known gotcha: when **both** the day-of-month and day-of-week fields are restricted (neither is `*`), the job runs when **either** matches — not both. `cron-explain` honors this in both the English description ("on day-of-month 1 *or* on Monday") and the computed run times.
+
+---
+
+## Options
+
+| Flag | Description |
+|---|---|
+| `-n, --next <N>` | Number of upcoming runs to show (default: 5, max: 50) |
+| `--utc` | Evaluate run times in UTC instead of local time |
+| `--no-next` | Print only the English explanation |
+| `--json` | Machine-readable output |
+
+---
+
+## License
+
+MIT
+
+---
+
+## Keywords
+
+`cron expression` · `explain cron` · `crontab` · `cron next run` · `cronstrue alternative` · `cron parser` · `human readable cron` · `schedule` · `zero dependencies` · `cli`
+
+---
+
+<div align="center">
+
+**Built to solve, shared to help — Rushabh Shah 🛠️✨**
+
+<sub>One of 40+ zero-dependency developer CLI tools — no <code>node_modules</code>, ever.</sub>
+
+</div>

package/bin/cron-explain.js

@@ -0,0 +1,318 @@
+#!/usr/bin/env node
+'use strict';
+
+const VERSION = '1.0.0';
+
+// ─── ANSI ─────────────────────────────────────────────────────────────────────
+const isTTY  = process.stdout.isTTY;
+const c      = (code, t) => isTTY ? `\x1b[${code}m${t}\x1b[0m` : t;
+const bold   = t => c('1',  t);
+const dim    = t => c('2',  t);
+const red    = t => c('31', t);
+const green  = t => c('32', t);
+const yellow = t => c('33', t);
+const cyan   = t => c('36', t);
+
+// ─── Field metadata ───────────────────────────────────────────────────────────
+const FIELDS = [
+  { name: 'minute',     min: 0, max: 59 },
+  { name: 'hour',       min: 0, max: 23 },
+  { name: 'dayOfMonth', min: 1, max: 31 },
+  { name: 'month',      min: 1, max: 12 },
+  { name: 'dayOfWeek',  min: 0, max: 6 },  // 0 = Sunday (7 also allowed → 0)
+];
+
+const MONTHS = ['January','February','March','April','May','June','July','August','September','October','November','December'];
+const DOW    = ['Sunday','Monday','Tuesday','Wednesday','Thursday','Friday','Saturday'];
+const MON_ABBR = { jan:1,feb:2,mar:3,apr:4,may:5,jun:6,jul:7,aug:8,sep:9,oct:10,nov:11,dec:12 };
+const DOW_ABBR = { sun:0,mon:1,tue:2,wed:3,thu:4,fri:5,sat:6 };
+
+// Named macros
+const MACROS = {
+  '@yearly':   '0 0 1 1 *',
+  '@annually': '0 0 1 1 *',
+  '@monthly':  '0 0 1 * *',
+  '@weekly':   '0 0 * * 0',
+  '@daily':    '0 0 * * *',
+  '@midnight': '0 0 * * *',
+  '@hourly':   '0 * * * *',
+};
+
+// ─── Parse a single field into a sorted set of allowed values ─────────────────
+function parseField(raw, field) {
+  const { min, max, name } = field;
+  const values = new Set();
+  let star = false;
+
+  const normalize = (tok) => {
+    const low = tok.toLowerCase();
+    if (name === 'month' && MON_ABBR[low] !== undefined) return MON_ABBR[low];
+    if (name === 'dayOfWeek' && DOW_ABBR[low] !== undefined) return DOW_ABBR[low];
+    const n = parseInt(tok, 10);
+    if (Number.isNaN(n)) throw new Error(`invalid value "${tok}" in ${name} field`);
+    // dayOfWeek 7 == 0 (Sunday)
+    if (name === 'dayOfWeek' && n === 7) return 0;
+    if (n < min || n > max) throw new Error(`${name} value ${n} out of range ${min}-${max}`);
+    return n;
+  };
+
+  for (const part of raw.split(',')) {
+    let stepBase = part, step = 1;
+    const slash = part.split('/');
+    if (slash.length === 2) { stepBase = slash[0]; step = parseInt(slash[1], 10); if (!step) throw new Error(`invalid step in ${name}`); }
+
+    let lo, hi;
+    if (stepBase === '*') { lo = min; hi = max; if (step > 1 || slash.length === 2) {} else star = true; }
+    else if (stepBase.includes('-')) {
+      const [a, b] = stepBase.split('-');
+      lo = normalize(a); hi = normalize(b);
+    } else {
+      lo = hi = normalize(stepBase);
+    }
+
+    if (lo > hi) { // wrap-around range (e.g. fri-mon)
+      for (let v = lo; v <= max; v += step) values.add(v);
+      for (let v = min; v <= hi; v += step) values.add(v);
+    } else {
+      for (let v = lo; v <= hi; v += step) values.add(v);
+    }
+  }
+
+  return { values: [...values].sort((a, b) => a - b), star, raw };
+}
+
+// ─── Parse full expression ────────────────────────────────────────────────────
+function parseCron(expr) {
+  let e = expr.trim();
+  if (MACROS[e.toLowerCase()]) e = MACROS[e.toLowerCase()];
+  const parts = e.split(/\s+/);
+  if (parts.length !== 5) {
+    throw new Error(`expected 5 fields, got ${parts.length}${parts.length === 6 ? ' (seconds field not supported)' : ''}`);
+  }
+  return FIELDS.map((f, i) => parseField(parts[i], f));
+}
+
+// ─── Humanize ─────────────────────────────────────────────────────────────────
+function listPhrase(values, mapFn) {
+  const mapped = values.map(mapFn);
+  if (mapped.length === 1) return mapped[0];
+  if (mapped.length === 2) return `${mapped[0]} and ${mapped[1]}`;
+  return mapped.slice(0, -1).join(', ') + ', and ' + mapped[mapped.length - 1];
+}
+
+function isContiguousStep(field) {
+  // Detect "*/n" style for nicer phrasing
+  const m = field.raw.match(/^\*\/(\d+)$/);
+  return m ? parseInt(m[1], 10) : null;
+}
+
+function pad2(n) { return String(n).padStart(2, '0'); }
+
+function explain(fields) {
+  const [minute, hour, dom, month, dow] = fields;
+
+  // Time-of-day phrase
+  let timePhrase;
+  const minStep = isContiguousStep(minute);
+  const hourStep = isContiguousStep(hour);
+
+  if (minute.star && hour.star) {
+    timePhrase = 'every minute';
+  } else if (minStep && hour.star) {
+    timePhrase = `every ${minStep} minutes`;
+  } else if (minute.values.length === 1 && hour.star) {
+    timePhrase = `at minute ${minute.values[0]} of every hour`;
+  } else if (minute.star && !hour.star) {
+    timePhrase = `every minute of ${hour.values.length === 1 ? `hour ${hour.values[0]}` : 'the selected hours'}`;
+  } else if (hourStep && minute.values.length === 1) {
+    timePhrase = `at minute ${minute.values[0]} past every ${hourStep} hours`;
+  } else if (minute.values.length === 1 && hour.values.length === 1) {
+    timePhrase = `at ${pad2(hour.values[0])}:${pad2(minute.values[0])}`;
+  } else {
+    // General: list specific times when small, else describe
+    const times = [];
+    for (const h of hour.values) for (const m of minute.values) times.push(`${pad2(h)}:${pad2(m)}`);
+    timePhrase = times.length <= 6 ? `at ${listPhrase(times, t => t)}` : `at ${minute.values.length} minute(s) past ${hour.values.length} hour(s)`;
+  }
+
+  // Day-of-month phrase
+  let domPhrase = '';
+  if (!dom.star) {
+    const domStep = isContiguousStep(dom);
+    if (domStep) domPhrase = `every ${domStep} days of the month`;
+    else domPhrase = `on day-of-month ${listPhrase(dom.values, v => String(v))}`;
+  }
+
+  // Month phrase
+  let monthPhrase = '';
+  if (!month.star) {
+    monthPhrase = `in ${listPhrase(month.values, v => MONTHS[v - 1])}`;
+  }
+
+  // Day-of-week phrase
+  let dowPhrase = '';
+  if (!dow.star) {
+    // Contiguous weekday range nicety
+    const v = dow.values;
+    if (v.length === 5 && v.join() === '1,2,3,4,5') dowPhrase = 'on weekdays (Mon–Fri)';
+    else if (v.length === 2 && v.join() === '0,6') dowPhrase = 'on weekends (Sat–Sun)';
+    else dowPhrase = `on ${listPhrase(v, d => DOW[d])}`;
+  }
+
+  // Compose. Cron quirk: if BOTH dom and dow are restricted, it's an OR.
+  let dayClause;
+  if (!dom.star && !dow.star) {
+    dayClause = `${domPhrase} ${dim('or')} ${dowPhrase}`;
+  } else {
+    dayClause = [domPhrase, dowPhrase].filter(Boolean).join(' ');
+  }
+
+  const pieces = [timePhrase];
+  if (dayClause) pieces.push(dayClause);
+  if (monthPhrase) pieces.push(monthPhrase);
+
+  let sentence = pieces.join(', ');
+  return sentence.charAt(0).toUpperCase() + sentence.slice(1) + '.';
+}
+
+// ─── Next run times ───────────────────────────────────────────────────────────
+function matches(fields, date, useUTC) {
+  const [minute, hour, dom, month, dow] = fields;
+  const mn = useUTC ? date.getUTCMinutes() : date.getMinutes();
+  const hr = useUTC ? date.getUTCHours()   : date.getHours();
+  const dm = useUTC ? date.getUTCDate()    : date.getDate();
+  const mo = (useUTC ? date.getUTCMonth() : date.getMonth()) + 1;
+  const dw = useUTC ? date.getUTCDay()     : date.getDay();
+
+  if (!minute.values.includes(mn)) return false;
+  if (!hour.values.includes(hr)) return false;
+  if (!month.values.includes(mo)) return false;
+
+  // Day matching: if both dom and dow restricted → OR; if one is * → AND on the other
+  const domMatch = dom.values.includes(dm);
+  const dowMatch = dow.values.includes(dw);
+  if (!dom.star && !dow.star) return domMatch || dowMatch;
+  if (!dom.star) return domMatch;
+  if (!dow.star) return dowMatch;
+  return true;
+}
+
+function nextRuns(fields, count, from, useUTC) {
+  const runs = [];
+  const d = new Date(from.getTime());
+  // Advance to the next whole minute
+  d.setSeconds(0, 0);
+  d.setMinutes(d.getMinutes() + 1);
+
+  let guard = 0;
+  const MAX_ITER = 5 * 366 * 24 * 60; // ~5 years of minutes
+  while (runs.length < count && guard++ < MAX_ITER) {
+    if (matches(fields, d, useUTC)) runs.push(new Date(d.getTime()));
+    d.setMinutes(d.getMinutes() + 1);
+  }
+  return runs;
+}
+
+function fmtDate(d, useUTC) {
+  const days = ['Sun','Mon','Tue','Wed','Thu','Fri','Sat'];
+  if (useUTC) {
+    return `${days[d.getUTCDay()]} ${d.getUTCFullYear()}-${pad2(d.getUTCMonth()+1)}-${pad2(d.getUTCDate())} ${pad2(d.getUTCHours())}:${pad2(d.getUTCMinutes())} UTC`;
+  }
+  return `${days[d.getDay()]} ${d.getFullYear()}-${pad2(d.getMonth()+1)}-${pad2(d.getDate())} ${pad2(d.getHours())}:${pad2(d.getMinutes())}`;
+}
+
+function relTime(d, from) {
+  const ms = d.getTime() - from.getTime();
+  const s = Math.round(ms / 1000);
+  const m = Math.round(s / 60), h = Math.round(m / 60), days = Math.round(h / 24);
+  if (s < 90) return `in ${s}s`;
+  if (m < 90) return `in ${m}m`;
+  if (h < 36) return `in ${h}h`;
+  return `in ${days}d`;
+}
+
+// ─── CLI ──────────────────────────────────────────────────────────────────────
+const args        = process.argv.slice(2);
+const VALUE_FLAGS  = new Set(['-n', '--next']);
+
+function getFlag(...names) { for (const f of names) { const i = args.indexOf(f); if (i !== -1) return args[i + 1]; } return null; }
+function hasFlag(...names) { return names.some(f => args.includes(f)); }
+
+const positional = [];
+for (let i = 0; i < args.length; i++) {
+  if (args[i].startsWith('-') && !/^-?\d/.test(args[i])) { if (VALUE_FLAGS.has(args[i])) i++; }
+  else positional.push(args[i]);
+}
+
+if (hasFlag('--version', '-v')) { console.log(`cron-explain v${VERSION}`); process.exit(0); }
+
+if (hasFlag('--help', '-h') || !positional.length) {
+  console.log(`
+${bold('cron-explain')} — Explain a cron expression and show its next run times, zero deps
+
+${bold('USAGE')}
+  cron-explain "<cron expression>" [options]
+
+${bold('OPTIONS')}
+  -n, --next <N>   Show the next N run times (default: 5)
+  --utc            Evaluate run times in UTC (default: local time)
+  --no-next        Only print the English explanation
+  --json           JSON output
+  --version        Show version
+
+${bold('SUPPORTS')}
+  5-field cron · ranges (1-5) · lists (1,3,5) · steps (*/15) ·
+  month/day names (jan, mon) · macros (@daily, @hourly, @weekly, ...)
+
+${bold('EXAMPLES')}
+  cron-explain "*/15 * * * *"          # Every 15 minutes
+  cron-explain "0 9 * * 1-5"           # 9am on weekdays
+  cron-explain "0 0 1 * *" --next 3    # Monthly, next 3 runs
+  cron-explain "@daily"                # Macro
+  cron-explain "30 14 * * mon" --utc
+`);
+  process.exit(positional.length ? 0 : 1);
+}
+
+const expr   = positional[0];
+const count  = Math.max(1, Math.min(50, parseInt(getFlag('-n', '--next') || '5', 10)));
+const useUTC = hasFlag('--utc');
+const noNext = hasFlag('--no-next');
+const asJson = hasFlag('--json');
+
+let fields;
+try {
+  fields = parseCron(expr);
+} catch (e) {
+  console.error(red(`\nInvalid cron expression: ${e.message}\n`));
+  process.exit(1);
+}
+
+const plainDesc = explain(fields).replace(/\x1b\[[0-9;]*m/g, '');
+const now = new Date();
+const runs = noNext ? [] : nextRuns(fields, count, now, useUTC);
+
+if (asJson) {
+  console.log(JSON.stringify({
+    expression: expr.trim(),
+    description: plainDesc,
+    nextRuns: runs.map(r => r.toISOString()),
+    timezone: useUTC ? 'UTC' : Intl.DateTimeFormat().resolvedOptions().timeZone,
+  }, null, 2));
+  process.exit(0);
+}
+
+console.log(`\n${bold('cron-explain')}  ${cyan(expr.trim())}\n`);
+console.log(`  ${explain(fields)}\n`);
+
+if (!noNext) {
+  if (!runs.length) {
+    console.log(yellow('  No upcoming run times found in the next ~5 years (impossible schedule?).\n'));
+  } else {
+    console.log(`  ${bold('Next ' + runs.length + ' run' + (runs.length > 1 ? 's' : ''))}  ${dim(useUTC ? '(UTC)' : '(local time)')}`);
+    for (const r of runs) {
+      console.log(`    ${green('▸')} ${fmtDate(r, useUTC)}  ${dim(relTime(r, now))}`);
+    }
+    console.log();
+  }
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@lowdep/cron-explain",
+  "version": "1.0.0",
+  "description": "Explain a cron expression in plain English and show the next N run times — supports macros, names, steps — zero dependencies",
+  "bin": {
+    "cron-explain": "bin/cron-explain.js"
+  },
+  "keywords": [
+    "cron",
+    "crontab",
+    "schedule",
+    "explain",
+    "next-run",
+    "cli",
+    "developer-tools",
+    "zero-dependencies",
+    "cron expression",
+    "explain cron",
+    "cron next run",
+    "cronstrue alternative",
+    "cron parser",
+    "human readable cron",
+    "zero dependencies"
+  ],
+  "author": "Rushabh Shah",
+  "license": "MIT",
+  "engines": {
+    "node": ">=14"
+  },
+  "files": [
+    "bin/"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Rushabh5000/cron-explain.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Rushabh5000/cron-explain/issues"
+  },
+  "homepage": "https://github.com/Rushabh5000/cron-explain#readme",
+  "publishConfig": {
+    "access": "public"
+  }
+}