@forcecalendar/core 2.3.0 → 2.5.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
@@ -304,6 +346,58 @@
  * @property {Date} start - Occurrence start date
  * @property {Date} end - Occurrence end date
  * @property {string} recurringEventId - ID of the parent recurring event
+ * @property {string} [timezone] - Timezone the occurrence was expanded in
+ * @property {Date} [originalStart] - Start of the series (DTSTART)
+ */
+
+/**
+ * Window for lazy occurrence iteration. Both bounds are exclusive unless
+ * `inclusive` is set: an occurrence starting exactly at `after` or `before`
+ * is skipped by default, so iterating from a known occurrence's start
+ * continues the series without repeating it. Omit a bound to leave that
+ * end of the window open.
+ * @typedef {Object} OccurrenceIteratorOptions
+ * @property {Date|number} [after] - Only occurrences starting after this instant (Date or timestamp)
+ * @property {Date|number} [before] - Only occurrences starting before this instant (Date or timestamp)
+ * @property {boolean} [inclusive=false] - Treat `after` and `before` as closed bounds
+ * @property {string} [timezone] - Timezone for expansion (defaults to the event's)
+ */
+
+/**
+ * Options for lazy occurrence iteration through RecurrenceEngineV2,
+ * EventStore and Calendar: the OccurrenceIteratorOptions window plus the
+ * expansion switches RecurrenceEngineV2.expandEvent accepts.
+ * @typedef {Object} ExpandedOccurrenceIteratorOptions
+ * @property {Date|number} [after] - Only occurrences starting after this instant (Date or timestamp)
+ * @property {Date|number} [before] - Only occurrences starting before this instant (Date or timestamp)
+ * @property {boolean} [inclusive=false] - Treat `after` and `before` as closed bounds
+ * @property {string} [timezone] - Timezone for expansion (defaults to the event's)
+ * @property {boolean} [includeModified=true] - Apply stored instance modifications
+ * @property {boolean} [includeCancelled=false] - Yield exception dates as cancelled occurrences
+ * @property {boolean} [handleDST=true] - Adjust occurrences across DST transitions
+ */
+
+/**
+ * Occurrence produced by RecurrenceEngineV2 (and therefore by EventStore
+ * and Calendar occurrence queries)
+ * @typedef {Object} ExpandedOccurrence
+ * @property {string} id - Occurrence ID (`<eventId>_<startTimestamp>` for recurring events)
+ * @property {string} [recurringEventId] - ID of the parent recurring event
+ * @property {string} title - Event title
+ * @property {Date} start - Occurrence start date
+ * @property {Date} end - Occurrence end date
+ * @property {Date} [startUTC] - Occurrence start in UTC
+ * @property {Date} [endUTC] - Occurrence end in UTC
+ * @property {string} timezone - Timezone the occurrence was expanded in
+ * @property {Date} [originalStart] - Start of the series (DTSTART)
+ * @property {boolean} allDay - Whether the event is all-day
+ * @property {string} [description] - Event description
+ * @property {string} [location] - Event location
+ * @property {string[]} [categories] - Event categories
+ * @property {EventStatus} [status] - 'confirmed', or 'cancelled' for exception dates yielded with includeCancelled
+ * @property {string} [cancellationReason] - Reason recorded for a cancelled occurrence
+ * @property {boolean} isRecurring - Whether the occurrence belongs to a recurring series
+ * @property {boolean} [isModified] - Whether a stored instance modification was applied
  */
 
 /**

package/package.json

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

package/types/calendar/Calendar.d.ts

@@ -80,14 +80,20 @@ export declare class Calendar {
     addEvent(eventData: import('../events/Event.js').Event | import('../types.js').EventData): import('../events/Event.js').Event;
     /**
      * 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: string, updates: Object): Event;
     /**
      * 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: string): boolean;
@@ -99,20 +105,81 @@ export declare class Calendar {
     deleteEvent(eventId: string): boolean;
     /**
      * 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: string): Event | null;
     /**
-     * Get all events
+     * Get all stored events (recurring masters, never their occurrences)
      * @returns {Event[]}
      */
     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
@@ -120,12 +187,23 @@ export declare class Calendar {
      */
     queryEvents(filters: Object): Event[];
     /**
-     * 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[]}
      */
     getEventsForDate(date: Date, timezone?: string): Event[];
+    /**
+     * 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: Date, end: Date, timezone?: string): Map<string, Event[]>;
     /**
      * Get events in a date range
      * @param {Date} start - Start date
@@ -134,6 +212,55 @@ export declare class Calendar {
      * @returns {Event[]}
      */
     getEventsInRange(start: Date, end: Date, timezone?: string): Event[];
+    /**
+     * 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: string, options?: import('../types.js').ExpandedOccurrenceIteratorOptions): Generator<import('../types.js').ExpandedOccurrence, void, undefined>;
+    /**
+     * 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: string, after?: Date | number, options?: import('../types.js').ExpandedOccurrenceIteratorOptions): import('../types.js').ExpandedOccurrence | null;
+    /**
+     * 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: string, count: number, options?: import('../types.js').ExpandedOccurrenceIteratorOptions): import('../types.js').ExpandedOccurrence[];
     /**
      * Set the calendar's timezone
      * @param {string} timezone - IANA timezone identifier

package/types/events/Event.d.ts

@@ -23,6 +23,12 @@ export declare class Event {
     textColor: string | undefined;
     recurring: boolean | undefined;
     recurrenceRule: string | import("../types.js").RecurrenceRule | undefined;
+    /** @type {boolean} True when this instance is one occurrence of a recurring series */
+    isOccurrence: boolean;
+    /** @type {string|null} Id of the recurring master this occurrence belongs to */
+    recurringEventId: string | null;
+    /** @type {Date|null} Start of this occurrence as generated by the recurrence rule */
+    occurrenceStart: Date | null;
     _originalTimeZone: string | null;
     status: import("../types.js").EventStatus | undefined;
     visibility: import("../types.js").EventVisibility | undefined;
@@ -156,6 +162,75 @@ 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;
+    /**
+     * 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: string, occurrenceStart: Date | number | string): string;
+    /**
+     * 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: string): {
+        recurringEventId: string;
+        occurrenceStart: Date;
+    } | null;
     /**
      * Add an attendee to the event
      * @param {import('../types.js').Attendee} attendee - Attendee to add