@forcecalendar/core 2.3.0 → 2.5.0

package/core/calendar/Calendar.js

@@ -178,9 +178,12 @@ export class Calendar {
 
   /**
    * Update an event
-   * @param {string} eventId - The event ID
+   *
+   * An occurrence id taken from view data (see {@link Event.occurrenceId})
+   * updates the recurring master, i.e. the whole series.
+   * @param {string} eventId - Event id or occurrence id
    * @param {Object} updates - Properties to update
-   * @returns {Event} The updated event
+   * @returns {Event} The updated event (the master for an occurrence id)
    */
   updateEvent(eventId, updates) {
     const oldEvent = this.eventStore.getEvent(eventId);
@@ -193,7 +196,10 @@ export class Calendar {
 
   /**
    * Remove an event
-   * @param {string} eventId - The event ID
+   *
+   * An occurrence id taken from view data (see {@link Event.occurrenceId})
+   * removes the recurring master, i.e. the whole series.
+   * @param {string} eventId - Event id or occurrence id
    * @returns {boolean} True if removed
    */
   removeEvent(eventId) {
@@ -218,15 +224,19 @@ export class Calendar {
 
   /**
    * Get an event by ID
-   * @param {string} eventId - The event ID
-   * @returns {Event|null}
+   *
+   * Occurrence ids taken from view data (`<masterId>_<startMs>`, see
+   * {@link Event.occurrenceId}) resolve to the stored recurring master, so
+   * every id a renderer hands back can be looked up here.
+   * @param {string} eventId - Event id or occurrence id
+   * @returns {Event|null} The stored event (the master for an occurrence id) or null
    */
   getEvent(eventId) {
     return this.eventStore.getEvent(eventId);
   }
 
   /**
-   * Get all events
+   * Get all stored events (recurring masters, never their occurrences)
    * @returns {Event[]}
    */
   getEvents() {
@@ -235,11 +245,103 @@ export class Calendar {
 
   /**
    * Set all events (replaces existing)
-   * @param {Event[]} events - Array of events
-   */
-  setEvents(events) {
+   *
+   * 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, options = {}) {
+    if (options.reconcile) {
+      return this.reconcileEvents(events, options);
+    }
+
+    const removed = this.getEvents();
     this.eventStore.loadEvents(events);
-    this._emit('eventsSet', { events: this.getEvents() });
+    const added = this.getEvents();
+
+    /** @type {import('../types.js').EventsSetPayload} */
+    const payload = { events: added, added, updated: [], removed, unchanged: [] };
+    this._emit('eventsSet', payload);
+    return payload;
+  }
+
+  /**
+   * 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, options = {}) {
+    const { removeMissing, isEquivalent } = options;
+    const prepared = [];
+    for (const eventData of events) {
+      if (!(eventData instanceof Event) && eventData && !eventData.timeZone) {
+        prepared.push({ ...eventData, timeZone: this.config.timeZone });
+      } else {
+        prepared.push(eventData);
+      }
+    }
+
+    const storeOptions = {};
+    if (removeMissing !== undefined) storeOptions.removeMissing = removeMissing;
+    if (isEquivalent !== undefined) storeOptions.isEquivalent = isEquivalent;
+
+    const result = this.eventStore.reconcile(prepared, storeOptions);
+
+    /** @type {import('../types.js').EventsSetPayload} */
+    const payload = { events: this.getEvents(), ...result };
+    this._emit('eventsSet', payload);
+    return payload;
+  }
+
+  /**
+   * 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() {
+    return this.eventStore.version;
   }
 
   /**
@@ -252,7 +354,7 @@ export class Calendar {
   }
 
   /**
-   * Get events for a specific date
+   * Get events for a specific date, with recurring series expanded into occurrences
    * @param {Date} date - The date
    * @param {string} [timezone] - Timezone for the query (defaults to calendar timezone)
    * @returns {Event[]}
@@ -261,6 +363,20 @@ export class Calendar {
     return this.eventStore.getEventsForDate(date, timezone || this.config.timeZone);
   }
 
+  /**
+   * Get the events for every day in a range, keyed by local date (YYYY-MM-DD)
+   *
+   * Recurring series are expanded once for the whole range; this is what the
+   * month and week views use. See `EventStore.getEventsByDate`.
+   * @param {Date} start - First day of the range
+   * @param {Date} end - Last day of the range
+   * @param {string} [timezone] - Timezone for the query (defaults to calendar timezone)
+   * @returns {Map<string, Event[]>} Local date string -> events on that day
+   */
+  getEventsByDate(start, end, timezone = null) {
+    return this.eventStore.getEventsByDate(start, end, timezone || this.config.timeZone);
+  }
+
   /**
    * Get events in a date range
    * @param {Date} start - Start date
@@ -272,6 +388,64 @@ export class Calendar {
     return this.eventStore.getEventsInRange(start, end, true, timezone || this.config.timeZone);
   }
 
+  /**
+   * Lazily iterate the occurrences of an event in chronological order.
+   *
+   * Occurrences are produced one at a time, so taking the next few of an
+   * open-ended series does not expand the series. `after` and `before`
+   * are exclusive unless `inclusive` is set; see
+   * RecurrenceEngineV2.iterateOccurrences for the full semantics.
+   *
+   * @example
+   * for (const occurrence of calendar.iterateOccurrences('standup', { after: new Date() })) {
+   *   if (occurrence.start > deadline) break;
+   *   remind(occurrence);
+   * }
+   *
+   * @param {string} eventId - The event ID
+   * @param {import('../types.js').ExpandedOccurrenceIteratorOptions} [options={}] - Window and expansion options
+   * @returns {Generator<import('../types.js').ExpandedOccurrence, void, undefined>} Occurrences in chronological order
+   * @throws {Error} If no event with the ID exists
+   */
+  iterateOccurrences(eventId, options = {}) {
+    return this.eventStore.iterateOccurrences(eventId, options);
+  }
+
+  /**
+   * 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.
+   *
+   * @example
+   * const upcoming = calendar.getNextOccurrence('standup', new Date());
+   *
+   * @param {string} eventId - The event ID
+   * @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
+   * @throws {Error} If no event with the ID exists
+   */
+  getNextOccurrence(eventId, after = null, options = {}) {
+    return this.eventStore.getNextOccurrence(eventId, after, options);
+  }
+
+  /**
+   * The first `count` occurrences of an event inside a window, generated
+   * lazily. `count` is capped at the engine's MAX_OCCURRENCES_HARD_LIMIT.
+   *
+   * @example
+   * const nextFive = calendar.takeOccurrences('standup', 5, { after: new Date() });
+   *
+   * @param {string} eventId - The event ID
+   * @param {number} count - Maximum number of occurrences to return
+   * @param {import('../types.js').ExpandedOccurrenceIteratorOptions} [options={}] - Window and expansion options
+   * @returns {import('../types.js').ExpandedOccurrence[]} Up to `count` occurrences in chronological order
+   * @throws {Error} If no event with the ID exists
+   */
+  takeOccurrences(eventId, count, options = {}) {
+    return this.eventStore.takeOccurrences(eventId, count, options);
+  }
+
   /**
    * Set the calendar's timezone
    * @param {string} timezone - IANA timezone identifier
@@ -437,6 +611,12 @@ export class Calendar {
       ? 6
       : Math.ceil((lastDay.getDate() + DateUtils.getDayOfWeek(firstDay, weekStartsOn)) / 7);
 
+    // Expand recurring series once for the whole grid, not once per cell
+    const eventsByDate = this.getEventsByDate(
+      startDate,
+      DateUtils.addDays(startDate, maxWeeks * 7 - 1)
+    );
+
     for (let weekIndex = 0; weekIndex < maxWeeks; weekIndex++) {
       const week = {
         weekNumber: DateUtils.getWeekNumber(currentDate),
@@ -455,7 +635,7 @@ export class Calendar {
           isCurrentMonth,
           isToday,
           isWeekend,
-          events: this.getEventsForDate(dayDate)
+          events: eventsByDate.get(DateUtils.getLocalDateString(dayDate)) || []
         });
 
         // Use DateUtils.addDays to handle month boundaries correctly
@@ -488,8 +668,12 @@ export class Calendar {
     const days = [];
     const currentDate = new Date(startDate);
 
+    // Expand recurring series once for the whole week, not once per day
+    const eventsByDate = this.getEventsByDate(startDate, endDate);
+
     for (let i = 0; i < 7; i++) {
       const dayDate = new Date(currentDate);
+      const events = eventsByDate.get(DateUtils.getLocalDateString(dayDate)) || [];
       days.push({
         date: dayDate,
         dayOfMonth: dayDate.getDate(),
@@ -497,9 +681,9 @@ export class Calendar {
         dayName: DateUtils.getDayName(dayDate, this.state.get('locale')),
         isToday: DateUtils.isToday(dayDate),
         isWeekend: dayDate.getDay() === 0 || dayDate.getDay() === 6,
-        events: this.getEventsForDate(dayDate),
+        events,
         // Add overlap groups for positioning overlapping events
-        overlapGroups: this.eventStore.getOverlapGroups(dayDate, true),
+        overlapGroups: this.eventStore.groupOverlappingEvents(events, true),
         getEventPositions: events => this.eventStore.calculateEventPositions(events)
       });
       // Move to next day

package/core/events/Event.js

@@ -6,6 +6,42 @@
 
 import { TimezoneManager } from '../timezone/TimezoneManager.js';
 
+/**
+ * Structural equality for plain event sub-values (attendees, metadata, rules...).
+ * Handles primitives, Dates, arrays (order-sensitive) and plain objects
+ * (key-order insensitive). Functions and symbols never compare equal unless
+ * they are the same reference.
+ * @param {*} a
+ * @param {*} b
+ * @returns {boolean}
+ */
+function deepEqual(a, b) {
+  if (a === b) return true;
+  if (a == null || b == null) return false;
+  if (typeof a !== 'object' || typeof b !== 'object') {
+    // NaN is the only primitive that is not === itself
+    return Number.isNaN(a) && Number.isNaN(b);
+  }
+  if (a instanceof Date || b instanceof Date) {
+    return a instanceof Date && b instanceof Date && a.getTime() === b.getTime();
+  }
+  if (Array.isArray(a) || Array.isArray(b)) {
+    if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) return false;
+    for (let i = 0; i < a.length; i++) {
+      if (!deepEqual(a[i], b[i])) return false;
+    }
+    return true;
+  }
+  const keysA = Object.keys(a).filter(k => a[k] !== undefined);
+  const keysB = Object.keys(b).filter(k => b[k] !== undefined);
+  if (keysA.length !== keysB.length) return false;
+  for (const key of keysA) {
+    if (!Object.prototype.hasOwnProperty.call(b, key)) return false;
+    if (!deepEqual(a[key], b[key])) return false;
+  }
+  return true;
+}
+
 export class Event {
   // Field size limits
   static FIELD_LIMITS = {
@@ -289,6 +325,16 @@ export class Event {
     this.recurring = normalized.recurring;
     this.recurrenceRule = normalized.recurrenceRule;
 
+    // Occurrence identity. Set by EventStore.expandRecurringEvent on the
+    // instances it derives from a recurring series; stored events keep the
+    // defaults. The id of an occurrence is Event.occurrenceId(master, start).
+    /** @type {boolean} True when this instance is one occurrence of a recurring series */
+    this.isOccurrence = false;
+    /** @type {string|null} Id of the recurring master this occurrence belongs to */
+    this.recurringEventId = null;
+    /** @type {Date|null} Start of this occurrence as generated by the recurrence rule */
+    this.occurrenceStart = null;
+
     // Store original timezone from system if not provided
     this._originalTimeZone = normalized.timeZone || null;
 
@@ -609,6 +655,133 @@ export class Event {
     );
   }
 
+  /**
+   * 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 = Object.freeze([
+    'id',
+    'title',
+    'start',
+    'end',
+    'allDay',
+    'timeZone',
+    'endTimeZone',
+    'description',
+    'location',
+    'color',
+    'backgroundColor',
+    'borderColor',
+    'textColor',
+    'recurring',
+    'recurrenceRule',
+    'status',
+    'visibility',
+    'organizer',
+    'attendees',
+    'reminders',
+    'categories',
+    'attachments',
+    'conferenceData',
+    'metadata'
+  ]);
+
+  /**
+   * 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, b) {
+    if (a === b) return true;
+    if (a == null || b == null) return false;
+
+    const left = a instanceof Event ? a : new Event(a);
+    const right = b instanceof Event ? b : new Event(b);
+
+    for (const field of Event.EQUIVALENCE_FIELDS) {
+      if (!deepEqual(left[field], right[field])) {
+        return false;
+      }
+    }
+    return true;
+  }
+
+  /**
+   * Build the id of one occurrence of a recurring series.
+   *
+   * The id is `<recurringEventId>_<startMs>` where `startMs` is the
+   * occurrence start as returned by `Date.prototype.getTime()`. It is
+   * deterministic, so the same occurrence gets the same id no matter which
+   * range it was expanded for, and it matches the ids generated by
+   * `RecurrenceEngineV2`. Use {@link Event.parseOccurrenceId} to get the
+   * master id back.
+   *
+   * @example
+   * Event.occurrenceId('standup', new Date(2025, 5, 16, 9)); // 'standup_1750028400000'
+   *
+   * @param {string} recurringEventId - Id of the recurring master event
+   * @param {Date|number|string} occurrenceStart - Start of the occurrence
+   * @returns {string} Occurrence id
+   */
+  static occurrenceId(recurringEventId, occurrenceStart) {
+    const start = occurrenceStart instanceof Date ? occurrenceStart : new Date(occurrenceStart);
+    return `${recurringEventId}_${start.getTime()}`;
+  }
+
+  /**
+   * Split an occurrence id built by {@link Event.occurrenceId} into the master
+   * id and the occurrence start.
+   *
+   * Returns `null` for ids that do not have the `<id>_<startMs>` shape. A
+   * positive result only means the id is well-formed; whether the master
+   * exists is for the caller (see `EventStore.getEvent`) to check.
+   *
+   * @param {string} id - Candidate occurrence id
+   * @returns {{recurringEventId: string, occurrenceStart: Date}|null} Parsed parts or null
+   */
+  static parseOccurrenceId(id) {
+    if (typeof id !== 'string') {
+      return null;
+    }
+    const separator = id.lastIndexOf('_');
+    if (separator <= 0 || separator === id.length - 1) {
+      return null;
+    }
+    const time = id.slice(separator + 1);
+    if (!/^-?\d+$/.test(time)) {
+      return null;
+    }
+    return {
+      recurringEventId: id.slice(0, separator),
+      occurrenceStart: new Date(Number(time))
+    };
+  }
+
   // ============ Attendee Management Methods ============
 
   /**