@forcecalendar/core 2.4.0 → 2.5.1

package/types/events/RecurrenceEngineV2.d.ts

@@ -15,10 +15,15 @@ export declare class RecurrenceEngineV2 {
     /**
      * Expand recurring event with advanced handling
      *
-     * 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.
+     * Occurrences before rangeStart are skipped without being generated for
+     * the rules seekToRange can seek: DAILY (without BYHOUR), WEEKLY (with or
+     * without BYDAY), HOURLY and MINUTELY. Such a series that started years
+     * before the queried window is expanded at the same cost as one that
+     * started yesterday. MONTHLY and YEARLY rules, and DAILY with BYHOUR,
+     * are stepped from DTSTART; they take few enough steps per year that
+     * this is cheap, but an expansion that would need more than
+     * MAX_ITERATIONS_HARD_LIMIT steps is truncated (with one console.warn
+     * per process).
      *
      * @param {import('./Event.js').Event} event - Recurring event
      * @param {Date} rangeStart - Start of expansion range
@@ -30,7 +35,7 @@ export declare class RecurrenceEngineV2 {
      * @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 {Array} Expanded occurrences
+     * @returns {import('../types.js').ExpandedOccurrence[]} Expanded occurrences
      */
     expandEvent(event: import('./Event.js').Event, rangeStart: Date, rangeEnd: Date, options?: {
         maxOccurrences?: number;
@@ -38,14 +43,107 @@ export declare class RecurrenceEngineV2 {
         includeCancelled?: boolean;
         timezone?: string;
         handleDST?: boolean;
-    }): any[];
+    }): 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 (daily, 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 (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
+     */
+    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
+     * transitions (plain DAILY and WEEKLY, HOURLY, MINUTELY) and to WEEKLY
+     * rules with BYDAY, whose steps repeat in a weekly cycle; the steps that
+     * cross a transition are taken with getNextDate so the result is exactly
      * what stepping from DTSTART would produce. Never seeks past UNTIL, and
      * counts skipped steps against COUNT.
      *
@@ -56,6 +154,40 @@ export declare class RecurrenceEngineV2 {
      * @param {string} timezone - Expansion timezone
      */
     seekToRange(state: Object, rule: Object, rangeStart: Date, rangeEnd: Date, timezone: string): void;
+    /**
+     * Seek for WEEKLY rules with BYDAY. getNextWeekly picks the next weekday
+     * from the BYDAY list (in list order), so the step from each weekday is
+     * fixed and the walk from DTSTART settles into a cycle of weekdays that
+     * repeats every whole number of weeks. The cursor is stepped one
+     * occurrence at a time until it is on that cycle (at most six steps),
+     * then whole cycles are skipped arithmetically between system-timezone
+     * transitions, exactly as seekToRange does for fixed steps.
+     * @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
+     * @private
+     */
+    private _seekWeekCycle;
+    /**
+     * Days getNextWeekly adds from each weekday (index 0-6) for a WEEKLY
+     * rule with BYDAY, or null when the rule cannot be seeked (an invalid
+     * interval or day code, which the expansion loop handles as before)
+     * @param {Object} rule - Parsed recurrence rule
+     * @returns {number[]|null} Delta table indexed by Date#getDay()
+     * @private
+     */
+    private _weekdayDeltas;
+    /**
+     * Weekday numbers (Date#getDay) of a rule's BYDAY entries in ascending
+     * order, computed once per parsed rule. Invalid day codes map to
+     * undefined and sort last.
+     * @param {Object} rule - Parsed recurrence rule with byDay
+     * @returns {number[]} Sorted weekday numbers
+     * @private
+     */
+    private _weekdayTargets;
     /**
      * Milliseconds per step for rules getNextDate advances by a fixed
      * duration while the system UTC offset is constant
@@ -111,12 +243,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
      */
@@ -150,8 +288,27 @@ export declare class RecurrenceEngineV2 {
     getDateKey(date: any): string;
     /**
      * Create cache key
+     *
+     * When given the event itself the key also covers everything the
+     * expansion depends on (DTSTART, end, recurrence rule), so a series that
+     * is updated, replaced or re-added under the same id can never be served
+     * a stale expansion. Keys always start with `<eventId>_`, which is what
+     * {@link RecurrenceEngineV2#clearEventCache} matches on.
+     * @param {import('./Event.js').Event|string} event - Recurring event, or just its id
+     * @param {Date} start - Start of expansion range
+     * @param {Date} end - End of expansion range
+     * @param {Object} options - Expansion options
+     * @returns {string} Cache key
+     */
+    getCacheKey(event: import('./Event.js').Event | string, start: Date, end: Date, options: Object): string;
+    /**
+     * Stable text form of a recurrence rule for cache keys. A rule that
+     * cannot be serialised gets a unique fingerprint, i.e. is never cached.
+     * @param {string|Object} rule - RRULE string or rule object
+     * @returns {string} Fingerprint
+     * @private
      */
-    getCacheKey(eventId: any, start: any, end: any, options: any): string;
+    private _ruleFingerprint;
     /**
      * Cache occurrences
      */
@@ -160,6 +317,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.4.0";
+export declare const VERSION = "2.5.1";
 export { Calendar as default } from './calendar/Calendar.js';

package/types/integration/EnhancedCalendar.d.ts

@@ -13,16 +13,51 @@ export declare class EnhancedCalendar extends Calendar {
         expansionTime: never[];
         renderTime: never[];
     };
+    _unsubscribeCacheInvalidation: Function;
     _clearReindexTimeout: (() => void) | null | undefined;
     constructor(config: any);
+    /**
+     * Invalidate the enhanced engine's cached expansions for a store change
+     * @param {import('../types.js').EventStoreChange} change - Store change
+     * @private
+     */
+    private _invalidateOccurrenceCache;
     /**
      * Enhanced search with worker support
      */
     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 +66,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

@@ -789,6 +789,24 @@ export type EventsSetPayload = {
      */
     unchanged: import('./events/Event.js').Event[];
 };
+export type EventSelectPayload = {
+    /**
+     * - The stored event (the master for an occurrence id)
+     */
+    event: import('./events/Event.js').Event;
+    /**
+     * - Id of the stored event, as kept in the state's selectedEventId
+     */
+    eventId: string;
+    /**
+     * - The occurrence id that was selected, or null for a stored event's id
+     */
+    occurrenceId: string | null;
+    /**
+     * - The selected occurrence as in view data, or null
+     */
+    occurrence: import('./events/Event.js').Event | null;
+};
 export type QueryFilters = {
     /**
      * - Start date for range query
@@ -856,6 +874,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 = {
     /**
@@ -1267,6 +1411,14 @@ export type ConflictSummary = {
  * @property {import('./events/Event.js').Event[]} removed - Events removed by the operation
  * @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
@@ -1288,6 +1440,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