@forcecalendar/core 2.3.0 → 2.4.0

package/core/calendar/Calendar.js

@@ -235,11 +235,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;
   }
 
   /**

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 = {
@@ -609,6 +645,82 @@ 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;
+  }
+
   // ============ Attendee Management Methods ============
 
   /**

package/core/events/EventStore.js

@@ -86,19 +86,11 @@ export class EventStore {
       this._indexEvent(event);
 
       // Notify listeners (batch if in batch mode)
-      if (this.isBatchMode) {
-        this.batchNotifications.push({
-          type: 'add',
-          event,
-          version: ++this.version
-        });
-      } else {
-        this._notifyChange({
-          type: 'add',
-          event,
-          version: ++this.version
-        });
-      }
+      this._queueChange({
+        type: 'add',
+        event,
+        version: ++this.version
+      });
 
       return event;
     });
@@ -117,24 +109,10 @@ export class EventStore {
       throw new Error(`Event with id ${eventId} not found`);
     }
 
-    // Remove old indices
-    this._unindexEvent(existingEvent);
-
     // Create updated event
     const updatedEvent = existingEvent.clone(updates);
 
-    // Store updated event
-    this.events.set(eventId, updatedEvent);
-
-    // Update cache with new event data
-    this.optimizer.cache(eventId, updatedEvent, 'event');
-
-    // Clear query and date range caches since results may have changed
-    this.optimizer.queryCache.clear();
-    this.optimizer.dateRangeCache.clear();
-
-    // Re-index
-    this._indexEvent(updatedEvent);
+    this._replaceEvent(existingEvent, updatedEvent);
 
     // Notify listeners
     this._notifyChange({
@@ -147,6 +125,31 @@ export class EventStore {
     return updatedEvent;
   }
 
+  /**
+   * 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
+   */
+  _replaceEvent(existingEvent, replacement) {
+    // Remove old indices
+    this._unindexEvent(existingEvent);
+
+    // Store replacement
+    this.events.set(replacement.id, replacement);
+
+    // Update cache with new event data
+    this.optimizer.cache(replacement.id, replacement, 'event');
+
+    // Clear query and date range caches since results may have changed
+    this.optimizer.queryCache.clear();
+    this.optimizer.dateRangeCache.clear();
+
+    // Re-index
+    this._indexEvent(replacement);
+  }
+
   /**
    * Remove an event from the store
    * @param {string} eventId - The event ID to remove
@@ -158,16 +161,7 @@ export class EventStore {
       return false;
     }
 
-    // Remove from primary storage
-    this.events.delete(eventId);
-
-    // Invalidate caches
-    this.optimizer.eventCache.delete(eventId);
-    this.optimizer.queryCache.clear();
-    this.optimizer.dateRangeCache.clear();
-
-    // Remove from indices
-    this._unindexEvent(event);
+    this._detachEvent(event);
 
     // Notify listeners
     this._notifyChange({
@@ -179,6 +173,24 @@ export class EventStore {
     return true;
   }
 
+  /**
+   * Remove an event from storage, caches and indices. Does not notify listeners.
+   * @param {Event} event - Event currently in the store
+   * @private
+   */
+  _detachEvent(event) {
+    // Remove from primary storage
+    this.events.delete(event.id);
+
+    // Invalidate caches
+    this.optimizer.eventCache.delete(event.id);
+    this.optimizer.queryCache.clear();
+    this.optimizer.dateRangeCache.clear();
+
+    // Remove from indices
+    this._unindexEvent(event);
+  }
+
   /**
    * Get an event by ID
    * @param {string} eventId - The event ID
@@ -705,6 +717,118 @@ export class EventStore {
     this.commitBatch();
   }
 
+  /**
+   * 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, options = {}) {
+    const { removeMissing = true, isEquivalent = Event.isEquivalent } = options;
+
+    if (!events || typeof events[Symbol.iterator] !== 'function') {
+      throw new Error('reconcile() expects an iterable of events');
+    }
+    if (typeof isEquivalent !== 'function') {
+      throw new Error('reconcile() option isEquivalent must be a function');
+    }
+
+    return this.optimizer.measure('reconcile', () => {
+      // Normalize and validate everything before touching the store
+      /** @type {Map<string, Event>} */
+      const incoming = new Map();
+      for (const eventData of events) {
+        const event = eventData instanceof Event ? eventData : new Event(eventData);
+        if (incoming.has(event.id)) {
+          throw new Error(`Duplicate event id in reconcile input: ${event.id}`);
+        }
+        incoming.set(event.id, event);
+      }
+
+      /** @type {import('../types.js').ReconcileResult} */
+      const result = { added: [], updated: [], removed: [], unchanged: [] };
+
+      // Nest inside an existing batch if one is open, otherwise own one
+      const ownsBatch = !this.isBatchMode;
+      if (ownsBatch) {
+        this.startBatch(true);
+      }
+
+      try {
+        if (removeMissing) {
+          for (const existing of Array.from(this.events.values())) {
+            if (!incoming.has(existing.id)) {
+              this._detachEvent(existing);
+              this._queueChange({ type: 'remove', event: existing, version: ++this.version });
+              result.removed.push(existing);
+            }
+          }
+        }
+
+        for (const event of incoming.values()) {
+          const existing = this.events.get(event.id);
+          if (!existing) {
+            this.events.set(event.id, event);
+            this.optimizer.cache(event.id, event, 'event');
+            this._indexEvent(event);
+            this._queueChange({ type: 'add', event, version: ++this.version });
+            result.added.push(event);
+          } else if (existing === event || isEquivalent(existing, event)) {
+            result.unchanged.push(existing);
+          } else {
+            this._replaceEvent(existing, event);
+            this._queueChange({
+              type: 'update',
+              event,
+              oldEvent: existing,
+              version: ++this.version
+            });
+            result.updated.push({ event, oldEvent: existing });
+          }
+        }
+
+        if (result.added.length > 0) {
+          // Newly indexed events may change range/query results
+          this.optimizer.queryCache.clear();
+          this.optimizer.dateRangeCache.clear();
+        }
+      } catch (error) {
+        if (ownsBatch) {
+          this.rollbackBatch();
+        }
+        throw error;
+      }
+
+      if (ownsBatch) {
+        this.commitBatch();
+      }
+
+      return result;
+    });
+  }
+
   /**
    * Subscribe to store changes
    * @param {Function} callback - Callback function
@@ -949,6 +1073,19 @@ export class EventStore {
    * Notify listeners of changes
    * @private
    */
+  /**
+   * Deliver a change now, or queue it when a batch is open
+   * @param {import('../types.js').EventStoreChange} change - Change to deliver
+   * @private
+   */
+  _queueChange(change) {
+    if (this.isBatchMode) {
+      this.batchNotifications.push(change);
+    } else {
+      this._notifyChange(change);
+    }
+  }
+
   _notifyChange(change) {
     for (const listener of this.listeners) {
       try {
@@ -1066,7 +1203,7 @@ export class EventStore {
       this.batchBackup = null;
 
       // Clear cache
-      this.optimizer.clearCache();
+      this.clearCaches();
     }
 
     this.batchNotifications = [];