Fix DST fall-back scheduling gap for high-frequency cron patterns (#344)

* Initial plan

* Fix DST fall-back scheduling gap for per-second and per-minute cron patterns

During DST fall-back transitions, cron jobs with high-frequency patterns
(per-second, per-minute) would experience a ~1 hour scheduling gap. This
was caused by the local time increment skipping over the second occurrence
of the overlap period.

Changes:
- Add afterMs field to CronDate for DST overlap resolution
- Improve fromTZ overlap detection to check both earlier and later times
- Add DST overlap fix in _next() to detect and handle UTC time jumps
- Preserve original UTC time in CronDate.fromDate() for correct round-trips
- Add 3 new test cases for DST fall-back behavior

Co-authored-by: Hexagon <419737+Hexagon@users.noreply.github.com>

* Clarify DST overlap handling for high-frequency vs specific-time patterns in docs

Updated pattern documentation in both README.md and docs/src/usage/pattern.md
to explain that DST overlap behavior differs by pattern type:
- Specific-time patterns (e.g. 0 30 2 * * *): run once at first occurrence
- High-frequency patterns (e.g. * * * * *): continue executing without gaps

Co-authored-by: Hexagon <419737+Hexagon@users.noreply.github.com>

* Bump version to 10.0.2-dev.0

Co-authored-by: Hexagon <419737+Hexagon@users.noreply.github.com>

* Fix fromTZ JSDoc for afterMs edge case and improve test comment clarity

- Clarified afterMs JSDoc to document behavior when both DST occurrences
  are before the threshold (returns second/later occurrence as closest option)
- Fixed misleading test comment to use explicit UTC instants (08:59Z → 09:00Z)

Co-authored-by: Hexagon <419737+Hexagon@users.noreply.github.com>

* Copy afterMs in fromCronDate to preserve DST overlap context across CronDate cloning

Co-authored-by: Hexagon <419737+Hexagon@users.noreply.github.com>

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: Hexagon <419737+Hexagon@users.noreply.github.com>

Author: Copilot

README.md

@@ -199,7 +199,7 @@ Croner uses [Vixie Cron](https://en.wikipedia.org/wiki/Cron#CRON_expression) bas
 *   **Enhanced logical control**:
 	-   *+*: Explicit AND logic modifier. Prefix the day-of-week field with `+` to require both day-of-month AND day-of-week to match. Example: `0 12 1 * +MON` only triggers when the 1st is also a Monday.
 	-   *?*: Wildcard alias (behaves identically to `*`). **Non-portable**: Its use is discouraged in patterns intended for cross-system use. Supported in all fields for compatibility, but primarily meaningful in day-of-month and day-of-week fields.
-	-   Proper DST handling: Jobs scheduled during DST gaps are skipped; jobs in DST overlaps run once at first occurrence.
+	-   Proper DST handling: Jobs scheduled during DST gaps are skipped. During DST overlaps (fall-back), specific-time patterns (e.g. `0 30 2 * * *`) run once at the first occurrence; high-frequency patterns (e.g. `* * * * *`) continue executing without gaps.
 
 *   Croner allows you to pass a JavaScript Date object or an ISO 8601 formatted string as a pattern. The scheduled function will trigger at the specified date/time and only once. If you use a timezone different from the local timezone, you should pass the ISO 8601 local time in the target location and specify the timezone using the options (2nd parameter).
 

deno.json

@@ -1,6 +1,6 @@
 {
   "name": "@hexagon/croner",
-  "version": "10.0.1",
+  "version": "10.0.2-dev.0",
   "exports": "./src/croner.ts",
   "lint": {
     "include": ["src", "build"]

docs/src/usage/pattern.md

@@ -35,7 +35,9 @@ Croner is fully compliant with the [Open Cron Pattern Specification (OCPS)](http
 *   **OCPS 1.4**: Enhanced logical control:
 	-   *+*: Explicit AND logic modifier. Prefix the day-of-week field with `+` to require both day-of-month AND day-of-week to match. Example: `0 12 1 * +MON` only triggers when the 1st is also a Monday.
 	-   *?*: Wildcard alias (behaves identically to `*`). **Non-portable**: Its use is discouraged in patterns intended for cross-system use. Supported in all fields for compatibility, but primarily meaningful in day-of-month and day-of-week fields.
-	-   Proper DST handling: Jobs scheduled during DST gaps are skipped; jobs in DST overlaps run once at first occurrence.
+	-   Proper DST handling: Jobs scheduled during DST gaps are skipped. During DST overlaps (fall-back), behavior depends on the pattern:
+		-   **Specific-time patterns** (e.g. `0 30 2 * * *`): Run once at the first occurrence of the ambiguous time, per OCPS 1.4 §4.3.1.
+		-   **High-frequency patterns** (e.g. `* * * * *`, `* * * * * *`): Continue executing through the overlap period without gaps. Each tick advances by the expected interval in UTC, so no executions are skipped or duplicated.
 
 *   Croner allows you to pass a JavaScript Date object or an ISO 8601 formatted string as a pattern. The scheduled function will trigger at the specified date/time and only once. If you use a timezone different from the local timezone, you should pass the ISO 8601 local time in the target location and specify the timezone using the options (2nd parameter).
 

src/croner.ts

@@ -633,6 +633,33 @@ class Cron<T = undefined> {
       );
     }
 
+    // DST fall-back overlap fix: When increment() produces a next run whose UTC time
+    // is not monotonically advancing relative to the previous run, we may be in a DST
+    // overlap period. This can manifest as:
+    // 1. A gap >= 1 hour beyond expected (skipped over the overlap period entirely)
+    // 2. A negative gap (increment wrapped to the first DST occurrence, which is before prevUtc)
+    if (nextRun !== null && nextRun !== this._states.once && typeof this.getTz() === "string") {
+      const prevUtc = (previousRun as CronDate<T>).getTime();
+      const nextUtc = nextRun.getTime();
+      const expectedIncrementMs =
+        ((this.options.interval && hasPreviousRun) ? this.options.interval : 1) * 1000;
+      const gap = nextUtc - prevUtc;
+
+      if (gap >= expectedIncrementMs + 3600000 || gap < 0) {
+        // Try the candidate 1 hour after the computed next time (for case 2: first→second occurrence)
+        // or 1 hour before (for case 1: skipped over overlap)
+        const overlapUtc = gap < 0 ? nextUtc + 3600000 : nextUtc - 3600000;
+        const overlapDate = new Date(overlapUtc);
+        const overlapCron = new CronDate<T>(overlapDate, this.getTz());
+        // Verify the candidate matches the pattern and is after the previous run
+        if (overlapCron.match(this._states.pattern, this.options) && overlapUtc > prevUtc) {
+          // Set afterMs to ensure getTime() returns the correct DST occurrence
+          overlapCron.setAfterMs(prevUtc);
+          nextRun = overlapCron;
+        }
+      }
+    }
+
     if (
       this._states.once && this._states.once.getTime() <= (previousRun as CronDate<T>).getTime()
     ) {

src/date.ts

@@ -50,6 +50,14 @@ const RecursionSteps: RecursionStep[] = [
 class CronDate<T = undefined> {
   tz: string | number | undefined;
 
+  /**
+   * Optional UTC ms threshold for resolving DST overlap ambiguity.
+   * When set, getTime()/getDate() will return the earliest occurrence
+   * that is at or after this threshold.
+   * @private
+   */
+  private afterMs?: number;
+
   /**
    * Current milliseconds
    * @type {number}
@@ -271,6 +279,8 @@ class CronDate<T = undefined> {
           this.day = d.d;
           this.month = d.m - 1;
           this.year = d.y;
+          // Preserve original UTC time for DST overlap resolution
+          this.afterMs = inDate.getTime();
         } catch (e) {
           const errorMessage = e instanceof Error ? e.message : String(e);
           throw new TypeError(
@@ -304,6 +314,7 @@ class CronDate<T = undefined> {
     this.minute = d.minute;
     this.second = d.second;
     this.ms = d.ms;
+    this.afterMs = d.afterMs;
   }
 
   /**
@@ -949,8 +960,11 @@ class CronDate<T = undefined> {
    * Convert current state back to a javascript Date()
    *
    * @param internal If this is an internal call
+   * @param afterMs Optional UTC ms threshold for resolving DST overlap ambiguity
    */
-  public getDate(internal?: boolean): Date {
+  public getDate(internal?: boolean, afterMs?: number): Date {
+    // Use the instance-level afterMs as fallback if not explicitly provided
+    const resolvedAfterMs = afterMs ?? this.afterMs;
     // If this is an internal call, return the date as is
     // Also use this option when no timezone or utcOffset is set
     if (internal || this.tz === void 0) {
@@ -993,16 +1007,30 @@ class CronDate<T = undefined> {
             this.tz,
           ),
           false,
+          resolvedAfterMs,
         );
       }
     }
   }
 
   /**
    * Convert current state back to a javascript Date() and return UTC milliseconds
+   *
+   * @param afterMs Optional UTC ms threshold for resolving DST overlap ambiguity
+   */
+  public getTime(afterMs?: number): number {
+    return this.getDate(false, afterMs).getTime();
+  }
+
+  /**
+   * Set the afterMs threshold for DST overlap resolution.
+   * When set, getTime()/getDate() will return the earliest occurrence
+   * that is at or after this threshold.
+   *
+   * @param ms UTC milliseconds threshold
    */
-  public getTime(): number {
-    return this.getDate(false).getTime();
+  public setAfterMs(ms: number): void {
+    this.afterMs = ms;
   }
 
   /**

src/helpers/timezone.ts

@@ -106,8 +106,9 @@ export function fromTimezone(
   s: number,
   tz: string,
   throwOnInvalid?: boolean,
+  afterMs?: number,
 ): Date {
-  return fromTZ(createTimePoint(y, m, d, h, i, s, tz), throwOnInvalid);
+  return fromTZ(createTimePoint(y, m, d, h, i, s, tz), throwOnInvalid, afterMs);
 }
 
 /**
@@ -127,9 +128,14 @@ export function fromTZISO(localTimeStr: string, tz?: string, throwOnInvalid?: bo
  *
  * @param tp - TimePoint with specified timezone
  * @param throwOnInvalid - Default is to return the adjusted time if the call happens during a DST switch
+ * @param afterMs - Optional UTC milliseconds threshold. When provided and the local time falls
+ *                  in a DST overlap, the returned Date will be the earliest occurrence that is
+ *                  at or after this threshold (ensures monotonic progress across DST transitions).
+ *                  If both occurrences are before the threshold, the second (later) occurrence
+ *                  is returned as the closest valid option.
  * @returns Normal date object
  */
-export function fromTZ(tp: TimePoint, throwOnInvalid?: boolean): Date {
+export function fromTZ(tp: TimePoint, throwOnInvalid?: boolean, afterMs?: number): Date {
   // Construct a Date object with UTC components matching the target local time
   const inDate = new Date(timePointToMs(tp));
 
@@ -148,14 +154,31 @@ export function fromTZ(tp: TimePoint, throwOnInvalid?: boolean): Date {
   // Check if the first guess produces the target local time
   if (timePointsMatch(check1, tp)) {
     // Even if it matches, we might be in a DST overlap (fall back)
-    // Check if there's another valid time 1 hour earlier
-    const altGuess = new Date(dateGuess.getTime() - 3600000); // 1 hour earlier
-    const altCheck = toTZ(altGuess, tp.tz!);
+    // Check if there's another valid time 1 hour earlier or later
+    const altEarlier = new Date(dateGuess.getTime() - 3600000);
+    const altEarlierCheck = toTZ(altEarlier, tp.tz!);
+    const altLater = new Date(dateGuess.getTime() + 3600000);
+    const altLaterCheck = toTZ(altLater, tp.tz!);
 
-    // If the earlier time also produces the same local time, we're in a DST overlap
-    if (timePointsMatch(altCheck, tp)) {
-      // Return the earlier time (first occurrence per OCPS 1.4)
-      return altGuess;
+    // Determine if we're in a DST overlap
+    const hasEarlier = timePointsMatch(altEarlierCheck, tp);
+    const hasLater = timePointsMatch(altLaterCheck, tp);
+
+    if (hasEarlier || hasLater) {
+      // We're in a DST overlap
+      const firstOccurrence = hasEarlier ? altEarlier : dateGuess;
+      const secondOccurrence = hasEarlier ? dateGuess : altLater;
+
+      // When afterMs is provided, return the earliest occurrence that is >= afterMs
+      // This ensures monotonic progress during DST fall-back transitions
+      if (afterMs !== undefined) {
+        if (firstOccurrence.getTime() >= afterMs) {
+          return firstOccurrence;
+        }
+        return secondOccurrence;
+      }
+      // Default: return the earlier time (first occurrence per OCPS 1.4)
+      return firstOccurrence;
     }
 
     return dateGuess;

test/timezone.test.ts

@@ -301,10 +301,11 @@ test("OCPS 1.4 compliance: DST Overlap (Fall Back) - job should run once at firs
   const nov2After = nyJob.nextRun("2025-11-02T05:31:00Z"); // Just after first occurrence
   assertEquals(nov2After?.toISOString(), "2025-11-03T06:30:00.000Z"); // Next day at 1:30 AM EST
 
-  // Verify it doesn't run at the second occurrence (1:30 AM EST on Nov 2)
-  // Second occurrence would be at 2025-11-02T06:30:00.000Z
+  // Verify behavior during the second occurrence window (1:00 AM EST on Nov 2)
+  // Since we correctly track DST occurrence, nextRun from the second occurrence
+  // window returns the second occurrence of 1:30 AM (06:30:00Z), which is after the input
   const nov2Second = nyJob.nextRun("2025-11-02T06:00:00Z"); // During second occurrence window
-  assertEquals(nov2Second?.toISOString(), "2025-11-02T05:30:00.000Z"); // Still points to first
+  assertEquals(nov2Second?.toISOString(), "2025-11-02T06:30:00.000Z");
   nyJob.stop();
 });
 
@@ -388,9 +389,9 @@ test("Issue #286: Starting from DST gap should not cause rapid-fire execution",
   // First run should be 1:59 AM PDT (1 minute from start)
   assertEquals(runs[0].toISOString(), "2025-11-02T08:59:00.000Z");
 
-  // Second run should skip to 2:00 AM PST (after DST transition)
-  // This is 61 minutes from 1:59 AM PDT because the 1:00-1:59 AM hour is skipped
-  assertEquals(runs[1].toISOString(), "2025-11-02T10:00:00.000Z");
+  // Second run should be the very next UTC minute (09:00Z),
+  // which locally corresponds to 1:00 AM PST after the fall-back from PDT.
+  assertEquals(runs[1].toISOString(), "2025-11-02T09:00:00.000Z");
 
   // Subsequent runs should be 1 minute apart
   for (let i = 2; i < runs.length; i++) {
@@ -403,3 +404,94 @@ test("Issue #286: Starting from DST gap should not cause rapid-fire execution",
   }
   laJob.stop();
 });
+
+test("DST fall-back should not cause scheduling gap with per-second cron", function () {
+  // Europe/Vienna: October 26, 2025 at 3:00 AM CEST -> 2:00 AM CET
+  // A per-second cron should not have a gap at the transition
+  const job = new Cron("* * * * * *", { paused: true, timezone: "Europe/Vienna" });
+
+  // Start just before DST transition: 2:59:58 CEST = 00:59:58 UTC
+  let current: string | Date = "2025-10-26T00:59:58.000Z";
+  const runs: Date[] = [];
+
+  for (let i = 0; i < 7; i++) {
+    const next = job.nextRun(current);
+    if (next) {
+      runs.push(next);
+      current = new Date(next.getTime());
+    }
+  }
+
+  assertEquals(runs.length, 7, "Should get 7 runs");
+
+  // Every run should be exactly 1 second apart
+  for (let i = 1; i < runs.length; i++) {
+    const diff = runs[i].getTime() - runs[i - 1].getTime();
+    assertEquals(
+      diff,
+      1000,
+      `Run ${i + 1} should be 1s after run ${i}, got ${diff}ms (${runs[i - 1].toISOString()} -> ${
+        runs[i].toISOString()
+      })`,
+    );
+  }
+
+  // Verify the transition happened correctly:
+  // Run 1: 2:59:59 CEST (00:59:59 UTC)
+  assertEquals(runs[0].toISOString(), "2025-10-26T00:59:59.000Z");
+  // Run 2: 2:00:00 CET second occurrence (01:00:00 UTC) - enters the overlap period
+  assertEquals(runs[1].toISOString(), "2025-10-26T01:00:00.000Z");
+
+  job.stop();
+});
+
+test("DST fall-back should not cause scheduling gap with per-minute cron", function () {
+  // Europe/Vienna: October 26, 2025 at 3:00 AM CEST -> 2:00 AM CET
+  const job = new Cron("* * * * *", { paused: true, timezone: "Europe/Vienna" });
+
+  // Start at 2:58:00 CEST = 00:58:00 UTC
+  let current: string | Date = "2025-10-26T00:58:00.000Z";
+  const runs: Date[] = [];
+
+  for (let i = 0; i < 5; i++) {
+    const next = job.nextRun(current);
+    if (next) {
+      runs.push(next);
+      current = new Date(next.getTime());
+    }
+  }
+
+  assertEquals(runs.length, 5, "Should get 5 runs");
+
+  // All runs should be exactly 60 seconds apart
+  for (let i = 1; i < runs.length; i++) {
+    const diff = runs[i].getTime() - runs[i - 1].getTime();
+    assertEquals(
+      diff,
+      60000,
+      `Run ${i + 1} should be 60s after run ${i}, got ${diff}ms`,
+    );
+  }
+
+  // Run 1: 2:59:00 CEST (00:59:00 UTC)
+  assertEquals(runs[0].toISOString(), "2025-10-26T00:59:00.000Z");
+  // Run 2: 2:00:00 CET second occurrence (01:00:00 UTC)
+  assertEquals(runs[1].toISOString(), "2025-10-26T01:00:00.000Z");
+
+  job.stop();
+});
+
+test("DST fall-back msToNext should not return large values at transition", function () {
+  // Europe/Vienna: October 26, 2025 at 3:00 AM CEST -> 2:00 AM CET
+  const job = new Cron("* * * * * *", { paused: true, timezone: "Europe/Vienna" });
+
+  // At the exact transition point: 2:59:59 CEST = 00:59:59 UTC
+  const ms = job.msToNext(new Date("2025-10-26T00:59:59.000Z"));
+  assertEquals(ms, 1000, "msToNext should be 1000ms at DST transition");
+
+  // During the second occurrence: 2:00:30 CET = 01:00:30 UTC
+  const ms2 = job.msToNext(new Date("2025-10-26T01:00:30.000Z"));
+  assertEquals(ms2, 1000, "msToNext should be 1000ms during second occurrence");
+
+  job.stop();
+});