@forcecalendar/core 2.4.0 → 2.5.1

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

package/core/integration/EnhancedCalendar.js

@@ -24,6 +24,40 @@ export class EnhancedCalendar extends Calendar {
 
     // Setup event listeners for real-time indexing
     this.setupRealtimeIndexing();
+
+    // The enhanced engine keeps its own expansion cache, so drop the entries
+    // of every series the store changes
+    this._unsubscribeCacheInvalidation = this.eventStore.subscribe(change =>
+      this._invalidateOccurrenceCache(change)
+    );
+  }
+
+  /**
+   * Invalidate the enhanced engine's cached expansions for a store change
+   * @param {import('../types.js').EventStoreChange} change - Store change
+   * @private
+   */
+  _invalidateOccurrenceCache(change) {
+    const engine = this.recurrenceEngine;
+    if (!engine || !change) {
+      return;
+    }
+    switch (change.type) {
+      case 'add':
+      case 'update':
+      case 'remove':
+        if (change.event) {
+          engine.clearEventCache(change.event.id);
+        }
+        break;
+      case 'batch':
+        for (const entry of change.changes || []) {
+          this._invalidateOccurrenceCache(entry);
+        }
+        break;
+      default:
+        engine.occurrenceCache.clear();
+    }
   }
 
   /**
@@ -56,29 +90,38 @@ export class EnhancedCalendar extends Calendar {
 
   /**
    * Get events with enhanced recurrence expansion
+   *
+   * Regular events overlapping the range are returned as stored. Every
+   * recurring series in the store is expanded with this calendar's
+   * RecurrenceEngineV2 (so instance modifications and cancellations apply),
+   * including series that started before the range. Occurrences are the
+   * engine's plain occurrence objects, with the id `<masterId>_<startMs>`
+   * (see `Event.occurrenceId`), `recurringEventId`, `isOccurrence: true` and
+   * `occurrenceStart`.
    */
   getEventsInRange(startDate, endDate, options = {}) {
     const startTime = performance.now();
+    const rangeStart = new Date(startDate);
+    const rangeEnd = new Date(endDate);
 
-    const regularEvents = [];
-    const recurringEvents = [];
+    // Recurring masters are represented by their occurrences below
+    const regularEvents = this.eventStore
+      .getEventsInRange(rangeStart, rangeEnd, false)
+      .filter(event => !event.recurring);
 
-    // Separate regular and recurring events
-    const allEvents = this.eventStore.getEventsInRange(startDate, endDate, false);
-
-    for (const event of allEvents) {
-      if (event.recurring) {
-        recurringEvents.push(event);
-      } else {
-        regularEvents.push(event);
-      }
-    }
+    // A series that started before the range can still occur inside it, so
+    // every recurring series is a candidate; the engine selects by range.
+    const recurringEvents = this.eventStore.queryEvents({ recurring: true });
 
     // Expand recurring events with enhanced engine
     const expandedOccurrences = [];
 
     for (const event of recurringEvents) {
-      const occurrences = this.recurrenceEngine.expandEvent(event, startDate, endDate, {
+      // Look back one event duration so occurrences that began before the
+      // range but overlap it are found
+      const duration = Math.max(0, event.end - event.start);
+      const expandStart = new Date(rangeStart.getTime() - duration);
+      const occurrences = this.recurrenceEngine.expandEvent(event, expandStart, rangeEnd, {
         maxOccurrences: options.maxOccurrences || 365,
         includeModified: options.includeModified !== false,
         includeCancelled: options.includeCancelled || false,
@@ -86,7 +129,16 @@ export class EnhancedCalendar extends Calendar {
         handleDST: options.handleDST !== false
       });
 
-      expandedOccurrences.push(...occurrences);
+      for (const occurrence of occurrences) {
+        if (occurrence.end < rangeStart || occurrence.start > rangeEnd) {
+          continue;
+        }
+        expandedOccurrences.push({
+          ...occurrence,
+          isOccurrence: true,
+          occurrenceStart: new Date(occurrence.start)
+        });
+      }
     }
 
     const endTime = performance.now();
@@ -129,6 +181,62 @@ export class EnhancedCalendar extends Calendar {
     });
   }
 
+  /**
+   * Lazily iterate the occurrences of an event through the enhanced
+   * engine, so occurrences changed with modifyOccurrence or cancelled with
+   * cancelOccurrence are reflected. Same semantics as
+   * Calendar#iterateOccurrences.
+   * @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 = {}) {
+    const query = this._occurrenceQuery(eventId, options);
+    return this.recurrenceEngine.iterateOccurrences(query.event, query.options);
+  }
+
+  /**
+   * First occurrence of an event after an instant through the enhanced
+   * engine, or null. Same semantics as Calendar#getNextOccurrence.
+   * @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 = {}) {
+    const query = this._occurrenceQuery(eventId, options);
+    return this.recurrenceEngine.nextOccurrence(query.event, after, query.options);
+  }
+
+  /**
+   * The first `count` occurrences of an event through the enhanced
+   * engine. Same semantics as Calendar#takeOccurrences.
+   * @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 = {}) {
+    const query = this._occurrenceQuery(eventId, options);
+    return this.recurrenceEngine.takeOccurrences(query.event, count, query.options);
+  }
+
+  /**
+   * Resolve an occurrence query to the stored event and its options, with
+   * the timezone defaulted as getEventsInRange does
+   * @private
+   */
+  _occurrenceQuery(eventId, options) {
+    const event = this.eventStore.getEvent(eventId);
+    if (!event) {
+      throw new Error(`Event with id ${eventId} not found`);
+    }
+    return { event, options: { ...options, timezone: options.timezone || event.timeZone } };
+  }
+
   /**
    * Bulk operations for recurring events
    */
@@ -366,6 +474,10 @@ export class EnhancedCalendar extends Calendar {
       this._clearReindexTimeout();
       this._clearReindexTimeout = null;
     }
+    if (typeof this._unsubscribeCacheInvalidation === 'function') {
+      this._unsubscribeCacheInvalidation();
+      this._unsubscribeCacheInvalidation = null;
+    }
 
     // Clean up worker
     if (this.searchManager) {

package/core/timezone/TimezoneManager.js

@@ -10,6 +10,11 @@ import { TimezoneDatabase } from './TimezoneDatabase.js';
 // Singleton instance for shared use across the application
 let sharedInstance = null;
 
+// Timezone databases know only local mean time before the 19th century, so
+// transition scans check a span that ends before this instant at its ends
+// rather than probing it week by week
+const PRE_TZDATA_FLOOR_MS = Date.UTC(1800, 0, 1);
+
 export class TimezoneManager {
   /**
    * Get the shared singleton instance of TimezoneManager
@@ -215,19 +220,43 @@ export class TimezoneManager {
     }
     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) };
+    if (!cached) {
+      cached = {
+        from: fromMs,
+        to: toMs,
+        transitions: this._scanTransitions(timezone, fromMs, toMs)
+      };
       this.transitionCache.set(timezone, cached);
+    } else {
+      // Extend coverage incrementally so only the uncovered span is scanned
+      if (fromMs < cached.from) {
+        cached.transitions = this._scanTransitions(timezone, fromMs, cached.from).concat(
+          cached.transitions
+        );
+        cached.from = fromMs;
+      }
+      if (toMs > cached.to) {
+        cached.transitions = cached.transitions.concat(
+          this._scanTransitions(timezone, cached.to, toMs)
+        );
+        cached.to = toMs;
+      }
     }
-    for (const t of cached.transitions) {
-      if (t > fromMs) {
-        return t <= toMs ? t : Infinity;
+    // First transition after fromMs; the list is sorted
+    const transitions = cached.transitions;
+    let lo = 0;
+    let hi = transitions.length;
+    while (lo < hi) {
+      const mid = (lo + hi) >>> 1;
+      if (transitions[mid] > fromMs) {
+        hi = mid;
+      } else {
+        lo = mid + 1;
       }
     }
+    if (lo < transitions.length && transitions[lo] <= toMs) {
+      return transitions[lo];
+    }
     return Infinity;
   }
 
@@ -247,6 +276,13 @@ export class TimezoneManager {
     const offsetAt = ms => this.getTimezoneOffset(new Date(ms), timezone);
     let lo = fromMs;
     let loOffset = offsetAt(lo);
+    // Timezone databases know only local mean time before the 19th century:
+    // that era has a single offset and is skipped in one step (probing it
+    // week by week could take minutes for a very old DTSTART)
+    if (lo < PRE_TZDATA_FLOOR_MS) {
+      lo = Math.min(toMs, PRE_TZDATA_FLOOR_MS);
+      loOffset = offsetAt(lo);
+    }
     while (lo < toMs) {
       const hi = Math.min(lo + WEEK, toMs);
       const hiOffset = offsetAt(hi);

package/core/types.js

@@ -324,6 +324,15 @@
  * @property {import('./events/Event.js').Event[]} unchanged - Events left untouched
  */
 
+/**
+ * Payload of the Calendar `eventSelect` event
+ * @typedef {Object} EventSelectPayload
+ * @property {import('./events/Event.js').Event} event - The stored event (the master for an occurrence id)
+ * @property {string} eventId - Id of the stored event, as kept in the state's selectedEventId
+ * @property {string|null} occurrenceId - The occurrence id that was selected, or null for a stored event's id
+ * @property {import('./events/Event.js').Event|null} occurrence - The selected occurrence as in view data, or null
+ */
+
 /**
  * @typedef {Object} QueryFilters
  * @property {Date} [start] - Start date for range query
@@ -346,6 +355,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.4.0",
+  "version": "2.5.1",
   "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,12 +105,39 @@ 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
+     * Resolve an event id or occurrence id to the id of the stored event it
+     * refers to: the id itself for a stored event, the master's id for an
+     * occurrence id taken from view data, `null` when nothing stored matches.
+     * See `EventStore.resolveEventId`.
+     *
+     * @example
+     * calendar.resolveEventId('standup_1750028400000'); // 'standup'
+     * calendar.resolveEventId('unknown'); // null
+     *
+     * @param {string} id - Event id or occurrence id
+     * @returns {string|null} Id of the stored event, or null
+     */
+    resolveEventId(id: string): string | null;
+    /**
+     * Get the occurrence an occurrence id from view data stands for, as an
+     * {@link Event} like the ones the views hold, or `null` when the id is
+     * not an occurrence of a stored recurring series. See
+     * `EventStore.getOccurrence`.
+     * @param {string} occurrenceId - Occurrence id (`<masterId>_<startMs>`)
+     * @returns {Event|null} The occurrence, or null
+     */
+    getOccurrence(occurrenceId: string): Event | null;
+    /**
+     * Get all stored events (recurring masters, never their occurrences)
      * @returns {Event[]}
      */
     getEvents(): Event[];
@@ -156,9 +189,16 @@ export declare class Calendar {
      * @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
+     * @throws {Error} If `events` is not iterable, 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;
+    /**
+     * Throw a clear error when a snapshot is not iterable
+     * @param {*} events - Candidate snapshot
+     * @param {string} method - Calling method, for the message
+     * @private
+     */
+    private _assertIterable;
     /**
      * Get the event store's change counter
      *
@@ -177,12 +217,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
@@ -191,6 +242,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 - Event id or occurrence id (resolved to its master)
+     * @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 - Event id or occurrence id (resolved to its master)
+     * @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 - Event id or occurrence id (resolved to its master)
+     * @param {number} count - Maximum number of occurrences to return (fractions are floored)
+     * @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
@@ -293,7 +393,21 @@ export declare class Calendar {
     private _getListViewData;
     /**
      * Select an event
-     * @param {string} eventId - Event ID to select
+     *
+     * Accepts a stored event's id or an occurrence id taken from view data
+     * (see {@link Event.occurrenceId}). Either way the stored event is what
+     * gets selected: `selectedEventId` in the state holds its id, so it can
+     * always be looked up with {@link Calendar#getEvent}. The `eventSelect`
+     * payload carries the stored `event`, its `eventId`, and for an
+     * occurrence id also `occurrenceId` and the `occurrence` itself (an
+     * {@link Event} as in view data, or null when the series has no
+     * occurrence at that instant). Nothing happens for an unknown id.
+     *
+     * @example
+     * calendar.on('eventSelect', ({ event, occurrence }) => open(occurrence || event));
+     * calendar.selectEvent(chip.dataset.eventId);
+     *
+     * @param {string} eventId - Event id or occurrence id to select
      */
     selectEvent(eventId: string): void;
     /**

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;
@@ -161,6 +167,8 @@ export declare class Event {
      * Scalars are compared with strict equality, dates by timestamp and
      * structured fields (recurrence rule, organizer, attendees, reminders,
      * categories, attachments, conference data, metadata) structurally.
+     * The `color` shorthand is not listed: normalization copies it into
+     * `backgroundColor` and `borderColor`, which are compared instead.
      * @type {ReadonlyArray<string>}
      */
     static EQUIVALENCE_FIELDS: ReadonlyArray<string>;
@@ -179,6 +187,14 @@ export declare class Event {
      * describe the same event. Two events with different ids are never
      * equivalent.
      *
+     * Two things to know when building snapshots for `reconcile()`:
+     * - `attendees`, `reminders`, `categories` and `attachments` are compared
+     *   in order, so the same attendees listed in a different order count as
+     *   a change.
+     * - Only the top-level dates are normalized. Values inside `metadata` are
+     *   compared as given, so a `Date` and its ISO string are not equivalent
+     *   there; keep metadata in one representation.
+     *
      * This is the default comparator used by `EventStore.reconcile()` to decide
      * whether an incoming snapshot entry replaces the stored event.
      *
@@ -192,6 +208,40 @@ export declare class Event {
      * @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
+     * @throws {TypeError} If occurrenceStart is not a valid date
+     */
+    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