@forcecalendar/core 2.3.0 → 2.5.0

package/types/events/RecurrenceEngineV2.d.ts

@@ -10,16 +10,151 @@ export declare class RecurrenceEngineV2 {
     modifiedInstances: Map<any, any>;
     exceptionStore: Map<any, any>;
     static MAX_OCCURRENCES_HARD_LIMIT: number;
+    static MAX_ITERATIONS_HARD_LIMIT: number;
     constructor();
     /**
      * 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
-     * @returns {Array} Expanded occurrences
+     * @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 {import('../types.js').ExpandedOccurrence[]} Expanded occurrences
      */
-    expandEvent(event: Event, rangeStart: Date, rangeEnd: Date, options?: Object): any[];
+    expandEvent(event: import('./Event.js').Event, rangeStart: Date, rangeEnd: Date, options?: {
+        maxOccurrences?: number;
+        includeModified?: boolean;
+        includeCancelled?: boolean;
+        timezone?: string;
+        handleDST?: boolean;
+    }): import('../types.js').ExpandedOccurrence[];
+    /**
+     * Lazily iterate the occurrences of an event in chronological order.
+     *
+     * Yields what expandEvent returns for the window, one occurrence at a
+     * time and without the expansion cache: stored instance modifications
+     * and exceptions are applied as each occurrence is produced, so changes
+     * made through addModifiedInstance or addException are visible on the
+     * next pull. Rules seekToRange can seek (plain daily and weekly, hourly,
+     * minutely) jump straight to `after`, and DST transitions are scanned
+     * lazily ahead of the cursor instead of for the whole window up front.
+     *
+     * Both bounds are exclusive unless `inclusive` is set: an occurrence that
+     * starts exactly at `after` or `before` is skipped by default, so
+     * iterating from a known occurrence's start continues the series without
+     * repeating it; with `inclusive: true` the window is closed on both ends
+     * like expandEvent's range. A non-recurring event yields its single
+     * occurrence when it falls inside the window. Iteration ends at COUNT or
+     * UNTIL, at `before`, or — as a guard for rules that produce no
+     * occurrences — after MAX_ITERATIONS_HARD_LIMIT consecutive steps
+     * without one. The generator is single-use; call again for a fresh one.
+     *
+     * @example
+     * const engine = new RecurrenceEngineV2();
+     * for (const occurrence of engine.iterateOccurrences(event, { after: new Date() })) {
+     *   if (occurrence.start > deadline) break;
+     *   schedule(occurrence);
+     * }
+     *
+     * @param {import('./Event.js').Event} event - The event to iterate
+     * @param {import('../types.js').ExpandedOccurrenceIteratorOptions} [options={}] - Window and expansion options
+     * @returns {Generator<import('../types.js').ExpandedOccurrence, void, undefined>} Occurrences in chronological order
+     * @throws {TypeError} If `after` or `before` is not a valid Date or timestamp
+     */
+    iterateOccurrences(event: import('./Event.js').Event, 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, so passing the start of a known occurrence
+     * returns the one that follows it.
+     *
+     * @example
+     * const upcoming = engine.nextOccurrence(event, new Date());
+     *
+     * @param {import('./Event.js').Event} event - The event to query
+     * @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
+     */
+    nextOccurrence(event: import('./Event.js').Event, 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 so an open-ended series costs only the occurrences taken.
+     * `count` is capped at MAX_OCCURRENCES_HARD_LIMIT; fewer are returned
+     * when the series or the window ends first.
+     *
+     * @example
+     * const nextFive = engine.takeOccurrences(event, 5, { after: new Date() });
+     *
+     * @param {import('./Event.js').Event} event - The event to query
+     * @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
+     */
+    takeOccurrences(event: import('./Event.js').Event, count: number, options?: import('../types.js').ExpandedOccurrenceIteratorOptions): import('../types.js').ExpandedOccurrence[];
+    /**
+     * Yield a non-recurring event's single occurrence if it starts inside
+     * the window
+     * @param {import('./Event.js').Event} event - The event
+     * @param {{ startMs: number, endMs: number }} window - Inclusive bounds
+     * @returns {Generator<import('../types.js').ExpandedOccurrence, void, undefined>}
+     * @private
+     */
+    private _iterateSingle;
+    /**
+     * Lazy counterpart of the expandEvent loop: seeks to the window, then
+     * steps the cursor and yields each in-window occurrence with the same
+     * DST adjustment, exception handling and instance modifications.
+     * @private
+     */
+    private _iterateRule;
+    /**
+     * Apply exceptions and stored instance modifications to a generated
+     * occurrence
+     * @param {import('./Event.js').Event} event - The recurring event
+     * @param {Object} occurrence - Occurrence from generateOccurrence
+     * @param {Object} rule - Parsed recurrence rule
+     * @param {boolean} includeCancelled - Return exception dates as cancelled occurrences
+     * @param {boolean} includeModified - Apply stored instance modifications
+     * @returns {Object|null} The occurrence, or null when it is excluded
+     * @private
+     */
+    private _applyOverrides;
+    /**
+     * 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: Object, rule: Object, rangeStart: Date, rangeEnd: Date, timezone: string): void;
+    /**
+     * 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: Object): number;
     /**
      * Generate a single occurrence with timezone handling
      */
@@ -68,12 +203,18 @@ export declare class RecurrenceEngineV2 {
     /**
      * Find DST transitions in date range
      */
-    findDSTTransitions(start: any, end: any, timezone: any): {
-        date: Date;
-        oldOffset: number;
-        newOffset: number;
-        type: string;
-    }[];
+    findDSTTransitions(start: any, end: any, timezone: any): any[];
+    /**
+     * Walk the scan cursor one day at a time up to untilMs, appending each
+     * offset change. The cursor and last offset persist in `scan`, so the
+     * walk can be resumed later on the same day grid.
+     * @param {{ cursor: Date, lastOffset: number }} scan - Resumable scan position (mutated)
+     * @param {Array} transitions - Transition list to append to
+     * @param {number} untilMs - Scan through this timestamp (inclusive)
+     * @param {string} timezone - Timezone to probe
+     * @private
+     */
+    private _scanDSTTransitions;
     /**
      * Adjust occurrence for DST transitions
      */
@@ -117,6 +258,12 @@ export declare class RecurrenceEngineV2 {
      * Clone occurrence results before returning or caching.
      */
     cloneOccurrences(occurrences: any): any;
+    /**
+     * Clone a single occurrence, copying its Date and array fields.
+     * @param {import('../types.js').ExpandedOccurrence} occurrence - Occurrence to clone
+     * @returns {import('../types.js').ExpandedOccurrence} Independent copy
+     */
+    cloneOccurrence(occurrence: import('../types.js').ExpandedOccurrence): import('../types.js').ExpandedOccurrence;
     /**
      * Clear cache for specific event
      */

package/types/index.d.ts

@@ -18,5 +18,5 @@ export { RRuleParser } from './events/RRuleParser.js';
 export { TimezoneManager } from './timezone/TimezoneManager.js';
 export { ConflictDetector } from './conflicts/ConflictDetector.js';
 export { EnhancedCalendar } from './integration/EnhancedCalendar.js';
-export declare const VERSION = "2.3.0";
+export declare const VERSION = "2.5.0";
 export { Calendar as default } from './calendar/Calendar.js';

package/types/integration/EnhancedCalendar.d.ts

@@ -21,8 +21,36 @@ export declare class EnhancedCalendar extends Calendar {
     search(query: any, options?: {}): Promise<any>;
     /**
      * 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: any, endDate: any, options?: {}): any[];
+    getEventsInRange(startDate: any, endDate: any, options?: {}): (import("../index.js").Event | {
+        id: string;
+        recurringEventId?: string;
+        title: string;
+        start: Date;
+        end: Date;
+        startUTC?: Date;
+        endUTC?: Date;
+        timezone: string;
+        originalStart?: Date;
+        allDay: boolean;
+        description?: string;
+        location?: string;
+        categories?: string[];
+        status?: import("../types.js").EventStatus;
+        cancellationReason?: string;
+        isRecurring: boolean;
+        isModified?: boolean;
+        isOccurrence: boolean;
+        occurrenceStart: Date;
+    })[];
     /**
      * Modify a single occurrence of a recurring event
      */
@@ -31,6 +59,43 @@ export declare class EnhancedCalendar extends Calendar {
      * Cancel a single occurrence of a recurring event
      */
     cancelOccurrence(eventId: any, occurrenceDate: any, reason?: string): void;
+    /**
+     * 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: string, options?: import('../types.js').ExpandedOccurrenceIteratorOptions): Generator<import('../types.js').ExpandedOccurrence, void, undefined>;
+    /**
+     * 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: string, after?: Date | number, options?: import('../types.js').ExpandedOccurrenceIteratorOptions): import('../types.js').ExpandedOccurrence | null;
+    /**
+     * 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: string, count: number, options?: import('../types.js').ExpandedOccurrenceIteratorOptions): import('../types.js').ExpandedOccurrence[];
+    /**
+     * Resolve an occurrence query to the stored event and its options, with
+     * the timezone defaulted as getEventsInRange does
+     * @private
+     */
+    private _occurrenceQuery;
     /**
      * Bulk operations for recurring events
      */

package/types/types.d.ts

@@ -688,7 +688,7 @@ export type EventStoreChange = {
     /**
      * - Type of change
      */
-    type: ('add' | 'update' | 'remove' | 'clear');
+    type: ('add' | 'update' | 'remove' | 'clear' | 'batch');
     /**
      * - Affected event
      */
@@ -701,11 +701,94 @@ export type EventStoreChange = {
      * - Previous events (for clear)
      */
     oldEvents?: import('./events/Event.js').Event[];
+    /**
+     * - Individual changes (for batch)
+     */
+    changes?: EventStoreChange[];
+    /**
+     * - Number of individual changes (for batch)
+     */
+    count?: number;
     /**
      * - Store version number
      */
     version: number;
 };
+export type EventEquivalenceFn = (a: import('./events/Event.js').Event, b: import('./events/Event.js').Event) => boolean;
+export type ReconcileOptions = {
+    /**
+     * - Remove stored events that are absent from the snapshot
+     */
+    removeMissing?: boolean;
+    /**
+     * - Comparator deciding whether a stored event is unchanged (defaults to Event.isEquivalent)
+     */
+    isEquivalent?: EventEquivalenceFn;
+};
+export type ReconciledUpdate = {
+    /**
+     * - Event now in the store
+     */
+    event: import('./events/Event.js').Event;
+    /**
+     * - Event it replaced
+     */
+    oldEvent: import('./events/Event.js').Event;
+};
+export type ReconcileResult = {
+    /**
+     * - Events that were not in the store before
+     */
+    added: import('./events/Event.js').Event[];
+    /**
+     * - Events whose data changed
+     */
+    updated: ReconciledUpdate[];
+    /**
+     * - Events removed from the store
+     */
+    removed: import('./events/Event.js').Event[];
+    /**
+     * - Stored events left untouched (same instances)
+     */
+    unchanged: import('./events/Event.js').Event[];
+};
+export type SetEventsOptions = {
+    /**
+     * - Apply only the differences instead of clearing and re-adding
+     */
+    reconcile?: boolean;
+    /**
+     * - Reconcile only: remove stored events absent from the snapshot
+     */
+    removeMissing?: boolean;
+    /**
+     * - Reconcile only: custom equivalence comparator
+     */
+    isEquivalent?: EventEquivalenceFn;
+};
+export type EventsSetPayload = {
+    /**
+     * - All events after the operation
+     */
+    events: import('./events/Event.js').Event[];
+    /**
+     * - Events added by the operation
+     */
+    added: import('./events/Event.js').Event[];
+    /**
+     * - Events replaced by the operation
+     */
+    updated: ReconciledUpdate[];
+    /**
+     * - Events removed by the operation
+     */
+    removed: import('./events/Event.js').Event[];
+    /**
+     * - Events left untouched
+     */
+    unchanged: import('./events/Event.js').Event[];
+};
 export type QueryFilters = {
     /**
      * - Start date for range query
@@ -773,6 +856,132 @@ export type EventOccurrence = {
      * - ID of the parent recurring event
      */
     recurringEventId: string;
+    /**
+     * - Timezone the occurrence was expanded in
+     */
+    timezone?: string;
+    /**
+     * - Start of the series (DTSTART)
+     */
+    originalStart?: Date;
+};
+export type OccurrenceIteratorOptions = {
+    /**
+     * - Only occurrences starting after this instant (Date or timestamp)
+     */
+    after?: Date | number;
+    /**
+     * - Only occurrences starting before this instant (Date or timestamp)
+     */
+    before?: Date | number;
+    /**
+     * - Treat `after` and `before` as closed bounds
+     */
+    inclusive?: boolean;
+    /**
+     * - Timezone for expansion (defaults to the event's)
+     */
+    timezone?: string;
+};
+export type ExpandedOccurrenceIteratorOptions = {
+    /**
+     * - Only occurrences starting after this instant (Date or timestamp)
+     */
+    after?: Date | number;
+    /**
+     * - Only occurrences starting before this instant (Date or timestamp)
+     */
+    before?: Date | number;
+    /**
+     * - Treat `after` and `before` as closed bounds
+     */
+    inclusive?: boolean;
+    /**
+     * - Timezone for expansion (defaults to the event's)
+     */
+    timezone?: string;
+    /**
+     * - Apply stored instance modifications
+     */
+    includeModified?: boolean;
+    /**
+     * - Yield exception dates as cancelled occurrences
+     */
+    includeCancelled?: boolean;
+    /**
+     * - Adjust occurrences across DST transitions
+     */
+    handleDST?: boolean;
+};
+export type ExpandedOccurrence = {
+    /**
+     * - Occurrence ID (`<eventId>_<startTimestamp>` for recurring events)
+     */
+    id: string;
+    /**
+     * - ID of the parent recurring event
+     */
+    recurringEventId?: string;
+    /**
+     * - Event title
+     */
+    title: string;
+    /**
+     * - Occurrence start date
+     */
+    start: Date;
+    /**
+     * - Occurrence end date
+     */
+    end: Date;
+    /**
+     * - Occurrence start in UTC
+     */
+    startUTC?: Date;
+    /**
+     * - Occurrence end in UTC
+     */
+    endUTC?: Date;
+    /**
+     * - Timezone the occurrence was expanded in
+     */
+    timezone: string;
+    /**
+     * - Start of the series (DTSTART)
+     */
+    originalStart?: Date;
+    /**
+     * - Whether the event is all-day
+     */
+    allDay: boolean;
+    /**
+     * - Event description
+     */
+    description?: string;
+    /**
+     * - Event location
+     */
+    location?: string;
+    /**
+     * - Event categories
+     */
+    categories?: string[];
+    /**
+     * - 'confirmed', or 'cancelled' for exception dates yielded with includeCancelled
+     */
+    status?: EventStatus;
+    /**
+     * - Reason recorded for a cancelled occurrence
+     */
+    cancellationReason?: string;
+    /**
+     * - Whether the occurrence belongs to a recurring series
+     */
+    isRecurring: boolean;
+    /**
+     * - Whether a stored instance modification was applied
+     */
+    isModified?: boolean;
 };
 export type CalendarPlugin = {
     /**
@@ -1142,12 +1351,48 @@ export type ConflictSummary = {
  */
 /**
  * @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
@@ -1169,6 +1414,55 @@ export type ConflictSummary = {
  * @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
  */
 /**
  * @typedef {Object} CalendarPlugin