Time and Date Handling

/**
 * iCalendar Time representation (similar to JS Date object)
 * @param data - Time initialization data
 * @param zone - Timezone for this time
 */
class Time {
  constructor(data?: timeInit, zone?: Timezone);
  
  // Properties (getters/setters)
  year: number;
  month: number;        // 1-12 (January = 1)
  day: number;          // Day of month
  hour: number;         // 0-23
  minute: number;       // 0-59
  second: number;       // 0-59
  isDate: boolean;      // Date-only flag
  readonly icaltype: string;  // iCal type identifier
  
  // Static methods
  static fromString(aValue: string, aProperty?: Property): Time;
  static fromStringv2(str: string): Time;  // @deprecated Use fromString instead
  static fromDateString(aValue: string): Time;
  static fromDateTimeString(aValue: string, prop?: Property): Time;
  static fromJSDate(aDate: Date, useUTC?: boolean): Time;
  static fromData(aData: object, aZone?: Timezone): Time;
  static now(): Time;
  static daysInMonth(month: number, year: number): number;
  static isLeapYear(year: number): boolean;
  static fromDayOfYear(aDayOfYear: number, aYear: number): Time;
  static weekOneStarts(aYear: number, aWeekStart?: number): number;
  static getDominicalLetter(yr: number): string;
  
  // Instance methods
  clone(): Time;
  reset(): void;
  resetTo(year: number, month: number, day: number, hour?: number, minute?: number, second?: number, timezone?: Timezone): void;
  fromJSDate(aDate: Date, useUTC?: boolean): Time;
  fromData(aData: object, aZone?: Timezone): void;
  dayOfWeek(aWeekStart?: number): number;
  dayOfYear(): number;
  startOfWeek(aWeekStart?: number): Time;
  endOfWeek(aWeekStart?: number): Time;
  startOfMonth(): Time;
  endOfMonth(): Time;
  startOfYear(): Time;
  endOfYear(): Time;
  startDoyWeek(aFirstDayOfWeek: number): number;
  getDominicalLetter(): string;
  nthWeekDay(aDayOfWeek: number, aPos: number): Time;
  isNthWeekDay(aDayOfWeek: number, aPos: number): boolean;
  weekNumber(aWeekStart?: number): number;
  addDuration(aDuration: Duration): void;
  subtractDate(aDate: Time): Duration;
  subtractDateTz(aDate: Time): Duration;
  compare(other: Time): number;
  compareDateOnlyTz(other: Time, tz: Timezone): number;
  convertToZone(zone: Timezone): Time;
  utcOffset(): number;
  toICALString(): string;
  toString(): string;
  toJSDate(): Date;
  adjust(aExtraDays: number, aExtraHours: number, aExtraMinutes: number, aExtraSeconds: number, aTime?: Time): void;
  fromUnixTime(seconds: number): void;
  toUnixTime(): number;
  toJSON(): object;
}

// Weekday constants
Time.SUNDAY = 1;
Time.MONDAY = 2;
Time.TUESDAY = 3;
Time.WEDNESDAY = 4;
Time.THURSDAY = 5;
Time.FRIDAY = 6;
Time.SATURDAY = 7;
Time.DEFAULT_WEEK_START = 2; // Monday

// Static getter
Time.epochTime: Time; // Get epoch time instance

import ICAL from "ical.js";

// Create time from individual components
const time1 = new ICAL.Time({
  year: 2023,
  month: 12,
  day: 25,
  hour: 15,
  minute: 30,
  second: 0,
  isDate: false
});

// Create date-only time
const dateOnly = new ICAL.Time({
  year: 2023,
  month: 12,
  day: 25,
  isDate: true
});

// Create from string
const timeFromString = ICAL.Time.fromString("20231225T153000Z");
console.log(timeFromString.toString()); // "2023-12-25T15:30:00Z"

// Create from JavaScript Date
const jsDate = new Date("2023-12-25T15:30:00Z");
const timeFromJS = ICAL.Time.fromJSDate(jsDate, true);

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

// Time calculations
const start = ICAL.Time.fromString("20231201T120000Z");
const duration = ICAL.Duration.fromString("PT2H30M");
start.addDuration(duration);
console.log(start.toString()); // "2023-12-01T14:30:00Z"

// Date comparisons
const time2 = ICAL.Time.fromString("20231202T120000Z");
console.log(start.compare(time2)); // -1 (start is before time2)

// Week and month calculations
const weekStart = time1.startOfWeek(ICAL.Time.MONDAY);
const monthEnd = time1.endOfMonth();
const dayOfWeek = time1.dayOfWeek();
const weekNumber = time1.weekNumber();

// Convert to different formats
const icalString = time1.toICALString(); // "20231225T153000"
const isoString = time1.toString();      // "2023-12-25T15:30:00"
const jsDate2 = time1.toJSDate();        // JavaScript Date object
const unixTime = time1.toUnixTime();     // Unix timestamp

/**
 * vCard-specific time representation
 * @param data - Time initialization data
 * @param zone - Timezone for this time
 * @param icaltype - iCal type identifier
 */
class VCardTime extends Time {
  constructor(data?: object, zone?: Timezone, icaltype?: string);
  
  // Static methods
  static fromDateAndOrTimeString(aValue: string, aIcalType: string): VCardTime;
  
  // Overridden instance methods
  clone(): VCardTime;
  utcOffset(): number;
  toICALString(): string;
  toString(): string;
}

import ICAL from "ical.js";

// Create vCard time from date/time string
const vcardTime = ICAL.VCardTime.fromDateAndOrTimeString("2023-12-25", "date");
console.log(vcardTime.toString());

// Create vCard time with specific type
const vcardDateTime = new ICAL.VCardTime({
  year: 2023,
  month: 12,
  day: 25,
  hour: 15,
  minute: 30
}, null, "date-time");

/**
 * Duration value type representation
 * @param data - Duration initialization data
 */
class Duration {
  constructor(data?: object);
  
  // Properties
  weeks: number;
  days: number;
  hours: number;
  minutes: number;
  seconds: number;
  isNegative: boolean;
  
  // Static methods
  static fromSeconds(aSeconds: number): Duration;
  static isValueString(string: string): boolean;
  static fromString(aStr: string): Duration;
  static fromData(aData: object): Duration;
  
  // Instance methods
  clone(): Duration;
  toSeconds(): number;
  fromSeconds(aSeconds: number): void;
  fromData(aData: object): void;
  reset(): void;
  compare(aOther: Duration): number;
  normalize(): void;
  toString(): string;
  toICALString(): string;
}

import ICAL from "ical.js";

// Create duration from string
const duration1 = ICAL.Duration.fromString("PT2H30M"); // 2 hours 30 minutes
const duration2 = ICAL.Duration.fromString("P1W2DT3H"); // 1 week, 2 days, 3 hours

// Create from seconds
const duration3 = ICAL.Duration.fromSeconds(3600); // 1 hour

// Create from data object
const duration4 = ICAL.Duration.fromData({
  hours: 2,
  minutes: 30,
  seconds: 15
});

// Duration operations
console.log(duration1.toSeconds()); // 9000 (2.5 hours in seconds)
console.log(duration1.toString());  // "PT2H30M"

// Compare durations
console.log(duration1.compare(duration2)); // -1, 0, or 1

// Normalize duration (convert smaller units to larger)
const unnormalized = new ICAL.Duration({ minutes: 90 });
unnormalized.normalize(); // Becomes 1 hour 30 minutes

// Negative durations
const negativeDuration = ICAL.Duration.fromString("-PT1H");
console.log(negativeDuration.isNegative); // true

/**
 * Period value type representation
 * @param aData - Period initialization data
 */
class Period {
  constructor(aData?: object);
  
  // Properties
  start: Time;
  end: Time;
  duration: Duration;
  
  // Static methods
  static fromString(str: string, prop?: Property): Period;
  static fromData(aData: object): Period;
  static fromJSON(aData: object, aProp?: Property, aLenient?: boolean): Period;
  
  // Instance methods
  clone(): Period;
  getDuration(): Duration;
  getEnd(): Time;
  compare(dt: Time): number;
  toString(): string;
  toJSON(): object;
  toICALString(): string;
}

import ICAL from "ical.js";

// Create period from start/end times
const start = ICAL.Time.fromString("20231201T120000Z");
const end = ICAL.Time.fromString("20231201T140000Z");
const period1 = new ICAL.Period({ start, end });

// Create period from start/duration
const duration = ICAL.Duration.fromString("PT2H");
const period2 = new ICAL.Period({ start, duration });

// Create from string
const period3 = ICAL.Period.fromString("20231201T120000Z/20231201T140000Z");
const period4 = ICAL.Period.fromString("20231201T120000Z/PT2H");

// Period operations
console.log(period1.getDuration().toString()); // "PT2H"
console.log(period1.getEnd().toString());      // End time
console.log(period1.toString());               // String representation

// Compare time with period
const testTime = ICAL.Time.fromString("20231201T130000Z");
console.log(period1.compare(testTime)); // 1 if time is after period

interface timeInit {
  year?: number;
  month?: number;
  day?: number;
  hour?: number;
  minute?: number;
  second?: number;
  isDate?: boolean;
  timezone?: string | Timezone;
}

type weekDay = 1 | 2 | 3 | 4 | 5 | 6 | 7; // Sunday = 1, Saturday = 7