@forcecalendar/core 2.3.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
    */
@@ -98,6 +111,8 @@ export class RecurrenceEngine {
 
     // 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
@@ -112,7 +127,31 @@ export class RecurrenceEngine {
     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);
@@ -223,7 +262,37 @@ export class RecurrenceEngine {
     let nextEventTzTransition = tzManager.getNextTransition(eventTimezone, currentMs, rangeEndMs);
     let nextSystemTransition = this._nextSystemTransition(currentMs, rangeEndMs);
 
-    while (currentMs <= rangeEndMs && count < maxOccurrences) {
+    // 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);
@@ -276,6 +345,152 @@ export class RecurrenceEngine {
     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.

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.3.0';
+export const VERSION = '2.4.0';
 
 // Default export
 export { Calendar as default } from './calendar/Calendar.js';

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.3.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}