@forcecalendar/core 2.1.69 → 2.2.0

package/types/events/Event.d.ts

@@ -0,0 +1,329 @@
+/**
+ * Event class - represents a calendar event with timezone support
+ * Pure JavaScript, no DOM dependencies
+ * Locker Service compatible
+ */
+import { TimezoneManager } from '../timezone/TimezoneManager.js';
+export declare class Event {
+    id: string;
+    title: string;
+    _timezoneManager: TimezoneManager;
+    timeZone: string;
+    endTimeZone: string;
+    start: string | Date;
+    end: string | Date | undefined;
+    startUTC: Date;
+    endUTC: Date;
+    allDay: boolean | undefined;
+    description: string | undefined;
+    location: string | undefined;
+    color: string | undefined;
+    backgroundColor: string | undefined;
+    borderColor: string | undefined;
+    textColor: string | undefined;
+    recurring: boolean | undefined;
+    recurrenceRule: string | import("../types.js").RecurrenceRule | undefined;
+    _originalTimeZone: string | null;
+    status: import("../types.js").EventStatus | undefined;
+    visibility: import("../types.js").EventVisibility | undefined;
+    organizer: import("../types.js").Organizer | undefined;
+    attendees: any[];
+    reminders: any[];
+    categories: string[];
+    attachments: any[];
+    conferenceData: import("../types.js").ConferenceData | undefined;
+    metadata: Object;
+    _cache: {};
+    static FIELD_LIMITS: {
+        id: number;
+        title: number;
+        description: number;
+        location: number;
+    };
+    static MAX_METADATA_SIZE: number;
+    /**
+     * Normalize event data
+     * @param {import('../types.js').EventData} data - Raw event data
+     * @returns {import('../types.js').EventData} Normalized event data
+     */
+    static normalize(data: import('../types.js').EventData): import('../types.js').EventData;
+    /**
+     * Validate event data
+     * @param {import('../types.js').EventData} data - Normalized event data
+     * @throws {Error} If validation fails
+     */
+    static validate(data: import('../types.js').EventData): void;
+    /**
+     * Create a new Event instance
+     * @param {import('../types.js').EventData} eventData - Event data object
+     * @throws {Error} If required fields are missing or invalid
+     */
+    constructor({ id, title, start, end, allDay, description, location, color, backgroundColor, borderColor, textColor, recurring, recurrenceRule, recurrence, // Backward-compatible alias for recurrenceRule
+    timeZone, endTimeZone, status, visibility, organizer, attendees, reminders, category, // Support singular category (no default)
+    categories, // Support plural categories (no default)
+    attachments, conferenceData, metadata, ...rest }: import('../types.js').EventData);
+    /**
+     * Get event duration in milliseconds
+     * @returns {number} Duration in milliseconds
+     */
+    get duration(): number;
+    /**
+     * Get start date in a specific timezone
+     * @param {string} timezone - Target timezone
+     * @returns {Date} Start date in specified timezone
+     */
+    getStartInTimezone(timezone: string): Date;
+    /**
+     * Get end date in a specific timezone
+     * @param {string} timezone - Target timezone
+     * @returns {Date} End date in specified timezone
+     */
+    getEndInTimezone(timezone: string): Date;
+    /**
+     * Update event times preserving the timezone
+     * @param {Date} start - New start date
+     * @param {Date} end - New end date
+     * @param {string} [timezone] - Timezone for the new dates
+     */
+    updateTimes(start: Date, end: Date, timezone?: string): void;
+    /**
+     * Get event duration in minutes
+     * @returns {number} Duration in minutes
+     */
+    get durationMinutes(): number;
+    /**
+     * Get event duration in hours
+     * @returns {number} Duration in hours
+     */
+    get durationHours(): number;
+    /**
+     * Check if this is a multi-day event
+     * @returns {boolean} True if event spans multiple days
+     */
+    get isMultiDay(): boolean;
+    /**
+     * Check if event is recurring
+     * @returns {boolean} True if event is recurring
+     */
+    isRecurring(): boolean;
+    /**
+     * Backward-compatible alias for recurrenceRule
+     * @returns {import('../types.js').RecurrenceRule|string|null}
+     */
+    get recurrence(): import('../types.js').RecurrenceRule | string | null;
+    /**
+     * Check if event occurs on a specific date
+     * @param {Date|string} date - The date to check
+     * @returns {boolean} True if event occurs on the given date
+     */
+    occursOn(date: Date | string): boolean;
+    /**
+     * Check if this event overlaps with another event
+     * @param {Event|{start: Date, end: Date}} otherEvent - The other event or time range to check
+     * @returns {boolean} True if events overlap
+     * @throws {Error} If otherEvent is not an Event instance or doesn't have start/end
+     */
+    overlaps(otherEvent: Event | {
+        start: Date;
+        end: Date;
+    }): boolean;
+    /**
+     * Check if event contains a specific datetime
+     * @param {Date|string} datetime - The datetime to check
+     * @returns {boolean} True if the datetime falls within the event
+     */
+    contains(datetime: Date | string): boolean;
+    /**
+     * Clone the event with optional updates
+     * @param {Partial<import('../types.js').EventData>} [updates={}] - Properties to update in the clone
+     * @returns {Event} New Event instance with updated properties
+     */
+    clone(updates?: Partial<import('../types.js').EventData>): Event;
+    /**
+     * Convert event to plain object
+     * @returns {import('../types.js').EventData} Plain object representation of the event
+     */
+    toObject(): import('../types.js').EventData;
+    /**
+     * Create Event from plain object
+     * @param {import('../types.js').EventData} obj - Plain object with event properties
+     * @returns {Event} New Event instance
+     */
+    static fromObject(obj: import('../types.js').EventData): Event;
+    /**
+     * Compare events for equality
+     * @param {Event} other - The other event
+     * @returns {boolean} True if events are equal
+     */
+    equals(other: Event): boolean;
+    /**
+     * Add an attendee to the event
+     * @param {import('../types.js').Attendee} attendee - Attendee to add
+     * @returns {boolean} True if attendee was added, false if already exists
+     */
+    addAttendee(attendee: import('../types.js').Attendee): boolean;
+    /**
+     * Remove an attendee from the event
+     * @param {string} emailOrId - Email or ID of the attendee to remove
+     * @returns {boolean} True if attendee was removed
+     */
+    removeAttendee(emailOrId: string): boolean;
+    /**
+     * Update an attendee's response status
+     * @param {string} email - Attendee's email
+     * @param {import('../types.js').AttendeeResponseStatus} responseStatus - New response status
+     * @returns {boolean} True if attendee was updated
+     */
+    updateAttendeeResponse(email: string, responseStatus: import('../types.js').AttendeeResponseStatus): boolean;
+    /**
+     * Get an attendee by email
+     * @param {string} email - Attendee's email
+     * @returns {import('../types.js').Attendee|null} The attendee or null
+     */
+    getAttendee(email: string): import('../types.js').Attendee | null;
+    /**
+     * Check if an attendee exists
+     * @param {string} email - Attendee's email
+     * @returns {boolean} True if attendee exists
+     */
+    hasAttendee(email: string): boolean;
+    /**
+     * Get attendees by response status
+     * @param {import('../types.js').AttendeeResponseStatus} status - Response status to filter by
+     * @returns {import('../types.js').Attendee[]} Filtered attendees
+     */
+    getAttendeesByStatus(status: import('../types.js').AttendeeResponseStatus): import('../types.js').Attendee[];
+    /**
+     * Get count of attendees by response status
+     * @returns {Object.<string, number>} Count by status
+     */
+    getAttendeeCounts(): Record<string, number>;
+    /**
+     * Add a reminder to the event
+     * @param {import('../types.js').Reminder} reminder - Reminder to add
+     * @returns {boolean} True if reminder was added
+     */
+    addReminder(reminder: import('../types.js').Reminder): boolean;
+    /**
+     * Remove a reminder from the event
+     * @param {string} reminderId - ID of the reminder to remove
+     * @returns {boolean} True if reminder was removed
+     */
+    removeReminder(reminderId: string): boolean;
+    /**
+     * Get active reminders
+     * @returns {import('../types.js').Reminder[]} Active reminders
+     */
+    getActiveReminders(): import('../types.js').Reminder[];
+    /**
+     * Get reminder trigger times
+     * @returns {Date[]} Array of dates when reminders should trigger
+     */
+    getReminderTriggerTimes(): Date[];
+    /**
+     * Add a category to the event
+     * @param {string} category - Category to add
+     * @returns {boolean} True if category was added
+     */
+    addCategory(category: string): boolean;
+    /**
+     * Remove a category from the event
+     * @param {string} category - Category to remove
+     * @returns {boolean} True if category was removed
+     */
+    removeCategory(category: string): boolean;
+    /**
+     * Get primary category (first in array) for backward compatibility
+     * @returns {string|null} Primary category or null
+     */
+    get category(): string | null;
+    /**
+     * Check if event has a specific category
+     * @param {string} category - Category to check
+     * @returns {boolean} True if event has the category
+     */
+    hasCategory(category: string): boolean;
+    /**
+     * Check if event has any of the specified categories
+     * @param {string[]} categories - Categories to check
+     * @returns {boolean} True if event has any of the categories
+     */
+    hasAnyCategory(categories: string[]): boolean;
+    /**
+     * Check if event has all of the specified categories
+     * @param {string[]} categories - Categories to check
+     * @returns {boolean} True if event has all of the categories
+     */
+    hasAllCategories(categories: string[]): boolean;
+    /**
+     * Sanitize metadata to enforce size limits and reject unsafe types
+     * @param {Object} metadata - Raw metadata object
+     * @returns {Object} Sanitized metadata
+     * @private
+     */
+    private static _sanitizeMetadata;
+    /**
+     * Validate attendees
+     * @private
+     * @throws {Error} If attendees are invalid
+     */
+    private _validateAttendees;
+    /**
+     * Validate reminders
+     * @private
+     * @throws {Error} If reminders are invalid
+     */
+    private _validateReminders;
+    /**
+     * Validate email address
+     * @private
+     * @param {string} email - Email to validate
+     * @returns {boolean} True if email is valid
+     */
+    private _isValidEmail;
+    /**
+     * Check if the event is cancelled
+     * @returns {boolean} True if event is cancelled
+     */
+    get isCancelled(): boolean;
+    /**
+     * Check if the event is tentative
+     * @returns {boolean} True if event is tentative
+     */
+    get isTentative(): boolean;
+    /**
+     * Check if the event is confirmed
+     * @returns {boolean} True if event is confirmed
+     */
+    get isConfirmed(): boolean;
+    /**
+     * Check if the event is private
+     * @returns {boolean} True if event is private
+     */
+    get isPrivate(): boolean;
+    /**
+     * Check if the event is public
+     * @returns {boolean} True if event is public
+     */
+    get isPublic(): boolean;
+    /**
+     * Check if the event has attendees
+     * @returns {boolean} True if event has attendees
+     */
+    get hasAttendees(): boolean;
+    /**
+     * Check if the event has reminders
+     * @returns {boolean} True if event has reminders
+     */
+    get hasReminders(): boolean;
+    /**
+     * Check if the event is a meeting (has attendees or conference data)
+     * @returns {boolean} True if event is a meeting
+     */
+    get isMeeting(): boolean;
+    /**
+     * Check if the event is virtual (has conference data)
+     * @returns {boolean} True if event is virtual
+     */
+    get isVirtual(): boolean;
+}

package/types/events/EventStore.d.ts

@@ -0,0 +1,341 @@
+import { Event } from './Event.js';
+import { PerformanceOptimizer } from '../performance/PerformanceOptimizer.js';
+import { ConflictDetector } from '../conflicts/ConflictDetector.js';
+import { TimezoneManager } from '../timezone/TimezoneManager.js';
+/**
+ * EventStore - Manages calendar events with efficient querying
+ * Uses Map for O(1) lookups and spatial indexing concepts for date queries
+ * Now with performance optimizations for large datasets
+ */
+export declare class EventStore {
+    /** @type {Map<string, Event>} */
+    events: Map<string, Event>;
+    indices: {
+        /** @type {Map<string, Set<string>>} UTC Date string -> Set of event IDs */
+        byDate: Map<string, Set<string>>;
+        /** @type {Map<string, Set<string>>} YYYY-MM (UTC) -> Set of event IDs */
+        byMonth: Map<string, Set<string>>;
+        /** @type {Set<string>} Set of recurring event IDs */
+        recurring: Set<string>;
+        /** @type {Map<string, Set<string>>} Category -> Set of event IDs */
+        byCategory: Map<string, Set<string>>;
+        /** @type {Map<string, Set<string>>} Status -> Set of event IDs */
+        byStatus: Map<string, Set<string>>;
+    };
+    eventIndexRefs: Map<any, any>;
+    timezoneManager: TimezoneManager;
+    defaultTimezone: any;
+    optimizer: PerformanceOptimizer;
+    recurrenceEngine: any;
+    conflictDetector: ConflictDetector;
+    isBatchMode: boolean;
+    batchNotifications: any[];
+    batchBackup: {
+        events: Map<string, Event>;
+        indices: {
+            byDate: Map<string, Set<string>>;
+            byMonth: Map<string, Set<string>>;
+            recurring: Set<string>;
+            byCategory: Map<string, Set<string>>;
+            byStatus: Map<string, Set<string>>;
+        };
+        eventIndexRefs: Map<any, {
+            byDate: Set<any>;
+            byMonth: Set<any>;
+            byCategory: Set<any>;
+            byStatus: Set<any>;
+            recurring: any;
+        }>;
+        version: number;
+    } | null;
+    _batchLock: Promise<any> | null;
+    _batchLockResolve: ((value: any) => void) | null;
+    /** @type {number} */
+    version: number;
+    /** @type {Set<import('../types.js').EventListener>} */
+    listeners: Set<import('../types.js').EventListener>;
+    constructor(config?: {});
+    /**
+     * Add an event to the store
+     * @param {Event|import('../types.js').EventData} event - The event to add
+     * @returns {Event} The added event
+     * @throws {Error} If event with same ID already exists
+     */
+    addEvent(event: Event | import('../types.js').EventData): Event;
+    /**
+     * Update an existing event
+     * @param {string} eventId - The event ID
+     * @param {Partial<import('../types.js').EventData>} updates - Properties to update
+     * @returns {Event} The updated event
+     * @throws {Error} If event not found
+     */
+    updateEvent(eventId: string, updates: Partial<import('../types.js').EventData>): Event;
+    /**
+     * Remove an event from the store
+     * @param {string} eventId - The event ID to remove
+     * @returns {boolean} True if removed, false if not found
+     */
+    removeEvent(eventId: string): boolean;
+    /**
+     * Get an event by ID
+     * @param {string} eventId - The event ID
+     * @returns {Event|null} The event or null if not found
+     */
+    getEvent(eventId: string): Event | null;
+    /**
+     * Get all events
+     * @returns {Event[]} Array of all events
+     */
+    getAllEvents(): Event[];
+    /**
+     * Query events with filters
+     * @param {import('../types.js').QueryFilters} [filters={}] - Query filters
+     * @returns {Event[]} Filtered events
+     */
+    queryEvents(filters?: import('../types.js').QueryFilters): Event[];
+    /**
+     * Get events for a specific date
+     * @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 events that overlap with a given time range
+     * @param {Date} start - Start time
+     * @param {Date} end - End time
+     * @param {string} [excludeId=null] - Optional event ID to exclude (useful when checking for conflicts)
+     * @returns {Event[]} Array of overlapping events
+     */
+    getOverlappingEvents(start: Date, end: Date, excludeId?: string): Event[];
+    /**
+     * Check if an event would conflict with existing events
+     * @param {Date} start - Start time
+     * @param {Date} end - End time
+     * @param {string} excludeId - Optional event ID to exclude
+     * @returns {boolean} True if there are conflicts
+     */
+    hasConflicts(start: Date, end: Date, excludeId?: string): boolean;
+    /**
+     * Get events grouped by overlapping time slots
+     * Useful for calculating event positions in week/day views
+     * @param {Date} date - The date to analyze
+     * @param {boolean} timedOnly - Only include timed events (not all-day)
+     * @returns {Array<Event[]>} Array of event groups that overlap
+     */
+    getOverlapGroups(date: Date, timedOnly?: boolean): Array<Event[]>;
+    /**
+     * Calculate positions for overlapping events (for rendering)
+     * @param {Event[]} events - Array of overlapping events
+     * @returns {Map<string, {column: number, totalColumns: number}>} Position data for each event
+     */
+    calculateEventPositions(events: Event[]): Map<string, {
+        column: number;
+        totalColumns: number;
+    }>;
+    /**
+     * Get events for a date range
+     * @param {Date} start - Start date
+     * @param {Date} end - End date
+     * @param {boolean|Object} [expandRecurringOrOptions=true] - Boolean to expand recurring events,
+     *   or options object: { expandRecurring?: boolean, timezone?: string }
+     * @param {string} [timezone] - Timezone for the query
+     * @returns {Event[]}
+     */
+    getEventsInRange(start: Date, end: Date, expandRecurringOrOptions?: boolean | Object, timezone?: string): Event[];
+    /**
+     * Expand a recurring event into individual occurrences
+     * @param {Event} event - The recurring event
+     * @param {Date} rangeStart - Start of the expansion range
+     * @param {Date} rangeEnd - End of the expansion range
+     * @param {string} [timezone] - Timezone for the expansion
+     * @returns {Event[]} Array of event occurrences
+     */
+    expandRecurringEvent(event: Event, rangeStart: Date, rangeEnd: Date, timezone?: string): Event[];
+    /**
+     * Clear all events
+     */
+    clear(): void;
+    /**
+     * Bulk load events
+     * @param {Event[]} events - Array of events or event data
+     */
+    loadEvents(events: Event[]): void;
+    /**
+     * Subscribe to store changes
+     * @param {Function} callback - Callback function
+     * @returns {Function} Unsubscribe function
+     */
+    subscribe(callback: Function): Function;
+    /**
+     * Index an event for efficient queries
+     * @private
+     */
+    private _indexEvent;
+    /**
+     * Lazy index for events with large date ranges
+     * @private
+     */
+    private _indexEventLazy;
+    /**
+     * Create reverse index references for an event.
+     * @private
+     */
+    private _createIndexRefs;
+    /**
+     * Add an event to a keyed index and record the reverse reference.
+     * @private
+     */
+    private _addToKeyedIndex;
+    /**
+     * Remove event from indices
+     * @private
+     */
+    private _unindexEvent;
+    /**
+     * Remove an event from only the keys it was indexed into.
+     * @private
+     */
+    private _removeFromReferencedIndex;
+    /**
+     * Notify listeners of changes
+     * @private
+     */
+    private _notifyChange;
+    /**
+     * Get store statistics
+     * @returns {Object}
+     */
+    getStats(): Object;
+    /**
+     * Start batch mode for bulk operations
+     * Delays notifications until batch is committed
+     * @param {boolean} [enableRollback=false] - Enable rollback support (creates backup)
+     */
+    startBatch(enableRollback?: boolean): void;
+    /**
+     * Commit batch operations
+     * Sends all notifications at once
+     */
+    commitBatch(): void;
+    /**
+     * Rollback batch operations
+     * Restores state to before batch started
+     */
+    rollbackBatch(): void;
+    /**
+     * Execute batch operation with automatic rollback on error
+     * Uses a lock to prevent concurrent batch operations from corrupting state
+     * @param {Function} operation - Operation to execute
+     * @param {boolean} [enableRollback=true] - Enable automatic rollback on error
+     * @returns {*} Result of operation
+     * @throws {Error} If operation fails
+     */
+    executeBatch(operation: Function, enableRollback?: boolean): any;
+    /**
+     * Add multiple events in batch
+     * @param {Array<Event|import('../types.js').EventData>} events - Events to add
+     * @returns {Event[]} Added events
+     */
+    addEvents(events: Array<Event | import('../types.js').EventData>): Event[];
+    /**
+     * Update multiple events in batch
+     * @param {Array<{id: string, updates: Object}>} updates - Update operations
+     * @returns {Event[]} Updated events
+     */
+    updateEvents(updates: Array<{
+        id: string;
+        updates: Object;
+    }>): Event[];
+    /**
+     * Remove multiple events in batch
+     * @param {string[]} eventIds - Event IDs to remove
+     * @returns {number} Number of events removed
+     */
+    removeEvents(eventIds: string[]): number;
+    /**
+     * Get performance metrics
+     * @returns {Object} Performance metrics
+     */
+    getPerformanceMetrics(): Object;
+    /**
+     * Clear all caches
+     */
+    clearCaches(): void;
+    /**
+     * Optimize indices by removing old or irrelevant entries
+     * @param {Date} [cutoffDate] - Remove indices older than this date
+     */
+    optimizeIndices(cutoffDate?: Date): number;
+    /**
+     * Destroy the store and clean up resources
+     */
+    destroy(): void;
+    /**
+     * Check for conflicts for an event
+     * @param {Event|import('../types.js').EventData} event - Event to check
+     * @param {import('../types.js').ConflictCheckOptions} [options={}] - Check options
+     * @returns {import('../types.js').ConflictSummary} Conflict summary
+     */
+    checkConflicts(event: Event | import('../types.js').EventData, options?: import('../types.js').ConflictCheckOptions): import('../types.js').ConflictSummary;
+    /**
+     * Check conflicts between two events
+     * @param {string} eventId1 - First event ID
+     * @param {string} eventId2 - Second event ID
+     * @param {import('../types.js').ConflictCheckOptions} [options={}] - Check options
+     * @returns {import('../types.js').ConflictDetails[]} Conflicts between events
+     */
+    checkEventPairConflicts(eventId1: string, eventId2: string, options?: import('../types.js').ConflictCheckOptions): import('../types.js').ConflictDetails[];
+    /**
+     * Get all conflicts in a date range
+     * @param {Date} start - Start date
+     * @param {Date} end - End date
+     * @param {import('../types.js').ConflictCheckOptions} [options={}] - Check options
+     * @returns {import('../types.js').ConflictSummary} All conflicts in range
+     */
+    getAllConflicts(start: Date, end: Date, options?: import('../types.js').ConflictCheckOptions): import('../types.js').ConflictSummary;
+    /**
+     * Get busy periods for attendees
+     * @param {string[]} attendeeEmails - Attendee emails
+     * @param {Date} start - Start date
+     * @param {Date} end - End date
+     * @param {Object} [options={}] - Options
+     * @returns {Array<{start: Date, end: Date, eventIds: string[]}>} Busy periods
+     */
+    getBusyPeriods(attendeeEmails: string[], start: Date, end: Date, options?: Object): Array<{
+        start: Date;
+        end: Date;
+        eventIds: string[];
+    }>;
+    /**
+     * Get free periods for scheduling
+     * @param {Date} start - Start date
+     * @param {Date} end - End date
+     * @param {number} durationMinutes - Required duration in minutes
+     * @param {Object} [options={}] - Options
+     * @returns {Array<{start: Date, end: Date}>} Free periods
+     */
+    getFreePeriods(start: Date, end: Date, durationMinutes: number, options?: Object): Array<{
+        start: Date;
+        end: Date;
+    }>;
+    /**
+     * Add event with conflict checking
+     * @param {Event|import('../types.js').EventData} event - Event to add
+     * @param {boolean} [allowConflicts=true] - Whether to allow adding with conflicts
+     * @returns {{event: Event, conflicts: import('../types.js').ConflictSummary}} Result
+     */
+    addEventWithConflictCheck(event: Event | import('../types.js').EventData, allowConflicts?: boolean): {
+        event: Event;
+        conflicts: import('../types.js').ConflictSummary;
+    };
+    /**
+     * Find events with conflicts
+     * @param {Object} [options={}] - Options
+     * @returns {Array<{event: Event, conflicts: import('../types.js').ConflictDetails[]}>} Events with conflicts
+     */
+    findEventsWithConflicts(options?: Object): Array<{
+        event: Event;
+        conflicts: import('../types.js').ConflictDetails[];
+    }>;
+}