Core Package Overview

Architecture

@forcecalendar/core is the headless calendar engine. It has zero runtime dependencies and ships as pure ESM JavaScript. The primary public classes are exported from the main entry point at core/index.js; some supporting classes -- LRUCache, PerformanceOptimizer, AdaptiveMemoryManager, and TimezoneDatabase -- are internal and not exported from the package.

core/
├── calendar/
│   ├── Calendar.js          Main calendar controller
│   └── DateUtils.js          Static date utilities
├── events/
│   ├── Event.js              Event model
│   ├── EventStore.js         Indexed event storage
│   ├── RecurrenceEngine.js   RFC 5545 recurrence expansion
│   ├── RecurrenceEngineV2.js Enhanced recurrence with caching
│   └── RRuleParser.js        RRULE parsing and generation
├── ics/
│   ├── ICSParser.js          Low-level ICS parser
│   └── ICSHandler.js         High-level import/export
├── integration/
│   └── EnhancedCalendar.js   Calendar + search + recurrence v2
├── performance/
│   ├── AdaptiveMemoryManager.js  Dynamic cache sizing
│   ├── LRUCache.js               O(1) LRU cache
│   └── PerformanceOptimizer.js   Caching and metrics
├── search/
│   ├── EventSearch.js             Full-text search
│   └── SearchWorkerManager.js     Web Worker search
├── state/
│   └── StateManager.js       Immutable state with undo/redo
├── timezone/
│   ├── TimezoneManager.js     Timezone operations
│   └── TimezoneDatabase.js    IANA timezone data
├── types.js                   TypeScript definitions
└── index.js                   Main entry point

Module Relationships

The Calendar class is the primary entry point. It composes:

• StateManager for view state, navigation, and UI flags
• EventStore for event storage, indexing, and queries
• TimezoneManager for timezone conversions (singleton)
• DateUtils for date calculations

EnhancedCalendar extends Calendar and adds:

• SearchWorkerManager for Web Worker-based full-text search
• RecurrenceEngineV2 for modified instance tracking and DST-aware expansion

The EventStore uses:

• RecurrenceEngineV2 by default for expanding recurring events in date ranges
• ConflictDetector for overlap detection and busy/free period calculation

Key Design Decisions

Headless computation. Core calendar computation can run without a DOM. Browser download helpers, optional Workers and URL-based ICS operations require their host APIs. Test runtime/bundler capabilities for the features you use; the Salesforce Web Component integration requires LWS.

O(1) event lookups. EventStore maintains five indices (byDate, byMonth, recurring, byCategory, byStatus) backed by Map<string, Set<string>>. Direct ID lookup is constant-time; date indexing, recurrence and batch work depend on the event span and workload.

Immutable state transitions. StateManager creates a new state object on every setState() call. Nested objects (filters, businessHours, metadata) are shallow-merged. All state snapshots are deep-cloned before being added to undo/redo history.

Static recurrence API. RecurrenceEngine methods are all static -- there is no instance state. RecurrenceEngineV2 uses instance methods because it maintains a modified-instance store and occurrence cache.

Lazy indexing. PerformanceOptimizer can defer index expansion for recurring events until a specific date range is queried, reducing startup cost for calendars with many recurring events.