@forcecalendar/core 2.1.69 → 2.2.0

package/core/timezone/TimezoneManager.js

@@ -39,11 +39,19 @@ export class TimezoneManager {
     this.database = new TimezoneDatabase();
 
     // Cache timezone offsets for performance
+    // offsetCache: Map<timezone, Map<15-minute UTC bucket, offset>>
     this.offsetCache = new Map();
     this.dstCache = new Map();
 
+    // Intl.DateTimeFormat construction is ~50x the cost of using one,
+    // so formatters are cached per timezone and reused
+    this.formatterCache = new Map();
+
     // Cache size management
     this.maxCacheSize = 1000;
+    // ~20k 15-minute buckets per zone (≈ a few hundred KB worst case) covers
+    // multi-year expansions without evicting entries mid-scan
+    this.maxOffsetBucketsPerZone = 20000;
     this.cacheHits = 0;
     this.cacheMisses = 0;
   }
@@ -109,68 +117,106 @@ export class TimezoneManager {
     // Resolve any aliases
     timezone = this.database.resolveAlias(timezone);
 
-    // Check cache first
-    const cacheKey = `${timezone}_${date.getFullYear()}_${date.getMonth()}_${date.getDate()}_${date.getHours()}`;
-    if (this.offsetCache.has(cacheKey)) {
-      this.cacheHits++;
-      this._manageCacheSize();
-      return this.offsetCache.get(cacheKey);
+    // Offsets only change at DST transitions, which occur on 15-minute UTC
+    // boundaries worldwide — one cached entry covers each 15-minute bucket
+    const bucket = Math.floor(date.getTime() / 900000);
+    let zoneCache = this.offsetCache.get(timezone);
+    if (zoneCache) {
+      const cached = zoneCache.get(bucket);
+      if (cached !== undefined) {
+        this.cacheHits++;
+        return cached;
+      }
+    } else {
+      zoneCache = new Map();
+      this.offsetCache.set(timezone, zoneCache);
     }
 
     this.cacheMisses++;
 
+    let offset;
+
     // Try using Intl API if available (best option for browser/Node.js environments)
     if (typeof Intl !== 'undefined' && Intl.DateTimeFormat) {
       try {
-        const formatter = new Intl.DateTimeFormat('en-US', {
-          timeZone: timezone,
-          year: 'numeric',
-          month: '2-digit',
-          day: '2-digit',
-          hour: '2-digit',
-          minute: '2-digit',
-          second: '2-digit',
-          hour12: false
-        });
-
         // Create same date in target timezone
-        const parts = formatter.formatToParts(date);
-        const tzDate = new Date(
-          parts.find(p => p.type === 'year').value,
-          parts.find(p => p.type === 'month').value - 1,
-          parts.find(p => p.type === 'day').value,
-          parts.find(p => p.type === 'hour').value,
-          parts.find(p => p.type === 'minute').value,
-          parts.find(p => p.type === 'second').value
-        );
-
-        const offset = (tzDate.getTime() - date.getTime()) / (1000 * 60);
-        this.offsetCache.set(cacheKey, -offset);
-        this._manageCacheSize();
-        return -offset;
+        const parts = this._getFormatter(timezone).formatToParts(date);
+        let year, month, day, hour, minute, second;
+        for (const part of parts) {
+          switch (part.type) {
+            case 'year':
+              year = +part.value;
+              break;
+            case 'month':
+              month = +part.value;
+              break;
+            case 'day':
+              day = +part.value;
+              break;
+            case 'hour':
+              hour = +part.value;
+              break;
+            case 'minute':
+              minute = +part.value;
+              break;
+            case 'second':
+              second = +part.value;
+              break;
+          }
+        }
+        const tzDate = new Date(year, month - 1, day, hour, minute, second);
+        offset = -((tzDate.getTime() - date.getTime()) / (1000 * 60));
       } catch (e) {
         // Fallback to database calculation
       }
     }
 
-    // Fallback: Use timezone database
-    const tzData = this.database.getTimezone(timezone);
-    if (!tzData) {
-      throw new Error(`Unknown timezone: ${timezone}`);
-    }
+    if (offset === undefined) {
+      // Fallback: Use timezone database
+      const tzData = this.database.getTimezone(timezone);
+      if (!tzData) {
+        throw new Error(`Unknown timezone: ${timezone}`);
+      }
 
-    let offset = tzData.offset;
+      offset = tzData.offset;
 
-    // Apply DST if applicable
-    if (tzData.dst && this.isDST(date, timezone, tzData.dst)) {
-      offset += tzData.dst.offset;
+      // Apply DST if applicable
+      if (tzData.dst && this.isDST(date, timezone, tzData.dst)) {
+        offset += tzData.dst.offset;
+      }
     }
 
-    this.offsetCache.set(cacheKey, offset);
-    this._manageCacheSize();
+    if (zoneCache.size >= this.maxOffsetBucketsPerZone) {
+      zoneCache.clear();
+    }
+    zoneCache.set(bucket, offset);
     return offset;
   }
 
+  /**
+   * Get a cached Intl.DateTimeFormat for a timezone
+   * @param {string} timezone - Timezone identifier
+   * @returns {Intl.DateTimeFormat}
+   * @private
+   */
+  _getFormatter(timezone) {
+    let formatter = this.formatterCache.get(timezone);
+    if (!formatter) {
+      formatter = new Intl.DateTimeFormat('en-US', {
+        timeZone: timezone,
+        year: 'numeric',
+        month: '2-digit',
+        day: '2-digit',
+        hour: '2-digit',
+        minute: '2-digit',
+        second: '2-digit',
+        hour12: false
+      });
+      this.formatterCache.set(timezone, formatter);
+    }
+    return formatter;
+  }
+
   /**
    * Check if date is in DST for given timezone
    * @param {Date} date - Date to check
@@ -449,7 +495,7 @@ export class TimezoneManager {
         : 0;
 
     return {
-      offsetCacheSize: this.offsetCache.size,
+      offsetCacheSize: [...this.offsetCache.values()].reduce((n, m) => n + m.size, 0),
       dstCacheSize: this.dstCache.size,
       maxCacheSize: this.maxCacheSize,
       cacheHits: this.cacheHits,
@@ -463,16 +509,8 @@ export class TimezoneManager {
    * @private
    */
   _manageCacheSize() {
-    // Clear caches if they get too large
-    if (this.offsetCache.size > this.maxCacheSize) {
-      // Remove first half of entries (oldest)
-      const entriesToRemove = Math.floor(this.offsetCache.size / 2);
-      const keys = Array.from(this.offsetCache.keys());
-      for (let i = 0; i < entriesToRemove; i++) {
-        this.offsetCache.delete(keys[i]);
-      }
-    }
-
+    // Offset cache size is managed per-zone at insertion time in
+    // getTimezoneOffset; only the DST cache needs periodic eviction here
     if (this.dstCache.size > this.maxCacheSize / 2) {
       const entriesToRemove = Math.floor(this.dstCache.size / 2);
       const keys = Array.from(this.dstCache.keys());

package/core/types.js

@@ -19,6 +19,9 @@
  * @property {boolean} [recurring=false] - Whether this is a recurring event
  * @property {RecurrenceRule|string} [recurrenceRule=null] - Recurrence rule (RRULE string or object)
  * @property {string} [timeZone=null] - IANA timezone for the event
+ * @property {string} [endTimeZone=null] - IANA timezone for the event end (cross-timezone events)
+ * @property {RecurrenceRule|string} [recurrence=null] - Backward-compatible alias for recurrenceRule
+ * @property {string} [category=null] - Single category (alias for a one-element categories array)
  * @property {EventStatus} [status='confirmed'] - Event status
  * @property {EventVisibility} [visibility='public'] - Event visibility
  * @property {Organizer} [organizer=null] - Event organizer
@@ -172,7 +175,7 @@
  * @property {boolean} isCurrentMonth - Whether this day is in the current month
  * @property {boolean} isToday - Whether this is today
  * @property {boolean} isWeekend - Whether this is a weekend day
- * @property {import('./core/events/Event.js').Event[]} events - Events for this day
+ * @property {import('./events/Event.js').Event[]} events - Events for this day
  */
 
 /**
@@ -191,9 +194,9 @@
  * @property {string} dayName - Localized day name
  * @property {boolean} isToday - Whether this is today
  * @property {boolean} isWeekend - Whether this is a weekend day
- * @property {import('./core/events/Event.js').Event[]} events - All events for this day
- * @property {Array<import('./core/events/Event.js').Event[]>} overlapGroups - Groups of overlapping events
- * @property {function(import('./core/events/Event.js').Event[]): Map<string, EventPosition>} getEventPositions - Function to calculate positions
+ * @property {import('./events/Event.js').Event[]} events - All events for this day
+ * @property {Array<import('./events/Event.js').Event[]>} overlapGroups - Groups of overlapping events
+ * @property {(events: import('./events/Event.js').Event[]) => Map<string, EventPosition>} getEventPositions - Function to calculate positions
  */
 
 /**
@@ -208,7 +211,7 @@
  * @property {Date} date - Date being displayed
  * @property {string} dayName - Localized day name
  * @property {boolean} isToday - Whether this is today
- * @property {import('./core/events/Event.js').Event[]} allDayEvents - All-day events
+ * @property {import('./events/Event.js').Event[]} allDayEvents - All-day events
  * @property {HourSlot[]} hours - Hourly time slots
  */
 
@@ -216,7 +219,7 @@
  * @typedef {Object} HourSlot
  * @property {number} hour - Hour (0-23)
  * @property {string} time - Formatted time string
- * @property {import('./core/events/Event.js').Event[]} events - Events in this hour
+ * @property {import('./events/Event.js').Event[]} events - Events in this hour
  */
 
 /**
@@ -233,7 +236,7 @@
  * @property {Date} date - Date object
  * @property {string} dayName - Localized day name
  * @property {boolean} isToday - Whether this is today
- * @property {import('./core/events/Event.js').Event[]} events - Events for this day
+ * @property {import('./events/Event.js').Event[]} events - Events for this day
  */
 
 /**
@@ -273,9 +276,9 @@
 /**
  * @typedef {Object} EventStoreChange
  * @property {('add'|'update'|'remove'|'clear')} type - Type of change
- * @property {import('./core/events/Event.js').Event} [event] - Affected event
- * @property {import('./core/events/Event.js').Event} [oldEvent] - Previous event state (for updates)
- * @property {import('./core/events/Event.js').Event[]} [oldEvents] - Previous events (for clear)
+ * @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 {number} version - Store version number
  */
 
@@ -305,16 +308,16 @@
 
 /**
  * @typedef {Object} CalendarPlugin
- * @property {function(import('./core/calendar/Calendar.js').Calendar): void} install - Installation function
- * @property {function(import('./core/calendar/Calendar.js').Calendar): void} [uninstall] - Cleanup function
+ * @property {(calendar: import('./calendar/Calendar.js').Calendar) => void} install - Installation function
+ * @property {(calendar: import('./calendar/Calendar.js').Calendar) => void} [uninstall] - Cleanup function
  */
 
 /**
- * @typedef {function(any): void} EventListener
+ * @typedef {(payload: any) => void} EventListener
  */
 
 /**
- * @typedef {function(): void} UnsubscribeFn
+ * @typedef {() => void} UnsubscribeFn
  */
 
 /**

package/package.json

@@ -1,32 +1,55 @@
 {
   "name": "@forcecalendar/core",
-  "version": "2.1.69",
+  "version": "2.2.0",
   "type": "module",
   "private": false,
   "description": "A modern, lightweight, framework-agnostic calendar engine optimized for Salesforce",
   "main": "core/index.js",
   "module": "core/index.js",
-  "types": "core/types.js",
+  "types": "./types/index.d.ts",
   "sideEffects": false,
   "scripts": {
     "test": "node tests/run-all.js",
     "test:ics": "node tests/integration/test-ics.js",
     "test:search": "node tests/integration/test-search.js",
-    "lint": "eslint core/ --ext .js",
-    "lint:fix": "eslint core/ --ext .js --fix",
+    "lint": "eslint core/",
+    "lint:fix": "eslint core/ --fix",
     "format": "prettier --write \"core/**/*.js\"",
     "format:check": "prettier --check \"core/**/*.js\"",
     "quality": "npm run lint && npm run format:check",
-    "sync:version": "node scripts/sync-version.js"
+    "sync:version": "node scripts/sync-version.js",
+    "build:types": "tsc -p tsconfig.types.json",
+    "prepublishOnly": "npm run build:types"
   },
   "exports": {
-    ".": "./core/index.js",
-    "./calendar": "./core/calendar/Calendar.js",
-    "./events": "./core/events/Event.js",
-    "./state": "./core/state/StateManager.js",
-    "./search": "./core/search/EventSearch.js",
-    "./ics": "./core/ics/ICSHandler.js",
-    "./types": "./core/types.js"
+    ".": {
+      "types": "./types/index.d.ts",
+      "default": "./core/index.js"
+    },
+    "./calendar": {
+      "types": "./types/calendar/Calendar.d.ts",
+      "default": "./core/calendar/Calendar.js"
+    },
+    "./events": {
+      "types": "./types/events/Event.d.ts",
+      "default": "./core/events/Event.js"
+    },
+    "./state": {
+      "types": "./types/state/StateManager.d.ts",
+      "default": "./core/state/StateManager.js"
+    },
+    "./search": {
+      "types": "./types/search/EventSearch.d.ts",
+      "default": "./core/search/EventSearch.js"
+    },
+    "./ics": {
+      "types": "./types/ics/ICSHandler.d.ts",
+      "default": "./core/ics/ICSHandler.js"
+    },
+    "./types": {
+      "types": "./types/types.d.ts",
+      "default": "./core/types.js"
+    }
   },
   "repository": {
     "type": "git",
@@ -50,20 +73,17 @@
   },
   "homepage": "https://github.com/forceCalendar/core#readme",
   "devDependencies": {
-    "@babel/core": "^7.29.6",
-    "@babel/preset-env": "^7.29.7",
-    "@rollup/plugin-babel": "^7.0.0",
-    "@rollup/plugin-node-resolve": "^16.0.3",
-    "@rollup/plugin-terser": "^1.0.0",
-    "eslint": "^8.50.0",
+    "@eslint/js": "^10.0.1",
+    "eslint": "^10.6.0",
+    "globals": "^17.7.0",
     "prettier": "^3.0.3",
-    "rollup": "^4.61.1",
-    "vite": "^6.4.3"
+    "typescript": "^7.0.2"
   },
   "files": [
     "core/**/*.js",
     "!core/**/*.test.js",
     "!core/**/*.spec.js",
+    "types/**/*.d.ts",
     "README.md",
     "LICENSE"
   ]

package/types/calendar/Calendar.d.ts

@@ -0,0 +1,287 @@
+import { EventStore } from '../events/EventStore.js';
+import { Event } from '../events/Event.js';
+import { StateManager } from '../state/StateManager.js';
+import { TimezoneManager } from '../timezone/TimezoneManager.js';
+/**
+ * Calendar - Main calendar class with full timezone support
+ * Pure JavaScript, no DOM dependencies
+ * Framework agnostic, Locker Service compatible
+ */
+export declare class Calendar {
+    timezoneManager: TimezoneManager;
+    config: {
+        events?: import("../types.js").EventData[];
+        view: string;
+        date: Date;
+        weekStartsOn: number;
+        locale: string;
+        timeZone: string;
+        showWeekNumbers: boolean;
+        showWeekends: boolean;
+        fixedWeekCount: boolean;
+        businessHours: {
+            start: string;
+            end: string;
+        };
+    };
+    eventStore: EventStore;
+    state: StateManager;
+    listeners: Map<any, any>;
+    plugins: Set<any>;
+    views: Map<any, any>;
+    /**
+     * Create a new Calendar instance
+     * @param {import('../types.js').CalendarConfig} [config={}] - Configuration options
+     */
+    constructor(config?: import('../types.js').CalendarConfig);
+    /**
+     * Set the calendar view
+     * @param {import('../types.js').ViewType} viewType - The view type ('month', 'week', 'day', 'list')
+     * @param {Date} [date=null] - Optional date to navigate to
+     */
+    setView(viewType: import('../types.js').ViewType, date?: Date): void;
+    /**
+     * Get the current view type
+     * @returns {import('../types.js').ViewType} The current view type
+     */
+    getView(): import('../types.js').ViewType;
+    /**
+     * Navigate to the next period
+     */
+    next(): void;
+    /**
+     * Navigate to the previous period
+     */
+    previous(): void;
+    /**
+     * Navigate to today
+     */
+    today(): void;
+    /**
+     * Navigate to a specific date
+     * @param {Date} date - The date to navigate to
+     */
+    goToDate(date: Date): void;
+    /**
+     * Alias for goToDate (compat)
+     * @param {Date} date - The date to navigate to
+     */
+    setDate(date: Date): void;
+    /**
+     * Get the current date
+     * @returns {Date}
+     */
+    getCurrentDate(): Date;
+    /**
+     * Add an event
+     * @param {import('../events/Event.js').Event|import('../types.js').EventData} eventData - Event data or Event instance
+     * @returns {import('../events/Event.js').Event} The added event
+     */
+    addEvent(eventData: import('../events/Event.js').Event | import('../types.js').EventData): import('../events/Event.js').Event;
+    /**
+     * Update an event
+     * @param {string} eventId - The event ID
+     * @param {Object} updates - Properties to update
+     * @returns {Event} The updated event
+     */
+    updateEvent(eventId: string, updates: Object): Event;
+    /**
+     * Remove an event
+     * @param {string} eventId - The event ID
+     * @returns {boolean} True if removed
+     */
+    removeEvent(eventId: string): boolean;
+    /**
+     * Alias for removeEvent (compat)
+     * @param {string} eventId - The event ID
+     * @returns {boolean} True if removed
+     */
+    deleteEvent(eventId: string): boolean;
+    /**
+     * Get an event by ID
+     * @param {string} eventId - The event ID
+     * @returns {Event|null}
+     */
+    getEvent(eventId: string): Event | null;
+    /**
+     * Get all events
+     * @returns {Event[]}
+     */
+    getEvents(): Event[];
+    /**
+     * Set all events (replaces existing)
+     * @param {Event[]} events - Array of events
+     */
+    setEvents(events: Event[]): void;
+    /**
+     * Query events with filters
+     * @param {Object} filters - Query filters
+     * @returns {Event[]}
+     */
+    queryEvents(filters: Object): Event[];
+    /**
+     * Get events for a specific date
+     * @param {Date} date - The date
+     * @param {string} [timezone] - Timezone for the query (defaults to calendar timezone)
+     * @returns {Event[]}
+     */
+    getEventsForDate(date: Date, timezone?: string): Event[];
+    /**
+     * Get events in a date range
+     * @param {Date} start - Start date
+     * @param {Date} end - End date
+     * @param {string} [timezone] - Timezone for the query (defaults to calendar timezone)
+     * @returns {Event[]}
+     */
+    getEventsInRange(start: Date, end: Date, timezone?: string): Event[];
+    /**
+     * Set the calendar's timezone
+     * @param {string} timezone - IANA timezone identifier
+     */
+    setTimezone(timezone: string): void;
+    /**
+     * Get the current timezone
+     * @returns {string} Current timezone
+     */
+    getTimezone(): string;
+    /**
+     * Set the calendar locale
+     * @param {string} locale - Locale identifier (e.g. 'en-US')
+     */
+    setLocale(locale: string): void;
+    /**
+     * Set the week start day
+     * @param {number} weekStartsOn - 0 = Sunday, 1 = Monday, etc.
+     */
+    setWeekStartsOn(weekStartsOn: number): void;
+    /**
+     * Convert a date from one timezone to another
+     * @param {Date} date - Date to convert
+     * @param {string} fromTimezone - Source timezone
+     * @param {string} toTimezone - Target timezone
+     * @returns {Date} Converted date
+     */
+    convertTimezone(date: Date, fromTimezone: string, toTimezone: string): Date;
+    /**
+     * Convert a date to the calendar's timezone
+     * @param {Date} date - Date to convert
+     * @param {string} fromTimezone - Source timezone
+     * @returns {Date} Date in calendar timezone
+     */
+    toCalendarTimezone(date: Date, fromTimezone: string): Date;
+    /**
+     * Convert a date from the calendar's timezone
+     * @param {Date} date - Date in calendar timezone
+     * @param {string} toTimezone - Target timezone
+     * @returns {Date} Converted date
+     */
+    fromCalendarTimezone(date: Date, toTimezone: string): Date;
+    /**
+     * Format a date in a specific timezone
+     * @param {Date} date - Date to format
+     * @param {string} [timezone] - Timezone for formatting (defaults to calendar timezone)
+     * @param {Object} [options] - Formatting options
+     * @returns {string} Formatted date string
+     */
+    formatInTimezone(date: Date, timezone?: string, options?: Object): string;
+    /**
+     * Get list of common timezones with offsets
+     * @returns {Array<{value: string, label: string, offset: string}>} Timezone list
+     */
+    getTimezones(): Array<{
+        value: string;
+        label: string;
+        offset: string;
+    }>;
+    /**
+     * Get overlapping event groups for a date
+     * @param {Date} date - The date to check
+     * @param {boolean} timedOnly - Only include timed events
+     * @returns {Array<Event[]>} Array of event groups that overlap
+     */
+    getOverlapGroups(date: Date, timedOnly?: boolean): Array<Event[]>;
+    /**
+     * Calculate event positions for rendering
+     * @param {Event[]} events - Array of overlapping events
+     * @returns {Map<string, {column: number, totalColumns: number}>} Position data
+     */
+    calculateEventPositions(events: Event[]): Map<string, {
+        column: number;
+        totalColumns: number;
+    }>;
+    /**
+     * Get the current view's data
+     * @returns {import('../types.js').MonthViewData|import('../types.js').WeekViewData|import('../types.js').DayViewData|import('../types.js').ListViewData|null} View-specific data
+     */
+    getViewData(): import('../types.js').MonthViewData | import('../types.js').WeekViewData | import('../types.js').DayViewData | import('../types.js').ListViewData | null;
+    /**
+     * Get month view data
+     * @private
+     */
+    private _getMonthViewData;
+    /**
+     * Get week view data
+     * @private
+     */
+    private _getWeekViewData;
+    /**
+     * Get day view data
+     * @private
+     */
+    private _getDayViewData;
+    /**
+     * Get list view data
+     * @private
+     */
+    private _getListViewData;
+    /**
+     * Select an event
+     * @param {string} eventId - Event ID to select
+     */
+    selectEvent(eventId: string): void;
+    /**
+     * Clear event selection
+     */
+    clearEventSelection(): void;
+    /**
+     * Select a date
+     * @param {Date} date - Date to select
+     */
+    selectDate(date: Date): void;
+    /**
+     * Clear date selection
+     */
+    clearDateSelection(): void;
+    /**
+     * Subscribe to calendar events
+     * @param {string} eventName - Event name
+     * @param {Function} callback - Callback function
+     * @returns {Function} Unsubscribe function
+     */
+    on(eventName: string, callback: Function): Function;
+    /**
+     * Unsubscribe from calendar events
+     * @param {string} eventName - Event name
+     * @param {Function} callback - Callback function
+     */
+    off(eventName: string, callback: Function): void;
+    /**
+     * Emit an event
+     * @private
+     */
+    private _emit;
+    /**
+     * Set up internal listeners
+     * @private
+     */
+    private _setupInternalListeners;
+    /**
+     * Install a plugin
+     * @param {Object} plugin - Plugin object with install method
+     */
+    use(plugin: Object): void;
+    /**
+     * Destroy the calendar and clean up
+     */
+    destroy(): void;
+}