Date and Time Objects

/**
 * A CalendarDate represents a date without any time components in a specific calendar system.
 */
class CalendarDate {
  constructor(year: number, month: number, day: number);
  constructor(era: string, year: number, month: number, day: number);
  constructor(calendar: Calendar, year: number, month: number, day: number);
  constructor(calendar: Calendar, era: string, year: number, month: number, day: number);

  /** The calendar system associated with this date, e.g. Gregorian. */
  readonly calendar: Calendar;
  /** The calendar era for this date, e.g. "BC" or "AD". */
  readonly era: string;
  /** The year of this date within the era. */
  readonly year: number;
  /** The month number within the year. */
  readonly month: number;
  /** The day number within the month. */
  readonly day: number;

  /** Returns a copy of this date. */
  copy(): CalendarDate;
  /** Returns a new CalendarDate with the given duration added to it. */
  add(duration: DateDuration): CalendarDate;
  /** Returns a new CalendarDate with the given duration subtracted from it. */
  subtract(duration: DateDuration): CalendarDate;
  /** Returns a new CalendarDate with the given fields set to the provided values. */
  set(fields: DateFields): CalendarDate;
  /** Returns a new CalendarDate with the given field adjusted by a specified amount. */
  cycle(field: DateField, amount: number, options?: CycleOptions): CalendarDate;
  /** Converts the date to a native JavaScript Date object, with the time set to midnight in the given time zone. */
  toDate(timeZone: string): Date;
  /** Converts the date to an ISO 8601 formatted string. */
  toString(): string;
  /** Compares this date with another. A negative result indicates that this date is before the given one. */
  compare(b: AnyCalendarDate): number;
}

import { CalendarDate, GregorianCalendar } from "@internationalized/date";

// Create dates using different constructors
const date1 = new CalendarDate(2024, 3, 15);
const date2 = new CalendarDate('AD', 2024, 3, 15);
const date3 = new CalendarDate(new GregorianCalendar(), 2024, 3, 15);

// Date arithmetic
const nextWeek = date1.add({ weeks: 1 });
const lastMonth = date1.subtract({ months: 1 });
const newYear = date1.set({ year: 2025 });

// Cycling fields
const nextDay = date1.cycle('day', 1);
const nextMonth = date1.cycle('month', 1);

// Conversion and comparison
const jsDate = date1.toDate('UTC');
const isoString = date1.toString(); // "2024-03-15"
const comparison = date1.compare(date2); // 0 (equal)

/**
 * A CalendarDateTime represents a date with time components in a specific calendar system.
 */
class CalendarDateTime {
  constructor(year: number, month: number, day: number, hour?: number, minute?: number, second?: number, millisecond?: number);
  constructor(era: string, year: number, month: number, day: number, hour?: number, minute?: number, second?: number, millisecond?: number);
  constructor(calendar: Calendar, year: number, month: number, day: number, hour?: number, minute?: number, second?: number, millisecond?: number);
  constructor(calendar: Calendar, era: string, year: number, month: number, day: number, hour?: number, minute?: number, second?: number, millisecond?: number);

  /** The calendar system associated with this date, e.g. Gregorian. */
  readonly calendar: Calendar;
  /** The calendar era for this date, e.g. "BC" or "AD". */
  readonly era: string;
  /** The year of this date within the era. */
  readonly year: number;
  /** The month number within the year. */
  readonly month: number;
  /** The day number within the month. */
  readonly day: number;
  /** The hour in the day, numbered from 0 to 23. */
  readonly hour: number;
  /** The minute in the hour. */
  readonly minute: number;
  /** The second in the minute. */
  readonly second: number;
  /** The millisecond in the second. */
  readonly millisecond: number;

  /** Returns a copy of this date. */
  copy(): CalendarDateTime;
  /** Returns a new CalendarDateTime with the given duration added to it. */
  add(duration: DateTimeDuration): CalendarDateTime;
  /** Returns a new CalendarDateTime with the given duration subtracted from it. */
  subtract(duration: DateTimeDuration): CalendarDateTime;
  /** Returns a new CalendarDateTime with the given fields set to the provided values. */
  set(fields: DateFields | TimeFields): CalendarDateTime;
  /** Returns a new CalendarDateTime with the given field adjusted by a specified amount. */
  cycle(field: DateField | TimeField, amount: number, options?: CycleOptions | CycleTimeOptions): CalendarDateTime;
  /** Converts the date to a native JavaScript Date object in the given time zone. */
  toDate(timeZone: string): Date;
  /** Converts the date to an ISO 8601 formatted string. */
  toString(): string;
  /** Compares this date with another. A negative result indicates that this date is before the given one. */
  compare(b: AnyDateTime): number;
}

/**
 * A Time represents a time without any date or timezone components.
 */
class Time {
  constructor(hour?: number, minute?: number, second?: number, millisecond?: number);

  /** The hour, numbered from 0 to 23. */
  readonly hour: number;
  /** The minute in the hour. */
  readonly minute: number;
  /** The second in the minute. */
  readonly second: number;
  /** The millisecond in the second. */
  readonly millisecond: number;

  /** Returns a copy of this time. */
  copy(): Time;
  /** Returns a new Time with the given duration added to it. */
  add(duration: TimeDuration): Time;
  /** Returns a new Time with the given duration subtracted from it. */
  subtract(duration: TimeDuration): Time;
  /** Returns a new Time with the given fields set to the provided values. */
  set(fields: TimeFields): Time;
  /** Returns a new Time with the given field adjusted by a specified amount. */
  cycle(field: TimeField, amount: number, options?: CycleTimeOptions): Time;
  /** Converts the time to an ISO 8601 formatted string. */
  toString(): string;
  /** Compares this time with another. A negative result indicates that this time is before the given one. */
  compare(b: AnyTime): number;
}

import { Time } from "@internationalized/date";

// Create time objects
const time = new Time(14, 30);
const preciseTime = new Time(9, 15, 30, 750);

// Time arithmetic
const laterTime = time.add({ hours: 2, minutes: 15 });
const earlierTime = time.subtract({ minutes: 30 });

// Set specific fields
const newTime = time.set({ hour: 12, minute: 0 });
const resetSeconds = time.set({ second: 0, millisecond: 0 });

// Cycle time with options
const nextHour = time.cycle('hour', 1);
const nextHour12 = time.cycle('hour', 1, { hourCycle: 12 });

// String representation
const timeString = time.toString(); // "14:30:00"

/**
 * A ZonedDateTime represents a date and time in a specific time zone and calendar system.
 */
class ZonedDateTime {
  constructor(year: number, month: number, day: number, timeZone: string, offset: number, hour?: number, minute?: number, second?: number, millisecond?: number);
  constructor(era: string, year: number, month: number, day: number, timeZone: string, offset: number, hour?: number, minute?: number, second?: number, millisecond?: number);
  constructor(calendar: Calendar, year: number, month: number, day: number, timeZone: string, offset: number, hour?: number, minute?: number, second?: number, millisecond?: number);
  constructor(calendar: Calendar, era: string, year: number, month: number, day: number, timeZone: string, offset: number, hour?: number, minute?: number, second?: number, millisecond?: number);

  /** The calendar system associated with this date, e.g. Gregorian. */
  readonly calendar: Calendar;
  /** The calendar era for this date, e.g. "BC" or "AD". */
  readonly era: string;
  /** The year of this date within the era. */
  readonly year: number;
  /** The month number within the year. */
  readonly month: number;
  /** The day number within the month. */
  readonly day: number;
  /** The hour in the day, numbered from 0 to 23. */
  readonly hour: number;
  /** The minute in the hour. */
  readonly minute: number;
  /** The second in the minute. */
  readonly second: number;
  /** The millisecond in the second. */
  readonly millisecond: number;
  /** The IANA time zone identifier that this date and time is represented in. */
  readonly timeZone: string;
  /** The UTC offset for this time, in milliseconds. */
  readonly offset: number;

  /** Returns a copy of this date. */
  copy(): ZonedDateTime;
  /** Returns a new ZonedDateTime with the given duration added to it. */
  add(duration: DateTimeDuration): ZonedDateTime;
  /** Returns a new ZonedDateTime with the given duration subtracted from it. */
  subtract(duration: DateTimeDuration): ZonedDateTime;
  /** Returns a new ZonedDateTime with the given fields set to the provided values. */
  set(fields: DateFields & TimeFields, disambiguation?: Disambiguation): ZonedDateTime;
  /** Returns a new ZonedDateTime with the given field adjusted by a specified amount. */
  cycle(field: DateField | TimeField, amount: number, options?: CycleTimeOptions): ZonedDateTime;
  /** Converts the date to a native JavaScript Date object. */
  toDate(): Date;
  /** Converts the date to an ISO 8601 formatted string, including the UTC offset and time zone identifier. */
  toString(): string;
  /** Converts the date to an ISO 8601 formatted string in UTC. */
  toAbsoluteString(): string;
  /** Compares this date with another. */
  compare(b: CalendarDate | CalendarDateTime | ZonedDateTime): number;
}

import { ZonedDateTime } from "@internationalized/date";

// Create zoned datetime objects
const zonedDT = new ZonedDateTime(2024, 3, 15, 'America/New_York', -5 * 60 * 60 * 1000, 14, 30);
const utcTime = new ZonedDateTime(2024, 3, 15, 'UTC', 0, 19, 30);

// Timezone-aware arithmetic (handles DST)
const nextDay = zonedDT.add({ days: 1 });
const nextHour = zonedDT.add({ hours: 1 });

// Set fields with disambiguation for DST
const newTime = zonedDT.set({ hour: 2, minute: 30 }, 'later');

// Different string representations
const withOffset = zonedDT.toString(); // "2024-03-15T14:30:00-05:00[America/New_York]"
const utcString = zonedDT.toAbsoluteString(); // "2024-03-15T19:30:00.000Z"

// Convert to JavaScript Date
const jsDate = zonedDT.toDate();

interface DateFields {
  era?: string;
  year?: number;
  month?: number;
  day?: number;
}

interface TimeFields {
  hour?: number;
  minute?: number;
  second?: number;
  millisecond?: number;
}

type DateField = keyof DateFields;
type TimeField = keyof TimeFields;

interface CycleOptions {
  /** Whether to round the field value to the nearest interval of the amount. */
  round?: boolean;
}

interface CycleTimeOptions extends CycleOptions {
  /**
   * Whether to use 12 or 24 hour time. If 12 hour time is chosen, the resulting value
   * will remain in the same day period as the original value.
   * @default 24
   */
  hourCycle?: 12 | 24;
}