@forcecalendar/core 2.3.0 → 2.4.0

package/types/events/RecurrenceEngine.d.ts

@@ -5,14 +5,23 @@
 export declare class RecurrenceEngine {
     static _systemTransitions: any;
     static MAX_OCCURRENCES_HARD_LIMIT: number;
+    static MAX_ITERATIONS_HARD_LIMIT: number;
     static _ruleCache: Map<any, any>;
     static _RULE_CACHE_MAX: number;
     /**
      * Expand a recurring event into individual occurrences
+     *
+     * Occurrences before rangeStart are skipped without being generated:
+     * daily, weekly and sub-daily rules seek straight to the range, so the
+     * cost of a query does not grow with the age of the series, and a series
+     * that started years before the queried window is still expanded.
+     *
      * @param {import('./Event.js').Event} event - The recurring event
      * @param {Date} rangeStart - Start of the expansion range
      * @param {Date} rangeEnd - End of the expansion range
-     * @param {number} [maxOccurrences=365] - Maximum number of occurrences to generate
+     * @param {number} [maxOccurrences=365] - Maximum number of occurrences to return.
+     *   Only occurrences inside the range count towards this limit; occurrences
+     *   between the series start and rangeStart do not consume it.
      * @param {string} [timezone] - Timezone for expansion (important for DST)
      * @returns {import('../types.js').EventOccurrence[]} Array of occurrence objects with start/end dates
      */
@@ -39,6 +48,56 @@ export declare class RecurrenceEngine {
      * @private
      */
     private static _expandFast;
+    /**
+     * Milliseconds per step for rules whose step is a fixed duration while
+     * the system UTC offset is constant. Only the sub-daily frequencies are
+     * reported here: DAILY and WEEKLY have their own numeric loop, and the
+     * calendar-based frequencies take too few steps per year to need seeking.
+     * @param {Object} rule - Parsed recurrence rule
+     * @returns {number} Step length in milliseconds, or 0 when not fixed
+     * @private
+     */
+    private static _fixedStepMs;
+    /**
+     * Skip the occurrences of a fixed-step rule that fall before
+     * rangeStartMs without visiting each one.
+     *
+     * While the system UTC offset is constant, a wall-clock step of the
+     * cursor is a constant number of milliseconds, so a whole run of steps
+     * collapses into one multiplication. The single step that crosses a
+     * system-timezone transition is taken with `advance` instead, so the
+     * cursor ends up exactly where stepping every occurrence would have put
+     * it. Stops at the last occurrence before rangeStartMs; the caller's loop
+     * takes the step into the range.
+     *
+     * @param {number} fromMs - Cursor position (an occurrence instant)
+     * @param {number} rangeStartMs - Seek target
+     * @param {number} rangeEndMs - Upper bound for transition lookup
+     * @param {number} stepMs - Step length while the UTC offset is constant
+     * @param {number} maxSteps - Steps still permitted under COUNT (Infinity if unbounded)
+     * @param {(cursor: Date) => void} advance - Wall-clock step, mutating the cursor
+     * @returns {{ ms: number, steps: number, nextSystemTransition: number }}
+     *   Cursor position, steps taken and the next system transition after it
+     * @private
+     */
+    private static _seekFixedStep;
+    /**
+     * Seek for WEEKLY BYDAY rules, whose step pattern repeats every week:
+     * whole weeks are skipped arithmetically from any weekday in the BYDAY
+     * set, and single steps (identical to the expansion loop's) are only
+     * taken to reach the set, around system-timezone transitions and in the
+     * last week before the range.
+     *
+     * @param {number} fromMs - Cursor position (an occurrence instant)
+     * @param {number} weekday - Weekday of the cursor (Date#getDay)
+     * @param {number} rangeStartMs - Seek target
+     * @param {number} rangeEndMs - Upper bound for transition lookup
+     * @param {Object} rule - Parsed rule with compiled _byDaySet/_byDayDeltas
+     * @param {number} maxSteps - Steps still permitted under COUNT (Infinity if unbounded)
+     * @returns {{ ms: number, steps: number, weekday: number, nextSystemTransition: number }}
+     * @private
+     */
+    private static _seekWeekCycle;
     /**
      * Find the next system-timezone offset transition after fromMs.
      * Cached module-wide: the system timezone is fixed for the process.

package/types/events/RecurrenceEngineV2.d.ts

@@ -10,16 +10,59 @@ 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
+     * @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 {Array} 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;
+    }): any[];
+    /**
+     * 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
      */

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.4.0";
 export { Calendar as default } from './calendar/Calendar.js';

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
@@ -1142,12 +1225,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