@forcecalendar/core 2.4.0 → 2.5.0

package/types/events/RecurrenceEngineV2.d.ts

@@ -30,7 +30,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,7 +38,99 @@ 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 (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.
@@ -111,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
      */
@@ -160,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.4.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

@@ -856,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 = {
     /**
@@ -1288,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