@forcecalendar/core 2.4.0 → 2.5.1

package/core/events/RecurrenceEngineV2.js

@@ -9,6 +9,24 @@ import { RRuleParser } from './RRuleParser.js';
 
 const DAY = 86400000;
 
+// How far ahead of the iteration cursor DST transitions are scanned at a time
+const DST_SCAN_CHUNK = 100 * DAY;
+
+const WEEKDAYS = { SU: 0, MO: 1, TU: 2, WE: 3, TH: 4, FR: 5, SA: 6 };
+
+// An expansion cut short by MAX_ITERATIONS_HARD_LIMIT is reported once per
+// process rather than on every render
+let iterationLimitWarned = false;
+function warnIterationLimit(eventId) {
+  if (iterationLimitWarned) {
+    return;
+  }
+  iterationLimitWarned = true;
+  console.warn(
+    `RecurrenceEngineV2: expansion of event ${eventId} stopped after ${RecurrenceEngineV2.MAX_ITERATIONS_HARD_LIMIT} steps without reaching the end of the range; results are truncated`
+  );
+}
+
 export class RecurrenceEngineV2 {
   // Hard limit to prevent resource exhaustion regardless of caller input
   static MAX_OCCURRENCES_HARD_LIMIT = 10000;
@@ -36,10 +54,15 @@ export class RecurrenceEngineV2 {
   /**
    * Expand recurring event with advanced handling
    *
-   * 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.
+   * Occurrences before rangeStart are skipped without being generated for
+   * the rules seekToRange can seek: DAILY (without BYHOUR), WEEKLY (with or
+   * without BYDAY), HOURLY and MINUTELY. Such a series that started years
+   * before the queried window is expanded at the same cost as one that
+   * started yesterday. MONTHLY and YEARLY rules, and DAILY with BYHOUR,
+   * are stepped from DTSTART; they take few enough steps per year that
+   * this is cheap, but an expansion that would need more than
+   * MAX_ITERATIONS_HARD_LIMIT steps is truncated (with one console.warn
+   * per process).
    *
    * @param {import('./Event.js').Event} event - Recurring event
    * @param {Date} rangeStart - Start of expansion range
@@ -51,7 +74,7 @@ export class RecurrenceEngineV2 {
    * @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
+   * @returns {import('../types.js').ExpandedOccurrence[]} Expanded occurrences
    */
   expandEvent(event, rangeStart, rangeEnd, options = {}) {
     const {
@@ -66,7 +89,7 @@ export class RecurrenceEngineV2 {
     const maxOccurrences = Math.min(requestedMax, RecurrenceEngineV2.MAX_OCCURRENCES_HARD_LIMIT);
 
     // Check cache
-    const cacheKey = this.getCacheKey(event.id, rangeStart, rangeEnd, options);
+    const cacheKey = this.getCacheKey(event, rangeStart, rangeEnd, options);
     if (this.occurrenceCache.has(cacheKey)) {
       return this.cloneOccurrences(this.occurrenceCache.get(cacheKey));
     }
@@ -105,40 +128,15 @@ export class RecurrenceEngineV2 {
     ) {
       iterations++;
       if (state.currentDate >= rangeStart) {
-        const occurrence = this.generateOccurrence(
+        const occurrence = this._applyOverrides(
           event,
-          state.currentDate,
-          duration,
-          timezone,
-          state
+          this.generateOccurrence(event, state.currentDate, duration, timezone, state),
+          rule,
+          includeCancelled,
+          includeModified
         );
-
-        // Check exceptions and modifications
         if (occurrence) {
-          let shouldInclude = true;
-
-          // Skip if exception
-          if (this.isException(event.id, occurrence.start, rule)) {
-            if (!includeCancelled) {
-              shouldInclude = false;
-            } else {
-              occurrence.status = 'cancelled';
-              occurrence.cancellationReason = this.getExceptionReason(event.id, occurrence.start);
-            }
-          }
-
-          // Apply modifications if any
-          if (shouldInclude && includeModified) {
-            const modified = this.getModifiedInstance(event.id, occurrence.start);
-            if (modified) {
-              Object.assign(occurrence, modified);
-              occurrence.isModified = true;
-            }
-          }
-
-          if (shouldInclude) {
-            occurrences.push(occurrence);
-          }
+          occurrences.push(occurrence);
         }
       }
 
@@ -167,19 +165,265 @@ export class RecurrenceEngineV2 {
       }
     }
 
+    if (
+      iterations >= RecurrenceEngineV2.MAX_ITERATIONS_HARD_LIMIT &&
+      state.currentDate <= rangeEnd &&
+      occurrences.length < maxOccurrences
+    ) {
+      warnIterationLimit(event.id);
+    }
+
     // Cache results
     this.cacheOccurrences(cacheKey, occurrences);
 
     return this.cloneOccurrences(occurrences);
   }
 
+  /**
+   * Lazily iterate the occurrences of an event in chronological order.
+   *
+   * Yields what expandEvent returns for the window, one occurrence at a
+   * time and without the expansion cache: stored instance modifications
+   * and exceptions are applied as each occurrence is produced, so changes
+   * made through addModifiedInstance or addException are visible on the
+   * next pull. Rules seekToRange can seek (daily, weekly, hourly,
+   * minutely) jump straight to `after`, and DST transitions are scanned
+   * lazily ahead of the cursor instead of for the whole window up front.
+   *
+   * Both bounds are exclusive unless `inclusive` is set: an occurrence that
+   * starts exactly at `after` or `before` is skipped by default, so
+   * iterating from a known occurrence's start continues the series without
+   * repeating it; with `inclusive: true` the window is closed on both ends
+   * like expandEvent's range. A non-recurring event yields its single
+   * occurrence when it falls inside the window. Iteration ends at COUNT or
+   * UNTIL, at `before`, or — as a guard for rules that produce no
+   * occurrences — after MAX_ITERATIONS_HARD_LIMIT consecutive steps
+   * without one. The generator is single-use; call again for a fresh one.
+   *
+   * @example
+   * const engine = new RecurrenceEngineV2();
+   * for (const occurrence of engine.iterateOccurrences(event, { after: new Date() })) {
+   *   if (occurrence.start > deadline) break;
+   *   schedule(occurrence);
+   * }
+   *
+   * @param {import('./Event.js').Event} event - The event to iterate
+   * @param {import('../types.js').ExpandedOccurrenceIteratorOptions} [options={}] - Window and expansion options
+   * @returns {Generator<import('../types.js').ExpandedOccurrence, void, undefined>} Occurrences in chronological order
+   * @throws {TypeError} If `after` or `before` is not a valid Date or timestamp
+   */
+  iterateOccurrences(event, options = {}) {
+    const window = RecurrenceEngine._occurrenceWindow(options);
+    if (!event.recurring || !event.recurrenceRule) {
+      return this._iterateSingle(event, window);
+    }
+    const {
+      includeModified = true,
+      includeCancelled = false,
+      timezone = event.timeZone || 'UTC',
+      handleDST = true
+    } = options;
+    return this._iterateRule(event, RRuleParser.parse(event.recurrenceRule), window, {
+      includeModified,
+      includeCancelled,
+      timezone,
+      handleDST
+    });
+  }
+
+  /**
+   * First occurrence of an event after an instant, or null when the series
+   * has no occurrence after it. `after` is exclusive unless
+   * `options.inclusive` is set, so passing the start of a known occurrence
+   * returns the one that follows it.
+   *
+   * @example
+   * const upcoming = engine.nextOccurrence(event, new Date());
+   *
+   * @param {import('./Event.js').Event} event - The event to query
+   * @param {Date|number} [after=null] - Instant to search from (defaults to the series start)
+   * @param {import('../types.js').ExpandedOccurrenceIteratorOptions} [options={}] - Further options
+   * @returns {import('../types.js').ExpandedOccurrence|null} The next occurrence, or null
+   */
+  nextOccurrence(event, after = null, options = {}) {
+    for (const occurrence of this.iterateOccurrences(event, { ...options, after })) {
+      return occurrence;
+    }
+    return null;
+  }
+
+  /**
+   * The first `count` occurrences of an event inside a window, generated
+   * lazily so an open-ended series costs only the occurrences taken.
+   * `count` is capped at MAX_OCCURRENCES_HARD_LIMIT; fewer are returned
+   * when the series or the window ends first.
+   *
+   * @example
+   * const nextFive = engine.takeOccurrences(event, 5, { after: new Date() });
+   *
+   * @param {import('./Event.js').Event} event - The event to query
+   * @param {number} count - Maximum number of occurrences to return (fractions are floored)
+   * @param {import('../types.js').ExpandedOccurrenceIteratorOptions} [options={}] - Window and expansion options
+   * @returns {import('../types.js').ExpandedOccurrence[]} Up to `count` occurrences in chronological order
+   */
+  takeOccurrences(event, count, options = {}) {
+    const limit = Math.floor(Math.min(count, RecurrenceEngineV2.MAX_OCCURRENCES_HARD_LIMIT));
+    const taken = [];
+    if (!(limit > 0)) {
+      return taken;
+    }
+    for (const occurrence of this.iterateOccurrences(event, options)) {
+      taken.push(occurrence);
+      if (taken.length >= limit) {
+        break;
+      }
+    }
+    return taken;
+  }
+
+  /**
+   * Yield a non-recurring event's single occurrence if it starts inside
+   * the window
+   * @param {import('./Event.js').Event} event - The event
+   * @param {{ startMs: number, endMs: number }} window - Inclusive bounds
+   * @returns {Generator<import('../types.js').ExpandedOccurrence, void, undefined>}
+   * @private
+   */
+  *_iterateSingle(event, window) {
+    const ms = new Date(event.start).getTime();
+    if (ms >= window.startMs && ms <= window.endMs) {
+      yield this.cloneOccurrence(this.createOccurrence(event, event.start, event.end));
+    }
+  }
+
+  /**
+   * Lazy counterpart of the expandEvent loop: seeks to the window, then
+   * steps the cursor and yields each in-window occurrence with the same
+   * DST adjustment, exception handling and instance modifications.
+   * @private
+   */
+  *_iterateRule(event, rule, window, options) {
+    const { includeModified, includeCancelled, timezone, handleDST } = options;
+    const duration = event.end - event.start;
+    const state = {
+      currentDate: new Date(event.start),
+      count: 0,
+      tzOffsets: new Map(),
+      dstTransitions: [],
+      stuckIterations: 0
+    };
+    if (Number.isNaN(state.currentDate.getTime()) || window.startMs > window.endMs) {
+      return;
+    }
+
+    // DST transitions are found on the same day grid expandEvent walks,
+    // starting from the window start (DTSTART for an open window) and
+    // extended in chunks ahead of the cursor
+    let dstScan = null;
+    if (handleDST) {
+      const scanStart = Number.isFinite(window.startMs)
+        ? window.startMs
+        : state.currentDate.getTime();
+      dstScan = { cursor: new Date(scanStart), lastOffset: 0 };
+      dstScan.lastOffset = this.tzManager.getTimezoneOffset(dstScan.cursor, timezone);
+    }
+
+    if (Number.isFinite(window.startMs)) {
+      const rangeStart = new Date(window.startMs);
+      this.seekToRange(state, rule, rangeStart, rangeStart, timezone);
+    }
+
+    let idleSteps = 0;
+    while (state.currentDate.getTime() <= window.endMs) {
+      const currentMs = state.currentDate.getTime();
+      if (currentMs >= window.startMs) {
+        if (dstScan) {
+          this._scanDSTTransitions(
+            dstScan,
+            state.dstTransitions,
+            Math.min(currentMs + DST_SCAN_CHUNK, window.endMs),
+            timezone
+          );
+        }
+        const occurrence = this._applyOverrides(
+          event,
+          this.generateOccurrence(event, state.currentDate, duration, timezone, state),
+          rule,
+          includeCancelled,
+          includeModified
+        );
+        if (occurrence) {
+          idleSteps = 0;
+          yield this.cloneOccurrence(occurrence);
+        }
+      }
+
+      state.currentDate = this.getNextDate(state.currentDate, rule, timezone, state);
+      state.count++;
+
+      if (state.currentDate.getTime() <= currentMs) {
+        state.stuckIterations++;
+        if (state.stuckIterations >= 3) {
+          return;
+        }
+      } else {
+        state.stuckIterations = 0;
+      }
+
+      if (rule.count && state.count >= rule.count) {
+        return;
+      }
+      if (rule.until && state.currentDate > rule.until) {
+        return;
+      }
+      idleSteps++;
+      if (idleSteps >= RecurrenceEngineV2.MAX_ITERATIONS_HARD_LIMIT) {
+        warnIterationLimit(event.id);
+        return;
+      }
+    }
+  }
+
+  /**
+   * Apply exceptions and stored instance modifications to a generated
+   * occurrence
+   * @param {import('./Event.js').Event} event - The recurring event
+   * @param {Object} occurrence - Occurrence from generateOccurrence
+   * @param {Object} rule - Parsed recurrence rule
+   * @param {boolean} includeCancelled - Return exception dates as cancelled occurrences
+   * @param {boolean} includeModified - Apply stored instance modifications
+   * @returns {Object|null} The occurrence, or null when it is excluded
+   * @private
+   */
+  _applyOverrides(event, occurrence, rule, includeCancelled, includeModified) {
+    if (!occurrence) {
+      return null;
+    }
+    if (this.isException(event.id, occurrence.start, rule)) {
+      if (!includeCancelled) {
+        return null;
+      }
+      occurrence.status = 'cancelled';
+      occurrence.cancellationReason = this.getExceptionReason(event.id, occurrence.start);
+    }
+    if (includeModified) {
+      const modified = this.getModifiedInstance(event.id, occurrence.start);
+      if (modified) {
+        Object.assign(occurrence, modified);
+        occurrence.isModified = true;
+      }
+    }
+    return occurrence;
+  }
+
   /**
    * 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
+   * transitions (plain DAILY and WEEKLY, HOURLY, MINUTELY) and to WEEKLY
+   * rules with BYDAY, whose steps repeat in a weekly cycle; the steps that
+   * cross a transition are taken with getNextDate so the result is exactly
    * what stepping from DTSTART would produce. Never seeks past UNTIL, and
    * counts skipped steps against COUNT.
    *
@@ -190,6 +434,10 @@ export class RecurrenceEngineV2 {
    * @param {string} timezone - Expansion timezone
    */
   seekToRange(state, rule, rangeStart, rangeEnd, timezone) {
+    if (rule.freq === 'WEEKLY' && rule.byDay && rule.byDay.length > 0) {
+      this._seekWeekCycle(state, rule, rangeStart, rangeEnd, timezone);
+      return;
+    }
     const stepMs = this.getFixedStepMs(rule);
     if (stepMs <= 0) {
       return;
@@ -219,6 +467,127 @@ export class RecurrenceEngineV2 {
     state.count = seek.steps;
   }
 
+  /**
+   * Seek for WEEKLY rules with BYDAY. getNextWeekly picks the next weekday
+   * from the BYDAY list (in list order), so the step from each weekday is
+   * fixed and the walk from DTSTART settles into a cycle of weekdays that
+   * repeats every whole number of weeks. The cursor is stepped one
+   * occurrence at a time until it is on that cycle (at most six steps),
+   * then whole cycles are skipped arithmetically between system-timezone
+   * transitions, exactly as seekToRange does for fixed steps.
+   * @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
+   * @private
+   */
+  _seekWeekCycle(state, rule, rangeStart, rangeEnd, timezone) {
+    const deltas = this._weekdayDeltas(rule);
+    if (!deltas) {
+      return;
+    }
+    let targetMs = rangeStart.getTime();
+    if (rule.until) {
+      const untilMs = new Date(rule.until).getTime();
+      if (untilMs < targetMs) {
+        targetMs = untilMs;
+      }
+    }
+    if (!(state.currentDate.getTime() < targetMs)) {
+      return;
+    }
+    const maxSteps = rule.count ? rule.count - 1 : Infinity;
+
+    // Follow the weekday graph from the cursor until a weekday repeats:
+    // the steps before the repeat lead in to the cycle
+    const path = [];
+    const seen = new Map();
+    let weekday = state.currentDate.getDay();
+    while (!seen.has(weekday)) {
+      seen.set(weekday, path.length);
+      path.push(weekday);
+      weekday = (weekday + deltas[weekday]) % 7;
+    }
+    const leadIn = seen.get(weekday);
+    const cycleSteps = path.length - leadIn;
+    let cycleDays = 0;
+    for (let i = leadIn; i < path.length; i++) {
+      cycleDays += deltas[path[i]];
+    }
+
+    // Lead-in: single steps, identical to the expansion loop's
+    for (let i = 0; i < leadIn; i++) {
+      if (state.count >= maxSteps) {
+        return;
+      }
+      const next = this.getNextDate(state.currentDate, rule, timezone, state);
+      if (!(next.getTime() < targetMs)) {
+        return; // the next step lands in the range; the loop takes it
+      }
+      state.currentDate = next;
+      state.count++;
+    }
+
+    const seek = RecurrenceEngine._seekFixedStep(
+      state.currentDate.getTime(),
+      targetMs,
+      rangeEnd.getTime(),
+      cycleDays * DAY,
+      Math.floor((maxSteps - state.count) / cycleSteps),
+      cursor => {
+        for (let i = 0; i < cycleSteps; i++) {
+          cursor.setTime(this.getNextDate(cursor, rule, timezone, state).getTime());
+        }
+      }
+    );
+    state.currentDate = new Date(seek.ms);
+    state.count += seek.steps * cycleSteps;
+  }
+
+  /**
+   * Days getNextWeekly adds from each weekday (index 0-6) for a WEEKLY
+   * rule with BYDAY, or null when the rule cannot be seeked (an invalid
+   * interval or day code, which the expansion loop handles as before)
+   * @param {Object} rule - Parsed recurrence rule
+   * @returns {number[]|null} Delta table indexed by Date#getDay()
+   * @private
+   */
+  _weekdayDeltas(rule) {
+    const interval = rule.interval;
+    if (!Number.isInteger(interval) || interval <= 0) {
+      return null;
+    }
+    const targets = this._weekdayTargets(rule);
+    if (targets.some(target => target === undefined)) {
+      return null;
+    }
+    const deltas = [];
+    for (let weekday = 0; weekday < 7; weekday++) {
+      const next = targets.find(target => target > weekday);
+      deltas[weekday] =
+        next !== undefined ? next - weekday : 7 - weekday + targets[0] + 7 * (interval - 1);
+    }
+    return deltas;
+  }
+
+  /**
+   * Weekday numbers (Date#getDay) of a rule's BYDAY entries in ascending
+   * order, computed once per parsed rule. Invalid day codes map to
+   * undefined and sort last.
+   * @param {Object} rule - Parsed recurrence rule with byDay
+   * @returns {number[]} Sorted weekday numbers
+   * @private
+   */
+  _weekdayTargets(rule) {
+    if (!rule._weekdayTargets) {
+      rule._weekdayTargets = rule.byDay
+        .map(byDay => WEEKDAYS[byDay.weekday || byDay])
+        .sort((a, b) => (a === undefined) - (b === undefined) || a - b);
+    }
+    return rule._weekdayTargets;
+  }
+
   /**
    * Milliseconds per step for rules getNextDate advances by a fixed
    * duration while the system UTC offset is constant
@@ -342,33 +711,16 @@ export class RecurrenceEngineV2 {
     const next = new Date(date);
 
     if (rule.byDay && rule.byDay.length > 0) {
-      // Find next matching weekday
-      const dayMap = {
-        SU: 0,
-        MO: 1,
-        TU: 2,
-        WE: 3,
-        TH: 4,
-        FR: 5,
-        SA: 6
-      };
-
+      // BYDAY is a set: the next weekday in it after the current one, or the
+      // earliest one INTERVAL weeks on when the week has none left
+      const targets = this._weekdayTargets(rule);
       const currentDay = next.getDay();
-      let daysToAdd = null;
-
-      // Find next occurrence day
-      for (const byDay of rule.byDay) {
-        const targetDay = dayMap[byDay.weekday || byDay];
-        if (targetDay > currentDay) {
-          daysToAdd = targetDay - currentDay;
-          break;
-        }
-      }
-
-      // If no day found in current week, go to next week
-      if (daysToAdd === null) {
-        const firstDay = dayMap[rule.byDay[0].weekday || rule.byDay[0]];
-        daysToAdd = 7 - currentDay + firstDay;
+      const nextDay = targets.find(target => target > currentDay);
+      let daysToAdd;
+      if (nextDay !== undefined) {
+        daysToAdd = nextDay - currentDay;
+      } else {
+        daysToAdd = 7 - currentDay + targets[0];
 
         // Apply interval for weekly recurrence
         if (rule.interval > 1) {
@@ -401,15 +753,17 @@ export class RecurrenceEngineV2 {
         // Found a day in current month
         next.setDate(targetDay);
       } else {
-        // Move to next month
-        next.setMonth(next.getMonth() + rule.interval);
-
-        // Handle negative days (from end of month)
         targetDay = targetDays[0];
         if (targetDay < 0) {
+          // Counted from the end of the month (-1 is the last day). Move to
+          // the first so the month step cannot overflow from a 31st.
+          next.setDate(1);
+          next.setMonth(next.getMonth() + rule.interval);
           const lastDay = new Date(next.getFullYear(), next.getMonth() + 1, 0).getDate();
-          next.setDate(lastDay + targetDay + 1);
+          next.setDate(Math.max(1, lastDay + targetDay + 1));
         } else {
+          // Move to next month
+          next.setMonth(next.getMonth() + rule.interval);
           next.setDate(targetDay);
         }
       }
@@ -573,28 +927,38 @@ export class RecurrenceEngineV2 {
    */
   findDSTTransitions(start, end, timezone) {
     const transitions = [];
-    const current = new Date(start);
-
-    // Check each day for offset changes
-    let lastOffset = this.tzManager.getTimezoneOffset(current, timezone);
+    const scan = { cursor: new Date(start), lastOffset: 0 };
+    scan.lastOffset = this.tzManager.getTimezoneOffset(scan.cursor, timezone);
+    this._scanDSTTransitions(scan, transitions, new Date(end).getTime(), timezone);
+    return transitions;
+  }
 
-    while (current <= end) {
-      const offset = this.tzManager.getTimezoneOffset(current, timezone);
+  /**
+   * Walk the scan cursor one day at a time up to untilMs, appending each
+   * offset change. The cursor and last offset persist in `scan`, so the
+   * walk can be resumed later on the same day grid.
+   * @param {{ cursor: Date, lastOffset: number }} scan - Resumable scan position (mutated)
+   * @param {Array} transitions - Transition list to append to
+   * @param {number} untilMs - Scan through this timestamp (inclusive)
+   * @param {string} timezone - Timezone to probe
+   * @private
+   */
+  _scanDSTTransitions(scan, transitions, untilMs, timezone) {
+    while (scan.cursor.getTime() <= untilMs) {
+      const offset = this.tzManager.getTimezoneOffset(scan.cursor, timezone);
 
-      if (offset !== lastOffset) {
+      if (offset !== scan.lastOffset) {
         transitions.push({
-          date: new Date(current),
-          oldOffset: lastOffset,
+          date: new Date(scan.cursor),
+          oldOffset: scan.lastOffset,
           newOffset: offset,
-          type: offset < lastOffset ? 'spring-forward' : 'fall-back'
+          type: offset < scan.lastOffset ? 'spring-forward' : 'fall-back'
         });
       }
 
-      lastOffset = offset;
-      current.setDate(current.getDate() + 1);
+      scan.lastOffset = offset;
+      scan.cursor.setDate(scan.cursor.getDate() + 1);
     }
-
-    return transitions;
   }
 
   /**
@@ -720,9 +1084,45 @@ export class RecurrenceEngineV2 {
 
   /**
    * Create cache key
+   *
+   * When given the event itself the key also covers everything the
+   * expansion depends on (DTSTART, end, recurrence rule), so a series that
+   * is updated, replaced or re-added under the same id can never be served
+   * a stale expansion. Keys always start with `<eventId>_`, which is what
+   * {@link RecurrenceEngineV2#clearEventCache} matches on.
+   * @param {import('./Event.js').Event|string} event - Recurring event, or just its id
+   * @param {Date} start - Start of expansion range
+   * @param {Date} end - End of expansion range
+   * @param {Object} options - Expansion options
+   * @returns {string} Cache key
+   */
+  getCacheKey(event, start, end, options) {
+    const eventId = typeof event === 'string' ? event : event.id;
+    const key = `${eventId}_${start.getTime()}_${end.getTime()}_${JSON.stringify(options)}`;
+    if (typeof event === 'string') {
+      return key;
+    }
+    const startMs = new Date(event.start).getTime();
+    const endMs = new Date(event.end).getTime();
+    return `${key}|${startMs}|${endMs}|${this._ruleFingerprint(event.recurrenceRule)}`;
+  }
+
+  /**
+   * Stable text form of a recurrence rule for cache keys. A rule that
+   * cannot be serialised gets a unique fingerprint, i.e. is never cached.
+   * @param {string|Object} rule - RRULE string or rule object
+   * @returns {string} Fingerprint
+   * @private
    */
-  getCacheKey(eventId, start, end, options) {
-    return `${eventId}_${start.getTime()}_${end.getTime()}_${JSON.stringify(options)}`;
+  _ruleFingerprint(rule) {
+    if (typeof rule === 'string') {
+      return rule;
+    }
+    try {
+      return JSON.stringify(rule);
+    } catch {
+      return `uncacheable:${Date.now()}:${Math.random()}`;
+    }
   }
 
   /**
@@ -742,7 +1142,16 @@ export class RecurrenceEngineV2 {
    * Clone occurrence results before returning or caching.
    */
   cloneOccurrences(occurrences) {
-    return occurrences.map(occurrence => ({
+    return occurrences.map(occurrence => this.cloneOccurrence(occurrence));
+  }
+
+  /**
+   * Clone a single occurrence, copying its Date and array fields.
+   * @param {import('../types.js').ExpandedOccurrence} occurrence - Occurrence to clone
+   * @returns {import('../types.js').ExpandedOccurrence} Independent copy
+   */
+  cloneOccurrence(occurrence) {
+    return {
       ...occurrence,
       start: occurrence.start ? new Date(occurrence.start) : occurrence.start,
       end: occurrence.end ? new Date(occurrence.end) : occurrence.end,
@@ -754,7 +1163,7 @@ export class RecurrenceEngineV2 {
       categories: Array.isArray(occurrence.categories)
         ? [...occurrence.categories]
         : occurrence.categories
-    }));
+    };
   }
 
   /**