Time and Date Handling

/**
 * Time constructor
 * @param {Object} data - Time initialization data (optional)
 * @param {number} data.year - The year for this date
 * @param {number} data.month - The month for this date (1-12, not 0-11)
 * @param {number} data.day - The day for this date
 * @param {number} data.hour - The hour for this date
 * @param {number} data.minute - The minute for this date
 * @param {number} data.second - The second for this date
 * @param {boolean} data.isDate - If true, represents a date (no time component)
 * @param {ICAL.Timezone} zone - Timezone this time occurs in (optional)
 */
class ICAL.Time {
  constructor(data, zone);
  
  // Properties
  year: number;                    // Year component
  month: number;                   // Month component (1-12)
  day: number;                     // Day component
  hour: number;                    // Hour component (0-23)
  minute: number;                  // Minute component (0-59)
  second: number;                  // Second component (0-59)
  isDate: boolean;                 // True for date-only values
  zone: ICAL.Timezone;            // Associated timezone
  readonly icaltype: string;       // "date" or "date-time"
  icalclass: string;              // Always "icaltime"
}

const ICAL = require('ical.js');

// Create a date-time
const dateTime = new ICAL.Time({
  year: 2023,
  month: 6,
  day: 15,
  hour: 14,
  minute: 30,
  second: 0,
  isDate: false
});

console.log(dateTime.toString()); // "2023-06-15T14:30:00"

// Create a date-only value
const date = new ICAL.Time({
  year: 2023,
  month: 6,
  day: 15,
  isDate: true
});

console.log(date.toString()); // "2023-06-15"
console.log(date.icaltype);  // "date"

// Weekday constants (0-based, Sunday = 1)
static readonly SUNDAY: number;      // 1
static readonly MONDAY: number;      // 2  
static readonly TUESDAY: number;     // 3
static readonly WEDNESDAY: number;   // 4
static readonly THURSDAY: number;    // 5
static readonly FRIDAY: number;      // 6
static readonly SATURDAY: number;    // 7

/**
 * Create Time representing current moment in UTC
 * @returns {ICAL.Time} Current time in UTC
 */
static now();

/**
 * Parse iCalendar date/time string
 * @param {string} str - iCalendar formatted date/time string
 * @returns {ICAL.Time} Parsed time object
 * @throws {Error} On invalid format
 */
static fromString(str);

/**
 * Create Time from JavaScript Date object
 * @param {Date} date - JavaScript Date to convert
 * @param {boolean} useUTC - Use UTC time instead of local (optional)
 * @returns {ICAL.Time} Converted time object
 */
static fromJSDate(date, useUTC);

/**
 * Create Time from data object
 * @param {Object} data - Time component data
 * @returns {ICAL.Time} New time object
 */
static fromData(data);

const ICAL = require('ical.js');

// Current time
const now = ICAL.Time.now();
console.log(now.toString());

// Parse from string
const parsed = ICAL.Time.fromString('20230615T143000Z');
console.log(parsed.year);  // 2023
console.log(parsed.month); // 6
console.log(parsed.day);   // 15
console.log(parsed.hour);  // 14

// From JavaScript Date
const jsDate = new Date(2023, 5, 15, 14, 30, 0); // Note: JS months are 0-based
const time = ICAL.Time.fromJSDate(jsDate);
console.log(time.month); // 6 (ICAL months are 1-based)

// From data object
const timeData = ICAL.Time.fromData({
  year: 2023,
  month: 6,
  day: 15,
  hour: 14,
  minute: 30
});

/**
 * Calculate start of week one for given year
 * @param {number} year - Year to calculate for
 * @param {number} wkst - Week start day (SUNDAY=1, MONDAY=2, etc.)
 * @returns {number} Day of year when week one starts
 */
static weekOneStarts(year, wkst);

/**
 * Get dominical letter for year (for Easter calculation)
 * @param {number} year - Year to calculate for
 * @returns {string} Dominical letter (A-G)
 */
static getDominicalLetter(year);

/**
 * Check if year is a leap year
 * @param {number} year - Year to check
 * @returns {boolean} True if leap year
 */
static isLeapYear(year);

/**
 * Create a copy of this time
 * @returns {ICAL.Time} Cloned time object
 */
clone();

/**
 * Reset time to Unix epoch (1970-01-01T00:00:00Z)
 */
reset();

/**
 * Set time from data object
 * @param {Object} data - Time data
 * @param {ICAL.Timezone} zone - Timezone (optional)
 */
fromData(data, zone);

/**
 * Get day of week (1=Sunday, 2=Monday, etc.)
 * @returns {number} Day of week
 */
dayOfWeek();

/**
 * Get day of year (1-366)
 * @returns {number} Day of year
 */
dayOfYear();

/**
 * Get ISO week number
 * @param {number} weekStart - Week start day (optional, defaults to Monday)
 * @returns {number} Week number (1-53)
 */
weekNumber(weekStart);

/**
 * Add duration to this time
 * @param {ICAL.Duration} duration - Duration to add
 */
addDuration(duration);

/**
 * Calculate duration between this time and another
 * @param {ICAL.Time} other - Other time to subtract
 * @returns {ICAL.Duration} Duration between times
 */
subtractDate(other);

/**
 * Compare this time with another
 * @param {ICAL.Time} other - Time to compare with
 * @returns {number} -1 if this < other, 0 if equal, 1 if this > other
 */
compare(other);

/**
 * Normalize invalid date values (e.g., day 32 becomes next month)
 */
normalize();

/**
 * Convert to JavaScript Date object
 * @returns {Date} JavaScript Date representation
 */
toJSDate();

/**
 * Convert to Unix timestamp (seconds since epoch)
 * @returns {number} Unix timestamp
 */
toUnixTime();

/**
 * Convert to iCalendar string format
 * @returns {string} iCalendar formatted string
 */
toString();

const ICAL = require('ical.js');

const time = new ICAL.Time({
  year: 2023,
  month: 6,
  day: 15,
  hour: 14,
  minute: 30,
  second: 0
});

// Calendar calculations
console.log(time.dayOfWeek());  // Day of week (5 = Thursday)
console.log(time.dayOfYear());  // Day of year (166)
console.log(time.weekNumber()); // ISO week number

// Time arithmetic
const duration = new ICAL.Duration({ days: 7 });
time.addDuration(duration);
console.log(time.toString()); // "2023-06-22T14:30:00"

// Compare times
const other = ICAL.Time.now();
const comparison = time.compare(other);
if (comparison < 0) {
  console.log('time is before now');
} else if (comparison > 0) {
  console.log('time is after now');
} else {
  console.log('times are equal');
}

// Convert to other formats
const jsDate = time.toJSDate();
const timestamp = time.toUnixTime();
console.log(jsDate);   // JavaScript Date object
console.log(timestamp); // Unix timestamp

/**
 * Convert time to different timezone
 * @param {ICAL.Timezone} zone - Target timezone
 * @returns {ICAL.Time} New time in target timezone
 */
convertToZone(zone);

/**
 * Get UTC offset for this time
 * @returns {number} UTC offset in seconds
 */
utcOffset();

const ICAL = require('ical.js');

// Create time in specific timezone
const timezone = new ICAL.Timezone({
  tzid: 'America/New_York'
});

const localTime = new ICAL.Time({
  year: 2023,
  month: 6,
  day: 15,
  hour: 14,
  minute: 30
}, timezone);

// Convert to different timezone
const pacificTz = new ICAL.Timezone({
  tzid: 'America/Los_Angeles'
});
const pacificTime = localTime.convertToZone(pacificTz);
console.log(pacificTime.toString());

YYYYMMDD

YYYYMMDDTHHMMSS

YYYYMMDDTHHMMSSZ

YYYYMMDDTHHMMSS;TZID=timezone

/**
 * Start of week
 * @param {number} weekStart - Week start day (optional)
 * @returns {ICAL.Time} New time at start of week
 */
startOfWeek(weekStart);

/**
 * End of week
 * @param {number} weekStart - Week start day (optional)
 * @returns {ICAL.Time} New time at end of week
 */
endOfWeek(weekStart);

/**
 * Start of month
 * @returns {ICAL.Time} New time at start of month
 */
startOfMonth();

/**
 * End of month
 * @returns {ICAL.Time} New time at end of month
 */
endOfMonth();

/**
 * Start of year
 * @returns {ICAL.Time} New time at start of year
 */
startOfYear();

/**
 * End of year
 * @returns {ICAL.Time} New time at end of year
 */
endOfYear();

/**
 * Adjust time by adding/subtracting time components
 * @param {number} extraDays - Days to add/subtract
 * @param {number} extraHours - Hours to add/subtract
 * @param {number} extraMinutes - Minutes to add/subtract
 * @param {number} extraSeconds - Seconds to add/subtract
 * @param {number} extraMonths - Months to add/subtract
 */
adjust(extraDays, extraHours, extraMinutes, extraSeconds, extraMonths);

const ICAL = require('ical.js');

const time = new ICAL.Time({
  year: 2023,
  month: 6,
  day: 15,
  hour: 14,
  minute: 30
});

// Date boundaries
const startWeek = time.startOfWeek();
console.log(startWeek.toString()); // Start of week

const endMonth = time.endOfMonth();
console.log(endMonth.toString()); // End of month

const startYear = time.startOfYear();
console.log(startYear.toString()); // "2023-01-01T14:30:00"

// Adjust time components
time.adjust(10, 2, 30, 0, 1); // Add 10 days, 2 hours, 30 minutes, 1 month
console.log(time.toString());

adjust

normalize