@forcecalendar/core 2.1.70 → 2.3.0

package/types/timezone/TimezoneManager.d.ts

@@ -0,0 +1,154 @@
+/**
+ * TimezoneManager - Comprehensive timezone handling for global calendar operations
+ * Handles timezone conversions, DST transitions, and IANA timezone database
+ *
+ * Critical for Salesforce orgs spanning multiple timezones
+ */
+import { TimezoneDatabase } from './TimezoneDatabase.js';
+export declare class TimezoneManager {
+    database: TimezoneDatabase;
+    offsetCache: Map<any, any>;
+    dstCache: Map<any, any>;
+    formatterCache: Map<any, any>;
+    transitionCache: Map<any, any>;
+    maxCacheSize: number;
+    maxOffsetBucketsPerZone: number;
+    cacheHits: number;
+    cacheMisses: number;
+    /**
+     * Get the shared singleton instance of TimezoneManager
+     * This should be used instead of creating new instances to avoid memory bloat
+     * @returns {TimezoneManager} The shared instance
+     */
+    static getInstance(): TimezoneManager;
+    /**
+     * Reset the singleton instance (useful for testing)
+     * @private
+     */
+    private static _resetInstance;
+    constructor();
+    /**
+     * Convert date from one timezone to another
+     * @param {Date} date - Date to convert
+     * @param {string} fromTimezone - Source timezone (IANA identifier)
+     * @param {string} toTimezone - Target timezone (IANA identifier)
+     * @returns {Date} Converted date
+     */
+    convertTimezone(date: Date, fromTimezone: string, toTimezone: string): Date;
+    /**
+     * Convert date to UTC
+     * @param {Date} date - Date in local timezone
+     * @param {string} timezone - Source timezone
+     * @returns {Date} Date in UTC
+     */
+    toUTC(date: Date, timezone: string): Date;
+    /**
+     * Convert UTC date to timezone
+     * @param {Date} utcDate - Date in UTC
+     * @param {string} timezone - Target timezone
+     * @returns {Date} Date in specified timezone
+     */
+    fromUTC(utcDate: Date, timezone: string): Date;
+    /**
+     * Get timezone offset in minutes
+     * @param {Date} date - Date to check (for DST calculation)
+     * @param {string} timezone - Timezone identifier
+     * @returns {number} Offset in minutes from UTC
+     */
+    getTimezoneOffset(date: Date, timezone: string): number;
+    /**
+     * Find the next instant at which the zone's UTC offset changes
+     * @param {string} timezone - Timezone identifier
+     * @param {number} fromMs - Search from this timestamp (exclusive)
+     * @param {number} toMs - Search up to this timestamp (inclusive)
+     * @returns {number} Timestamp of the first offset change after fromMs, or Infinity
+     */
+    getNextTransition(timezone: string, fromMs: number, toMs: number): number;
+    /**
+     * Scan a range for offset transitions. Probes in 7-day steps (shorter
+     * than any gap between real-world transitions, including Ramadan DST
+     * suspensions) and binary-searches each change to the exact instant.
+     * @param {string} timezone - Resolved timezone identifier
+     * @param {number} fromMs - Range start
+     * @param {number} toMs - Range end
+     * @returns {number[]} Sorted transition timestamps
+     * @private
+     */
+    private _scanTransitions;
+    /**
+     * Get a cached Intl.DateTimeFormat for a timezone
+     * @param {string} timezone - Timezone identifier
+     * @returns {Intl.DateTimeFormat}
+     * @private
+     */
+    private _getFormatter;
+    /**
+     * Check if date is in DST for given timezone
+     * @param {Date} date - Date to check
+     * @param {string} timezone - Timezone identifier
+     * @param {Object} [dstRule] - DST rule object (optional, will fetch if not provided)
+     * @returns {boolean} True if in DST
+     */
+    isDST(date: Date, timezone: string, dstRule?: Object): boolean;
+    /**
+     * Get nth weekday of month
+     * @private
+     */
+    private getNthWeekdayOfMonth;
+    /**
+     * Get list of common timezones
+     * @returns {Array<{value: string, label: string, offset: string}>}
+     */
+    getCommonTimezones(): Array<{
+        value: string;
+        label: string;
+        offset: string;
+    }>;
+    /**
+     * Format date in specific timezone
+     * @param {Date} date - Date to format
+     * @param {string} timezone - Timezone for formatting
+     * @param {Object} options - Formatting options
+     * @returns {string} Formatted date string
+     */
+    formatInTimezone(date: Date, timezone: string, options?: Object): string;
+    /**
+     * Get timezone from browser/system
+     * @returns {string} IANA timezone identifier
+     */
+    getSystemTimezone(): string;
+    /**
+     * Parse timezone from string (handles abbreviations)
+     * @param {string} tzString - Timezone string
+     * @returns {string} IANA timezone identifier
+     */
+    parseTimezone(tzString: string): string;
+    /**
+     * Calculate timezone difference in hours
+     * @param {string} timezone1 - First timezone
+     * @param {string} timezone2 - Second timezone
+     * @param {Date} [date] - Date for DST calculation
+     * @returns {number} Hour difference
+     */
+    getTimezoneDifference(timezone1: string, timezone2: string, date?: Date): number;
+    /**
+     * Clear caches (useful when date changes significantly)
+     */
+    clearCache(): void;
+    /**
+     * Validate timezone identifier
+     * @param {string} timezone - Timezone to validate
+     * @returns {boolean} True if valid
+     */
+    isValidTimezone(timezone: string): boolean;
+    /**
+     * Get cache statistics
+     * @returns {Object} Cache stats
+     */
+    getCacheStats(): Object;
+    /**
+     * Manage cache size - evict old entries if needed
+     * @private
+     */
+    private _manageCacheSize;
+}