hron-ts 0.5.0 → 0.6.0

package/dist/index.cjs

@@ -141,6 +141,14 @@ function ordinalToN(ord) {
   };
   return map[ord];
 }
+var ALL_WEEKDAYS = [
+  "monday",
+  "tuesday",
+  "wednesday",
+  "thursday",
+  "friday"
+];
+var ALL_WEEKEND = ["saturday", "sunday"];
 function newScheduleData(expr) {
   return {
     expr,
@@ -286,14 +294,23 @@ function toCron(schedule) {
           "not expressible as cron (last day of month not supported)"
         );
       }
-      throw HronError.cron(
-        "not expressible as cron (last weekday of month not supported)"
-      );
+      if (target.type === "lastWeekday") {
+        throw HronError.cron(
+          "not expressible as cron (last weekday of month not supported)"
+        );
+      }
+      if (target.type === "ordinalWeekday") {
+        throw HronError.cron(
+          "not expressible as cron (ordinal weekday of month not supported)"
+        );
+      }
+      if (target.direction !== null) {
+        throw HronError.cron(
+          "not expressible as cron (directional nearest weekday not supported)"
+        );
+      }
+      return `${time.minute} ${time.hour} ${target.day}W * *`;
     }
-    case "ordinalRepeat":
-      throw HronError.cron(
-        "not expressible as cron (ordinal weekday of month not supported)"
-      );
     case "singleDate":
       throw HronError.cron(
         "not expressible as cron (single dates are not repeating)"
@@ -320,110 +337,596 @@ function dayFilterToCronDow(filter) {
   }
 }
 function fromCron(cron) {
-  const fields = cron.trim().split(/\s+/);
+  const trimmed = cron.trim();
+  if (trimmed.startsWith("@")) {
+    return parseCronShortcut(trimmed);
+  }
+  const fields = trimmed.split(/\s+/);
   if (fields.length !== 5) {
     throw HronError.cron(`expected 5 cron fields, got ${fields.length}`);
   }
-  const [minuteField, hourField, domField, _monthField, dowField] = fields;
-  if (minuteField.startsWith("*/")) {
-    const interval = parseInt(minuteField.slice(2), 10);
-    if (Number.isNaN(interval)) throw HronError.cron("invalid minute interval");
-    let fromHour = 0;
-    let toHour = 23;
+  const [minuteField, hourField, domFieldRaw, monthField, dowFieldRaw] = fields;
+  const domField = domFieldRaw === "?" ? "*" : domFieldRaw;
+  const dowField = dowFieldRaw === "?" ? "*" : dowFieldRaw;
+  const during = parseMonthField(monthField);
+  const nthWeekdayResult = tryParseNthWeekday(
+    minuteField,
+    hourField,
+    domField,
+    dowField,
+    during
+  );
+  if (nthWeekdayResult) return nthWeekdayResult;
+  const lastDayResult = tryParseLastDay(
+    minuteField,
+    hourField,
+    domField,
+    dowField,
+    during
+  );
+  if (lastDayResult) return lastDayResult;
+  if (domField.endsWith("W") && domField !== "LW") {
+    const nearestWeekdayResult = tryParseNearestWeekday(
+      minuteField,
+      hourField,
+      domField,
+      dowField,
+      during
+    );
+    if (nearestWeekdayResult) return nearestWeekdayResult;
+  }
+  const intervalResult = tryParseInterval(
+    minuteField,
+    hourField,
+    domField,
+    dowField,
+    during
+  );
+  if (intervalResult) return intervalResult;
+  const minute = parseSingleValue(minuteField, "minute", 0, 59);
+  const hour = parseSingleValue(hourField, "hour", 0, 23);
+  const time = { hour, minute };
+  if (domField !== "*" && dowField === "*") {
+    const target = parseDomField(domField);
+    const schedule2 = newScheduleData({
+      type: "monthRepeat",
+      interval: 1,
+      target,
+      times: [time]
+    });
+    schedule2.during = during;
+    return schedule2;
+  }
+  const days = parseCronDow(dowField);
+  const schedule = newScheduleData({
+    type: "dayRepeat",
+    interval: 1,
+    days,
+    times: [time]
+  });
+  schedule.during = during;
+  return schedule;
+}
+function parseCronShortcut(cron) {
+  switch (cron.toLowerCase()) {
+    case "@yearly":
+    case "@annually":
+      return newScheduleData({
+        type: "yearRepeat",
+        interval: 1,
+        target: { type: "date", month: "jan", day: 1 },
+        times: [{ hour: 0, minute: 0 }]
+      });
+    case "@monthly":
+      return newScheduleData({
+        type: "monthRepeat",
+        interval: 1,
+        target: { type: "days", specs: [{ type: "single", day: 1 }] },
+        times: [{ hour: 0, minute: 0 }]
+      });
+    case "@weekly":
+      return newScheduleData({
+        type: "dayRepeat",
+        interval: 1,
+        days: { type: "days", days: ["sunday"] },
+        times: [{ hour: 0, minute: 0 }]
+      });
+    case "@daily":
+    case "@midnight":
+      return newScheduleData({
+        type: "dayRepeat",
+        interval: 1,
+        days: { type: "every" },
+        times: [{ hour: 0, minute: 0 }]
+      });
+    case "@hourly":
+      return newScheduleData({
+        type: "intervalRepeat",
+        interval: 1,
+        unit: "hours",
+        from: { hour: 0, minute: 0 },
+        to: { hour: 23, minute: 59 },
+        dayFilter: null
+      });
+    default:
+      throw HronError.cron(`unknown @ shortcut: ${cron}`);
+  }
+}
+function parseMonthField(field) {
+  if (field === "*") return [];
+  const months = [];
+  for (const part of field.split(",")) {
+    if (part.includes("/")) {
+      const [rangePart, stepStr] = part.split("/");
+      let start, end;
+      if (rangePart === "*") {
+        start = 1;
+        end = 12;
+      } else if (rangePart.includes("-")) {
+        const [s, e] = rangePart.split("-");
+        start = monthNumber(parseMonthValue(s));
+        end = monthNumber(parseMonthValue(e));
+      } else {
+        throw HronError.cron(`invalid month step expression: ${part}`);
+      }
+      const step = parseInt(stepStr, 10);
+      if (Number.isNaN(step)) {
+        throw HronError.cron(`invalid month step value: ${stepStr}`);
+      }
+      if (step === 0) {
+        throw HronError.cron("step cannot be 0");
+      }
+      for (let n = start; n <= end; n += step) {
+        months.push(monthFromNumber(n));
+      }
+    } else if (part.includes("-")) {
+      const [startStr, endStr] = part.split("-");
+      const startMonth = parseMonthValue(startStr);
+      const endMonth = parseMonthValue(endStr);
+      const startNum = monthNumber(startMonth);
+      const endNum = monthNumber(endMonth);
+      if (startNum > endNum) {
+        throw HronError.cron(`invalid month range: ${startStr} > ${endStr}`);
+      }
+      for (let n = startNum; n <= endNum; n++) {
+        months.push(monthFromNumber(n));
+      }
+    } else {
+      months.push(parseMonthValue(part));
+    }
+  }
+  return months;
+}
+function parseMonthValue(s) {
+  const n = parseInt(s, 10);
+  if (!Number.isNaN(n)) {
+    return monthFromNumber(n);
+  }
+  const name = parseMonthName(s);
+  if (!name) {
+    throw HronError.cron(`invalid month: ${s}`);
+  }
+  return name;
+}
+function monthFromNumber(n) {
+  const map = {
+    1: "jan",
+    2: "feb",
+    3: "mar",
+    4: "apr",
+    5: "may",
+    6: "jun",
+    7: "jul",
+    8: "aug",
+    9: "sep",
+    10: "oct",
+    11: "nov",
+    12: "dec"
+  };
+  const result = map[n];
+  if (!result) {
+    throw HronError.cron(`invalid month number: ${n}`);
+  }
+  return result;
+}
+function tryParseNthWeekday(minuteField, hourField, domField, dowField, during) {
+  if (dowField.includes("#")) {
+    const [dowStr, nthStr] = dowField.split("#");
+    const dowNum = parseDowValue(dowStr);
+    const weekday = cronDowToWeekday(dowNum);
+    const nth = parseInt(nthStr, 10);
+    if (Number.isNaN(nth) || nth < 1 || nth > 5) {
+      throw HronError.cron(`nth must be 1-5, got ${nthStr}`);
+    }
+    if (domField !== "*" && domField !== "?") {
+      throw HronError.cron("DOM must be * when using # for nth weekday");
+    }
+    const minute = parseSingleValue(minuteField, "minute", 0, 59);
+    const hour = parseSingleValue(hourField, "hour", 0, 23);
+    const ordinalMap = {
+      1: "first",
+      2: "second",
+      3: "third",
+      4: "fourth",
+      5: "fifth"
+    };
+    const schedule = newScheduleData({
+      type: "monthRepeat",
+      interval: 1,
+      target: { type: "ordinalWeekday", ordinal: ordinalMap[nth], weekday },
+      times: [{ hour, minute }]
+    });
+    schedule.during = during;
+    return schedule;
+  }
+  if (dowField.endsWith("L") && dowField.length > 1) {
+    const dowStr = dowField.slice(0, -1);
+    const dowNum = parseDowValue(dowStr);
+    const weekday = cronDowToWeekday(dowNum);
+    if (domField !== "*" && domField !== "?") {
+      throw HronError.cron("DOM must be * when using nL for last weekday");
+    }
+    const minute = parseSingleValue(minuteField, "minute", 0, 59);
+    const hour = parseSingleValue(hourField, "hour", 0, 23);
+    const schedule = newScheduleData({
+      type: "monthRepeat",
+      interval: 1,
+      target: { type: "ordinalWeekday", ordinal: "last", weekday },
+      times: [{ hour, minute }]
+    });
+    schedule.during = during;
+    return schedule;
+  }
+  return null;
+}
+function tryParseLastDay(minuteField, hourField, domField, dowField, during) {
+  if (domField !== "L" && domField !== "LW") {
+    return null;
+  }
+  if (dowField !== "*" && dowField !== "?") {
+    throw HronError.cron("DOW must be * when using L or LW in DOM");
+  }
+  const minute = parseSingleValue(minuteField, "minute", 0, 59);
+  const hour = parseSingleValue(hourField, "hour", 0, 23);
+  const target = domField === "LW" ? { type: "lastWeekday" } : { type: "lastDay" };
+  const schedule = newScheduleData({
+    type: "monthRepeat",
+    interval: 1,
+    target,
+    times: [{ hour, minute }]
+  });
+  schedule.during = during;
+  return schedule;
+}
+function tryParseNearestWeekday(minuteField, hourField, domField, dowField, during) {
+  if (!domField.endsWith("W") || domField === "LW") {
+    return null;
+  }
+  if (dowField !== "*" && dowField !== "?") {
+    throw HronError.cron("DOW must be * when using W in DOM");
+  }
+  const dayStr = domField.slice(0, -1);
+  const day = parseInt(dayStr, 10);
+  if (Number.isNaN(day)) {
+    throw HronError.cron(`invalid W day: ${dayStr}`);
+  }
+  if (day < 1 || day > 31) {
+    throw HronError.cron(`W day must be 1-31, got ${day}`);
+  }
+  const minute = parseSingleValue(minuteField, "minute", 0, 59);
+  const hour = parseSingleValue(hourField, "hour", 0, 23);
+  const target = {
+    type: "nearestWeekday",
+    day,
+    direction: null
+  };
+  const schedule = newScheduleData({
+    type: "monthRepeat",
+    interval: 1,
+    target,
+    times: [{ hour, minute }]
+  });
+  schedule.during = during;
+  return schedule;
+}
+function tryParseInterval(minuteField, hourField, domField, dowField, during) {
+  if (minuteField.includes("/")) {
+    const [rangePart, stepStr] = minuteField.split("/");
+    const interval = parseInt(stepStr, 10);
+    if (Number.isNaN(interval)) {
+      throw HronError.cron("invalid minute interval value");
+    }
+    if (interval === 0) {
+      throw HronError.cron("step cannot be 0");
+    }
+    let fromMinute, toMinute;
+    if (rangePart === "*") {
+      fromMinute = 0;
+      toMinute = 59;
+    } else if (rangePart.includes("-")) {
+      const [s, e] = rangePart.split("-");
+      fromMinute = parseInt(s, 10);
+      toMinute = parseInt(e, 10);
+      if (Number.isNaN(fromMinute) || Number.isNaN(toMinute)) {
+        throw HronError.cron("invalid minute range");
+      }
+      if (fromMinute > toMinute) {
+        throw HronError.cron(
+          `range start must be <= end: ${fromMinute}-${toMinute}`
+        );
+      }
+    } else {
+      fromMinute = parseInt(rangePart, 10);
+      if (Number.isNaN(fromMinute)) {
+        throw HronError.cron("invalid minute value");
+      }
+      toMinute = 59;
+    }
+    let fromHour, toHour;
     if (hourField === "*") {
-    } else if (hourField.includes("-")) {
-      const [start, end] = hourField.split("-");
-      fromHour = parseInt(start, 10);
-      toHour = parseInt(end, 10);
-      if (Number.isNaN(fromHour) || Number.isNaN(toHour))
+      fromHour = 0;
+      toHour = 23;
+    } else if (hourField.includes("-") && !hourField.includes("/")) {
+      const [s, e] = hourField.split("-");
+      fromHour = parseInt(s, 10);
+      toHour = parseInt(e, 10);
+      if (Number.isNaN(fromHour) || Number.isNaN(toHour)) {
         throw HronError.cron("invalid hour range");
+      }
+    } else if (hourField.includes("/")) {
+      return null;
     } else {
       const h = parseInt(hourField, 10);
-      if (Number.isNaN(h)) throw HronError.cron("invalid hour");
+      if (Number.isNaN(h)) {
+        throw HronError.cron("invalid hour");
+      }
       fromHour = h;
       toHour = h;
     }
     const dayFilter = dowField === "*" ? null : parseCronDow(dowField);
-    if (domField === "*") {
-      const expr2 = {
+    if (domField === "*" || domField === "?") {
+      let endMinute;
+      if (fromMinute === 0 && toMinute === 59 && toHour === 23) {
+        endMinute = 59;
+      } else if (fromMinute === 0 && toMinute === 59) {
+        endMinute = 0;
+      } else {
+        endMinute = toMinute;
+      }
+      const schedule = newScheduleData({
         type: "intervalRepeat",
         interval,
         unit: "min",
-        from: { hour: fromHour, minute: 0 },
-        to: { hour: toHour, minute: toHour === 23 ? 59 : 0 },
+        from: { hour: fromHour, minute: fromMinute },
+        to: { hour: toHour, minute: endMinute },
         dayFilter
-      };
-      return newScheduleData(expr2);
+      });
+      schedule.during = during;
+      return schedule;
+    }
+  }
+  if (hourField.includes("/") && (minuteField === "0" || minuteField === "00")) {
+    const [rangePart, stepStr] = hourField.split("/");
+    const interval = parseInt(stepStr, 10);
+    if (Number.isNaN(interval)) {
+      throw HronError.cron("invalid hour interval value");
+    }
+    if (interval === 0) {
+      throw HronError.cron("step cannot be 0");
+    }
+    let fromHour, toHour;
+    if (rangePart === "*") {
+      fromHour = 0;
+      toHour = 23;
+    } else if (rangePart.includes("-")) {
+      const [s, e] = rangePart.split("-");
+      fromHour = parseInt(s, 10);
+      toHour = parseInt(e, 10);
+      if (Number.isNaN(fromHour) || Number.isNaN(toHour)) {
+        throw HronError.cron("invalid hour range");
+      }
+      if (fromHour > toHour) {
+        throw HronError.cron(
+          `range start must be <= end: ${fromHour}-${toHour}`
+        );
+      }
+    } else {
+      fromHour = parseInt(rangePart, 10);
+      if (Number.isNaN(fromHour)) {
+        throw HronError.cron("invalid hour value");
+      }
+      toHour = 23;
     }
-  }
-  if (hourField.startsWith("*/") && minuteField === "0") {
-    const interval = parseInt(hourField.slice(2), 10);
-    if (Number.isNaN(interval)) throw HronError.cron("invalid hour interval");
-    if (domField === "*" && dowField === "*") {
-      const expr2 = {
+    if ((domField === "*" || domField === "?") && (dowField === "*" || dowField === "?")) {
+      const endMinute = fromHour === 0 && toHour === 23 ? 59 : 0;
+      const schedule = newScheduleData({
         type: "intervalRepeat",
         interval,
         unit: "hours",
-        from: { hour: 0, minute: 0 },
-        to: { hour: 23, minute: 59 },
+        from: { hour: fromHour, minute: 0 },
+        to: { hour: toHour, minute: endMinute },
         dayFilter: null
-      };
-      return newScheduleData(expr2);
+      });
+      schedule.during = during;
+      return schedule;
     }
   }
-  const minute = parseInt(minuteField, 10);
-  if (Number.isNaN(minute))
-    throw HronError.cron(`invalid minute field: ${minuteField}`);
-  const hour = parseInt(hourField, 10);
-  if (Number.isNaN(hour))
-    throw HronError.cron(`invalid hour field: ${hourField}`);
-  const time = { hour, minute };
-  if (domField !== "*" && dowField === "*") {
-    if (domField.includes("-")) {
-      throw HronError.cron(`DOM ranges not supported: ${domField}`);
+  return null;
+}
+function parseDomField(field) {
+  const specs = [];
+  for (const part of field.split(",")) {
+    if (part.includes("/")) {
+      const [rangePart, stepStr] = part.split("/");
+      let start, end;
+      if (rangePart === "*") {
+        start = 1;
+        end = 31;
+      } else if (rangePart.includes("-")) {
+        const [s, e] = rangePart.split("-");
+        start = parseInt(s, 10);
+        end = parseInt(e, 10);
+        if (Number.isNaN(start)) {
+          throw HronError.cron(`invalid DOM range start: ${s}`);
+        }
+        if (Number.isNaN(end)) {
+          throw HronError.cron(`invalid DOM range end: ${e}`);
+        }
+        if (start > end) {
+          throw HronError.cron(`range start must be <= end: ${start}-${end}`);
+        }
+      } else {
+        start = parseInt(rangePart, 10);
+        if (Number.isNaN(start)) {
+          throw HronError.cron(`invalid DOM value: ${rangePart}`);
+        }
+        end = 31;
+      }
+      const step = parseInt(stepStr, 10);
+      if (Number.isNaN(step)) {
+        throw HronError.cron(`invalid DOM step: ${stepStr}`);
+      }
+      if (step === 0) {
+        throw HronError.cron("step cannot be 0");
+      }
+      validateDom(start);
+      validateDom(end);
+      for (let d = start; d <= end; d += step) {
+        specs.push({ type: "single", day: d });
+      }
+    } else if (part.includes("-")) {
+      const [startStr, endStr] = part.split("-");
+      const start = parseInt(startStr, 10);
+      const end = parseInt(endStr, 10);
+      if (Number.isNaN(start)) {
+        throw HronError.cron(`invalid DOM range start: ${startStr}`);
+      }
+      if (Number.isNaN(end)) {
+        throw HronError.cron(`invalid DOM range end: ${endStr}`);
+      }
+      if (start > end) {
+        throw HronError.cron(`range start must be <= end: ${start}-${end}`);
+      }
+      validateDom(start);
+      validateDom(end);
+      specs.push({ type: "range", start, end });
+    } else {
+      const day = parseInt(part, 10);
+      if (Number.isNaN(day)) {
+        throw HronError.cron(`invalid DOM value: ${part}`);
+      }
+      validateDom(day);
+      specs.push({ type: "single", day });
     }
-    const dayNums = domField.split(",").map((s) => {
-      const n = parseInt(s, 10);
-      if (Number.isNaN(n))
-        throw HronError.cron(`invalid DOM field: ${domField}`);
-      return n;
-    });
-    const specs = dayNums.map((d) => ({
-      type: "single",
-      day: d
-    }));
-    const expr2 = {
-      type: "monthRepeat",
-      interval: 1,
-      target: { type: "days", specs },
-      times: [time]
-    };
-    return newScheduleData(expr2);
   }
-  const days = parseCronDow(dowField);
-  const expr = {
-    type: "dayRepeat",
-    interval: 1,
-    days,
-    times: [time]
-  };
-  return newScheduleData(expr);
+  return { type: "days", specs };
+}
+function validateDom(day) {
+  if (day < 1 || day > 31) {
+    throw HronError.cron(`DOM must be 1-31, got ${day}`);
+  }
 }
 function parseCronDow(field) {
   if (field === "*") return { type: "every" };
-  if (field === "1-5") return { type: "weekday" };
-  if (field === "0,6" || field === "6,0") return { type: "weekend" };
-  if (field.includes("-")) {
-    throw HronError.cron(`DOW ranges not supported: ${field}`);
-  }
-  const nums = field.split(",").map((s) => {
-    const n = parseInt(s, 10);
-    if (Number.isNaN(n)) throw HronError.cron(`invalid DOW field: ${field}`);
-    return n;
-  });
-  const days = nums.map((n) => cronDowToWeekday(n));
+  const days = [];
+  for (const part of field.split(",")) {
+    if (part.includes("/")) {
+      const [rangePart, stepStr] = part.split("/");
+      let start, end;
+      if (rangePart === "*") {
+        start = 0;
+        end = 6;
+      } else if (rangePart.includes("-")) {
+        const [s, e] = rangePart.split("-");
+        start = parseDowValueRaw(s);
+        end = parseDowValueRaw(e);
+        if (start > end) {
+          throw HronError.cron(`range start must be <= end: ${s}-${e}`);
+        }
+      } else {
+        start = parseDowValueRaw(rangePart);
+        end = 6;
+      }
+      const step = parseInt(stepStr, 10);
+      if (Number.isNaN(step)) {
+        throw HronError.cron(`invalid DOW step: ${stepStr}`);
+      }
+      if (step === 0) {
+        throw HronError.cron("step cannot be 0");
+      }
+      for (let d = start; d <= end; d += step) {
+        const normalized = d === 7 ? 0 : d;
+        days.push(cronDowToWeekday(normalized));
+      }
+    } else if (part.includes("-")) {
+      const [startStr, endStr] = part.split("-");
+      const start = parseDowValueRaw(startStr);
+      const end = parseDowValueRaw(endStr);
+      if (start > end) {
+        throw HronError.cron(
+          `range start must be <= end: ${startStr}-${endStr}`
+        );
+      }
+      for (let d = start; d <= end; d++) {
+        const normalized = d === 7 ? 0 : d;
+        days.push(cronDowToWeekday(normalized));
+      }
+    } else {
+      const dow = parseDowValue(part);
+      days.push(cronDowToWeekday(dow));
+    }
+  }
+  if (days.length === 5) {
+    const sorted = [...days].sort(
+      (a, b) => weekdayNumber(a) - weekdayNumber(b)
+    );
+    const weekdays = [...ALL_WEEKDAYS].sort(
+      (a, b) => weekdayNumber(a) - weekdayNumber(b)
+    );
+    if (JSON.stringify(sorted) === JSON.stringify(weekdays)) {
+      return { type: "weekday" };
+    }
+  }
+  if (days.length === 2) {
+    const sorted = [...days].sort(
+      (a, b) => weekdayNumber(a) - weekdayNumber(b)
+    );
+    const weekend = [...ALL_WEEKEND].sort(
+      (a, b) => weekdayNumber(a) - weekdayNumber(b)
+    );
+    if (JSON.stringify(sorted) === JSON.stringify(weekend)) {
+      return { type: "weekend" };
+    }
+  }
   return { type: "days", days };
 }
+function parseDowValue(s) {
+  const raw = parseDowValueRaw(s);
+  return raw === 7 ? 0 : raw;
+}
+function parseDowValueRaw(s) {
+  const n = parseInt(s, 10);
+  if (!Number.isNaN(n)) {
+    if (n > 7) {
+      throw HronError.cron(`DOW must be 0-7, got ${n}`);
+    }
+    return n;
+  }
+  const map = {
+    SUN: 0,
+    MON: 1,
+    TUE: 2,
+    WED: 3,
+    THU: 4,
+    FRI: 5,
+    SAT: 6
+  };
+  const result = map[s.toUpperCase()];
+  if (result === void 0) {
+    throw HronError.cron(`invalid DOW: ${s}`);
+  }
+  return result;
+}
 function cronDowToWeekday(n) {
   const map = {
     0: "sunday",
@@ -436,9 +939,21 @@ function cronDowToWeekday(n) {
     7: "sunday"
   };
   const result = map[n];
-  if (!result) throw HronError.cron(`invalid DOW number: ${n}`);
+  if (!result) {
+    throw HronError.cron(`invalid DOW number: ${n}`);
+  }
   return result;
 }
+function parseSingleValue(field, name, min, max) {
+  const value = parseInt(field, 10);
+  if (Number.isNaN(value)) {
+    throw HronError.cron(`invalid ${name} field: ${field}`);
+  }
+  if (value < min || value > max) {
+    throw HronError.cron(`${name} must be ${min}-${max}, got ${value}`);
+  }
+  return value;
+}
 
 // src/display.ts
 function display(schedule) {
@@ -491,19 +1006,24 @@ function displayExpr(expr) {
         targetStr = formatOrdinalDaySpecs(expr.target.specs);
       } else if (expr.target.type === "lastDay") {
         targetStr = "last day";
-      } else {
+      } else if (expr.target.type === "lastWeekday") {
         targetStr = "last weekday";
+      } else if (expr.target.type === "ordinalWeekday") {
+        targetStr = `${expr.target.ordinal} ${expr.target.weekday}`;
+      } else if (expr.target.type === "nearestWeekday") {
+        const { day, direction } = expr.target;
+        const dirPrefix = direction ? `${direction} ` : "";
+        targetStr = `${dirPrefix}nearest weekday to ${day}${ordinalSuffix(day)}`;
+      } else {
+        throw new Error(
+          `unknown month target type: ${expr.target.type}`
+        );
       }
       if (expr.interval > 1) {
         return `every ${expr.interval} months on the ${targetStr} at ${formatTimeList(expr.times)}`;
       }
       return `every month on the ${targetStr} at ${formatTimeList(expr.times)}`;
     }
-    case "ordinalRepeat":
-      if (expr.interval > 1) {
-        return `${expr.ordinal} ${expr.day} of every ${expr.interval} months at ${formatTimeList(expr.times)}`;
-      }
-      return `${expr.ordinal} ${expr.day} of every month at ${formatTimeList(expr.times)}`;
     case "singleDate": {
       let dateStr;
       if (expr.date.type === "named") {
@@ -521,14 +1041,24 @@ function displayExpr(expr) {
         targetStr = `the ${expr.target.ordinal} ${expr.target.weekday} of ${expr.target.month}`;
       } else if (expr.target.type === "dayOfMonth") {
         targetStr = `the ${expr.target.day}${ordinalSuffix(expr.target.day)} of ${expr.target.month}`;
-      } else {
+      } else if (expr.target.type === "lastWeekday") {
         targetStr = `the last weekday of ${expr.target.month}`;
+      } else {
+        throw new Error(
+          `unknown year target type: ${expr.target.type}`
+        );
       }
       if (expr.interval > 1) {
         return `every ${expr.interval} years on ${targetStr} at ${formatTimeList(expr.times)}`;
       }
       return `every year on ${targetStr} at ${formatTimeList(expr.times)}`;
     }
+    default: {
+      const _exhaustive = expr;
+      throw new Error(
+        `unknown expression type: ${_exhaustive.type}`
+      );
+    }
   }
 }
 function displayDayFilter(filter) {
@@ -541,6 +1071,12 @@ function displayDayFilter(filter) {
       return "weekend";
     case "days":
       return formatDayList(filter.days);
+    default: {
+      const _exhaustive = filter;
+      throw new Error(
+        `unknown day filter type: ${_exhaustive.type}`
+      );
+    }
   }
 }
 function formatTime(t) {
@@ -620,6 +1156,40 @@ function lastWeekdayOfMonth(year, month) {
   }
   return d;
 }
+function nearestWeekday(year, month, targetDay, direction) {
+  const last = lastDayOfMonth(year, month);
+  const lastDay = last.day;
+  if (targetDay > lastDay) {
+    return null;
+  }
+  const date = import_polyfill.Temporal.PlainDate.from({ year, month, day: targetDay });
+  const dow = date.dayOfWeek;
+  if (dow >= 1 && dow <= 5) {
+    return date;
+  }
+  if (dow === 6) {
+    if (direction === null) {
+      if (targetDay === 1) {
+        return date.add({ days: 2 });
+      }
+      return date.subtract({ days: 1 });
+    }
+    if (direction === "next") {
+      return date.add({ days: 2 });
+    }
+    return date.subtract({ days: 1 });
+  }
+  if (direction === null) {
+    if (targetDay >= lastDay) {
+      return date.subtract({ days: 2 });
+    }
+    return date.add({ days: 1 });
+  }
+  if (direction === "next") {
+    return date.add({ days: 1 });
+  }
+  return date.subtract({ days: 2 });
+}
 function nthWeekdayOfMonth(year, month, weekday, n) {
   const targetDow = weekdayNameToNumber(weekday);
   let d = import_polyfill.Temporal.PlainDate.from({ year, month, day: 1 });
@@ -762,18 +1332,24 @@ function nextFrom(schedule, now) {
   const parsedExceptions = parseExceptions(schedule.except);
   const hasExceptions = schedule.except.length > 0;
   const hasDuring = schedule.during.length > 0;
-  const needsTzConversion = untilDate !== null || hasDuring || hasExceptions;
+  const handlesDuringInternally = schedule.expr.type === "monthRepeat" && schedule.expr.target.type === "nearestWeekday" && schedule.expr.target.direction !== null;
   let current = now;
   for (let i = 0; i < 1e3; i++) {
-    const candidate = nextExpr(schedule.expr, tz, schedule.anchor, current);
+    const candidate = nextExpr(
+      schedule.expr,
+      tz,
+      schedule.anchor,
+      current,
+      schedule.during
+    );
     if (candidate === null) return null;
-    const cDate = needsTzConversion ? candidate.withTimeZone(tz).toPlainDate() : null;
+    const cDate = candidate.withTimeZone(tz).toPlainDate();
     if (untilDate) {
       if (import_polyfill.Temporal.PlainDate.compare(cDate, untilDate) > 0) {
         return null;
       }
     }
-    if (hasDuring && !matchesDuring(cDate, schedule.during)) {
+    if (hasDuring && !handlesDuringInternally && !matchesDuring(cDate, schedule.during)) {
       const skipTo = nextDuringMonth(cDate, schedule.during);
       current = atTimeOnDate(skipTo, MIDNIGHT, tz).subtract({ seconds: 1 });
       continue;
@@ -787,7 +1363,7 @@ function nextFrom(schedule, now) {
   }
   return null;
 }
-function nextExpr(expr, tz, anchor, now) {
+function nextExpr(expr, tz, anchor, now, during) {
   switch (expr.type) {
     case "dayRepeat":
       return nextDayRepeat(
@@ -824,17 +1400,8 @@ function nextExpr(expr, tz, anchor, now) {
         expr.times,
         tz,
         anchor,
-        now
-      );
-    case "ordinalRepeat":
-      return nextOrdinalRepeat(
-        expr.interval,
-        expr.ordinal,
-        expr.day,
-        expr.times,
-        tz,
-        anchor,
-        now
+        now,
+        during
       );
     case "singleDate":
       return nextSingleDate(expr.date, expr.times, tz, now);
@@ -926,30 +1493,35 @@ function matches(schedule, datetime) {
         const last = lastDayOfMonth(date.year, date.month);
         return import_polyfill.Temporal.PlainDate.compare(date, last) === 0;
       }
-      const lastWd = lastWeekdayOfMonth(date.year, date.month);
-      return import_polyfill.Temporal.PlainDate.compare(date, lastWd) === 0;
-    }
-    case "ordinalRepeat": {
-      if (!timeMatchesWithDst(schedule.expr.times)) return false;
-      if (schedule.expr.interval > 1) {
-        const anchorDate = schedule.anchor ? import_polyfill.Temporal.PlainDate.from(schedule.anchor) : EPOCH_DATE;
-        const monthOffset = monthsBetweenYM(anchorDate, date);
-        if (monthOffset < 0 || monthOffset % schedule.expr.interval !== 0) {
-          return false;
-        }
+      if (target.type === "lastWeekday") {
+        const lastWd = lastWeekdayOfMonth(date.year, date.month);
+        return import_polyfill.Temporal.PlainDate.compare(date, lastWd) === 0;
       }
-      const { ordinal, day } = schedule.expr;
-      let targetDate;
-      if (ordinal === "last") {
-        targetDate = lastWeekdayInMonth(date.year, date.month, day);
-      } else {
-        targetDate = nthWeekdayOfMonth(
-          date.year,
-          date.month,
-          day,
-          ordinalToN(ordinal)
-        );
+      if (target.type === "ordinalWeekday") {
+        let targetDate2;
+        if (target.ordinal === "last") {
+          targetDate2 = lastWeekdayInMonth(
+            date.year,
+            date.month,
+            target.weekday
+          );
+        } else {
+          targetDate2 = nthWeekdayOfMonth(
+            date.year,
+            date.month,
+            target.weekday,
+            ordinalToN(target.ordinal)
+          );
+        }
+        if (!targetDate2) return false;
+        return import_polyfill.Temporal.PlainDate.compare(date, targetDate2) === 0;
       }
+      const targetDate = nearestWeekday(
+        date.year,
+        date.month,
+        target.day,
+        target.direction
+      );
       if (!targetDate) return false;
       return import_polyfill.Temporal.PlainDate.compare(date, targetDate) === 0;
     }
@@ -1082,8 +1654,7 @@ function nextWeekRepeat(interval, days, times, tz, anchor, now) {
   for (let i = 0; i < 54; i++) {
     const weeks = weeksBetween(anchorMonday, currentMonday);
     if (weeks < 0) {
-      const skip = Math.ceil(-weeks / interval);
-      currentMonday = currentMonday.add({ days: skip * interval * 7 });
+      currentMonday = anchorMonday;
       continue;
     }
     if (weeks % interval === 0) {
@@ -1100,13 +1671,22 @@ function nextWeekRepeat(interval, days, times, tz, anchor, now) {
   }
   return null;
 }
-function nextMonthRepeat(interval, target, times, tz, anchor, now) {
+function nextMonthRepeat(interval, target, times, tz, anchor, now, during) {
   const nowInTz = now.withTimeZone(tz);
   let year = nowInTz.year;
   let month = nowInTz.month;
   const anchorDate = anchor ? import_polyfill.Temporal.PlainDate.from(anchor) : EPOCH_DATE;
   const maxIter = interval > 1 ? 24 * interval : 24;
+  const applyDuringFilter = during.length > 0 && target.type === "nearestWeekday" && target.direction !== null;
   for (let i = 0; i < maxIter; i++) {
+    if (applyDuringFilter && !during.some((mn) => monthNumber(mn) === month)) {
+      month++;
+      if (month > 12) {
+        month = 1;
+        year++;
+      }
+      continue;
+    }
     if (interval > 1) {
       const cur = import_polyfill.Temporal.PlainDate.from({ year, month, day: 1 });
       const monthOffset = monthsBetweenYM(anchorDate, cur);
@@ -1135,161 +1715,567 @@ function nextMonthRepeat(interval, target, times, tz, anchor, now) {
       }
     } else if (target.type === "lastDay") {
       dateCandidates.push(lastDayOfMonth(year, month));
-    } else {
+    } else if (target.type === "lastWeekday") {
       dateCandidates.push(lastWeekdayOfMonth(year, month));
+    } else if (target.type === "ordinalWeekday") {
+      let owDate;
+      if (target.ordinal === "last") {
+        owDate = lastWeekdayInMonth(year, month, target.weekday);
+      } else {
+        owDate = nthWeekdayOfMonth(
+          year,
+          month,
+          target.weekday,
+          ordinalToN(target.ordinal)
+        );
+      }
+      if (owDate) {
+        dateCandidates.push(owDate);
+      }
+    } else {
+      const nwDate = nearestWeekday(year, month, target.day, target.direction);
+      if (nwDate) {
+        dateCandidates.push(nwDate);
+      }
+    }
+    let best = null;
+    for (const date of dateCandidates) {
+      const candidate = earliestFutureAtTimes(date, times, tz, now);
+      if (candidate) {
+        if (best === null || import_polyfill.Temporal.ZonedDateTime.compare(candidate, best) < 0) {
+          best = candidate;
+        }
+      }
+    }
+    if (best) return best;
+    month++;
+    if (month > 12) {
+      month = 1;
+      year++;
+    }
+  }
+  return null;
+}
+function nextSingleDate(dateSpec, times, tz, now) {
+  const nowInTz = now.withTimeZone(tz);
+  if (dateSpec.type === "iso") {
+    const date = import_polyfill.Temporal.PlainDate.from(dateSpec.date);
+    return earliestFutureAtTimes(date, times, tz, now);
+  }
+  if (dateSpec.type === "named") {
+    const startYear = nowInTz.year;
+    for (let y = 0; y < 8; y++) {
+      const year = startYear + y;
+      try {
+        const date = import_polyfill.Temporal.PlainDate.from(
+          {
+            year,
+            month: monthNumber(dateSpec.month),
+            day: dateSpec.day
+          },
+          { overflow: "reject" }
+        );
+        const candidate = earliestFutureAtTimes(date, times, tz, now);
+        if (candidate) return candidate;
+      } catch {
+      }
+    }
+    return null;
+  }
+  return null;
+}
+function nextYearRepeat(interval, target, times, tz, anchor, now) {
+  const nowInTz = now.withTimeZone(tz);
+  const startYear = nowInTz.year;
+  const anchorYear = anchor ? import_polyfill.Temporal.PlainDate.from(anchor).year : EPOCH_DATE.year;
+  const maxIter = interval > 1 ? 8 * interval : 8;
+  for (let y = 0; y < maxIter; y++) {
+    const year = startYear + y;
+    if (interval > 1) {
+      const yearOffset = year - anchorYear;
+      if (yearOffset < 0 || euclideanMod(yearOffset, interval) !== 0) {
+        continue;
+      }
+    }
+    let targetDate = null;
+    switch (target.type) {
+      case "date":
+        try {
+          targetDate = import_polyfill.Temporal.PlainDate.from(
+            {
+              year,
+              month: monthNumber(target.month),
+              day: target.day
+            },
+            { overflow: "reject" }
+          );
+        } catch {
+          continue;
+        }
+        break;
+      case "ordinalWeekday":
+        if (target.ordinal === "last") {
+          targetDate = lastWeekdayInMonth(
+            year,
+            monthNumber(target.month),
+            target.weekday
+          );
+        } else {
+          targetDate = nthWeekdayOfMonth(
+            year,
+            monthNumber(target.month),
+            target.weekday,
+            ordinalToN(target.ordinal)
+          );
+        }
+        break;
+      case "dayOfMonth":
+        try {
+          targetDate = import_polyfill.Temporal.PlainDate.from(
+            {
+              year,
+              month: monthNumber(target.month),
+              day: target.day
+            },
+            { overflow: "reject" }
+          );
+        } catch {
+          continue;
+        }
+        break;
+      case "lastWeekday":
+        targetDate = lastWeekdayOfMonth(year, monthNumber(target.month));
+        break;
+    }
+    if (targetDate) {
+      const candidate = earliestFutureAtTimes(targetDate, times, tz, now);
+      if (candidate) return candidate;
+    }
+  }
+  return null;
+}
+function previousFrom(schedule, now) {
+  const tz = resolveTz(schedule.timezone);
+  const anchor = schedule.anchor;
+  const parsedExceptions = parseExceptions(schedule.except);
+  const hasExceptions = schedule.except.length > 0;
+  const hasDuring = schedule.during.length > 0;
+  let current = now;
+  for (let i = 0; i < 1e3; i++) {
+    const candidate = prevExpr(schedule, tz, anchor, current);
+    if (candidate === null) return null;
+    const cDate = candidate.withTimeZone(tz).toPlainDate();
+    if (anchor) {
+      const anchorDate = import_polyfill.Temporal.PlainDate.from(anchor);
+      if (import_polyfill.Temporal.PlainDate.compare(cDate, anchorDate) < 0) {
+        return null;
+      }
+    }
+    if (schedule.until) {
+      const untilDate = resolveUntil(schedule.until, now);
+      if (import_polyfill.Temporal.PlainDate.compare(cDate, untilDate) > 0) {
+        const endOfDay = toPlainTime({ hour: 23, minute: 59 });
+        const skipTo = atTimeOnDate(untilDate, endOfDay, tz);
+        current = skipTo.add({ seconds: 1 });
+        continue;
+      }
+    }
+    if (hasDuring && !matchesDuring(cDate, schedule.during)) {
+      const skipTo = prevDuringMonth(cDate, schedule.during);
+      const endOfDay = toPlainTime({ hour: 23, minute: 59 });
+      current = atTimeOnDate(skipTo, endOfDay, tz).add({
+        seconds: 1
+      });
+      continue;
+    }
+    if (hasExceptions && isExceptedParsed(cDate, parsedExceptions)) {
+      const prevDay = cDate.subtract({ days: 1 });
+      const endOfDay = toPlainTime({ hour: 23, minute: 59 });
+      current = atTimeOnDate(prevDay, endOfDay, tz).add({
+        seconds: 1
+      });
+      continue;
+    }
+    return candidate;
+  }
+  return null;
+}
+function prevExpr(schedule, tz, anchor, now) {
+  const expr = schedule.expr;
+  switch (expr.type) {
+    case "dayRepeat":
+      return prevDayRepeat(expr, tz, anchor, now);
+    case "intervalRepeat":
+      return prevIntervalRepeat(expr, tz, now);
+    case "weekRepeat":
+      return prevWeekRepeat(expr, tz, anchor, now);
+    case "monthRepeat":
+      return prevMonthRepeat(expr, tz, anchor, now);
+    case "singleDate":
+      return prevSingleDate(expr, tz, now);
+    case "yearRepeat":
+      return prevYearRepeat(expr, tz, anchor, now);
+    default:
+      return null;
+  }
+}
+function prevDayRepeat(expr, tz, anchor, now) {
+  const nowInTz = now.withTimeZone(tz);
+  let date = nowInTz.toPlainDate();
+  const { interval, days, times } = expr;
+  if (interval <= 1) {
+    if (matchesDayFilter(date, days)) {
+      const candidate = latestPastAtTimes(date, times, tz, now);
+      if (candidate !== null) return candidate;
+    }
+    for (let i = 0; i < 8; i++) {
+      date = date.subtract({ days: 1 });
+      if (matchesDayFilter(date, days)) {
+        const candidate = latestAtTimes(date, times, tz);
+        if (candidate !== null) return candidate;
+      }
+    }
+    return null;
+  }
+  const anchorDate = anchor ? import_polyfill.Temporal.PlainDate.from(anchor) : EPOCH_DATE;
+  const offset = daysBetween(anchorDate, date);
+  const remainder = (offset % interval + interval) % interval;
+  const alignedDate = remainder === 0 ? date : date.subtract({ days: remainder });
+  for (let i = 0; i < 2; i++) {
+    const checkDate = alignedDate.subtract({ days: i * interval });
+    const candidate = latestPastAtTimes(checkDate, times, tz, now);
+    if (candidate !== null) return candidate;
+    const latest = latestAtTimes(checkDate, times, tz);
+    if (latest !== null && import_polyfill.Temporal.ZonedDateTime.compare(latest, now) < 0) {
+      return latest;
+    }
+  }
+  return null;
+}
+function prevIntervalRepeat(expr, tz, now) {
+  const nowInTz = now.withTimeZone(tz);
+  let date = nowInTz.toPlainDate();
+  const { interval, unit, from, to, dayFilter } = expr;
+  const stepMinutes = unit === "min" ? interval : interval * 60;
+  const fromMinutes = from.hour * 60 + from.minute;
+  const toMinutes = to.hour * 60 + to.minute;
+  for (let d = 0; d < 8; d++) {
+    if (dayFilter && !matchesDayFilter(date, dayFilter)) {
+      date = date.subtract({ days: 1 });
+      continue;
+    }
+    const nowMinutes = d === 0 ? nowInTz.hour * 60 + nowInTz.minute : toMinutes + 1;
+    const searchUntil = Math.min(nowMinutes, toMinutes);
+    if (searchUntil >= fromMinutes) {
+      const slotsInRange = Math.floor(
+        (searchUntil - fromMinutes) / stepMinutes
+      );
+      let lastSlotMinutes = fromMinutes + slotsInRange * stepMinutes;
+      if (d === 0 && lastSlotMinutes >= nowMinutes) {
+        lastSlotMinutes -= stepMinutes;
+      }
+      if (lastSlotMinutes >= fromMinutes) {
+        const h = Math.floor(lastSlotMinutes / 60);
+        const m = lastSlotMinutes % 60;
+        return atTimeOnDate(date, toPlainTime({ hour: h, minute: m }), tz);
+      }
+    }
+    date = date.subtract({ days: 1 });
+  }
+  return null;
+}
+function prevWeekRepeat(expr, tz, anchor, now) {
+  const nowInTz = now.withTimeZone(tz);
+  const date = nowInTz.toPlainDate();
+  const { interval, days, times } = expr;
+  const dayOfWeek = date.dayOfWeek;
+  const currentMonday = date.subtract({ days: dayOfWeek - 1 });
+  const anchorDate = anchor ? import_polyfill.Temporal.PlainDate.from(anchor) : EPOCH_MONDAY;
+  const anchorDayOfWeek = anchorDate.dayOfWeek;
+  const anchorMonday = anchorDate.subtract({ days: anchorDayOfWeek - 1 });
+  const sortedDays = [...days].sort((a, b) => dayToNumber(b) - dayToNumber(a));
+  let checkMonday = currentMonday;
+  for (let w = 0; w < 54; w++) {
+    const weeks = weeksBetween(anchorMonday, checkMonday);
+    if (weeks < 0) {
+      return null;
     }
-    let best = null;
-    for (const date of dateCandidates) {
-      const candidate = earliestFutureAtTimes(date, times, tz, now);
-      if (candidate) {
-        if (best === null || import_polyfill.Temporal.ZonedDateTime.compare(candidate, best) < 0) {
-          best = candidate;
+    if (weeks % interval === 0) {
+      for (const wd of sortedDays) {
+        const dayNum = dayToNumber(wd);
+        const targetDate = checkMonday.add({ days: dayNum - 1 });
+        if (import_polyfill.Temporal.PlainDate.compare(targetDate, date) < 0) {
+          const candidate = latestAtTimes(targetDate, times, tz);
+          if (candidate !== null) return candidate;
+        } else if (import_polyfill.Temporal.PlainDate.compare(targetDate, date) === 0) {
+          const candidate = latestPastAtTimes(targetDate, times, tz, now);
+          if (candidate !== null) return candidate;
         }
       }
     }
-    if (best) return best;
-    month++;
-    if (month > 12) {
-      month = 1;
-      year++;
-    }
+    checkMonday = checkMonday.subtract({ days: interval * 7 });
   }
   return null;
 }
-function nextOrdinalRepeat(interval, ordinal, day, times, tz, anchor, now) {
+function prevMonthRepeat(expr, tz, anchor, now) {
   const nowInTz = now.withTimeZone(tz);
-  let year = nowInTz.year;
-  let month = nowInTz.month;
+  const startDate = nowInTz.toPlainDate();
+  const { interval, target, times } = expr;
   const anchorDate = anchor ? import_polyfill.Temporal.PlainDate.from(anchor) : EPOCH_DATE;
+  let year = startDate.year;
+  let month = startDate.month;
   const maxIter = interval > 1 ? 24 * interval : 24;
   for (let i = 0; i < maxIter; i++) {
     if (interval > 1) {
-      const cur = import_polyfill.Temporal.PlainDate.from({ year, month, day: 1 });
-      const monthOffset = monthsBetweenYM(anchorDate, cur);
-      if (monthOffset < 0 || euclideanMod(monthOffset, interval) !== 0) {
-        month++;
-        if (month > 12) {
-          month = 1;
-          year++;
-        }
+      const monthOffset = monthsBetweenYM(
+        anchorDate,
+        import_polyfill.Temporal.PlainDate.from({ year, month, day: 1 })
+      );
+      if (monthOffset < 0 || monthOffset % interval !== 0) {
+        ({ year, month } = prevMonth(year, month));
         continue;
       }
     }
-    let targetDate;
-    if (ordinal === "last") {
-      targetDate = lastWeekdayInMonth(year, month, day);
-    } else {
-      targetDate = nthWeekdayOfMonth(year, month, day, ordinalToN(ordinal));
-    }
-    if (targetDate) {
-      const candidate = earliestFutureAtTimes(targetDate, times, tz, now);
-      if (candidate) return candidate;
-    }
-    month++;
-    if (month > 12) {
-      month = 1;
-      year++;
+    const targetDates = getMonthTargetDates(year, month, target);
+    for (const d of targetDates.sort(
+      (a, b) => import_polyfill.Temporal.PlainDate.compare(b, a)
+    )) {
+      if (import_polyfill.Temporal.PlainDate.compare(d, startDate) > 0) continue;
+      if (import_polyfill.Temporal.PlainDate.compare(d, startDate) === 0) {
+        const candidate = latestPastAtTimes(d, times, tz, now);
+        if (candidate !== null) return candidate;
+      } else {
+        const candidate = latestAtTimes(d, times, tz);
+        if (candidate !== null) return candidate;
+      }
     }
+    ({ year, month } = prevMonth(year, month));
   }
   return null;
 }
-function nextSingleDate(dateSpec, times, tz, now) {
+function prevSingleDate(expr, tz, now) {
   const nowInTz = now.withTimeZone(tz);
+  const nowDate = nowInTz.toPlainDate();
+  const { date: dateSpec, times } = expr;
+  let targetDate;
   if (dateSpec.type === "iso") {
-    const date = import_polyfill.Temporal.PlainDate.from(dateSpec.date);
-    return earliestFutureAtTimes(date, times, tz, now);
-  }
-  if (dateSpec.type === "named") {
-    const startYear = nowInTz.year;
-    for (let y = 0; y < 8; y++) {
-      const year = startYear + y;
-      try {
-        const date = import_polyfill.Temporal.PlainDate.from(
-          {
-            year,
-            month: monthNumber(dateSpec.month),
-            day: dateSpec.day
-          },
-          { overflow: "reject" }
-        );
-        const candidate = earliestFutureAtTimes(date, times, tz, now);
-        if (candidate) return candidate;
-      } catch {
-      }
+    targetDate = import_polyfill.Temporal.PlainDate.from(dateSpec.date);
+    if (import_polyfill.Temporal.PlainDate.compare(targetDate, nowDate) > 0) {
+      return null;
+    }
+    if (import_polyfill.Temporal.PlainDate.compare(targetDate, nowDate) === 0) {
+      return latestPastAtTimes(targetDate, times, tz, now);
+    }
+    return latestAtTimes(targetDate, times, tz);
+  } else {
+    const { month, day } = dateSpec;
+    const monthNum = monthNumber(month);
+    const thisYear = import_polyfill.Temporal.PlainDate.from({
+      year: nowDate.year,
+      month: monthNum,
+      day
+    });
+    const lastYear = import_polyfill.Temporal.PlainDate.from({
+      year: nowDate.year - 1,
+      month: monthNum,
+      day
+    });
+    if (import_polyfill.Temporal.PlainDate.compare(thisYear, nowDate) < 0) {
+      targetDate = thisYear;
+    } else if (import_polyfill.Temporal.PlainDate.compare(thisYear, nowDate) === 0) {
+      const candidate = latestPastAtTimes(thisYear, times, tz, now);
+      if (candidate !== null) return candidate;
+      targetDate = lastYear;
+    } else {
+      targetDate = lastYear;
     }
-    return null;
+    return latestAtTimes(targetDate, times, tz);
   }
-  return null;
 }
-function nextYearRepeat(interval, target, times, tz, anchor, now) {
+function prevYearRepeat(expr, tz, anchor, now) {
   const nowInTz = now.withTimeZone(tz);
-  const startYear = nowInTz.year;
+  const startDate = nowInTz.toPlainDate();
+  const startYear = startDate.year;
+  const { interval, target, times } = expr;
   const anchorYear = anchor ? import_polyfill.Temporal.PlainDate.from(anchor).year : EPOCH_DATE.year;
   const maxIter = interval > 1 ? 8 * interval : 8;
   for (let y = 0; y < maxIter; y++) {
-    const year = startYear + y;
+    const year = startYear - y;
     if (interval > 1) {
       const yearOffset = year - anchorYear;
-      if (yearOffset < 0 || euclideanMod(yearOffset, interval) !== 0) {
+      if (yearOffset < 0 || yearOffset % interval !== 0) {
         continue;
       }
     }
-    let targetDate = null;
-    switch (target.type) {
-      case "date":
-        try {
-          targetDate = import_polyfill.Temporal.PlainDate.from(
-            {
-              year,
-              month: monthNumber(target.month),
-              day: target.day
-            },
-            { overflow: "reject" }
-          );
-        } catch {
-          continue;
-        }
-        break;
-      case "ordinalWeekday":
-        if (target.ordinal === "last") {
-          targetDate = lastWeekdayInMonth(
-            year,
-            monthNumber(target.month),
-            target.weekday
-          );
-        } else {
-          targetDate = nthWeekdayOfMonth(
-            year,
-            monthNumber(target.month),
-            target.weekday,
-            ordinalToN(target.ordinal)
-          );
-        }
-        break;
-      case "dayOfMonth":
+    const targetDate = getYearTargetDate(year, target);
+    if (targetDate !== null) {
+      if (import_polyfill.Temporal.PlainDate.compare(targetDate, startDate) > 0) {
+        continue;
+      }
+      if (import_polyfill.Temporal.PlainDate.compare(targetDate, startDate) === 0) {
+        const candidate = latestPastAtTimes(targetDate, times, tz, now);
+        if (candidate !== null) return candidate;
+      } else {
+        const candidate = latestAtTimes(targetDate, times, tz);
+        if (candidate !== null) return candidate;
+      }
+    }
+  }
+  return null;
+}
+function latestPastAtTimes(date, times, tz, now) {
+  const sortedTimes = [...times].sort(
+    (a, b) => b.hour * 60 + b.minute - (a.hour * 60 + a.minute)
+  );
+  for (const tod of sortedTimes) {
+    const t = toPlainTime(tod);
+    const candidate = atTimeOnDate(date, t, tz);
+    if (import_polyfill.Temporal.ZonedDateTime.compare(candidate, now) < 0) {
+      return candidate;
+    }
+  }
+  return null;
+}
+function latestAtTimes(date, times, tz) {
+  const sortedTimes = [...times].sort(
+    (a, b) => a.hour * 60 + a.minute - (b.hour * 60 + b.minute)
+  );
+  if (sortedTimes.length === 0) return null;
+  const latest = sortedTimes[sortedTimes.length - 1];
+  return atTimeOnDate(date, toPlainTime(latest), tz);
+}
+function prevMonth(year, month) {
+  if (month === 1) {
+    return { year: year - 1, month: 12 };
+  }
+  return { year, month: month - 1 };
+}
+function prevDuringMonth(date, during) {
+  let { year, month } = prevMonth(date.year, date.month);
+  for (let i = 0; i < 12; i++) {
+    const monthName = numberToMonthName(month);
+    if (during.includes(monthName)) {
+      return lastDayOfMonth(year, month);
+    }
+    ({ year, month } = prevMonth(year, month));
+  }
+  return date.subtract({ days: 1 });
+}
+function numberToMonthName(n) {
+  const names = [
+    "jan",
+    "feb",
+    "mar",
+    "apr",
+    "may",
+    "jun",
+    "jul",
+    "aug",
+    "sep",
+    "oct",
+    "nov",
+    "dec"
+  ];
+  return names[n - 1];
+}
+function getMonthTargetDates(year, month, target) {
+  switch (target.type) {
+    case "days": {
+      const expanded = expandMonthTarget(target);
+      return expanded.map((d) => {
         try {
-          targetDate = import_polyfill.Temporal.PlainDate.from(
-            {
-              year,
-              month: monthNumber(target.month),
-              day: target.day
-            },
-            { overflow: "reject" }
-          );
+          return import_polyfill.Temporal.PlainDate.from({ year, month, day: d });
         } catch {
-          continue;
+          return null;
         }
-        break;
-      case "lastWeekday":
-        targetDate = lastWeekdayOfMonth(year, monthNumber(target.month));
-        break;
+      }).filter((d) => d !== null);
     }
-    if (targetDate) {
-      const candidate = earliestFutureAtTimes(targetDate, times, tz, now);
-      if (candidate) return candidate;
+    case "lastDay":
+      return [lastDayOfMonth(year, month)];
+    case "lastWeekday":
+      return [lastWeekdayOfMonth(year, month)];
+    case "nearestWeekday": {
+      const d = nearestWeekday(year, month, target.day, target.direction);
+      return d ? [d] : [];
+    }
+    case "ordinalWeekday": {
+      const d = getOrdinalWeekday(year, month, target.ordinal, target.weekday);
+      return d ? [d] : [];
     }
+    default:
+      return [];
+  }
+}
+function getYearTargetDate(year, target) {
+  switch (target.type) {
+    case "date": {
+      const monthNum = monthNumber(target.month);
+      try {
+        return import_polyfill.Temporal.PlainDate.from({
+          year,
+          month: monthNum,
+          day: target.day
+        });
+      } catch {
+        return null;
+      }
+    }
+    case "ordinalWeekday": {
+      const monthNum = monthNumber(target.month);
+      return getOrdinalWeekday(year, monthNum, target.ordinal, target.weekday);
+    }
+    case "dayOfMonth": {
+      const monthNum = monthNumber(target.month);
+      try {
+        return import_polyfill.Temporal.PlainDate.from({
+          year,
+          month: monthNum,
+          day: target.day
+        });
+      } catch {
+        return null;
+      }
+    }
+    case "lastWeekday": {
+      const monthNum = monthNumber(target.month);
+      return lastWeekdayOfMonth(year, monthNum);
+    }
+    default:
+      return null;
+  }
+}
+function getOrdinalWeekday(year, month, ordinal, day) {
+  if (ordinal === "last") {
+    return lastWeekdayInMonth(year, month, day);
+  }
+  return nthWeekdayOfMonth(year, month, day, ordinalToN(ordinal));
+}
+function dayToNumber(day) {
+  const map = {
+    monday: 1,
+    tuesday: 2,
+    wednesday: 3,
+    thursday: 4,
+    friday: 5,
+    saturday: 6,
+    sunday: 7
+  };
+  return map[day];
+}
+function* occurrences(schedule, from) {
+  let current = from;
+  for (; ; ) {
+    const next = nextFrom(schedule, current);
+    if (next === null) return;
+    current = next.add({ minutes: 1 });
+    yield next;
+  }
+}
+function* between(schedule, from, to) {
+  for (const dt of occurrences(schedule, from)) {
+    if (import_polyfill.Temporal.ZonedDateTime.compare(dt, to) > 0) return;
+    yield dt;
   }
-  return null;
 }
 
 // src/lexer.ts
@@ -1459,6 +2445,9 @@ var KEYWORD_MAP = {
   during: { type: "during" },
   year: { type: "year" },
   years: { type: "year" },
+  nearest: { type: "nearest" },
+  next: { type: "next" },
+  previous: { type: "previous" },
   day: { type: "day" },
   days: { type: "day" },
   weekday: { type: "weekday" },
@@ -1594,13 +2583,8 @@ var Parser = class {
     } else if (kind?.type === "on") {
       this.advance();
       expr = this.parseOn();
-    } else if (kind?.type === "ordinal" || kind?.type === "last") {
-      expr = this.parseOrdinalRepeat();
     } else {
-      throw this.error(
-        "expected 'every', 'on', or an ordinal (first, second, ...)",
-        span
-      );
+      throw this.error("expected 'every' or 'on'", span);
     }
     return this.parseTrailingClauses(expr);
   }
@@ -1618,7 +2602,9 @@ var Parser = class {
       this.advance();
       const k = this.peekKind();
       if (k?.type === "isoDate") {
-        schedule.anchor = k.date;
+        const startDate = k.date;
+        this.validateIsoDate(startDate);
+        schedule.anchor = startDate;
         this.advance();
       } else {
         throw this.error(
@@ -1655,6 +2641,7 @@ var Parser = class {
     const k = this.peekKind();
     if (k?.type === "isoDate") {
       const date = k.date;
+      this.validateIsoDate(date);
       this.advance();
       return { type: "iso", date };
     }
@@ -1662,10 +2649,13 @@ var Parser = class {
       const month = parseMonthName(
         k.name
       );
+      if (!month) throw this.error("invalid month name", this.currentSpan());
       this.advance();
+      const dayPos = this.currentSpan().start;
       const day = this.parseDayNumber(
         "expected day number after month name in exception"
       );
+      this.validateNamedDate(month, day, dayPos);
       return { type: "named", month, day };
     }
     throw this.error(
@@ -1677,6 +2667,7 @@ var Parser = class {
     const k = this.peekKind();
     if (k?.type === "isoDate") {
       const date = k.date;
+      this.validateIsoDate(date);
       this.advance();
       return { type: "iso", date };
     }
@@ -1684,10 +2675,13 @@ var Parser = class {
       const month = parseMonthName(
         k.name
       );
+      if (!month) throw this.error("invalid month name", this.currentSpan());
       this.advance();
+      const dayPos = this.currentSpan().start;
       const day = this.parseDayNumber(
         "expected day number after month name in until"
       );
+      this.validateNamedDate(month, day, dayPos);
       return { type: "named", month, day };
     }
     throw this.error(
@@ -1699,11 +2693,23 @@ var Parser = class {
     const k = this.peekKind();
     if (k?.type === "number") {
       const n = k.value;
+      if (n < 1 || n > 31) {
+        throw this.error(
+          `invalid day number ${n} (must be 1-31)`,
+          this.currentSpan()
+        );
+      }
       this.advance();
       return n;
     }
     if (k?.type === "ordinalNumber") {
       const n = k.value;
+      if (n < 1 || n > 31) {
+        throw this.error(
+          `invalid day number ${n} (must be 1-31)`,
+          this.currentSpan()
+        );
+      }
       this.advance();
       return n;
     }
@@ -1713,6 +2719,7 @@ var Parser = class {
   parseEvery() {
     if (!this.peek()) throw this.errorAtEnd("expected repeater");
     const k = this.peekKind();
+    if (!k) throw this.errorAtEnd("expected repeater");
     if (k.type === "year") {
       this.advance();
       return this.parseYearRepeat(1);
@@ -1755,6 +2762,7 @@ var Parser = class {
   parseNumberRepeat() {
     const span = this.currentSpan();
     const k = this.peekKind();
+    if (!k) throw this.errorAtEnd("expected number");
     const num = k.value;
     if (num === 0) {
       throw this.error("interval must be at least 1", span);
@@ -1786,6 +2794,7 @@ var Parser = class {
   }
   parseIntervalRepeat(interval) {
     const k = this.peekKind();
+    if (!k) throw this.errorAtEnd("expected interval unit");
     const unitStr = k.unit;
     this.advance();
     const unit = unitStr === "min" ? "min" : "hours";
@@ -1821,18 +2830,43 @@ var Parser = class {
       } else if (next?.type === "weekday") {
         this.advance();
         target = { type: "lastWeekday" };
+      } else if (next?.type === "dayName") {
+        const weekday = parseWeekday(
+          next.name
+        );
+        if (!weekday) throw this.error("invalid weekday", this.currentSpan());
+        this.advance();
+        target = { type: "ordinalWeekday", ordinal: "last", weekday };
+      } else {
+        throw this.error(
+          "expected 'day', 'weekday', or day name after 'last'",
+          this.currentSpan()
+        );
+      }
+    } else if (k?.type === "ordinal") {
+      const ordinal = this.parseOrdinalPosition();
+      const next = this.peekKind();
+      if (next?.type === "dayName") {
+        const weekday = parseWeekday(
+          next.name
+        );
+        if (!weekday) throw this.error("invalid weekday", this.currentSpan());
+        this.advance();
+        target = { type: "ordinalWeekday", ordinal, weekday };
       } else {
         throw this.error(
-          "expected 'day' or 'weekday' after 'last'",
+          "expected day name after ordinal in month expression",
           this.currentSpan()
         );
       }
     } else if (k?.type === "ordinalNumber") {
       const specs = this.parseOrdinalDayList();
       target = { type: "days", specs };
+    } else if (k?.type === "next" || k?.type === "previous" || k?.type === "nearest") {
+      target = this.parseNearestWeekdayTarget();
     } else {
       throw this.error(
-        "expected ordinal day (1st, 15th) or 'last' after 'the'",
+        "expected ordinal day (1st, 15th), 'last', ordinal weekday, or '[next|previous] nearest' after 'the'",
         this.currentSpan()
       );
     }
@@ -1840,31 +2874,37 @@ var Parser = class {
     const times = this.parseTimeList();
     return { type: "monthRepeat", interval, target, times };
   }
-  parseOrdinalRepeat() {
-    const ordinal = this.parseOrdinalPosition();
+  // [next|previous] nearest weekday to <day>
+  parseNearestWeekdayTarget() {
+    let direction = null;
     const k = this.peekKind();
-    if (k?.type !== "dayName") {
-      throw this.error("expected day name after ordinal", this.currentSpan());
+    if (k?.type === "next") {
+      this.advance();
+      direction = "next";
+    } else if (k?.type === "previous") {
+      this.advance();
+      direction = "previous";
     }
-    const day = parseWeekday(
-      k.name
-    );
-    this.advance();
-    this.consumeKind("'of'", (k2) => k2.type === "of");
-    this.consumeKind("'every'", (k2) => k2.type === "every");
-    let interval = 1;
-    const next = this.peekKind();
-    if (next?.type === "number") {
-      interval = next.value;
-      if (interval === 0) {
-        throw this.error("interval must be at least 1", this.currentSpan());
+    this.consumeKind("'nearest'", (k2) => k2.type === "nearest");
+    this.consumeKind("'weekday'", (k2) => k2.type === "weekday");
+    this.consumeKind("'to'", (k2) => k2.type === "to");
+    const day = this.parseOrdinalDayNumber();
+    return { type: "nearestWeekday", day, direction };
+  }
+  parseOrdinalDayNumber() {
+    const k = this.peekKind();
+    if (k?.type === "ordinalNumber") {
+      const d = k.value;
+      if (d < 1 || d > 31) {
+        throw this.error(
+          `invalid day number ${d} (must be 1-31)`,
+          this.currentSpan()
+        );
       }
       this.advance();
+      return d;
     }
-    this.consumeKind("'month'", (k2) => k2.type === "month");
-    this.consumeKind("'at'", (k2) => k2.type === "at");
-    const times = this.parseTimeList();
-    return { type: "ordinalRepeat", interval, ordinal, day, times };
+    throw this.error("expected ordinal day number", this.currentSpan());
   }
   parseYearRepeat(interval) {
     this.consumeKind("'on'", (k2) => k2.type === "on");
@@ -1877,8 +2917,11 @@ var Parser = class {
       const month = parseMonthName(
         k.name
       );
+      if (!month) throw this.error("invalid month name", this.currentSpan());
       this.advance();
+      const dayPos = this.currentSpan().start;
       const day = this.parseDayNumber("expected day number after month name");
+      this.validateNamedDate(month, day, dayPos);
       target = { type: "date", month, day };
     } else {
       throw this.error(
@@ -1905,6 +2948,7 @@ var Parser = class {
         const weekday = parseWeekday(
           next.name
         );
+        if (!weekday) throw this.error("invalid weekday", this.currentSpan());
         this.advance();
         this.consumeKind("'of'", (k2) => k2.type === "of");
         const month = this.parseMonthNameToken();
@@ -1922,6 +2966,7 @@ var Parser = class {
         const weekday = parseWeekday(
           next.name
         );
+        if (!weekday) throw this.error("invalid weekday", this.currentSpan());
         this.advance();
         this.consumeKind("'of'", (k2) => k2.type === "of");
         const month = this.parseMonthNameToken();
@@ -1934,9 +2979,17 @@ var Parser = class {
     }
     if (k?.type === "ordinalNumber") {
       const day = k.value;
+      if (day < 1 || day > 31) {
+        throw this.error(
+          `invalid day number ${day} (must be 1-31)`,
+          this.currentSpan()
+        );
+      }
+      const dayPos = this.currentSpan().start;
       this.advance();
       this.consumeKind("'of'", (k2) => k2.type === "of");
       const month = this.parseMonthNameToken();
+      this.validateNamedDate(month, day, dayPos);
       return { type: "dayOfMonth", day, month };
     }
     throw this.error(
@@ -1950,6 +3003,7 @@ var Parser = class {
       const month = parseMonthName(
         k.name
       );
+      if (!month) throw this.error("invalid month name", this.currentSpan());
       this.advance();
       return month;
     }
@@ -1978,10 +3032,50 @@ var Parser = class {
     const times = this.parseTimeList();
     return { type: "singleDate", date, times };
   }
+  validateNamedDate(month, day, pos) {
+    const maxDays = {
+      jan: 31,
+      feb: 29,
+      mar: 31,
+      apr: 30,
+      may: 31,
+      jun: 30,
+      jul: 31,
+      aug: 31,
+      sep: 30,
+      oct: 31,
+      nov: 30,
+      dec: 31
+    };
+    const max = maxDays[month];
+    if (day > max) {
+      throw this.error(`invalid day ${day} for ${month} (max ${max})`, {
+        start: pos,
+        end: pos
+      });
+    }
+  }
+  validateIsoDate(dateStr) {
+    const parts = dateStr.split("-");
+    const year = parseInt(parts[0], 10);
+    const month = parseInt(parts[1], 10);
+    const day = parseInt(parts[2], 10);
+    if (month < 1 || month > 12 || day < 1) {
+      throw this.error(`invalid date: ${dateStr}`, this.currentSpan());
+    }
+    const daysInMonth = [0, 31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
+    if (year % 4 === 0 && year % 100 !== 0 || year % 400 === 0) {
+      daysInMonth[2] = 29;
+    }
+    if (day > daysInMonth[month]) {
+      throw this.error(`invalid date: ${dateStr}`, this.currentSpan());
+    }
+  }
   parseDateTarget() {
     const k = this.peekKind();
     if (k?.type === "isoDate") {
       const date = k.date;
+      this.validateIsoDate(date);
       this.advance();
       return { type: "iso", date };
     }
@@ -1989,8 +3083,11 @@ var Parser = class {
       const month = parseMonthName(
         k.name
       );
+      if (!month) throw this.error("invalid month name", this.currentSpan());
       this.advance();
+      const dayPos = this.currentSpan().start;
       const day = this.parseDayNumber("expected day number after month name");
+      this.validateNamedDate(month, day, dayPos);
       return { type: "named", month, day };
     }
     throw this.error(
@@ -2026,9 +3123,11 @@ var Parser = class {
     if (k?.type !== "dayName") {
       throw this.error("expected day name", this.currentSpan());
     }
-    const days = [
-      parseWeekday(k.name)
-    ];
+    const firstDay = parseWeekday(
+      k.name
+    );
+    if (!firstDay) throw this.error("invalid weekday", this.currentSpan());
+    const days = [firstDay];
     this.advance();
     while (this.peekKind()?.type === "comma") {
       this.advance();
@@ -2036,11 +3135,11 @@ var Parser = class {
       if (next?.type !== "dayName") {
         throw this.error("expected day name after ','", this.currentSpan());
       }
-      days.push(
-        parseWeekday(
-          next.name
-        )
+      const day = parseWeekday(
+        next.name
       );
+      if (!day) throw this.error("invalid weekday", this.currentSpan());
+      days.push(day);
       this.advance();
     }
     return days;
@@ -2059,6 +3158,12 @@ var Parser = class {
       throw this.error("expected ordinal day number", this.currentSpan());
     }
     const start = k.value;
+    if (start < 1 || start > 31) {
+      throw this.error(
+        `invalid day number ${start} (must be 1-31)`,
+        this.currentSpan()
+      );
+    }
     this.advance();
     if (this.peekKind()?.type === "to") {
       this.advance();
@@ -2070,7 +3175,19 @@ var Parser = class {
         );
       }
       const end = next.value;
+      if (end < 1 || end > 31) {
+        throw this.error(
+          `invalid day number ${end} (must be 1-31)`,
+          this.currentSpan()
+        );
+      }
       this.advance();
+      if (start > end) {
+        throw this.error(
+          `invalid day range: ${start} to ${end} (start must be <= end)`,
+          this.currentSpan()
+        );
+      }
       return { type: "range", start, end };
     }
     return { type: "single", day: start };
@@ -2151,10 +3268,29 @@ var Schedule = class _Schedule {
   nextNFrom(now, n) {
     return nextNFrom(this.data, now, n);
   }
+  /** Compute the most recent occurrence strictly before `now`. */
+  previousFrom(now) {
+    return previousFrom(this.data, now);
+  }
   /** Check if a datetime matches this schedule. */
   matches(datetime) {
     return matches(this.data, datetime);
   }
+  /**
+   * Returns a lazy iterator of occurrences starting after `from`.
+   * The iterator is unbounded for repeating schedules (will iterate forever unless limited),
+   * but respects the `until` clause if specified in the schedule.
+   */
+  *occurrences(from) {
+    yield* occurrences(this.data, from);
+  }
+  /**
+   * Returns a bounded iterator of occurrences where `from < occurrence <= to`.
+   * The iterator yields occurrences strictly after `from` and up to and including `to`.
+   */
+  *between(from, to) {
+    yield* between(this.data, from, to);
+  }
   /** Convert this schedule to a 5-field cron expression. */
   toCron() {
     return toCron(this.data);