@forcecalendar/core 2.2.0 → 2.4.0

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/core/types.js

@@ -275,13 +275,55 @@
 
 /**
  * @typedef {Object} EventStoreChange
- * @property {('add'|'update'|'remove'|'clear')} type - Type of change
+ * @property {('add'|'update'|'remove'|'clear'|'batch')} type - Type of change
  * @property {import('./events/Event.js').Event} [event] - Affected event
  * @property {import('./events/Event.js').Event} [oldEvent] - Previous event state (for updates)
  * @property {import('./events/Event.js').Event[]} [oldEvents] - Previous events (for clear)
+ * @property {EventStoreChange[]} [changes] - Individual changes (for batch)
+ * @property {number} [count] - Number of individual changes (for batch)
  * @property {number} version - Store version number
  */
 
+/**
+ * @typedef {(a: import('./events/Event.js').Event, b: import('./events/Event.js').Event) => boolean} EventEquivalenceFn
+ */
+
+/**
+ * @typedef {Object} ReconcileOptions
+ * @property {boolean} [removeMissing=true] - Remove stored events that are absent from the snapshot
+ * @property {EventEquivalenceFn} [isEquivalent] - Comparator deciding whether a stored event is unchanged (defaults to Event.isEquivalent)
+ */
+
+/**
+ * @typedef {Object} ReconciledUpdate
+ * @property {import('./events/Event.js').Event} event - Event now in the store
+ * @property {import('./events/Event.js').Event} oldEvent - Event it replaced
+ */
+
+/**
+ * @typedef {Object} ReconcileResult
+ * @property {import('./events/Event.js').Event[]} added - Events that were not in the store before
+ * @property {ReconciledUpdate[]} updated - Events whose data changed
+ * @property {import('./events/Event.js').Event[]} removed - Events removed from the store
+ * @property {import('./events/Event.js').Event[]} unchanged - Stored events left untouched (same instances)
+ */
+
+/**
+ * @typedef {Object} SetEventsOptions
+ * @property {boolean} [reconcile=false] - Apply only the differences instead of clearing and re-adding
+ * @property {boolean} [removeMissing=true] - Reconcile only: remove stored events absent from the snapshot
+ * @property {EventEquivalenceFn} [isEquivalent] - Reconcile only: custom equivalence comparator
+ */
+
+/**
+ * @typedef {Object} EventsSetPayload
+ * @property {import('./events/Event.js').Event[]} events - All events after the operation
+ * @property {import('./events/Event.js').Event[]} added - Events added by the operation
+ * @property {ReconciledUpdate[]} updated - Events replaced by the operation
+ * @property {import('./events/Event.js').Event[]} removed - Events removed by the operation
+ * @property {import('./events/Event.js').Event[]} unchanged - Events left untouched
+ */
+
 /**
  * @typedef {Object} QueryFilters
  * @property {Date} [start] - Start date for range query

package/package.json

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

package/types/calendar/Calendar.d.ts

@@ -110,9 +110,66 @@ export declare class Calendar {
     getEvents(): Event[];
     /**
      * Set all events (replaces existing)
-     * @param {Event[]} events - Array of events
-     */
-    setEvents(events: Event[]): void;
+     *
+     * By default this clears the store and re-adds every entry, so every stored
+     * {@link Event} instance is replaced. Pass `{ reconcile: true }` to apply only
+     * the differences instead (see {@link Calendar#reconcileEvents}).
+     *
+     * Emits a single `eventsSet` event whose payload lists the resulting
+     * `events` plus the `added`, `updated`, `removed` and `unchanged` sets, so
+     * listeners can tell a snapshot load apart from user mutations (no
+     * `eventAdd`/`eventUpdate`/`eventRemove` events are emitted).
+     *
+     * @example
+     * calendar.on('eventsSet', ({ added, updated, removed }) => {
+     *   if (added.length || updated.length || removed.length) render();
+     * });
+     * calendar.setEvents(snapshot, { reconcile: true });
+     *
+     * @param {Array<import('../events/Event.js').Event|import('../types.js').EventData>} events - Array of events
+     * @param {import('../types.js').SetEventsOptions} [options={}] - Load options
+     * @returns {import('../types.js').EventsSetPayload} The applied change set
+     */
+    setEvents(events: Array<import('../events/Event.js').Event | import('../types.js').EventData>, options?: import('../types.js').SetEventsOptions): import('../types.js').EventsSetPayload;
+    /**
+     * Reconcile the calendar with a snapshot of events, applying only the differences.
+     *
+     * Intended for consumers that receive periodic full snapshots (polling a
+     * server, a reactive `events` prop). Unchanged events keep their existing
+     * {@link Event} instance, changed ones are replaced, new ones are added and
+     * events missing from the snapshot are removed (unless
+     * `removeMissing: false`). Equivalence is decided by
+     * {@link Event.isEquivalent} unless an `isEquivalent` comparator is supplied.
+     * Plain event data without a `timeZone` defaults to the calendar timezone,
+     * exactly as with {@link Calendar#addEvent}.
+     *
+     * The store emits one `eventStoreChange` of type `batch` (or none when
+     * nothing differs) and the calendar emits a single `eventsSet` event
+     * carrying the change set. Per-event `eventAdd`/`eventUpdate`/`eventRemove`
+     * events are not emitted, so listeners that forward those to a backend are
+     * not triggered by a snapshot load.
+     *
+     * @example
+     * const { added, updated, removed, unchanged } = calendar.reconcileEvents(rows);
+     * updated.forEach(({ event, oldEvent }) => console.log(oldEvent.title, '->', event.title));
+     *
+     * @param {Array<import('../events/Event.js').Event|import('../types.js').EventData>} events - Complete snapshot of events
+     * @param {import('../types.js').ReconcileOptions} [options={}] - Reconcile options
+     * @returns {import('../types.js').EventsSetPayload} Resulting events and the applied change set
+     * @throws {Error} If an entry fails validation or two entries share an id
+     */
+    reconcileEvents(events: Array<import('../events/Event.js').Event | import('../types.js').EventData>, options?: import('../types.js').ReconcileOptions): import('../types.js').EventsSetPayload;
+    /**
+     * Get the event store's change counter
+     *
+     * The counter increases with every add/update/remove/clear and every
+     * committed batch, so comparing two readings is a cheap way to find out
+     * whether {@link Calendar#setEvents} or {@link Calendar#reconcileEvents}
+     * changed anything.
+     *
+     * @returns {number} Current store version
+     */
+    getEventsVersion(): number;
     /**
      * Query events with filters
      * @param {Object} filters - Query filters

package/types/events/Event.d.ts

@@ -156,6 +156,42 @@ export declare class Event {
      * @returns {boolean} True if events are equal
      */
     equals(other: Event): boolean;
+    /**
+     * Fields compared by {@link Event.isEquivalent}, in comparison order.
+     * Scalars are compared with strict equality, dates by timestamp and
+     * structured fields (recurrence rule, organizer, attendees, reminders,
+     * categories, attachments, conference data, metadata) structurally.
+     * @type {ReadonlyArray<string>}
+     */
+    static EQUIVALENCE_FIELDS: ReadonlyArray<string>;
+    /**
+     * Deep equivalence check over the full event data surface.
+     *
+     * Unlike {@link Event#equals} (which only looks at identity, title, dates,
+     * description, location, recurrence and status) this compares every field
+     * that can be supplied through {@link EventData}: timezones, all-day flag,
+     * colours, visibility, organizer, attendees, reminders, categories,
+     * attachments, conference data and metadata. Dates are compared by
+     * timestamp; structured fields are compared structurally (arrays are
+     * order-sensitive, object key order is ignored). Plain event data objects
+     * are normalized through the {@link Event} constructor before comparison so
+     * that `{ color: 'red' }` and `{ backgroundColor: 'red', borderColor: 'red' }`
+     * describe the same event. Two events with different ids are never
+     * equivalent.
+     *
+     * This is the default comparator used by `EventStore.reconcile()` to decide
+     * whether an incoming snapshot entry replaces the stored event.
+     *
+     * @example
+     * Event.isEquivalent(stored, { ...stored.toObject(), backgroundColor: '#f00' }); // false
+     * Event.isEquivalent(stored, stored.clone()); // true
+     *
+     * @param {Event|import('../types.js').EventData} a - First event or raw event data
+     * @param {Event|import('../types.js').EventData} b - Second event or raw event data
+     * @returns {boolean} True when both describe the same event data
+     * @throws {Error} If raw event data fails {@link Event.validate}
+     */
+    static isEquivalent(a: Event | import('../types.js').EventData, b: Event | import('../types.js').EventData): boolean;
     /**
      * Add an attendee to the event
      * @param {import('../types.js').Attendee} attendee - Attendee to add

package/types/events/EventStore.d.ts

@@ -70,12 +70,26 @@ export declare class EventStore {
      * @throws {Error} If event not found
      */
     updateEvent(eventId: string, updates: Partial<import('../types.js').EventData>): Event;
+    /**
+     * Swap a stored event for a new instance with the same id, keeping
+     * indices and caches in sync. Does not notify listeners.
+     * @param {Event} existingEvent - Event currently in the store
+     * @param {Event} replacement - Event instance that takes its place
+     * @private
+     */
+    private _replaceEvent;
     /**
      * Remove an event from the store
      * @param {string} eventId - The event ID to remove
      * @returns {boolean} True if removed, false if not found
      */
     removeEvent(eventId: string): boolean;
+    /**
+     * Remove an event from storage, caches and indices. Does not notify listeners.
+     * @param {Event} event - Event currently in the store
+     * @private
+     */
+    private _detachEvent;
     /**
      * Get an event by ID
      * @param {string} eventId - The event ID
@@ -161,6 +175,35 @@ export declare class EventStore {
      * @param {Event[]} events - Array of events or event data
      */
     loadEvents(events: Event[]): void;
+    /**
+     * Reconcile the store with a snapshot of events, applying only the differences.
+     *
+     * Compared with {@link EventStore#loadEvents} (clear + re-add everything) this:
+     * - keeps the existing {@link Event} instance for every entry that is
+     *   equivalent to the stored one (identity is preserved, no notification),
+     * - replaces stored events whose incoming data differs (`update` change),
+     * - adds events whose id is not in the store (`add` change),
+     * - removes stored events missing from the snapshot (`remove` change),
+     *   unless `removeMissing` is `false`,
+     * - emits a single `batch` notification listing those changes, or nothing at
+     *   all when the snapshot matches the store. When called while a batch is
+     *   already open the changes are queued on that batch instead.
+     *
+     * Input is validated up front: invalid event data or duplicate ids throw
+     * before the store is modified. Any error raised while applying the diff
+     * rolls the store back to its previous state.
+     *
+     * @example
+     * // periodic server snapshot
+     * const { added, updated, removed } = store.reconcile(rowsFromServer);
+     * if (added.length || updated.length || removed.length) rerender();
+     *
+     * @param {Array<Event|import('../types.js').EventData>} events - Complete snapshot of events
+     * @param {import('../types.js').ReconcileOptions} [options={}] - Reconcile options
+     * @returns {import('../types.js').ReconcileResult} Events that were added, updated, removed and left untouched
+     * @throws {Error} If an entry fails validation or two entries share an id
+     */
+    reconcile(events: Array<Event | import('../types.js').EventData>, options?: import('../types.js').ReconcileOptions): import('../types.js').ReconcileResult;
     /**
      * Subscribe to store changes
      * @param {Function} callback - Callback function
@@ -201,7 +244,13 @@ export declare class EventStore {
      * Notify listeners of changes
      * @private
      */
-    private _notifyChange;
+    /**
+     * Deliver a change now, or queue it when a batch is open
+     * @param {import('../types.js').EventStoreChange} change - Change to deliver
+     * @private
+     */
+    private _queueChange;
+    _notifyChange(change: any): void;
     /**
      * Get store statistics
      * @returns {Object}

package/types/events/RecurrenceEngine.d.ts

@@ -3,19 +3,117 @@
  * Full support for RFC 5545 (iCalendar) RRULE specification
  */
 export declare class RecurrenceEngine {
+    static _systemTransitions: any;
     static MAX_OCCURRENCES_HARD_LIMIT: number;
+    static MAX_ITERATIONS_HARD_LIMIT: number;
     static _ruleCache: Map<any, any>;
     static _RULE_CACHE_MAX: number;
     /**
      * 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
      */
     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;
+    /**
+     * 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
+     */
+    private static _fixedStepMs;
+    /**
+     * 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
+     */
+    private static _seekFixedStep;
+    /**
+     * 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
+     */
+    private static _seekWeekCycle;
+    /**
+     * 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/events/RecurrenceEngineV2.d.ts

@@ -10,16 +10,59 @@ export declare class RecurrenceEngineV2 {
     modifiedInstances: Map<any, any>;
     exceptionStore: Map<any, any>;
     static MAX_OCCURRENCES_HARD_LIMIT: number;
+    static MAX_ITERATIONS_HARD_LIMIT: number;
     constructor();
     /**
      * 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: Event, rangeStart: Date, rangeEnd: Date, options?: Object): any[];
+    expandEvent(event: import('./Event.js').Event, rangeStart: Date, rangeEnd: Date, options?: {
+        maxOccurrences?: number;
+        includeModified?: boolean;
+        includeCancelled?: boolean;
+        timezone?: string;
+        handleDST?: boolean;
+    }): any[];
+    /**
+     * 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: Object, rule: Object, rangeStart: Date, rangeEnd: Date, timezone: string): void;
+    /**
+     * 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: Object): number;
     /**
      * Generate a single occurrence with timezone handling
      */

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.4.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