@forcecalendar/core 2.1.69 → 2.2.0

package/types/performance/AdaptiveMemoryManager.d.ts

@@ -0,0 +1,104 @@
+/**
+ * AdaptiveMemoryManager - Dynamically manages cache sizes based on memory pressure
+ * Monitors memory usage and adjusts cache capacity to prevent memory issues
+ */
+export declare class AdaptiveMemoryManager {
+    config: {
+        checkInterval: number;
+        memoryThreshold: number;
+        criticalThreshold: number;
+        minCacheSize: number;
+        maxCacheSize: number;
+        adaptiveScaling: boolean;
+    };
+    caches: Map<any, any>;
+    stats: {
+        adjustments: number;
+        emergencyClears: number;
+        lastMemoryUsage: number;
+        lastCheckTime: null;
+        cacheResizes: never[];
+    };
+    monitoringInterval: number | null;
+    constructor(config?: {});
+    /**
+     * Register a cache for management
+     * @param {string} name - Cache identifier
+     * @param {Object} cache - Cache instance with size/clear methods
+     * @param {Object} [options] - Cache-specific options
+     */
+    registerCache(name: string, cache: Object, options?: Object): void;
+    /**
+     * Unregister a cache
+     * @param {string} name - Cache identifier
+     */
+    unregisterCache(name: string): void;
+    /**
+     * Start memory monitoring
+     */
+    startMonitoring(): void;
+    /**
+     * Stop memory monitoring
+     */
+    stopMonitoring(): void;
+    /**
+     * Check memory pressure and adjust caches
+     */
+    checkMemoryPressure(): Promise<void>;
+    /**
+     * Get current memory usage percentage
+     * @returns {Promise<number>} Memory usage as percentage (0-1)
+     */
+    getMemoryUsage(): Promise<number>;
+    /**
+     * Estimate memory usage based on cache sizes
+     * @private
+     */
+    private estimateMemoryUsage;
+    /**
+     * Reduce cache sizes based on memory pressure
+     * @param {number} memoryUsage - Current memory usage percentage
+     */
+    reduceCacheSizes(memoryUsage: number): void;
+    /**
+     * Increase cache sizes when memory is available
+     */
+    increaseCacheSizes(): void;
+    /**
+     * Resize a cache
+     * @private
+     */
+    private resizeCache;
+    /**
+     * Evict excess items from cache
+     * @private
+     */
+    private evictExcessItems;
+    /**
+     * Emergency clear all caches
+     */
+    emergencyClear(): void;
+    /**
+     * Update cache access time
+     * @param {string} name - Cache name
+     */
+    touchCache(name: string): void;
+    /**
+     * Get memory management statistics
+     * @returns {Object} Statistics object
+     */
+    getStats(): Object;
+    /**
+     * Manual trigger for memory pressure check
+     */
+    checkNow(): Promise<void>;
+    /**
+     * Set memory thresholds
+     * @param {Object} thresholds - New threshold values
+     */
+    setThresholds(thresholds: Object): void;
+    /**
+     * Destroy manager and clean up
+     */
+    destroy(): void;
+}

package/types/performance/LRUCache.d.ts

@@ -0,0 +1,59 @@
+/**
+ * LRU (Least Recently Used) Cache implementation
+ * Provides O(1) get and put operations
+ */
+export declare class LRUCache {
+    capacity: number;
+    cache: Map<any, any>;
+    hits: number;
+    misses: number;
+    evictions: number;
+    /**
+     * Create a new LRU Cache
+     * @param {number} capacity - Maximum number of items in cache
+     */
+    constructor(capacity?: number);
+    /**
+     * Get a value from the cache
+     * @param {string} key - Cache key
+     * @returns {*} Cached value or undefined
+     */
+    get(key: string): any;
+    /**
+     * Put a value in the cache
+     * @param {string} key - Cache key
+     * @param {*} value - Value to cache
+     */
+    put(key: string, value: any): void;
+    /**
+     * Check if key exists in cache
+     * @param {string} key - Cache key
+     * @returns {boolean} True if key exists
+     */
+    has(key: string): boolean;
+    /**
+     * Remove a key from the cache
+     * @param {string} key - Cache key
+     * @returns {boolean} True if key was removed
+     */
+    delete(key: string): boolean;
+    /**
+     * Clear all cached items
+     */
+    clear(): void;
+    /**
+     * Get cache statistics
+     * @returns {Object} Cache stats
+     */
+    getStats(): Object;
+    /**
+     * Get all keys in order (least to most recently used)
+     * @returns {string[]} Array of keys
+     */
+    keys(): string[];
+    /**
+     * Get cache size
+     * @returns {number} Number of items in cache
+     */
+    get size(): number;
+}

package/types/performance/PerformanceOptimizer.d.ts

@@ -0,0 +1,134 @@
+/**
+ * PerformanceOptimizer - Optimizes calendar operations for large datasets
+ * Includes caching, lazy loading, and batch processing with adaptive memory management
+ */
+import { LRUCache } from './LRUCache.js';
+import { AdaptiveMemoryManager } from './AdaptiveMemoryManager.js';
+export declare class PerformanceOptimizer {
+    config: {
+        enableCache: boolean;
+        cacheCapacity: number;
+        maxIndexDays: number;
+        batchSize: number;
+        enableMetrics: boolean;
+        cleanupInterval: number;
+        maxIndexAge: number;
+        enableAdaptiveMemory: boolean;
+    };
+    eventCache: LRUCache;
+    queryCache: LRUCache;
+    dateRangeCache: LRUCache;
+    memoryManager: AdaptiveMemoryManager | undefined;
+    lazyIndexes: Map<any, any>;
+    pendingIndexes: Map<any, any>;
+    batchQueue: any[];
+    batchTimer: number | null;
+    batchCallbacks: any[];
+    metrics: {
+        operations: {};
+        averageTimes: {};
+        slowQueries: never[];
+    };
+    cleanupTimer: number | null;
+    constructor(config?: {});
+    /**
+     * Measure operation performance
+     * @param {string} operation - Operation name
+     * @param {Function} fn - Function to measure
+     * @returns {*} Function result
+     */
+    measure(operation: string, fn: Function): any;
+    /**
+     * Measure async operation performance
+     * @param {string} operation - Operation name
+     * @param {Function} fn - Async function to measure
+     * @returns {Promise<*>} Function result
+     */
+    measureAsync(operation: string, fn: Function): Promise<any>;
+    /**
+     * Record performance metric
+     * @private
+     */
+    private recordMetric;
+    /**
+     * Get performance metrics
+     * @returns {Object} Performance metrics
+     */
+    getMetrics(): Object;
+    /**
+     * Check if event should use lazy indexing
+     * @param {import('../events/Event.js').Event} event - Event to check
+     * @returns {boolean} True if should use lazy indexing
+     */
+    shouldUseLazyIndexing(event: import('../events/Event.js').Event): boolean;
+    /**
+     * Create lazy index markers for large events
+     * @param {import('../events/Event.js').Event} event - Event to index
+     * @returns {Object} Index boundaries
+     */
+    createLazyIndexMarkers(event: import('../events/Event.js').Event): Object;
+    /**
+     * Expand lazy index for a specific date range
+     * @param {string} eventId - Event ID
+     * @param {Date} rangeStart - Start of range to index
+     * @param {Date} rangeEnd - End of range to index
+     * @returns {Promise<Set<string>>} Indexed date strings
+     */
+    expandLazyIndex(eventId: string, rangeStart: Date, rangeEnd: Date): Promise<Set<string>>;
+    /**
+     * Get month key for date
+     * @private
+     */
+    private getMonthKey;
+    /**
+     * Cache event with TTL
+     * @param {string} key - Cache key
+     * @param {*} value - Value to cache
+     * @param {string} cacheType - Type of cache to use
+     */
+    cache(key: string, value: any, cacheType?: string): void;
+    /**
+     * Get from cache
+     * @param {string} key - Cache key
+     * @param {string} cacheType - Type of cache
+     * @returns {*} Cached value or undefined
+     */
+    getFromCache(key: string, cacheType?: string): any;
+    /**
+     * Invalidate caches for an event
+     * @param {string} eventId - Event ID
+     */
+    invalidateEventCaches(eventId: string): void;
+    /**
+     * Batch operation for efficiency
+     * @param {Function} operation - Operation to batch
+     * @returns {Promise} Batch result
+     */
+    batch(operation: Function): Promise<any>;
+    /**
+     * Process batched operations
+     * @private
+     */
+    private processBatch;
+    /**
+     * Start cleanup timer for old indexes
+     * @private
+     */
+    private startCleanupTimer;
+    /**
+     * Clean up old indexes
+     * @private
+     */
+    private cleanupOldIndexes;
+    /**
+     * Optimize query by checking cache first
+     * @param {string} queryKey - Unique query identifier
+     * @param {Function} queryFn - Function to execute if not cached
+     * @returns {*} Query result
+     */
+    optimizeQuery(queryKey: string, queryFn: Function): any;
+    /**
+     * Destroy optimizer and clean up resources
+     */
+    destroy(): void;
+}

package/types/search/EventSearch.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Event Search Engine
+ * Full-text search and filtering for calendar events
+ */
+export declare class EventSearch {
+    eventStore: any;
+    searchIndex: Map<any, any>;
+    indexFields: string[];
+    _indexDirty: boolean;
+    _unsubscribe: any;
+    constructor(eventStore: any);
+    /**
+     * Destroy the search engine and unsubscribe from store changes
+     */
+    destroy(): void;
+    /**
+     * Search events by query string
+     * @param {string} query - Search query
+     * @param {Object} options - Search options
+     * @returns {Array} Matching events
+     */
+    search(query: string, options?: Object): any[];
+    /**
+     * Filter events by criteria
+     * @param {Object} filters - Filter criteria
+     * @returns {Array} Filtered events
+     */
+    filter(filters: Object): any[];
+    /**
+     * Advanced search combining text search and filters
+     * @param {string} query - Search query
+     * @param {Object} filters - Filter criteria
+     * @param {Object} options - Search options
+     * @returns {Array} Matching events
+     */
+    advancedSearch(query: string, filters?: Object, options?: Object): any[];
+    /**
+     * Get search suggestions/autocomplete
+     * @param {string} partial - Partial search term
+     * @param {Object} options - Suggestion options
+     * @returns {Array} Suggested terms
+     */
+    getSuggestions(partial: string, options?: Object): any[];
+    /**
+     * Get unique values for a field (for filter dropdowns)
+     * @param {string} field - Field name
+     * @returns {Array} Unique values
+     */
+    getUniqueValues(field: string): any[];
+    /**
+     * Group events by a field
+     * @param {string} field - Field to group by
+     * @param {Object} options - Grouping options
+     * @returns {Object} Grouped events
+     */
+    groupBy(field: string, options?: Object): Object;
+    /**
+     * Calculate match score for an event
+     * @private
+     */
+    private calculateMatchScore;
+    /**
+     * Get match details for highlighting
+     * @private
+     */
+    private getMatchDetails;
+    /**
+     * Tokenize search query
+     * @private
+     */
+    private tokenize;
+    /**
+     * Calculate Levenshtein distance for fuzzy matching
+     * @private
+     */
+    private levenshteinDistance;
+    /**
+     * Sort search results
+     * @private
+     */
+    private sortResults;
+    /**
+     * Ensure the search index is up to date
+     * @private
+     */
+    private _ensureIndex;
+    /**
+     * Rebuild search index
+     */
+    rebuildIndex(): void;
+}

package/types/search/SearchWorkerManager.d.ts

@@ -0,0 +1,116 @@
+/**
+ * SearchWorkerManager - Offloads search indexing to Web Workers
+ * Provides scalable search for large event datasets
+ */
+export declare class SearchWorkerManager {
+    eventStore: any;
+    workerSupported: boolean;
+    worker: Worker | null;
+    indexReady: boolean;
+    indexMode: string;
+    workerExpectedCount: number;
+    pendingSearches: any[];
+    fallbackIndex: InvertedIndex | null;
+    config: {
+        chunkSize: number;
+        maxWorkers: number;
+        indexThreshold: number;
+        cacheSize: number;
+        searchTimeout: number;
+    };
+    searchCache: Map<any, any>;
+    cacheOrder: any[];
+    constructor(eventStore: any);
+    /**
+     * Initialize the search worker
+     */
+    initializeWorker(): void;
+    /**
+     * Ensure a fallback index exists.
+     * @private
+     */
+    private ensureFallbackIndex;
+    /**
+     * Setup worker message handlers
+     */
+    setupWorkerHandlers(): void;
+    /**
+     * Index all events
+     */
+    indexEvents(): Promise<void>;
+    /**
+     * Search with caching and worker support
+     */
+    search(query: any, options?: {}): Promise<any>;
+    /**
+     * Search using worker
+     */
+    workerSearch(query: any, options: any): Promise<any>;
+    /**
+     * Direct search without worker
+     */
+    directSearch(query: any, options: any): {
+        event: any;
+        score: number;
+    }[];
+    /**
+     * Handle search results from worker
+     */
+    handleSearchResults(data: any): void;
+    /**
+     * Process any pending searches
+     */
+    processPendingSearches(): void;
+    /**
+     * Cache search results with LRU eviction
+     */
+    cacheResults(key: any, results: any): void;
+    /**
+     * Clear index and cache
+     */
+    clear(): void;
+    /**
+     * Destroy worker and clean up
+     */
+    destroy(): void;
+    /**
+     * Reject all pending worker searches.
+     * @private
+     */
+    private rejectPendingSearches;
+}
+/**
+ * InvertedIndex - Efficient inverted index for text search
+ * Used as fallback when Web Workers not available
+ */
+export declare class InvertedIndex {
+    index: Map<any, any>;
+    events: Map<any, any>;
+    fieldBoosts: {
+        title: number;
+        description: number;
+        location: number;
+        category: number;
+        categories: number;
+    };
+    constructor();
+    /**
+     * Build inverted index from events
+     */
+    buildIndex(events: any): void;
+    /**
+     * Tokenize text into searchable terms
+     */
+    tokenize(text: any): any;
+    /**
+     * Search the index
+     */
+    search(query: any, options?: {}): {
+        event: any;
+        score: any;
+    }[];
+    /**
+     * Clear the index
+     */
+    clear(): void;
+}

package/types/state/StateManager.d.ts

@@ -0,0 +1,200 @@
+/**
+ * StateManager - Central state management for the calendar
+ * Implements an immutable state pattern with change notifications
+ */
+export declare class StateManager {
+    state: {
+        view: string;
+        currentDate: Date;
+        selectedEventId: string | null;
+        selectedDate: Date | null;
+        hoveredEventId: string | null;
+        hoveredDate: Date | null;
+        weekStartsOn: number;
+        showWeekNumbers: boolean;
+        showWeekends: boolean;
+        fixedWeekCount: boolean;
+        timeZone: string;
+        locale: string;
+        hourFormat: string;
+        businessHours: {
+            start: string;
+            end: string;
+        };
+        filters: import("../types.js").FilterState;
+        isDragging: boolean;
+        isResizing: boolean;
+        isCreating: boolean;
+        isLoading: boolean;
+        loadingMessage: string;
+        error: string | null;
+        metadata: {};
+    };
+    listeners: Map<any, any>;
+    globalListeners: Set<any>;
+    history: any[];
+    historyIndex: number;
+    maxHistorySize: number;
+    /**
+     * Create a new StateManager instance
+     * @param {Partial<import('../types.js').CalendarState>} [initialState={}] - Initial state values
+     */
+    constructor(initialState?: Partial<import('../types.js').CalendarState>);
+    /**
+     * Get the current state
+     * @returns {import('../types.js').CalendarState} Current state (frozen)
+     */
+    getState(): import('../types.js').CalendarState;
+    /**
+     * Get a specific state value
+     * @param {keyof import('../types.js').CalendarState} key - The state key
+     * @returns {any} The state value
+     */
+    get(key: keyof import('../types.js').CalendarState): any;
+    /**
+     * Update state with partial updates
+     * @param {Object|Function} updates - Object with updates or updater function
+     */
+    setState(updates: Object | Function): void;
+    /**
+     * Set the current view
+     * @param {string} view - The view type
+     */
+    setView(view: string): void;
+    /**
+     * Set the current date
+     * @param {Date} date - The date to set
+     */
+    setCurrentDate(date: Date): void;
+    /**
+     * Navigate to the next period (month/week/day based on view)
+     */
+    navigateNext(): void;
+    /**
+     * Navigate to the previous period
+     */
+    navigatePrevious(): void;
+    /**
+     * Navigate to today
+     */
+    navigateToday(): void;
+    /**
+     * Select an event
+     * @param {string} eventId - The event ID to select
+     */
+    selectEvent(eventId: string): void;
+    /**
+     * Clear event selection
+     */
+    clearEventSelection(): void;
+    /**
+     * Select a date
+     * @param {Date} date - The date to select
+     */
+    selectDate(date: Date): void;
+    /**
+     * Clear date selection
+     */
+    clearDateSelection(): void;
+    /**
+     * Set loading state
+     * @param {boolean} isLoading - Loading state
+     * @param {string} message - Optional loading message
+     */
+    setLoading(isLoading: boolean, message?: string): void;
+    /**
+     * Set error state
+     * @param {Error|string|null} error - The error
+     */
+    setError(error: Error | string | null): void;
+    /**
+     * Update filters
+     * @param {Object} filters - Filter updates
+     */
+    updateFilters(filters: Object): void;
+    /**
+     * Subscribe to all state changes
+     * @param {Function} callback - Callback function
+     * @returns {Function} Unsubscribe function
+     */
+    subscribe(callback: Function): Function;
+    /**
+     * Subscribe to specific state key changes
+     * @param {string|string[]} keys - State key(s) to watch
+     * @param {Function} callback - Callback function
+     * @returns {Function} Unsubscribe function
+     */
+    watch(keys: string | string[], callback: Function): Function;
+    /**
+     * Check if undo is available
+     * @returns {boolean} True if undo is available
+     */
+    canUndo(): boolean;
+    /**
+     * Check if redo is available
+     * @returns {boolean} True if redo is available
+     */
+    canRedo(): boolean;
+    /**
+     * Get the number of undo operations available
+     * @returns {number} Number of undo operations
+     */
+    getUndoCount(): number;
+    /**
+     * Get the number of redo operations available
+     * @returns {number} Number of redo operations
+     */
+    getRedoCount(): number;
+    /**
+     * Undo the last state change
+     * @returns {boolean} True if undo was performed
+     */
+    undo(): boolean;
+    /**
+     * Redo the next state change
+     * @returns {boolean} True if redo was performed
+     */
+    redo(): boolean;
+    /**
+     * Reset state to initial values
+     */
+    reset(): void;
+    /**
+     * Recursively sanitize an object to prevent prototype pollution
+     * Removes dangerous keys (__proto__, constructor, prototype) at all levels
+     * @param {*} obj - Object to sanitize
+     * @param {number} depth - Current recursion depth
+     * @returns {*} Sanitized object
+     * @private
+     */
+    private static _deepSanitize;
+    /**
+     * Check if state has changed
+     * @private
+     */
+    private _hasChanged;
+    /**
+     * Deep equality check optimized for state comparison
+     * @private
+     * @param {*} a - First value
+     * @param {*} b - Second value
+     * @param {Set} seen - Track circular references
+     * @returns {boolean} True if values are deeply equal
+     */
+    private _deepEqual;
+    /**
+     * Add state to history
+     * @private
+     */
+    private _addToHistory;
+    /**
+     * Deep clone a value for history storage
+     * @private
+     */
+    private _deepClone;
+    /**
+     * Notify listeners of state changes
+     * @private
+     */
+    private _notifyListeners;
+}