@forcecalendar/core 2.2.0 → 2.4.0

package/core/events/RecurrenceEngine.js

@@ -12,6 +12,11 @@ export class RecurrenceEngine {
   // Hard limit to prevent resource exhaustion regardless of caller input
   static MAX_OCCURRENCES_HARD_LIMIT = 10000;
 
+  // Hard limit on expansion loop iterations (every occurrence stepped
+  // through, inside the range or not) so a rule that cannot be seeked
+  // arithmetically still terminates in bounded time
+  static MAX_ITERATIONS_HARD_LIMIT = 100000;
+
   // expandEvent is typically called many times with the same RRULE string
   // (every view render), so parsed rules are cached by their source string
   static _ruleCache = new Map();
@@ -19,10 +24,18 @@ export class RecurrenceEngine {
 
   /**
    * Expand a recurring event into individual occurrences
+   *
+   * Occurrences before rangeStart are skipped without being generated:
+   * daily, weekly and sub-daily rules seek straight to the range, so the
+   * cost of a query does not grow with the age of the series, and a series
+   * that started years before the queried window is still expanded.
+   *
    * @param {import('./Event.js').Event} event - The recurring event
    * @param {Date} rangeStart - Start of the expansion range
    * @param {Date} rangeEnd - End of the expansion range
-   * @param {number} [maxOccurrences=365] - Maximum number of occurrences to generate
+   * @param {number} [maxOccurrences=365] - Maximum number of occurrences to return.
+   *   Only occurrences inside the range count towards this limit; occurrences
+   *   between the series start and rangeStart do not consume it.
    * @param {string} [timezone] - Timezone for expansion (important for DST)
    * @returns {import('../types.js').EventOccurrence[]} Array of occurrence objects with start/end dates
    */
@@ -34,20 +47,74 @@ export class RecurrenceEngine {
     }
 
     const rule = this._getParsedRule(event.recurrenceRule);
-    const occurrences = [];
     const duration = event.end - event.start;
     const eventTimezone = timezone || event.timeZone || 'UTC';
     const tzManager = TimezoneManager.getInstance();
 
-    // Work in event's timezone for accurate recurrence calculation
-    const currentDate = new Date(event.start);
-    let count = 0;
-
     // If UNTIL is specified, use it as the range end
     if (rule.until && rule.until < rangeEnd) {
       rangeEnd = rule.until;
     }
 
+    // DAILY and WEEKLY series iterate on numeric timestamps (no Date
+    // arithmetic per step); other frequencies use the general loop
+    let occurrences = null;
+    if (rule.freq === 'DAILY' || rule.freq === 'WEEKLY') {
+      occurrences = this._expandFast(
+        event,
+        rule,
+        rangeStart.getTime(),
+        rangeEnd.getTime(),
+        maxOccurrences,
+        eventTimezone,
+        tzManager,
+        duration
+      );
+    }
+    if (!occurrences) {
+      occurrences = this._expandGeneral(
+        event,
+        rule,
+        rangeStart.getTime(),
+        rangeEnd.getTime(),
+        maxOccurrences,
+        eventTimezone,
+        tzManager,
+        duration
+      );
+    }
+
+    // Apply BYSETPOS filtering if present and not already handled by MONTHLY+byDay
+    if (rule.bySetPos && rule.bySetPos.length > 0 && rule.freq !== 'MONTHLY') {
+      return this._applyBySetPos(occurrences, rule);
+    }
+
+    return occurrences;
+  }
+
+  /**
+   * General expansion loop: advances a Date cursor per step. Handles every
+   * frequency and degenerate rules (non-advancing dates, invalid intervals).
+   * @private
+   */
+  static _expandGeneral(
+    event,
+    rule,
+    rangeStartMs,
+    rangeEndMs,
+    maxOccurrences,
+    eventTimezone,
+    tzManager,
+    duration
+  ) {
+    const occurrences = [];
+
+    // Work in event's timezone for accurate recurrence calculation
+    const currentDate = new Date(event.start);
+    // Steps taken from DTSTART: RFC 5545 COUNT is measured from there,
+    // independent of how many occurrences fall inside the range
+    let count = 0;
+
     // Track DST transitions for proper timezone handling
     let lastOffset = tzManager.getTimezoneOffset(currentDate, eventTimezone);
 
@@ -57,12 +124,34 @@ export class RecurrenceEngine {
 
     // Compare on numeric timestamps in the loop — Date-object comparisons
     // re-coerce through valueOf on every check
-    const rangeStartMs = rangeStart.getTime();
-    const rangeEndMs = rangeEnd.getTime();
     const hasExceptions = !!(rule.exceptions && rule.exceptions.length > 0);
     let currentMs = currentDate.getTime();
 
-    while (currentMs <= rangeEndMs && count < maxOccurrences) {
+    // Sub-daily rules step a fixed number of milliseconds, so the span
+    // before the range is skipped arithmetically instead of one step at a
+    // time; other frequencies take few enough steps per year to just walk
+    const stepMs = this._fixedStepMs(rule);
+    if (stepMs > 0 && currentMs < rangeStartMs) {
+      const seek = this._seekFixedStep(
+        currentMs,
+        rangeStartMs,
+        rangeEndMs,
+        stepMs,
+        rule.count ? rule.count - 1 : Infinity,
+        cursor => this._advanceInPlace(cursor, rule)
+      );
+      currentMs = seek.ms;
+      count = seek.steps;
+      currentDate.setTime(currentMs);
+    }
+
+    let iterations = 0;
+    while (
+      currentMs <= rangeEndMs &&
+      occurrences.length < maxOccurrences &&
+      iterations < RecurrenceEngine.MAX_ITERATIONS_HARD_LIMIT
+    ) {
+      iterations++;
       // Check if this occurrence is within the range
       if (currentMs >= rangeStartMs) {
         const occurrenceStart = new Date(currentMs);
@@ -113,14 +202,355 @@ export class RecurrenceEngine {
       }
     }
 
-    // Apply BYSETPOS filtering if present and not already handled by MONTHLY+byDay
-    if (rule.bySetPos && rule.bySetPos.length > 0 && rule.freq !== 'MONTHLY') {
-      return this._applyBySetPos(occurrences, rule);
+    return occurrences;
+  }
+
+  /**
+   * Numeric expansion loop for DAILY and WEEKLY rules.
+   *
+   * Between DST transitions a wall-clock-preserving day step is a constant
+   * number of milliseconds, so the loop is pure numeric addition. Transition
+   * instants — in the system timezone (which defines Date arithmetic) and in
+   * the event's timezone (which drives occurrence adjustment) — are
+   * discovered by binary search and cached, so only the one step that
+   * crosses a transition falls back to Date arithmetic, and only the first
+   * occurrence after a transition queries a timezone offset.
+   *
+   * Produces output identical to _expandGeneral for the rules it accepts;
+   * returns null to delegate anything it cannot handle exactly.
+   * @private
+   */
+  static _expandFast(
+    event,
+    rule,
+    rangeStartMs,
+    rangeEndMs,
+    maxOccurrences,
+    eventTimezone,
+    tzManager,
+    duration
+  ) {
+    const DAY = 86400000;
+    let dayDeltas = null;
+    let stepDays = 0;
+    let weekday = 0;
+
+    const startDate = new Date(event.start);
+    if (rule.freq === 'WEEKLY' && rule.byDay && rule.byDay.length > 0) {
+      const daySet = rule._byDaySet || (rule._byDaySet = this._buildByDaySet(rule.byDay));
+      if (daySet.size === 0) {
+        return null; // invalid byDay — general loop handles the fallback warning
+      }
+      dayDeltas = rule._byDayDeltas || (rule._byDayDeltas = this._buildByDayDeltas(daySet));
+      weekday = startDate.getDay();
+    } else {
+      stepDays = (rule.freq === 'DAILY' ? 1 : 7) * rule.interval;
+      if (!Number.isInteger(stepDays) || stepDays <= 0) {
+        return null; // degenerate interval — general loop's stuck detection applies
+      }
+    }
+
+    const occurrences = [];
+    let currentMs = startDate.getTime();
+    if (Number.isNaN(currentMs)) {
+      return null;
+    }
+    let count = 0;
+    const hasExceptions = !!(rule.exceptions && rule.exceptions.length > 0);
+
+    let lastOffset = tzManager.getTimezoneOffset(startDate, eventTimezone);
+    let nextEventTzTransition = tzManager.getNextTransition(eventTimezone, currentMs, rangeEndMs);
+    let nextSystemTransition = this._nextSystemTransition(currentMs, rangeEndMs);
+
+    // Seek to the last occurrence before the range. nextEventTzTransition is
+    // deliberately left as computed from DTSTART: if the seek passed an
+    // event-timezone transition, the first in-range occurrence must still
+    // compare its offset with lastOffset, exactly as the general loop does.
+    if (currentMs < rangeStartMs) {
+      const maxSteps = rule.count ? rule.count - 1 : Infinity;
+      const seek = dayDeltas
+        ? this._seekWeekCycle(currentMs, weekday, rangeStartMs, rangeEndMs, rule, maxSteps)
+        : this._seekFixedStep(
+            currentMs,
+            rangeStartMs,
+            rangeEndMs,
+            stepDays * DAY,
+            maxSteps,
+            cursor => cursor.setDate(cursor.getDate() + stepDays)
+          );
+      currentMs = seek.ms;
+      count = seek.steps;
+      nextSystemTransition = seek.nextSystemTransition;
+      if (dayDeltas) {
+        weekday = seek.weekday;
+      }
+    }
+
+    let iterations = 0;
+    while (
+      currentMs <= rangeEndMs &&
+      occurrences.length < maxOccurrences &&
+      iterations < RecurrenceEngine.MAX_ITERATIONS_HARD_LIMIT
+    ) {
+      iterations++;
+      if (currentMs >= rangeStartMs) {
+        const occurrenceStart = new Date(currentMs);
+        const occurrenceEnd = new Date(currentMs + duration);
+
+        // Only the first occurrence past a transition needs an offset check
+        if (currentMs >= nextEventTzTransition) {
+          const currentOffset = tzManager.getTimezoneOffset(occurrenceStart, eventTimezone);
+          if (currentOffset !== lastOffset) {
+            const offsetDiff = lastOffset - currentOffset;
+            occurrenceStart.setMinutes(occurrenceStart.getMinutes() + offsetDiff);
+            occurrenceEnd.setMinutes(occurrenceEnd.getMinutes() + offsetDiff);
+            lastOffset = currentOffset;
+          }
+          nextEventTzTransition = tzManager.getNextTransition(eventTimezone, currentMs, rangeEndMs);
+        }
+
+        if (!hasExceptions || !this.isException(occurrenceStart, rule, event.id)) {
+          occurrences.push({
+            start: occurrenceStart,
+            end: occurrenceEnd,
+            recurringEventId: event.id,
+            timezone: eventTimezone,
+            originalStart: event.start
+          });
+        }
+      }
+
+      // Advance: pure addition unless the step crosses a system-timezone
+      // transition, where Date arithmetic reproduces wall-clock semantics
+      const days = dayDeltas ? dayDeltas[weekday] : stepDays;
+      if (dayDeltas) {
+        weekday = (weekday + days) % 7;
+      }
+      const naiveMs = currentMs + days * DAY;
+      if (naiveMs >= nextSystemTransition) {
+        const cursor = new Date(currentMs);
+        cursor.setDate(cursor.getDate() + days);
+        currentMs = cursor.getTime();
+        nextSystemTransition = this._nextSystemTransition(currentMs, rangeEndMs);
+      } else {
+        currentMs = naiveMs;
+      }
+      count++;
+
+      if (rule.count && count >= rule.count) {
+        break;
+      }
     }
 
     return occurrences;
   }
 
+  /**
+   * Milliseconds per step for rules whose step is a fixed duration while
+   * the system UTC offset is constant. Only the sub-daily frequencies are
+   * reported here: DAILY and WEEKLY have their own numeric loop, and the
+   * calendar-based frequencies take too few steps per year to need seeking.
+   * @param {Object} rule - Parsed recurrence rule
+   * @returns {number} Step length in milliseconds, or 0 when not fixed
+   * @private
+   */
+  static _fixedStepMs(rule) {
+    const interval = rule.interval;
+    if (!Number.isInteger(interval) || interval <= 0) {
+      return 0;
+    }
+    switch (rule.freq) {
+      case 'SECONDLY':
+        return interval * 1000;
+      case 'MINUTELY':
+        return interval * 60000;
+      case 'HOURLY':
+        return interval * 3600000;
+      default:
+        return 0;
+    }
+  }
+
+  /**
+   * Skip the occurrences of a fixed-step rule that fall before
+   * rangeStartMs without visiting each one.
+   *
+   * While the system UTC offset is constant, a wall-clock step of the
+   * cursor is a constant number of milliseconds, so a whole run of steps
+   * collapses into one multiplication. The single step that crosses a
+   * system-timezone transition is taken with `advance` instead, so the
+   * cursor ends up exactly where stepping every occurrence would have put
+   * it. Stops at the last occurrence before rangeStartMs; the caller's loop
+   * takes the step into the range.
+   *
+   * @param {number} fromMs - Cursor position (an occurrence instant)
+   * @param {number} rangeStartMs - Seek target
+   * @param {number} rangeEndMs - Upper bound for transition lookup
+   * @param {number} stepMs - Step length while the UTC offset is constant
+   * @param {number} maxSteps - Steps still permitted under COUNT (Infinity if unbounded)
+   * @param {(cursor: Date) => void} advance - Wall-clock step, mutating the cursor
+   * @returns {{ ms: number, steps: number, nextSystemTransition: number }}
+   *   Cursor position, steps taken and the next system transition after it
+   * @private
+   */
+  static _seekFixedStep(fromMs, rangeStartMs, rangeEndMs, stepMs, maxSteps, advance) {
+    let ms = fromMs;
+    let steps = 0;
+    let nextSystemTransition = this._nextSystemTransition(ms, rangeEndMs);
+    if (!Number.isFinite(rangeStartMs) || !(stepMs > 0)) {
+      return { ms, steps, nextSystemTransition };
+    }
+    // Comparisons are written so an invalid (NaN) cursor ends the seek
+    while (ms < rangeStartMs && steps < maxSteps) {
+      const limit = Math.min(rangeStartMs, nextSystemTransition);
+      // Largest k with ms + k * stepMs < limit
+      let k = Math.ceil((limit - ms) / stepMs) - 1;
+      if (ms + k * stepMs >= limit) {
+        k--; // division rounded up
+      }
+      k = Math.min(k, maxSteps - steps);
+      if (k > 0) {
+        ms += k * stepMs;
+        steps += k;
+        continue;
+      }
+      if (ms + stepMs >= rangeStartMs) {
+        break; // next step lands in the range
+      }
+      // Next step crosses a system-timezone transition
+      const cursor = new Date(ms);
+      advance(cursor);
+      ms = cursor.getTime();
+      steps++;
+      nextSystemTransition = this._nextSystemTransition(ms, rangeEndMs);
+    }
+    return { ms, steps, nextSystemTransition };
+  }
+
+  /**
+   * Seek for WEEKLY BYDAY rules, whose step pattern repeats every week:
+   * whole weeks are skipped arithmetically from any weekday in the BYDAY
+   * set, and single steps (identical to the expansion loop's) are only
+   * taken to reach the set, around system-timezone transitions and in the
+   * last week before the range.
+   *
+   * @param {number} fromMs - Cursor position (an occurrence instant)
+   * @param {number} weekday - Weekday of the cursor (Date#getDay)
+   * @param {number} rangeStartMs - Seek target
+   * @param {number} rangeEndMs - Upper bound for transition lookup
+   * @param {Object} rule - Parsed rule with compiled _byDaySet/_byDayDeltas
+   * @param {number} maxSteps - Steps still permitted under COUNT (Infinity if unbounded)
+   * @returns {{ ms: number, steps: number, weekday: number, nextSystemTransition: number }}
+   * @private
+   */
+  static _seekWeekCycle(fromMs, weekday, rangeStartMs, rangeEndMs, rule, maxSteps) {
+    const DAY = 86400000;
+    const WEEK = 7 * DAY;
+    const daySet = rule._byDaySet;
+    const dayDeltas = rule._byDayDeltas;
+    const stepsPerWeek = daySet.size;
+    let ms = fromMs;
+    let steps = 0;
+    let nextSystemTransition = this._nextSystemTransition(ms, rangeEndMs);
+    if (!Number.isFinite(rangeStartMs)) {
+      return { ms, steps, weekday, nextSystemTransition };
+    }
+    while (ms < rangeStartMs && steps < maxSteps) {
+      // A week from a weekday in the set is exactly stepsPerWeek steps and
+      // returns to the same weekday
+      if (daySet.has(weekday)) {
+        const limit = Math.min(rangeStartMs, nextSystemTransition);
+        let weeks = Math.ceil((limit - ms) / WEEK) - 1;
+        if (ms + weeks * WEEK >= limit) {
+          weeks--;
+        }
+        weeks = Math.min(weeks, Math.floor((maxSteps - steps) / stepsPerWeek));
+        if (weeks > 0) {
+          ms += weeks * WEEK;
+          steps += weeks * stepsPerWeek;
+          continue;
+        }
+      }
+      // Single step, identical to the expansion loop
+      const days = dayDeltas[weekday];
+      const naiveMs = ms + days * DAY;
+      if (naiveMs >= rangeStartMs) {
+        break; // next step lands in the range
+      }
+      weekday = (weekday + days) % 7;
+      if (naiveMs >= nextSystemTransition) {
+        const cursor = new Date(ms);
+        cursor.setDate(cursor.getDate() + days);
+        ms = cursor.getTime();
+        nextSystemTransition = this._nextSystemTransition(ms, rangeEndMs);
+      } else {
+        ms = naiveMs;
+      }
+      steps++;
+    }
+    return { ms, steps, weekday, nextSystemTransition };
+  }
+
+  /**
+   * Find the next system-timezone offset transition after fromMs.
+   * Cached module-wide: the system timezone is fixed for the process.
+   * @param {number} fromMs - Search from this timestamp (exclusive)
+   * @param {number} toMs - Extend cache coverage at least this far
+   * @returns {number} Transition timestamp, or Infinity if none within coverage
+   * @private
+   */
+  static _nextSystemTransition(fromMs, toMs) {
+    if (fromMs >= toMs) {
+      return Infinity;
+    }
+    let cache = this._systemTransitions;
+    if (!cache || fromMs < cache.from || toMs > cache.to) {
+      const from = Math.min(fromMs, cache ? cache.from : fromMs);
+      const to = Math.max(toMs, cache ? cache.to : toMs);
+      cache = { from, to, transitions: this._scanSystemTransitions(from, to) };
+      this._systemTransitions = cache;
+    }
+    for (const t of cache.transitions) {
+      if (t > fromMs) {
+        return t;
+      }
+    }
+    return Infinity;
+  }
+
+  /**
+   * Scan for system-timezone offset transitions via Date#getTimezoneOffset.
+   * Probes weekly (shorter than any real-world gap between transitions)
+   * and binary-searches each change to the exact millisecond.
+   * @private
+   */
+  static _scanSystemTransitions(fromMs, toMs) {
+    const WEEK = 7 * 86400000;
+    const transitions = [];
+    let lo = fromMs;
+    let loOffset = new Date(lo).getTimezoneOffset();
+    while (lo < toMs) {
+      const hi = Math.min(lo + WEEK, toMs);
+      const hiOffset = new Date(hi).getTimezoneOffset();
+      if (hiOffset !== loOffset) {
+        let a = lo;
+        let b = hi;
+        while (b - a > 1) {
+          const mid = Math.floor((a + b) / 2);
+          if (new Date(mid).getTimezoneOffset() === loOffset) {
+            a = mid;
+          } else {
+            b = mid;
+          }
+        }
+        transitions.push(b);
+        loOffset = hiOffset;
+      }
+      lo = hi;
+    }
+    return transitions;
+  }
+
   /**
    * Apply BYSETPOS to filter occurrences within each frequency period
    * @param {Array} occurrences - Generated occurrences

package/core/events/RecurrenceEngineV2.js

@@ -4,12 +4,20 @@
  */
 
 import { TimezoneManager } from '../timezone/TimezoneManager.js';
+import { RecurrenceEngine } from './RecurrenceEngine.js';
 import { RRuleParser } from './RRuleParser.js';
 
+const DAY = 86400000;
+
 export class RecurrenceEngineV2 {
   // Hard limit to prevent resource exhaustion regardless of caller input
   static MAX_OCCURRENCES_HARD_LIMIT = 10000;
 
+  // Hard limit on expansion loop iterations (every occurrence stepped
+  // through, inside the range or not) so a rule that cannot be seeked
+  // arithmetically still terminates in bounded time
+  static MAX_ITERATIONS_HARD_LIMIT = 100000;
+
   constructor() {
     // Use singleton to share cache across all components
     this.tzManager = TimezoneManager.getInstance();
@@ -27,10 +35,22 @@ export class RecurrenceEngineV2 {
 
   /**
    * Expand recurring event with advanced handling
-   * @param {Event} event - Recurring event
+   *
+   * Occurrences before rangeStart are skipped without being generated:
+   * daily, weekly, hourly and minutely rules seek straight to the range, so
+   * a series that started years before the queried window is expanded at
+   * the same cost as one that started yesterday.
+   *
+   * @param {import('./Event.js').Event} event - Recurring event
    * @param {Date} rangeStart - Start of expansion range
    * @param {Date} rangeEnd - End of expansion range
    * @param {Object} options - Expansion options
+   * @param {number} [options.maxOccurrences=365] - Maximum number of occurrences to
+   *   return. Only occurrences inside the range count towards this limit.
+   * @param {boolean} [options.includeModified=true] - Apply stored instance modifications
+   * @param {boolean} [options.includeCancelled=false] - Return exception dates as cancelled occurrences
+   * @param {string} [options.timezone] - Timezone for expansion (defaults to the event's)
+   * @param {boolean} [options.handleDST=true] - Adjust occurrences across DST transitions
    * @returns {Array} Expanded occurrences
    */
   expandEvent(event, rangeStart, rangeEnd, options = {}) {
@@ -59,7 +79,8 @@ export class RecurrenceEngineV2 {
     const occurrences = [];
     const duration = event.end - event.start;
 
-    // Initialize expansion state
+    // Initialize expansion state. `count` is the number of steps taken from
+    // DTSTART, which is what RFC 5545 COUNT measures.
     const state = {
       currentDate: new Date(event.start),
       count: 0,
@@ -73,8 +94,16 @@ export class RecurrenceEngineV2 {
       state.dstTransitions = this.findDSTTransitions(rangeStart, rangeEnd, timezone);
     }
 
+    this.seekToRange(state, rule, rangeStart, rangeEnd, timezone);
+
     // Expand occurrences
-    while (state.currentDate <= rangeEnd && state.count < maxOccurrences) {
+    let iterations = 0;
+    while (
+      state.currentDate <= rangeEnd &&
+      occurrences.length < maxOccurrences &&
+      iterations < RecurrenceEngineV2.MAX_ITERATIONS_HARD_LIMIT
+    ) {
+      iterations++;
       if (state.currentDate >= rangeStart) {
         const occurrence = this.generateOccurrence(
           event,
@@ -144,6 +173,77 @@ export class RecurrenceEngineV2 {
     return this.cloneOccurrences(occurrences);
   }
 
+  /**
+   * Move the expansion cursor to the last occurrence before the range
+   * without stepping through every occurrence in between.
+   *
+   * Applies to rules whose step is a fixed duration between system-timezone
+   * transitions (plain DAILY and WEEKLY, HOURLY, MINUTELY); the step that
+   * crosses a transition is taken with getNextDate so the result is exactly
+   * what stepping from DTSTART would produce. Never seeks past UNTIL, and
+   * counts skipped steps against COUNT.
+   *
+   * @param {Object} state - Expansion state (currentDate and count are updated)
+   * @param {Object} rule - Parsed recurrence rule
+   * @param {Date} rangeStart - Start of expansion range
+   * @param {Date} rangeEnd - End of expansion range
+   * @param {string} timezone - Expansion timezone
+   */
+  seekToRange(state, rule, rangeStart, rangeEnd, timezone) {
+    const stepMs = this.getFixedStepMs(rule);
+    if (stepMs <= 0) {
+      return;
+    }
+    let targetMs = rangeStart.getTime();
+    if (rule.until) {
+      // Rule objects may carry UNTIL as a string; an unparseable value
+      // compares false and leaves the target alone
+      const untilMs = new Date(rule.until).getTime();
+      if (untilMs < targetMs) {
+        targetMs = untilMs;
+      }
+    }
+    const fromMs = state.currentDate.getTime();
+    if (!(fromMs < targetMs)) {
+      return;
+    }
+    const seek = RecurrenceEngine._seekFixedStep(
+      fromMs,
+      targetMs,
+      rangeEnd.getTime(),
+      stepMs,
+      rule.count ? rule.count - 1 : Infinity,
+      cursor => cursor.setTime(this.getNextDate(cursor, rule, timezone, state).getTime())
+    );
+    state.currentDate = new Date(seek.ms);
+    state.count = seek.steps;
+  }
+
+  /**
+   * Milliseconds per step for rules getNextDate advances by a fixed
+   * duration while the system UTC offset is constant
+   * @param {Object} rule - Parsed recurrence rule
+   * @returns {number} Step length in milliseconds, or 0 when not fixed
+   */
+  getFixedStepMs(rule) {
+    const interval = rule.interval;
+    if (!Number.isInteger(interval) || interval <= 0) {
+      return 0;
+    }
+    switch (rule.freq) {
+      case 'DAILY':
+        return rule.byHour && rule.byHour.length > 0 ? 0 : interval * DAY;
+      case 'WEEKLY':
+        return rule.byDay && rule.byDay.length > 0 ? 0 : 7 * interval * DAY;
+      case 'HOURLY':
+        return interval * 3600000;
+      case 'MINUTELY':
+        return interval * 60000;
+      default:
+        return 0;
+    }
+  }
+
   /**
    * Generate a single occurrence with timezone handling
    */

package/core/index.js

@@ -32,7 +32,7 @@ export { ConflictDetector } from './conflicts/ConflictDetector.js';
 export { EnhancedCalendar } from './integration/EnhancedCalendar.js';
 
 // Version — keep in sync with package.json
-export const VERSION = '2.2.0';
+export const VERSION = '2.4.0';
 
 // Default export
 export { Calendar as default } from './calendar/Calendar.js';