@forcecalendar/core 2.2.0 → 2.3.0

package/core/events/RecurrenceEngine.js

@@ -34,20 +34,72 @@ 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);
+    let count = 0;
+
     // Track DST transitions for proper timezone handling
     let lastOffset = tzManager.getTimezoneOffset(currentDate, eventTimezone);
 
@@ -57,8 +109,6 @@ 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();
 
@@ -113,14 +163,179 @@ 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);
+
+    while (currentMs <= rangeEndMs && count < maxOccurrences) {
+      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;
   }
 
+  /**
+   * 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/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.3.0';
 
 // Default export
 export { Calendar as default } from './calendar/Calendar.js';

package/core/timezone/TimezoneManager.js

@@ -47,6 +47,11 @@ export class TimezoneManager {
     // so formatters are cached per timezone and reused
     this.formatterCache = new Map();
 
+    // Discovered offset-transition instants per zone:
+    // Map<timezone, {from: number, to: number, transitions: number[]}>
+    // covering [from, to] with a sorted list of transition timestamps
+    this.transitionCache = new Map();
+
     // Cache size management
     this.maxCacheSize = 1000;
     // ~20k 15-minute buckets per zone (≈ a few hundred KB worst case) covers
@@ -165,7 +170,11 @@ export class TimezoneManager {
           }
         }
         const tzDate = new Date(year, month - 1, day, hour, minute, second);
-        offset = -((tzDate.getTime() - date.getTime()) / (1000 * 60));
+        // formatToParts carries no milliseconds, so compare against the
+        // whole-second part of the input or sub-second noise leaks into
+        // the offset (e.g. 660.0042 instead of 660)
+        const wholeSecondMs = Math.floor(date.getTime() / 1000) * 1000;
+        offset = -((tzDate.getTime() - wholeSecondMs) / (1000 * 60));
       } catch (e) {
         // Fallback to database calculation
       }
@@ -193,6 +202,74 @@ export class TimezoneManager {
     return offset;
   }
 
+  /**
+   * Find the next instant at which the zone's UTC offset changes
+   * @param {string} timezone - Timezone identifier
+   * @param {number} fromMs - Search from this timestamp (exclusive)
+   * @param {number} toMs - Search up to this timestamp (inclusive)
+   * @returns {number} Timestamp of the first offset change after fromMs, or Infinity
+   */
+  getNextTransition(timezone, fromMs, toMs) {
+    if (fromMs >= toMs) {
+      return Infinity;
+    }
+    timezone = this.database.resolveAlias(timezone);
+    let cached = this.transitionCache.get(timezone);
+    if (!cached || fromMs < cached.from || toMs > cached.to) {
+      // Extend coverage generously so repeated expansions over the same
+      // span hit the cache
+      const from = Math.min(fromMs, cached ? cached.from : fromMs);
+      const to = Math.max(toMs, cached ? cached.to : toMs);
+      cached = { from, to, transitions: this._scanTransitions(timezone, from, to) };
+      this.transitionCache.set(timezone, cached);
+    }
+    for (const t of cached.transitions) {
+      if (t > fromMs) {
+        return t <= toMs ? t : Infinity;
+      }
+    }
+    return Infinity;
+  }
+
+  /**
+   * Scan a range for offset transitions. Probes in 7-day steps (shorter
+   * than any gap between real-world transitions, including Ramadan DST
+   * suspensions) and binary-searches each change to the exact instant.
+   * @param {string} timezone - Resolved timezone identifier
+   * @param {number} fromMs - Range start
+   * @param {number} toMs - Range end
+   * @returns {number[]} Sorted transition timestamps
+   * @private
+   */
+  _scanTransitions(timezone, fromMs, toMs) {
+    const WEEK = 7 * 86400000;
+    const transitions = [];
+    const offsetAt = ms => this.getTimezoneOffset(new Date(ms), timezone);
+    let lo = fromMs;
+    let loOffset = offsetAt(lo);
+    while (lo < toMs) {
+      const hi = Math.min(lo + WEEK, toMs);
+      const hiOffset = offsetAt(hi);
+      if (hiOffset !== loOffset) {
+        // Binary search for the first ms with the new offset
+        let a = lo;
+        let b = hi;
+        while (b - a > 1) {
+          const mid = Math.floor((a + b) / 2);
+          if (offsetAt(mid) === loOffset) {
+            a = mid;
+          } else {
+            b = mid;
+          }
+        }
+        transitions.push(b);
+        loOffset = hiOffset;
+      }
+      lo = hi;
+    }
+    return transitions;
+  }
+
   /**
    * Get a cached Intl.DateTimeFormat for a timezone
    * @param {string} timezone - Timezone identifier
@@ -471,6 +548,7 @@ export class TimezoneManager {
   clearCache() {
     this.offsetCache.clear();
     this.dstCache.clear();
+    this.transitionCache.clear();
     this.cacheHits = 0;
     this.cacheMisses = 0;
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forcecalendar/core",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "type": "module",
   "private": false,
   "description": "A modern, lightweight, framework-agnostic calendar engine optimized for Salesforce",

package/types/events/RecurrenceEngine.d.ts

@@ -3,6 +3,7 @@
  * Full support for RFC 5545 (iCalendar) RRULE specification
  */
 export declare class RecurrenceEngine {
+    static _systemTransitions: any;
     static MAX_OCCURRENCES_HARD_LIMIT: number;
     static _ruleCache: Map<any, any>;
     static _RULE_CACHE_MAX: number;
@@ -16,6 +17,44 @@ export declare class RecurrenceEngine {
      * @returns {import('../types.js').EventOccurrence[]} Array of occurrence objects with start/end dates
      */
     static expandEvent(event: import('./Event.js').Event, rangeStart: Date, rangeEnd: Date, maxOccurrences?: number, timezone?: string): import('../types.js').EventOccurrence[];
+    /**
+     * General expansion loop: advances a Date cursor per step. Handles every
+     * frequency and degenerate rules (non-advancing dates, invalid intervals).
+     * @private
+     */
+    private static _expandGeneral;
+    /**
+     * 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
+     */
+    private static _expandFast;
+    /**
+     * 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
+     */
+    private static _nextSystemTransition;
+    /**
+     * 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
+     */
+    private static _scanSystemTransitions;
     /**
      * Apply BYSETPOS to filter occurrences within each frequency period
      * @param {Array} occurrences - Generated occurrences

package/types/index.d.ts

@@ -18,5 +18,5 @@ export { RRuleParser } from './events/RRuleParser.js';
 export { TimezoneManager } from './timezone/TimezoneManager.js';
 export { ConflictDetector } from './conflicts/ConflictDetector.js';
 export { EnhancedCalendar } from './integration/EnhancedCalendar.js';
-export declare const VERSION = "2.2.0";
+export declare const VERSION = "2.3.0";
 export { Calendar as default } from './calendar/Calendar.js';

package/types/timezone/TimezoneManager.d.ts

@@ -10,6 +10,7 @@ export declare class TimezoneManager {
     offsetCache: Map<any, any>;
     dstCache: Map<any, any>;
     formatterCache: Map<any, any>;
+    transitionCache: Map<any, any>;
     maxCacheSize: number;
     maxOffsetBucketsPerZone: number;
     cacheHits: number;
@@ -55,6 +56,25 @@ export declare class TimezoneManager {
      * @returns {number} Offset in minutes from UTC
      */
     getTimezoneOffset(date: Date, timezone: string): number;
+    /**
+     * Find the next instant at which the zone's UTC offset changes
+     * @param {string} timezone - Timezone identifier
+     * @param {number} fromMs - Search from this timestamp (exclusive)
+     * @param {number} toMs - Search up to this timestamp (inclusive)
+     * @returns {number} Timestamp of the first offset change after fromMs, or Infinity
+     */
+    getNextTransition(timezone: string, fromMs: number, toMs: number): number;
+    /**
+     * Scan a range for offset transitions. Probes in 7-day steps (shorter
+     * than any gap between real-world transitions, including Ramadan DST
+     * suspensions) and binary-searches each change to the exact instant.
+     * @param {string} timezone - Resolved timezone identifier
+     * @param {number} fromMs - Range start
+     * @param {number} toMs - Range end
+     * @returns {number[]} Sorted transition timestamps
+     * @private
+     */
+    private _scanTransitions;
     /**
      * Get a cached Intl.DateTimeFormat for a timezone
      * @param {string} timezone - Timezone identifier