@aarunyaapps/cron-utils 1.0.0

package/dist/index.d.mts

@@ -0,0 +1,18 @@
+interface CronFields {
+    minute: string;
+    hour: string;
+    dayOfMonth: string;
+    month: string;
+    dayOfWeek: string;
+}
+interface ValidationResult {
+    valid: boolean;
+    errors: string[];
+    fields?: CronFields;
+}
+declare function expandField(field: string, min: number, max: number): number[];
+declare function validate(expression: string): ValidationResult;
+declare function nextRuns(expression: string, count?: number, from?: Date): Date[];
+declare function toHumanReadable(expression: string): string;
+
+export { type CronFields, type ValidationResult, expandField, nextRuns, toHumanReadable, validate };

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+interface CronFields {
+    minute: string;
+    hour: string;
+    dayOfMonth: string;
+    month: string;
+    dayOfWeek: string;
+}
+interface ValidationResult {
+    valid: boolean;
+    errors: string[];
+    fields?: CronFields;
+}
+declare function expandField(field: string, min: number, max: number): number[];
+declare function validate(expression: string): ValidationResult;
+declare function nextRuns(expression: string, count?: number, from?: Date): Date[];
+declare function toHumanReadable(expression: string): string;
+
+export { type CronFields, type ValidationResult, expandField, nextRuns, toHumanReadable, validate };

package/dist/index.js

@@ -0,0 +1,202 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  expandField: () => expandField,
+  nextRuns: () => nextRuns,
+  toHumanReadable: () => toHumanReadable,
+  validate: () => validate
+});
+module.exports = __toCommonJS(index_exports);
+var FIELD_RANGES = [
+  { 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: 7 }
+];
+function expandField(field, min, max) {
+  const result = /* @__PURE__ */ new Set();
+  for (const part of field.split(",")) {
+    if (part === "*" || part === "?") {
+      for (let i = min; i <= max; i++) result.add(i);
+    } else if (part.includes("/")) {
+      const [rangeStr, stepStr] = part.split("/");
+      const step = parseInt(stepStr, 10);
+      if (isNaN(step) || step < 1) continue;
+      let lo = min, hi = max;
+      if (rangeStr !== "*" && rangeStr !== "?") {
+        if (rangeStr.includes("-")) {
+          const [a, b] = rangeStr.split("-").map(Number);
+          lo = a;
+          hi = b;
+        } else {
+          lo = parseInt(rangeStr, 10);
+        }
+      }
+      for (let i = lo; i <= hi; i += step) result.add(i);
+    } else if (part.includes("-")) {
+      const [a, b] = part.split("-").map(Number);
+      for (let i = a; i <= b; i++) result.add(i);
+    } else {
+      const n = parseInt(part, 10);
+      if (!isNaN(n)) result.add(n);
+    }
+  }
+  if (result.has(7)) {
+    result.add(0);
+    result.delete(7);
+  }
+  return [...result].filter((n) => n >= min && n <= max).sort((a, b) => a - b);
+}
+function validate(expression) {
+  const parts = expression.trim().split(/\s+/);
+  if (parts.length !== 5) {
+    return { valid: false, errors: [`Expected 5 fields, got ${parts.length}`] };
+  }
+  const errors = [];
+  const fields = {
+    minute: parts[0],
+    hour: parts[1],
+    dayOfMonth: parts[2],
+    month: parts[3],
+    dayOfWeek: parts[4]
+  };
+  for (let i = 0; i < FIELD_RANGES.length; i++) {
+    const { name, min, max } = FIELD_RANGES[i];
+    const field = parts[i];
+    if (field === "*" || field === "?") continue;
+    try {
+      const vals = expandField(field, min, max);
+      if (vals.length === 0) errors.push(`${name}: no valid values in "${field}"`);
+    } catch {
+      errors.push(`${name}: invalid value "${field}"`);
+    }
+  }
+  return { valid: errors.length === 0, errors, fields };
+}
+function nextRuns(expression, count = 10, from = /* @__PURE__ */ new Date()) {
+  const parts = expression.trim().split(/\s+/);
+  if (parts.length !== 5) throw new Error("Expected 5-field cron expression");
+  const [mF, hF, domF, monF, dowF] = parts;
+  const minutes = expandField(mF, 0, 59);
+  const hours = expandField(hF, 0, 23);
+  const months = expandField(monF, 1, 12);
+  const domRestricted = domF !== "*" && domF !== "?";
+  const dowRestricted = dowF !== "*" && dowF !== "?";
+  const doms = domRestricted ? expandField(domF, 1, 31) : [];
+  const dows = dowRestricted ? expandField(dowF, 0, 6) : [];
+  if (minutes.length === 0 || hours.length === 0 || months.length === 0) {
+    throw new Error("Cron expression produces no valid run times");
+  }
+  const results = [];
+  const d = new Date(from);
+  d.setSeconds(0, 0);
+  d.setMinutes(d.getMinutes() + 1);
+  let iterations = 0;
+  const MAX_ITER = 5e5;
+  while (results.length < count && iterations++ < MAX_ITER) {
+    const month = d.getMonth() + 1;
+    if (!months.includes(month)) {
+      d.setDate(1);
+      d.setHours(0);
+      d.setMinutes(0);
+      d.setMonth(d.getMonth() + 1);
+      continue;
+    }
+    const dayOk = !domRestricted && !dowRestricted ? true : domRestricted && dowRestricted ? doms.includes(d.getDate()) || dows.includes(d.getDay()) : domRestricted ? doms.includes(d.getDate()) : dows.includes(d.getDay());
+    if (!dayOk) {
+      d.setDate(d.getDate() + 1);
+      d.setHours(0);
+      d.setMinutes(0);
+      continue;
+    }
+    if (!hours.includes(d.getHours())) {
+      const next = hours.find((h) => h > d.getHours());
+      if (next !== void 0) {
+        d.setHours(next);
+        d.setMinutes(0);
+      } else {
+        d.setDate(d.getDate() + 1);
+        d.setHours(hours[0]);
+        d.setMinutes(0);
+      }
+      continue;
+    }
+    const nextMin = minutes.find((m) => m >= d.getMinutes());
+    if (nextMin !== void 0) {
+      if (nextMin === d.getMinutes()) {
+        results.push(new Date(d));
+        d.setMinutes(d.getMinutes() + 1);
+      } else {
+        d.setMinutes(nextMin);
+      }
+    } else {
+      const nextHour = hours.find((h) => h > d.getHours());
+      if (nextHour !== void 0) {
+        d.setHours(nextHour);
+        d.setMinutes(minutes[0]);
+      } else {
+        d.setDate(d.getDate() + 1);
+        d.setHours(hours[0]);
+        d.setMinutes(minutes[0]);
+      }
+    }
+  }
+  return results;
+}
+var MONTH_SHORT = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];
+var DOW_LONG = ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"];
+function toHumanReadable(expression) {
+  const parts = expression.trim().split(/\s+/);
+  if (parts.length !== 5) return "Invalid expression";
+  const [min, hour, dom, month, dow] = parts;
+  if (min === "*" && hour === "*" && dom === "*" && month === "*" && dow === "*") return "Every minute";
+  if (min.startsWith("*/")) return `Every ${min.slice(2)} minutes`;
+  if (min === "0" && hour.startsWith("*/")) return `Every ${hour.slice(2)} hours`;
+  if (min === "0" && hour === "0" && dom === "*" && month === "*" && dow === "*") return "Daily at midnight";
+  if (min === "0" && dom === "*" && month === "*" && dow === "*") return `Daily at ${hour.padStart(2, "0")}:00`;
+  const parts2 = [];
+  if (min === "*") parts2.push("every minute");
+  else if (min.startsWith("*/")) parts2.push(`every ${min.slice(2)} min`);
+  else parts2.push(`at :${min.padStart(2, "0")}`);
+  if (hour !== "*") {
+    if (hour.startsWith("*/")) parts2.push(`every ${hour.slice(2)}h`);
+    else parts2.push(`${hour.padStart(2, "0")}:xx`);
+  }
+  if (dom !== "*" && dom !== "?") parts2.push(`on day ${dom}`);
+  if (month !== "*") {
+    const mIdx = parseInt(month, 10);
+    parts2.push(`in ${!isNaN(mIdx) ? MONTH_SHORT[mIdx - 1] : month}`);
+  }
+  if (dow !== "*" && dow !== "?") {
+    const d = parseInt(dow, 10);
+    parts2.push(`on ${!isNaN(d) ? DOW_LONG[d % 7] : dow}`);
+  }
+  return parts2.join(", ");
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  expandField,
+  nextRuns,
+  toHumanReadable,
+  validate
+});

package/dist/index.mjs

@@ -0,0 +1,174 @@
+// src/index.ts
+var FIELD_RANGES = [
+  { 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: 7 }
+];
+function expandField(field, min, max) {
+  const result = /* @__PURE__ */ new Set();
+  for (const part of field.split(",")) {
+    if (part === "*" || part === "?") {
+      for (let i = min; i <= max; i++) result.add(i);
+    } else if (part.includes("/")) {
+      const [rangeStr, stepStr] = part.split("/");
+      const step = parseInt(stepStr, 10);
+      if (isNaN(step) || step < 1) continue;
+      let lo = min, hi = max;
+      if (rangeStr !== "*" && rangeStr !== "?") {
+        if (rangeStr.includes("-")) {
+          const [a, b] = rangeStr.split("-").map(Number);
+          lo = a;
+          hi = b;
+        } else {
+          lo = parseInt(rangeStr, 10);
+        }
+      }
+      for (let i = lo; i <= hi; i += step) result.add(i);
+    } else if (part.includes("-")) {
+      const [a, b] = part.split("-").map(Number);
+      for (let i = a; i <= b; i++) result.add(i);
+    } else {
+      const n = parseInt(part, 10);
+      if (!isNaN(n)) result.add(n);
+    }
+  }
+  if (result.has(7)) {
+    result.add(0);
+    result.delete(7);
+  }
+  return [...result].filter((n) => n >= min && n <= max).sort((a, b) => a - b);
+}
+function validate(expression) {
+  const parts = expression.trim().split(/\s+/);
+  if (parts.length !== 5) {
+    return { valid: false, errors: [`Expected 5 fields, got ${parts.length}`] };
+  }
+  const errors = [];
+  const fields = {
+    minute: parts[0],
+    hour: parts[1],
+    dayOfMonth: parts[2],
+    month: parts[3],
+    dayOfWeek: parts[4]
+  };
+  for (let i = 0; i < FIELD_RANGES.length; i++) {
+    const { name, min, max } = FIELD_RANGES[i];
+    const field = parts[i];
+    if (field === "*" || field === "?") continue;
+    try {
+      const vals = expandField(field, min, max);
+      if (vals.length === 0) errors.push(`${name}: no valid values in "${field}"`);
+    } catch {
+      errors.push(`${name}: invalid value "${field}"`);
+    }
+  }
+  return { valid: errors.length === 0, errors, fields };
+}
+function nextRuns(expression, count = 10, from = /* @__PURE__ */ new Date()) {
+  const parts = expression.trim().split(/\s+/);
+  if (parts.length !== 5) throw new Error("Expected 5-field cron expression");
+  const [mF, hF, domF, monF, dowF] = parts;
+  const minutes = expandField(mF, 0, 59);
+  const hours = expandField(hF, 0, 23);
+  const months = expandField(monF, 1, 12);
+  const domRestricted = domF !== "*" && domF !== "?";
+  const dowRestricted = dowF !== "*" && dowF !== "?";
+  const doms = domRestricted ? expandField(domF, 1, 31) : [];
+  const dows = dowRestricted ? expandField(dowF, 0, 6) : [];
+  if (minutes.length === 0 || hours.length === 0 || months.length === 0) {
+    throw new Error("Cron expression produces no valid run times");
+  }
+  const results = [];
+  const d = new Date(from);
+  d.setSeconds(0, 0);
+  d.setMinutes(d.getMinutes() + 1);
+  let iterations = 0;
+  const MAX_ITER = 5e5;
+  while (results.length < count && iterations++ < MAX_ITER) {
+    const month = d.getMonth() + 1;
+    if (!months.includes(month)) {
+      d.setDate(1);
+      d.setHours(0);
+      d.setMinutes(0);
+      d.setMonth(d.getMonth() + 1);
+      continue;
+    }
+    const dayOk = !domRestricted && !dowRestricted ? true : domRestricted && dowRestricted ? doms.includes(d.getDate()) || dows.includes(d.getDay()) : domRestricted ? doms.includes(d.getDate()) : dows.includes(d.getDay());
+    if (!dayOk) {
+      d.setDate(d.getDate() + 1);
+      d.setHours(0);
+      d.setMinutes(0);
+      continue;
+    }
+    if (!hours.includes(d.getHours())) {
+      const next = hours.find((h) => h > d.getHours());
+      if (next !== void 0) {
+        d.setHours(next);
+        d.setMinutes(0);
+      } else {
+        d.setDate(d.getDate() + 1);
+        d.setHours(hours[0]);
+        d.setMinutes(0);
+      }
+      continue;
+    }
+    const nextMin = minutes.find((m) => m >= d.getMinutes());
+    if (nextMin !== void 0) {
+      if (nextMin === d.getMinutes()) {
+        results.push(new Date(d));
+        d.setMinutes(d.getMinutes() + 1);
+      } else {
+        d.setMinutes(nextMin);
+      }
+    } else {
+      const nextHour = hours.find((h) => h > d.getHours());
+      if (nextHour !== void 0) {
+        d.setHours(nextHour);
+        d.setMinutes(minutes[0]);
+      } else {
+        d.setDate(d.getDate() + 1);
+        d.setHours(hours[0]);
+        d.setMinutes(minutes[0]);
+      }
+    }
+  }
+  return results;
+}
+var MONTH_SHORT = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];
+var DOW_LONG = ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"];
+function toHumanReadable(expression) {
+  const parts = expression.trim().split(/\s+/);
+  if (parts.length !== 5) return "Invalid expression";
+  const [min, hour, dom, month, dow] = parts;
+  if (min === "*" && hour === "*" && dom === "*" && month === "*" && dow === "*") return "Every minute";
+  if (min.startsWith("*/")) return `Every ${min.slice(2)} minutes`;
+  if (min === "0" && hour.startsWith("*/")) return `Every ${hour.slice(2)} hours`;
+  if (min === "0" && hour === "0" && dom === "*" && month === "*" && dow === "*") return "Daily at midnight";
+  if (min === "0" && dom === "*" && month === "*" && dow === "*") return `Daily at ${hour.padStart(2, "0")}:00`;
+  const parts2 = [];
+  if (min === "*") parts2.push("every minute");
+  else if (min.startsWith("*/")) parts2.push(`every ${min.slice(2)} min`);
+  else parts2.push(`at :${min.padStart(2, "0")}`);
+  if (hour !== "*") {
+    if (hour.startsWith("*/")) parts2.push(`every ${hour.slice(2)}h`);
+    else parts2.push(`${hour.padStart(2, "0")}:xx`);
+  }
+  if (dom !== "*" && dom !== "?") parts2.push(`on day ${dom}`);
+  if (month !== "*") {
+    const mIdx = parseInt(month, 10);
+    parts2.push(`in ${!isNaN(mIdx) ? MONTH_SHORT[mIdx - 1] : month}`);
+  }
+  if (dow !== "*" && dow !== "?") {
+    const d = parseInt(dow, 10);
+    parts2.push(`on ${!isNaN(d) ? DOW_LONG[d % 7] : dow}`);
+  }
+  return parts2.join(", ");
+}
+export {
+  expandField,
+  nextRuns,
+  toHumanReadable,
+  validate
+};

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@aarunyaapps/cron-utils",
+  "version": "1.0.0",
+  "description": "Parse, validate, and calculate next run times for 5-field cron expressions. Zero dependencies. Browser + Node.js compatible.",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": ["dist", "README.md"],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+    "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
+    "type-check": "tsc --noEmit"
+  },
+  "keywords": ["cron", "cron-expression", "scheduler", "next-run", "cron-parser"],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/aarunyaapps/cron-utils"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.8.3"
+  }
+}