@forcecalendar/core 2.1.70 → 2.3.0

package/types/events/RRuleParser.d.ts

@@ -0,0 +1,60 @@
+/**
+ * RRuleParser - Full RFC 5545 compliant RRULE parser
+ * Supports all RFC 5545 recurrence rule features
+ */
+export declare class RRuleParser {
+    /**
+     * Parse an RRULE string into a structured rule object
+     * @param {string|Object} rrule - RRULE string or rule object
+     * @returns {Object} Parsed rule object
+     */
+    static parse(rrule: string | Object): Object;
+    /**
+     * Parse frequency value
+     * @private
+     */
+    private static parseFrequency;
+    /**
+     * Parse BYDAY value
+     * Returns array of strings like ['MO', '2TU', '-1FR'] for compatibility with RecurrenceEngine
+     * @private
+     */
+    private static parseByDay;
+    /**
+     * Parse comma-separated integer list
+     * @private
+     */
+    private static parseIntList;
+    /**
+     * Parse date/datetime value
+     * @private
+     */
+    private static parseDateTime;
+    /**
+     * Parse exception dates
+     * @private
+     */
+    private static parseExceptionDates;
+    /**
+     * Validate and normalize rule
+     * @private
+     */
+    private static validateRule;
+    /**
+     * Build RRULE string from rule object
+     * @param {Object} rule - Rule object
+     * @returns {string} RRULE string
+     */
+    static buildRRule(rule: Object): string;
+    /**
+     * Format date/datetime for RRULE
+     * @private
+     */
+    private static formatDateTime;
+    /**
+     * Get human-readable description of rule
+     * @param {Object} rule - Parsed rule object
+     * @returns {string} Human-readable description
+     */
+    static getDescription(rule: Object): string;
+}

package/types/events/RecurrenceEngine.d.ts

@@ -0,0 +1,167 @@
+/**
+ * RecurrenceEngine - Handles expansion of recurring events
+ * Full support for RFC 5545 (iCalendar) RRULE specification
+ */
+export declare class RecurrenceEngine {
+    static _systemTransitions: any;
+    static MAX_OCCURRENCES_HARD_LIMIT: number;
+    static _ruleCache: Map<any, any>;
+    static _RULE_CACHE_MAX: number;
+    /**
+     * Expand a recurring event into individual occurrences
+     * @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 {string} [timezone] - Timezone for expansion (important for DST)
+     * @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[];
+    /**
+     * General expansion loop: advances a Date cursor per step. Handles every
+     * frequency and degenerate rules (non-advancing dates, invalid intervals).
+     * @private
+     */
+    private static _expandGeneral;
+    /**
+     * Numeric expansion loop for DAILY and WEEKLY rules.
+     *
+     * Between DST transitions a wall-clock-preserving day step is a constant
+     * number of milliseconds, so the loop is pure numeric addition. Transition
+     * instants — in the system timezone (which defines Date arithmetic) and in
+     * the event's timezone (which drives occurrence adjustment) — are
+     * discovered by binary search and cached, so only the one step that
+     * crosses a transition falls back to Date arithmetic, and only the first
+     * occurrence after a transition queries a timezone offset.
+     *
+     * Produces output identical to _expandGeneral for the rules it accepts;
+     * returns null to delegate anything it cannot handle exactly.
+     * @private
+     */
+    private static _expandFast;
+    /**
+     * Find the next system-timezone offset transition after fromMs.
+     * Cached module-wide: the system timezone is fixed for the process.
+     * @param {number} fromMs - Search from this timestamp (exclusive)
+     * @param {number} toMs - Extend cache coverage at least this far
+     * @returns {number} Transition timestamp, or Infinity if none within coverage
+     * @private
+     */
+    private static _nextSystemTransition;
+    /**
+     * Scan for system-timezone offset transitions via Date#getTimezoneOffset.
+     * Probes weekly (shorter than any real-world gap between transitions)
+     * and binary-searches each change to the exact millisecond.
+     * @private
+     */
+    private static _scanSystemTransitions;
+    /**
+     * Apply BYSETPOS to filter occurrences within each frequency period
+     * @param {Array} occurrences - Generated occurrences
+     * @param {Object} rule - Recurrence rule
+     * @returns {Array} Filtered occurrences
+     * @private
+     */
+    private static _applyBySetPos;
+    /**
+     * 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
+     * @returns {import('../types.js').RecurrenceRule} Parsed rule object
+     */
+    static parseRule(ruleString: string | import('../types.js').RecurrenceRule): import('../types.js').RecurrenceRule;
+    /**
+     * Parse a rule with caching for string rules (internal use by expandEvent).
+     * Cached rule objects are shared across calls and must not be mutated.
+     * @param {string|Object} recurrenceRule - RRULE string or rule object
+     * @returns {import('../types.js').RecurrenceRule} Parsed rule object
+     * @private
+     */
+    private static _getParsedRule;
+    /**
+     * Calculate the next occurrence based on the rule
+     * @param {Date} currentDate - Current occurrence date
+     * @param {Object} rule - Recurrence rule object
+     * @param {string} [timezone] - Timezone for calculation
+     * @returns {Date} Next occurrence date
+     */
+    static getNextOccurrence(currentDate: Date, rule: Object, _timezone?: string): Date;
+    /**
+     * Advance a date to the next occurrence, mutating it in place.
+     * Used by expandEvent to avoid one Date allocation per step.
+     * @param {Date} next - Date to advance (mutated)
+     * @param {Object} rule - Recurrence rule object
+     * @private
+     */
+    private static _advanceInPlace;
+    /**
+     * Days to add from each weekday (index 0-6) to reach the next weekday
+     * present in the given set
+     * @param {Set<number>} daySet - Non-empty set of weekday numbers
+     * @returns {number[]} Delta table indexed by Date#getDay()
+     * @private
+     */
+    private static _buildByDayDeltas;
+    /**
+     * Number of days in a month without allocating a Date
+     * @param {number} year - Full year
+     * @param {number} month - Month index (0-11)
+     * @returns {number}
+     * @private
+     */
+    private static _daysInMonth;
+    /**
+     * Build a Set of numeric weekdays (0-6) from BYDAY codes
+     * @param {Array<string>} byDay - Array of day codes (e.g., ['MO', '2TU'])
+     * @returns {Set<number>} Weekday numbers; invalid codes are skipped
+     * @private
+     */
+    private static _buildByDaySet;
+    /**
+     * Check if a date matches the BYDAY rule
+     * @param {Date} date - Date to check
+     * @param {Array<string>} byDay - Array of day codes (e.g., ['MO', 'WE', 'FR'])
+     * @returns {boolean}
+     */
+    static matchesByDay(date: Date, byDay: Array<string>): boolean;
+    /**
+     * Set date to specific weekday of month
+     * @param {Date} date - Date to modify
+     * @param {string} weekday - Weekday code (e.g., 'MO', 'TU')
+     * @param {number} position - Position in month (1-5, or -1 for last)
+     */
+    static setToWeekdayOfMonth(date: Date, weekday: string, position?: number): void;
+    /**
+     * Check if a date is an exception
+     * @param {Date} date - Date to check
+     * @param {Object} rule - Rule object with exceptions
+     * @param {string} [eventId] - Event ID for better exception tracking
+     * @returns {boolean}
+     */
+    static isException(date: Date, rule: Object, _eventId?: null): boolean;
+    /**
+     * Add exception dates to a recurrence rule
+     * @param {Object} rule - Recurrence rule
+     * @param {Date|Date[]} exceptions - Exception date(s) to add
+     * @param {Object} [options] - Options for exception
+     * @returns {Object} Updated rule
+     */
+    static addExceptions(rule: Object, exceptions: Date | Date[], options?: Object): Object;
+    /**
+     * Parse date from RRULE format (YYYYMMDDTHHMMSSZ)
+     * @param {string} dateStr - Date string in RRULE format
+     * @returns {Date}
+     */
+    static parseDate(dateStr: string): Date;
+    /**
+     * Generate a human-readable description of the recurrence rule
+     * @param {Object|string} rule - Recurrence rule
+     * @returns {string} Human-readable description
+     */
+    static getDescription(rule: Object | string): string;
+    /**
+     * Get day name from RRULE day code
+     * @param {string} dayCode - Day code (e.g., 'MO', '2TU')
+     * @returns {string} Day name
+     */
+    static getDayName(dayCode: string): string;
+}

package/types/events/RecurrenceEngineV2.d.ts

@@ -0,0 +1,140 @@
+/**
+ * RecurrenceEngineV2 - Enhanced recurrence engine with advanced features
+ * Handles modified instances, complex timezone transitions, and performance optimization
+ */
+import { TimezoneManager } from '../timezone/TimezoneManager.js';
+export declare class RecurrenceEngineV2 {
+    tzManager: TimezoneManager;
+    occurrenceCache: Map<any, any>;
+    cacheSize: number;
+    modifiedInstances: Map<any, any>;
+    exceptionStore: Map<any, any>;
+    static MAX_OCCURRENCES_HARD_LIMIT: number;
+    constructor();
+    /**
+     * Expand recurring event with advanced handling
+     * @param {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
+     */
+    expandEvent(event: Event, rangeStart: Date, rangeEnd: Date, options?: Object): any[];
+    /**
+     * Generate a single occurrence with timezone handling
+     */
+    generateOccurrence(event: any, date: any, duration: any, timezone: any, state: any): {
+        id: string;
+        recurringEventId: any;
+        title: any;
+        start: Date;
+        end: Date;
+        startUTC: Date;
+        endUTC: Date;
+        timezone: any;
+        originalStart: any;
+        allDay: any;
+        description: any;
+        location: any;
+        categories: any;
+        status: string;
+        isRecurring: boolean;
+        isModified: boolean;
+    };
+    /**
+     * Get next occurrence date with complex pattern support
+     */
+    getNextDate(currentDate: any, rule: any, timezone: any, _state?: {}): Date;
+    /**
+     * Get next daily occurrence
+     */
+    getNextDaily(date: any, rule: any): Date;
+    /**
+     * Get next weekly occurrence with BYDAY support
+     */
+    getNextWeekly(date: any, rule: any, _timezone: any): Date;
+    /**
+     * Get next monthly occurrence with complex patterns
+     */
+    getNextMonthly(date: any, rule: any, _timezone: any): Date;
+    /**
+     * Get next yearly occurrence
+     */
+    getNextYearly(date: any, rule: any, _timezone: any): Date;
+    /**
+     * Set date to Nth weekday of month
+     */
+    setToNthWeekdayOfMonth(date: any, weekday: any, nth: any): void;
+    /**
+     * Find DST transitions in date range
+     */
+    findDSTTransitions(start: any, end: any, timezone: any): {
+        date: Date;
+        oldOffset: number;
+        newOffset: number;
+        type: string;
+    }[];
+    /**
+     * Adjust occurrence for DST transitions
+     */
+    adjustForDST(start: any, end: any, timezone: any, transitions: any): {
+        start: any;
+        end: any;
+    };
+    /**
+     * Add or update a modified instance
+     */
+    addModifiedInstance(eventId: any, occurrenceDate: any, modifications: any): void;
+    /**
+     * Get modified instance data
+     */
+    getModifiedInstance(eventId: any, occurrenceDate: any): any;
+    /**
+     * Add exception with reason
+     */
+    addException(eventId: any, date: any, reason?: string): void;
+    /**
+     * Check if date is an exception
+     */
+    isException(eventId: any, date: any, rule: any): any;
+    /**
+     * Get exception reason
+     */
+    getExceptionReason(eventId: any, date: any): any;
+    /**
+     * Create date key for indexing
+     */
+    getDateKey(date: any): string;
+    /**
+     * Create cache key
+     */
+    getCacheKey(eventId: any, start: any, end: any, options: any): string;
+    /**
+     * Cache occurrences
+     */
+    cacheOccurrences(key: any, occurrences: any): void;
+    /**
+     * Clone occurrence results before returning or caching.
+     */
+    cloneOccurrences(occurrences: any): any;
+    /**
+     * Clear cache for specific event
+     */
+    clearEventCache(eventId: any): void;
+    /**
+     * Create occurrence object
+     */
+    createOccurrence(event: any, start: any, end: any): {
+        id: any;
+        title: any;
+        start: any;
+        end: any;
+        allDay: any;
+        description: any;
+        location: any;
+        categories: any;
+        timezone: any;
+        isRecurring: boolean;
+    };
+}
+export default RecurrenceEngineV2;

package/types/ics/ICSHandler.d.ts

@@ -0,0 +1,111 @@
+/**
+ * ICS Import/Export Handler
+ * High-level API for calendar data interchange
+ */
+import { ICSParser } from './ICSParser.js';
+export declare class ICSHandler {
+    calendar: any;
+    parser: ICSParser;
+    constructor(calendar: any);
+    /**
+     * Import events from ICS file or string
+     * @param {string|File|Blob} input - ICS data source
+     * @param {Object} options - Import options
+     * @returns {Promise<Object>} Import results
+     */
+    import(input: string | File | Blob, options?: Object): Promise<Object>;
+    /**
+     * Export calendar events to ICS format
+     * @param {Object} options - Export options
+     * @returns {string} ICS formatted string
+     */
+    export(options?: Object): string;
+    /**
+     * Export and download as file
+     * @param {string} filename - Name for the downloaded file
+     * @param {Object} options - Export options
+     */
+    downloadAsFile(filename?: string, options?: Object): void;
+    /**
+     * Import from URL
+     * @param {string} url - URL to ICS file
+     * @param {Object} options - Import options
+     * @returns {Promise<Object>} Import results
+     */
+    importFromURL(url: string, options?: Object): Promise<Object>;
+    /**
+     * Fetch a URL after validating the initial URL and each redirect target.
+     * @private
+     */
+    private fetchSafeURL;
+    /**
+     * Read a response body while enforcing a byte limit.
+     * @private
+     */
+    private readResponseText;
+    /**
+     * Validate a URL for safety (prevent SSRF attacks)
+     * @param {string} url - URL to validate
+     * @throws {Error} If URL is not safe
+     */
+    static validateURL(url: string): URL;
+    /**
+     * Validate a URL and, in Node runtimes, ensure DNS does not resolve privately.
+     * @param {string} url - URL to validate
+     * @returns {Promise<URL>} Parsed safe URL
+     */
+    static validateURLForFetch(url: string): Promise<URL>;
+    /**
+     * @private
+     */
+    private static isNodeRuntime;
+    /**
+     * @private
+     */
+    private static normalizeHostname;
+    /**
+     * @private
+     */
+    private static isBlockedHostname;
+    /**
+     * @private
+     */
+    private static isIPAddress;
+    /**
+     * @private
+     */
+    private static isPrivateIPAddress;
+    /**
+     * Subscribe to calendar feed
+     * @param {string} url - URL to ICS feed
+     * @param {Object} options - Subscription options
+     * @returns {Object} Subscription object
+     */
+    subscribe(url: string, options?: Object): Object;
+    /**
+     * Get ICS string from various input types
+     * @private
+     */
+    private getICSString;
+    /**
+     * Check if event is in date range
+     * @private
+     */
+    private isInDateRange;
+    /**
+     * Generate new ID for duplicate event
+     * @private
+     */
+    private generateNewId;
+    /**
+     * Expand recurring events into individual instances
+     * @private
+     */
+    private expandRecurringEvents;
+    /**
+     * Validate ICS string
+     * @param {string} icsString - ICS content to validate
+     * @returns {Object} Validation results
+     */
+    validate(icsString: string): Object;
+}

package/types/ics/ICSParser.d.ts

@@ -0,0 +1,111 @@
+/**
+ * ICS (iCalendar) Parser
+ * Converts between ICS format and Calendar events
+ * RFC 5545 compliant
+ */
+export declare class ICSParser {
+    maxFileSize: any;
+    maxLineLength: number;
+    propertyMap: {
+        SUMMARY: string;
+        DESCRIPTION: string;
+        LOCATION: string;
+        DTSTART: string;
+        DTEND: string;
+        UID: string;
+        CATEGORIES: string;
+        STATUS: string;
+        TRANSP: string;
+        ORGANIZER: string;
+        ATTENDEE: string;
+        RRULE: string;
+        EXDATE: string;
+    };
+    static MAX_INPUT_SIZE: number;
+    static MAX_LINES: number;
+    static MAX_EVENTS: number;
+    constructor(options?: {});
+    /**
+     * Parse ICS string into events
+     * @param {string} icsString - The ICS formatted string
+     * @returns {Array} Array of event objects
+     */
+    parse(icsString: string): any[];
+    /**
+     * Export events to ICS format
+     * @param {Array} events - Array of event objects
+     * @param {string} calendarName - Name of the calendar
+     * @returns {string} ICS formatted string
+     */
+    export(events: any[], calendarName?: string): string;
+    /**
+     * Convert single event to ICS lines
+     * @private
+     */
+    private eventToICS;
+    /**
+     * Parse ICS property into event object
+     * @private
+     */
+    private parseProperty;
+    /**
+     * Parse ICS date string
+     * @private
+     */
+    private parseDate;
+    /**
+     * Parse property name and parameters from a line prefix.
+     * @private
+     */
+    private parsePropertyParts;
+    /**
+     * Escape an ICS parameter value.
+     * @private
+     */
+    private escapeParamValue;
+    /**
+     * Format date for ICS
+     * @private
+     */
+    private formatDate;
+    /**
+     * Unfold ICS lines (reverse line folding)
+     * @private
+     */
+    private unfoldLines;
+    /**
+     * Fold long lines per ICS spec
+     * @private
+     */
+    private foldLines;
+    /**
+     * Escape special characters for ICS
+     * @private
+     */
+    private escapeText;
+    /**
+     * Unescape ICS text
+     * @private
+     */
+    private unescapeText;
+    /**
+     * Generate unique ID
+     * @private
+     */
+    private generateUID;
+    /**
+     * Create empty event object
+     * @private
+     */
+    private createEmptyEvent;
+    /**
+     * Normalize event object
+     * @private
+     */
+    private normalizeEvent;
+    /**
+     * Convert recurrence object to RRULE string
+     * @private
+     */
+    private objectToRRule;
+}

package/types/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Force Calendar Core - Main entry point
+ * A modern, lightweight, framework-agnostic calendar library
+ * Optimized for Salesforce and Locker Service
+ */
+export { Calendar } from './calendar/Calendar.js';
+export { Event } from './events/Event.js';
+export { EventStore } from './events/EventStore.js';
+export { StateManager } from './state/StateManager.js';
+export { DateUtils } from './calendar/DateUtils.js';
+export { ICSParser } from './ics/ICSParser.js';
+export { ICSHandler } from './ics/ICSHandler.js';
+export { EventSearch } from './search/EventSearch.js';
+export { SearchWorkerManager, InvertedIndex } from './search/SearchWorkerManager.js';
+export { RecurrenceEngine } from './events/RecurrenceEngine.js';
+export { RecurrenceEngineV2 } from './events/RecurrenceEngineV2.js';
+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 { Calendar as default } from './calendar/Calendar.js';

package/types/integration/EnhancedCalendar.d.ts

@@ -0,0 +1,76 @@
+/**
+ * EnhancedCalendar - Integration of advanced search and recurrence features
+ * Demonstrates how to use the new scalable components
+ */
+import { Calendar } from '../calendar/Calendar.js';
+import { SearchWorkerManager } from '../search/SearchWorkerManager.js';
+import { RecurrenceEngineV2 } from '../events/RecurrenceEngineV2.js';
+export declare class EnhancedCalendar extends Calendar {
+    searchManager: SearchWorkerManager;
+    recurrenceEngine: RecurrenceEngineV2;
+    performanceMetrics: {
+        searchTime: never[];
+        expansionTime: never[];
+        renderTime: never[];
+    };
+    _clearReindexTimeout: (() => void) | null | undefined;
+    constructor(config: any);
+    /**
+     * Enhanced search with worker support
+     */
+    search(query: any, options?: {}): Promise<any>;
+    /**
+     * Get events with enhanced recurrence expansion
+     */
+    getEventsInRange(startDate: any, endDate: any, options?: {}): any[];
+    /**
+     * Modify a single occurrence of a recurring event
+     */
+    modifyOccurrence(eventId: any, occurrenceDate: any, modifications: any): void;
+    /**
+     * Cancel a single occurrence of a recurring event
+     */
+    cancelOccurrence(eventId: any, occurrenceDate: any, reason?: string): void;
+    /**
+     * Bulk operations for recurring events
+     */
+    bulkModifyOccurrences(eventId: any, dateRange: any, modifications: any): Promise<void>;
+    /**
+     * Advanced search with filters and recurrence awareness
+     */
+    advancedSearch(query: any, filters?: {}, options?: {}): Promise<any>;
+    /**
+     * Setup real-time indexing for search
+     */
+    setupRealtimeIndexing(): void;
+    /**
+     * Get search suggestions (autocomplete)
+     */
+    getSuggestions(partial: any, field?: string): Promise<any[]>;
+    /**
+     * Performance monitoring
+     */
+    recordMetric(type: any, value: any): void;
+    /**
+     * Get performance statistics
+     */
+    getPerformanceStats(): {};
+    /**
+     * Export calendar with recurrence data
+     */
+    exportWithRecurrence(format?: string): string | {
+        events: import("../index.js").Event[];
+        modifiedInstances: {};
+        exceptions: {};
+    };
+    /**
+     * Import calendar with recurrence data
+     */
+    importWithRecurrence(data: any, format?: string): void;
+    /**
+     * Clean up resources
+     */
+    destroy(): void;
+}
+export declare function createEnhancedCalendar(config: any): EnhancedCalendar;
+export default EnhancedCalendar;