@forcecalendar/core 2.4.0 → 2.5.0

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,16 @@ export declare class Calendar {
     deleteEvent(eventId: string): boolean;
     /**
      * Get an event by ID
-     * @param {string} eventId - The event ID
-     * @returns {Event|null}
+     *
+     * Occurrence ids taken from view data (`<masterId>_<startMs>`, see
+     * {@link Event.occurrenceId}) resolve to the stored recurring master, so
+     * every id a renderer hands back can be looked up here.
+     * @param {string} eventId - Event id or occurrence id
+     * @returns {Event|null} The stored event (the master for an occurrence id) or null
      */
     getEvent(eventId: string): Event | null;
     /**
-     * Get all events
+     * Get all stored events (recurring masters, never their occurrences)
      * @returns {Event[]}
      */
     getEvents(): Event[];
@@ -177,12 +187,23 @@ export declare class Calendar {
      */
     queryEvents(filters: Object): Event[];
     /**
-     * Get events for a specific date
+     * Get events for a specific date, with recurring series expanded into occurrences
      * @param {Date} date - The date
      * @param {string} [timezone] - Timezone for the query (defaults to calendar timezone)
      * @returns {Event[]}
      */
     getEventsForDate(date: Date, timezone?: string): Event[];
+    /**
+     * Get the events for every day in a range, keyed by local date (YYYY-MM-DD)
+     *
+     * Recurring series are expanded once for the whole range; this is what the
+     * month and week views use. See `EventStore.getEventsByDate`.
+     * @param {Date} start - First day of the range
+     * @param {Date} end - Last day of the range
+     * @param {string} [timezone] - Timezone for the query (defaults to calendar timezone)
+     * @returns {Map<string, Event[]>} Local date string -> events on that day
+     */
+    getEventsByDate(start: Date, end: Date, timezone?: string): Map<string, Event[]>;
     /**
      * Get events in a date range
      * @param {Date} start - Start date
@@ -191,6 +212,55 @@ export declare class Calendar {
      * @returns {Event[]}
      */
     getEventsInRange(start: Date, end: Date, timezone?: string): Event[];
+    /**
+     * Lazily iterate the occurrences of an event in chronological order.
+     *
+     * Occurrences are produced one at a time, so taking the next few of an
+     * open-ended series does not expand the series. `after` and `before`
+     * are exclusive unless `inclusive` is set; see
+     * RecurrenceEngineV2.iterateOccurrences for the full semantics.
+     *
+     * @example
+     * for (const occurrence of calendar.iterateOccurrences('standup', { after: new Date() })) {
+     *   if (occurrence.start > deadline) break;
+     *   remind(occurrence);
+     * }
+     *
+     * @param {string} eventId - The event ID
+     * @param {import('../types.js').ExpandedOccurrenceIteratorOptions} [options={}] - Window and expansion options
+     * @returns {Generator<import('../types.js').ExpandedOccurrence, void, undefined>} Occurrences in chronological order
+     * @throws {Error} If no event with the ID exists
+     */
+    iterateOccurrences(eventId: string, options?: import('../types.js').ExpandedOccurrenceIteratorOptions): Generator<import('../types.js').ExpandedOccurrence, void, undefined>;
+    /**
+     * First occurrence of an event after an instant, or null when the
+     * series has no occurrence after it. `after` is exclusive unless
+     * `options.inclusive` is set.
+     *
+     * @example
+     * const upcoming = calendar.getNextOccurrence('standup', new Date());
+     *
+     * @param {string} eventId - The event ID
+     * @param {Date|number} [after=null] - Instant to search from (defaults to the series start)
+     * @param {import('../types.js').ExpandedOccurrenceIteratorOptions} [options={}] - Further options
+     * @returns {import('../types.js').ExpandedOccurrence|null} The next occurrence, or null
+     * @throws {Error} If no event with the ID exists
+     */
+    getNextOccurrence(eventId: string, after?: Date | number, options?: import('../types.js').ExpandedOccurrenceIteratorOptions): import('../types.js').ExpandedOccurrence | null;
+    /**
+     * The first `count` occurrences of an event inside a window, generated
+     * lazily. `count` is capped at the engine's MAX_OCCURRENCES_HARD_LIMIT.
+     *
+     * @example
+     * const nextFive = calendar.takeOccurrences('standup', 5, { after: new Date() });
+     *
+     * @param {string} eventId - The event ID
+     * @param {number} count - Maximum number of occurrences to return
+     * @param {import('../types.js').ExpandedOccurrenceIteratorOptions} [options={}] - Window and expansion options
+     * @returns {import('../types.js').ExpandedOccurrence[]} Up to `count` occurrences in chronological order
+     * @throws {Error} If no event with the ID exists
+     */
+    takeOccurrences(eventId: string, count: number, options?: import('../types.js').ExpandedOccurrenceIteratorOptions): import('../types.js').ExpandedOccurrence[];
     /**
      * Set the calendar's timezone
      * @param {string} timezone - IANA timezone identifier

package/types/events/Event.d.ts

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

package/types/events/EventStore.d.ts

@@ -64,9 +64,12 @@ export declare class EventStore {
     addEvent(event: Event | import('../types.js').EventData): Event;
     /**
      * Update an existing event
-     * @param {string} eventId - The event ID
+     *
+     * An occurrence id (see {@link Event.occurrenceId}) updates the recurring
+     * master the occurrence belongs to, i.e. the whole series.
+     * @param {string} eventId - Event id or occurrence id
      * @param {Partial<import('../types.js').EventData>} updates - Properties to update
-     * @returns {Event} The updated event
+     * @returns {Event} The updated event (the master for an occurrence id)
      * @throws {Error} If event not found
      */
     updateEvent(eventId: string, updates: Partial<import('../types.js').EventData>): Event;
@@ -80,7 +83,10 @@ export declare class EventStore {
     private _replaceEvent;
     /**
      * Remove an event from the store
-     * @param {string} eventId - The event ID to remove
+     *
+     * An occurrence id (see {@link Event.occurrenceId}) removes the recurring
+     * master the occurrence belongs to, i.e. the whole series.
+     * @param {string} eventId - Event id or occurrence id
      * @returns {boolean} True if removed, false if not found
      */
     removeEvent(eventId: string): boolean;
@@ -92,10 +98,23 @@ export declare class EventStore {
     private _detachEvent;
     /**
      * Get an event by ID
-     * @param {string} eventId - The event ID
-     * @returns {Event|null} The event or null if not found
+     *
+     * Occurrence ids produced by {@link EventStore#expandRecurringEvent}
+     * (`<masterId>_<startMs>`, see {@link Event.occurrenceId}) resolve to the
+     * stored recurring master they were derived from, so an id taken from view
+     * data can always be looked up. Occurrences themselves are never stored.
+     * @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;
+    /**
+     * Resolve an occurrence id to the stored recurring master it belongs to.
+     * Not cached: the master's own cache entry is the one kept in sync.
+     * @param {string} eventId - Candidate occurrence id
+     * @returns {Event|null} The master event or null
+     * @private
+     */
+    private _resolveOccurrenceMaster;
     /**
      * Get all events
      * @returns {Event[]} Array of all events
@@ -109,11 +128,59 @@ export declare class EventStore {
     queryEvents(filters?: import('../types.js').QueryFilters): Event[];
     /**
      * Get events for a specific date
+     *
+     * Recurring series are expanded for the day, so the result holds their
+     * occurrences (see {@link EventStore#expandRecurringEvent}) rather than the
+     * master events. When building a grid of days use
+     * {@link EventStore#getEventsByDate}, which expands once for the whole range.
      * @param {Date} date - The date to query
      * @param {string} [timezone] - Timezone for the query (defaults to store timezone)
      * @returns {Event[]} Events occurring on the date, sorted by start time
      */
     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 rather than once
+     * per day, which is what a month or week grid needs. Every day in the range
+     * has an entry (an empty array when nothing occurs) and multi-day events
+     * appear under each day they span. Each array is sorted like
+     * {@link EventStore#getEventsForDate}.
+     *
+     * @example
+     * const byDate = store.getEventsByDate(gridStart, gridEnd);
+     * const events = byDate.get(DateUtils.getLocalDateString(cellDate)) || [];
+     *
+     * @param {Date} start - First day of the range
+     * @param {Date} end - Last day of the range
+     * @param {string} [timezone] - Timezone deciding which day an event falls on (defaults to store timezone)
+     * @returns {Map<string, Event[]>} Local date string -> events on that day
+     */
+    getEventsByDate(start: Date, end: Date, timezone?: string): Map<string, Event[]>;
+    /**
+     * Collect the ids of stored events that may occur on a date.
+     * @param {Date} date - The date to query
+     * @returns {Set<string>} Candidate event ids
+     * @private
+     */
+    private _collectDateCandidateIds;
+    /**
+     * Keep the events that overlap a day in the given timezone, sorted by start.
+     * @param {Event[]} events - Candidate events
+     * @param {Date} dayStart - Start of the day
+     * @param {Date} dayEnd - End of the day
+     * @param {string} timezone - Timezone deciding whether an event falls on the day
+     * @returns {Event[]} Events on the day, sorted
+     * @private
+     */
+    private _selectEventsForDay;
+    /**
+     * Comparator ordering events by start time in a timezone, longer events first.
+     * @param {string} timezone - Timezone used for the start comparison
+     * @returns {(a: Event, b: Event) => number} Comparator
+     * @private
+     */
+    private _compareByStart;
     /**
      * Get events that overlap with a given time range
      * @param {Date} start - Start time
@@ -138,6 +205,15 @@ export declare class EventStore {
      * @returns {Array<Event[]>} Array of event groups that overlap
      */
     getOverlapGroups(date: Date, timedOnly?: boolean): Array<Event[]>;
+    /**
+     * Group a list of events into clusters of overlapping time slots
+     * Same result as {@link EventStore#getOverlapGroups} for events already fetched
+     * (for example one day of {@link EventStore#getEventsByDate}).
+     * @param {Event[]} events - Events to group; the array is not modified
+     * @param {boolean} [timedOnly=true] - Only include timed events (not all-day)
+     * @returns {Array<Event[]>} Array of event groups that overlap
+     */
+    groupOverlappingEvents(events: Event[], timedOnly?: boolean): Array<Event[]>;
     /**
      * Calculate positions for overlapping events (for rendering)
      * @param {Event[]} events - Array of overlapping events
@@ -159,6 +235,16 @@ export declare class EventStore {
     getEventsInRange(start: Date, end: Date, expandRecurringOrOptions?: boolean | Object, timezone?: string): Event[];
     /**
      * Expand a recurring event into individual occurrences
+     *
+     * Returns every occurrence that overlaps the range, including ones that
+     * start before it but run into it (multi-day series). Each occurrence is an
+     * {@link Event} cloned from the master with:
+     * - `id` from {@link Event.occurrenceId} (`<masterId>_<startMs>`), stable
+     *   across ranges and resolvable with {@link EventStore#getEvent},
+     * - `isOccurrence: true`, `recurringEventId` and `occurrenceStart`,
+     * - `metadata.recurringEventId`, `metadata.occurrenceId` (same as `id`) and
+     *   `metadata.occurrenceIndex` (position within this expansion).
+     * Non-recurring events are returned as-is in a one-element array.
      * @param {Event} event - The recurring event
      * @param {Date} rangeStart - Start of the expansion range
      * @param {Date} rangeEnd - End of the expansion range
@@ -166,6 +252,78 @@ export declare class EventStore {
      * @returns {Event[]} Array of event occurrences
      */
     expandRecurringEvent(event: Event, rangeStart: Date, rangeEnd: Date, timezone?: string): Event[];
+    /**
+     * Build the Event instance for one occurrence of a recurring master.
+     * @param {Event} event - The recurring master
+     * @param {{start: Date, end: Date, timezone?: string}} occurrence - Engine occurrence
+     * @param {string} eventTimezone - Timezone the series was expanded in
+     * @param {number} index - Position within the current expansion
+     * @returns {Event} Occurrence event
+     * @private
+     */
+    private _createOccurrence;
+    /**
+     * Lazily iterate the occurrences of a stored event in chronological order.
+     *
+     * Occurrences come one at a time from the store's recurrence engine
+     * (RecurrenceEngineV2 by default), so taking the next few occurrences 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. The
+     * expansion timezone defaults to the event's, then the store's.
+     *
+     * @example
+     * for (const occurrence of store.iterateOccurrences('standup', { after: new Date() })) {
+     *   if (occurrence.start > deadline) break;
+     *   remind(occurrence);
+     * }
+     *
+     * @param {string} eventId - The event ID
+     * @param {import('../types.js').ExpandedOccurrenceIteratorOptions} [options={}] - Window and expansion options
+     * @returns {Generator<import('../types.js').ExpandedOccurrence, void, undefined>} Occurrences in chronological order
+     * @throws {Error} If no event with the ID exists
+     */
+    iterateOccurrences(eventId: string, options?: import('../types.js').ExpandedOccurrenceIteratorOptions): Generator<import('../types.js').ExpandedOccurrence, void, undefined>;
+    /**
+     * First occurrence of a stored 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 = store.getNextOccurrence('standup', new Date());
+     *
+     * @param {string} eventId - The event ID
+     * @param {Date|number} [after=null] - Instant to search from (defaults to the series start)
+     * @param {import('../types.js').ExpandedOccurrenceIteratorOptions} [options={}] - Further options
+     * @returns {import('../types.js').ExpandedOccurrence|null} The next occurrence, or null
+     * @throws {Error} If no event with the ID exists
+     */
+    getNextOccurrence(eventId: string, after?: Date | number, options?: import('../types.js').ExpandedOccurrenceIteratorOptions): import('../types.js').ExpandedOccurrence | null;
+    /**
+     * The first `count` occurrences of a stored event inside a window,
+     * generated lazily. `count` is capped at the engine's
+     * MAX_OCCURRENCES_HARD_LIMIT.
+     *
+     * @example
+     * const nextFive = store.takeOccurrences('standup', 5, { after: new Date() });
+     *
+     * @param {string} eventId - The event ID
+     * @param {number} count - Maximum number of occurrences to return
+     * @param {import('../types.js').ExpandedOccurrenceIteratorOptions} [options={}] - Window and expansion options
+     * @returns {import('../types.js').ExpandedOccurrence[]} Up to `count` occurrences in chronological order
+     * @throws {Error} If no event with the ID exists
+     */
+    takeOccurrences(eventId: string, count: number, options?: import('../types.js').ExpandedOccurrenceIteratorOptions): import('../types.js').ExpandedOccurrence[];
+    /**
+     * Resolve an occurrence query to the stored event and its options, with
+     * the timezone defaulted as expandRecurringEvent does
+     * @param {string} eventId - The event ID
+     * @param {Object} options - Caller options
+     * @returns {{ event: Event, options: Object }}
+     * @throws {Error} If no event with the ID exists
+     * @private
+     */
+    private _occurrenceQuery;
     /**
      * Clear all events
      */

package/types/events/RecurrenceEngine.d.ts

@@ -26,6 +26,145 @@ export declare class RecurrenceEngine {
      * @returns {import('../types.js').EventOccurrence[]} Array of occurrence objects with start/end dates
      */
     static expandEvent(event: import('./Event.js').Event, rangeStart: Date, rangeEnd: Date, maxOccurrences?: number, timezone?: string): import('../types.js').EventOccurrence[];
+    /**
+     * Lazily iterate the occurrences of an event in chronological order.
+     *
+     * Yields the same occurrence objects, in the same order, that expandEvent
+     * returns for the window — but one at a time, so a caller can stop after
+     * any number of them without the rest of the series being generated.
+     * Daily, weekly and sub-daily rules are seeked to `after` arithmetically,
+     * so finding the first occurrence after a far-away instant does not step
+     * through the series from its start.
+     *
+     * Both bounds are exclusive unless `inclusive` is set: an occurrence that
+     * starts exactly at `after` or `before` is skipped by default, which lets
+     * `iterateOccurrences(event, { after: previous.start })` continue a series
+     * without repeating `previous`. With `inclusive: true` the window is
+     * closed on both ends, exactly like expandEvent's range. An omitted bound
+     * leaves that end of the window open.
+     *
+     * COUNT, UNTIL, INTERVAL, BYDAY/BYMONTHDAY/BYSETPOS and exception dates
+     * are honoured as in expandEvent; BYSETPOS rules are yielded one period at
+     * a time, since the set positions of a period are only known once it is
+     * complete. 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 this method again for a fresh one.
+     *
+     * @example
+     * for (const occurrence of RecurrenceEngine.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').OccurrenceIteratorOptions} [options={}] - Window and timezone
+     * @returns {Generator<import('../types.js').EventOccurrence, void, undefined>} Occurrences in chronological order
+     * @throws {TypeError} If `after` or `before` is not a valid Date or timestamp
+     */
+    static iterateOccurrences(event: import('./Event.js').Event, options?: import('../types.js').OccurrenceIteratorOptions): Generator<import('../types.js').EventOccurrence, void, undefined>;
+    /**
+     * First occurrence of an event after an instant, or null when the series
+     * has no occurrence after it (past COUNT or UNTIL, or a non-recurring
+     * event that already started).
+     *
+     * `after` is exclusive unless `options.inclusive` is set, so passing the
+     * start of a known occurrence returns the one that follows it. Not to be
+     * confused with getNextOccurrence, which steps a parsed rule once
+     * without regard to COUNT, UNTIL or exceptions.
+     *
+     * @example
+     * const upcoming = RecurrenceEngine.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').OccurrenceIteratorOptions} [options={}] - Further window options
+     * @returns {import('../types.js').EventOccurrence|null} The next occurrence, or null
+     */
+    static nextOccurrence(event: import('./Event.js').Event, after?: Date | number, options?: import('../types.js').OccurrenceIteratorOptions): import('../types.js').EventOccurrence | 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 = RecurrenceEngine.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').OccurrenceIteratorOptions} [options={}] - Window and timezone
+     * @returns {import('../types.js').EventOccurrence[]} Up to `count` occurrences in chronological order
+     */
+    static takeOccurrences(event: import('./Event.js').Event, count: number, options?: import('../types.js').OccurrenceIteratorOptions): import('../types.js').EventOccurrence[];
+    /**
+     * Resolve iterator options into a closed window on numeric timestamps.
+     * Exclusive bounds are shifted by one millisecond, the resolution of
+     * Date, so the expansion loops only ever compare inclusively.
+     * @param {import('../types.js').OccurrenceIteratorOptions} options - Iterator options
+     * @returns {{ startMs: number, endMs: number }} Inclusive bounds (infinite when open)
+     * @throws {TypeError} If a bound is not a valid Date or timestamp
+     * @private
+     */
+    private static _occurrenceWindow;
+    /**
+     * Timestamp of a window bound given as a Date or a number
+     * @param {Date|number} value - Bound to convert
+     * @param {string} name - Option name for the error message
+     * @returns {number} Timestamp in milliseconds
+     * @throws {TypeError} If the value is not a valid Date or timestamp
+     * @private
+     */
+    private static _boundMs;
+    /**
+     * Yield a single occurrence if it starts inside the window
+     * @param {import('../types.js').EventOccurrence} occurrence - The occurrence
+     * @param {{ startMs: number, endMs: number }} window - Inclusive bounds
+     * @returns {Generator<import('../types.js').EventOccurrence, void, undefined>}
+     * @private
+     */
+    private static _iterateSingle;
+    /**
+     * Lazy counterpart of the expansion loops: seeks to the window, then
+     * advances a Date cursor per step and yields each in-window occurrence,
+     * applying the same DST adjustment and exception filtering.
+     * @private
+     */
+    private static _iterateRule;
+    /**
+     * Seek the iteration cursor to the last occurrence before rangeStartMs
+     * using the same arithmetic as expandEvent. The system-transition scan
+     * is bounded by the target itself, so an open-ended window costs no
+     * more than a closed one.
+     * @param {number} fromMs - Cursor position (DTSTART)
+     * @param {number} weekday - Weekday of the cursor
+     * @param {Object} rule - Parsed recurrence rule
+     * @param {number} rangeStartMs - Seek target
+     * @returns {{ ms: number, steps: number }|null} New cursor, or null for rules that cannot seek
+     * @private
+     */
+    private static _seekToWindow;
+    /**
+     * Milliseconds per _advanceInPlace step for every rule whose step is a
+     * fixed duration between system-timezone transitions: the sub-daily
+     * frequencies, DAILY and plain WEEKLY
+     * @param {Object} rule - Parsed recurrence rule
+     * @returns {number} Step length in milliseconds, or 0 when not fixed
+     * @private
+     */
+    private static _seekStepMs;
+    /**
+     * Streaming BYSETPOS filter: buffers the occurrences of one period and
+     * yields its selected positions once the next period begins. Periods
+     * arrive contiguously and in order, so the result matches _applyBySetPos.
+     * @param {Iterable<import('../types.js').EventOccurrence>} source - Occurrences in order
+     * @param {Object} rule - Rule with bySetPos
+     * @returns {Generator<import('../types.js').EventOccurrence, void, undefined>}
+     * @private
+     */
+    private static _iterateBySetPos;
     /**
      * General expansion loop: advances a Date cursor per step. Handles every
      * frequency and degenerate rules (non-advancing dates, invalid intervals).
@@ -122,6 +261,23 @@ export declare class RecurrenceEngine {
      * @private
      */
     private static _applyBySetPos;
+    /**
+     * Key of the BYSETPOS period an occurrence belongs to
+     * @param {import('../types.js').EventOccurrence} occurrence - The occurrence
+     * @param {Object} rule - Recurrence rule
+     * @returns {string|number} Period key
+     * @private
+     */
+    private static _bySetPosKey;
+    /**
+     * Occurrences of one period selected by the rule's BYSETPOS positions,
+     * in BYSETPOS order
+     * @param {Array} group - Occurrences of a single period, in order
+     * @param {Object} rule - Rule with bySetPos
+     * @returns {Array} Selected occurrences
+     * @private
+     */
+    private static _selectBySetPos;
     /**
      * Parse an RRULE string into a rule object
      * @param {string|import('../types.js').RecurrenceRule} ruleString - RRULE string (e.g., "FREQ=DAILY;INTERVAL=1;COUNT=10") or rule object