Comprehensive timezone handling with VTIMEZONE component support, UTC offset calculations, and timezone service management. ICAL.js provides full timezone support including standard and daylight time transitions.
Timezone representation with VTIMEZONE component support.
/**
* Timezone constructor
* @param {Object|ICAL.Component} data - Timezone data or VTIMEZONE component
* @param {string} data.tzid - Timezone identifier
* @param {string} data.location - Timezone location (optional)
* @param {ICAL.Component} data.component - VTIMEZONE component (optional)
*/
class ICAL.Timezone {
constructor(data);
// Properties
tzid: string; // Timezone identifier
location: string; // Timezone location
component: ICAL.Component; // VTIMEZONE component
}// Static timezone instances
static utcTimezone: ICAL.Timezone; // UTC timezone
static localTimezone: ICAL.Timezone; // Local system timezone
/**
* Create timezone from data
* @param {Object} data - Timezone data
* @returns {ICAL.Timezone} New timezone
*/
static fromData(data);/**
* Get UTC offset for given date/time
* @param {ICAL.Time} dt - Date/time to get offset for
* @returns {number} UTC offset in seconds
*/
utcOffset(dt);
/**
* Get timezone identifier
* @returns {string} Timezone ID
*/
toString();UTC offset representation for timezone calculations.
/**
* UtcOffset constructor
* @param {Object} data - Offset data (optional)
* @param {number} data.hours - Offset hours
* @param {number} data.minutes - Offset minutes
* @param {number} data.factor - Sign factor (1 or -1)
*/
class ICAL.UtcOffset {
constructor(data);
// Properties
hours: number; // Offset hours
minutes: number; // Offset minutes
factor: number; // Sign factor (1 or -1)
readonly icaltype: string; // Always "utc-offset"
}/**
* Parse UTC offset from string
* @param {string} str - Offset string (e.g., "+0500", "-0800")
* @returns {ICAL.UtcOffset} Parsed offset
*/
static fromString(str: string): ICAL.UtcOffset;
/**
* Create UTC offset from seconds
* @param {number} seconds - Total offset in seconds
* @returns {ICAL.UtcOffset} UTC offset instance
*/
static fromSeconds(seconds: number): ICAL.UtcOffset;/**
* Clone offset
* @returns {ICAL.UtcOffset} Cloned offset
*/
clone(): ICAL.UtcOffset;
/**
* Convert to total seconds
* @returns {number} Offset in seconds
*/
toSeconds(): number;
/**
* Convert to string format
* @returns {string} Offset string
*/
toString(): string;
/**
* Convert to iCalendar string format
* @returns {string} iCalendar formatted offset string
*/
toICALString(): string;Service for managing timezone database.
/**
* Get timezone by ID
* @param {string} tzid - Timezone identifier
* @returns {ICAL.Timezone|null} Timezone or null if not found
*/
ICAL.TimezoneService.get(tzid);
/**
* Check if timezone exists
* @param {string} tzid - Timezone identifier
* @returns {boolean} True if timezone exists
*/
ICAL.TimezoneService.has(tzid);
/**
* Register timezone
* @param {string} name - Timezone name (optional)
* @param {ICAL.Timezone} timezone - Timezone to register (optional)
*/
ICAL.TimezoneService.register(name, timezone);
/**
* Remove timezone from service
* @param {string} tzid - Timezone identifier to remove
*/
ICAL.TimezoneService.remove(tzid);Usage Examples:
const ICAL = require('ical.js');
// Use predefined UTC timezone
const utcTime = new ICAL.Time({
year: 2023, month: 6, day: 15,
hour: 14, minute: 30
}, ICAL.Timezone.utcTimezone);
// Create custom timezone
const timezone = new ICAL.Timezone({
tzid: 'America/New_York'
});
// Create time with timezone
const localTime = new ICAL.Time({
year: 2023, month: 6, day: 15,
hour: 10, minute: 30
}, timezone);
// Get UTC offset
const offset = timezone.utcOffset(localTime);
console.log(offset); // -14400 (4 hours behind UTC in EDT)
// Work with UTC offsets
const utcOffset = ICAL.UtcOffset.fromString('-0400');
console.log(utcOffset.hours); // 4
console.log(utcOffset.minutes); // 0
console.log(utcOffset.factor); // -1
console.log(utcOffset.toSeconds()); // -14400
// Create from seconds
const offsetFromSeconds = ICAL.UtcOffset.fromSeconds(-14400); // -4 hours
console.log(offsetFromSeconds.toString()); // "-0400"