Date and Time Classes

/**
 * Represents a calendar date without time or timezone
 */
class PlainDate {
  /** Creates a PlainDate from various inputs */
  static from(item: PlainDateLike | string, options?: AssignmentOptions): PlainDate;
  /** Compares two dates and returns -1, 0, or 1 */
  static compare(one: PlainDateLike, two: PlainDateLike): ComparisonResult;
  /** Constructs a new PlainDate */
  constructor(isoYear: number, isoMonth: number, isoDay: number, calendar?: CalendarLike);

  // Date component properties
  readonly calendarId: string;
  readonly year: number;
  readonly month: number;
  readonly monthCode: string;
  readonly day: number;
  readonly era: string | undefined;
  readonly eraYear: number | undefined;
  readonly dayOfWeek: number;
  readonly dayOfYear: number;
  readonly weekOfYear: number;
  readonly yearOfWeek: number;
  readonly daysInWeek: number;
  readonly daysInMonth: number;
  readonly daysInYear: number;
  readonly monthsInYear: number;
  readonly inLeapYear: boolean;

  // Date manipulation methods
  /** Returns a new PlainDate with the duration added */
  add(duration: DurationLike, options?: ArithmeticOptions): PlainDate;
  /** Returns a new PlainDate with the duration subtracted */
  subtract(duration: DurationLike, options?: ArithmeticOptions): PlainDate;
  /** Returns a new PlainDate with the specified fields changed */
  with(dateLike: PlainDateLike, options?: AssignmentOptions): PlainDate;
  /** Changes the calendar system of this date */
  withCalendar(calendar: CalendarLike): PlainDate;

  // Comparison and difference methods
  /** Returns the duration from this date until the other date */
  until(other: PlainDateLike, options?: DifferenceOptions<DateUnit>): Duration;
  /** Returns the duration from the other date since this date */
  since(other: PlainDateLike, options?: DifferenceOptions<DateUnit>): Duration;
  /** Tests if this date equals another date */
  equals(other: PlainDateLike): boolean;

  // Conversion methods
  /** Combines this date with a time to create a PlainDateTime */
  toPlainDateTime(plainTime?: PlainTimeLike): PlainDateTime;
  /** Converts this date to a ZonedDateTime in the specified timezone */
  toZonedDateTime(timeZone: TimeZoneLike | {timeZone: TimeZoneLike, plainTime?: PlainTimeLike}): ZonedDateTime;
  /** Extracts the year-month portion */
  toPlainYearMonth(): PlainYearMonth;
  /** Extracts the month-day portion */
  toPlainMonthDay(): PlainMonthDay;

  // String representation methods
  /** Returns a locale-formatted string representation */
  toLocaleString(locales?: string | string[], options?: Intl.DateTimeFormatOptions): string;
  /** Returns an ISO 8601 string representation */
  toString(options?: ShowCalendarOption): string;
  /** Returns a JSON representation (same as toString) */
  toJSON(): string;
  /** Throws a TypeError when used in comparison operators */
  valueOf(): never;
}

import { Temporal } from "temporal-polyfill";

// Creating dates
const today = Temporal.Now.plainDateISO();
const birthday = new Temporal.PlainDate(1990, 6, 15);
const fromString = Temporal.PlainDate.from("2024-03-15");
const fromObject = Temporal.PlainDate.from({ year: 2024, month: 3, day: 15 });

// Date arithmetic
const nextWeek = today.add({ days: 7 });
const lastMonth = today.subtract({ months: 1 });

// Modifying dates
const sameYear = birthday.with({ year: 2024 });
const endOfMonth = today.with({ day: today.daysInMonth });

// Comparisons
const daysBetween = birthday.until(today).days;
const isAfter = Temporal.PlainDate.compare(today, birthday) > 0;

// Conversions
const dateTime = today.toPlainDateTime(Temporal.PlainTime.from("09:00"));
const yearMonth = today.toPlainYearMonth();

/**
 * Represents a wall-clock time without date or timezone
 */
class PlainTime {
  /** Creates a PlainTime from various inputs */
  static from(item: PlainTimeLike | string, options?: AssignmentOptions): PlainTime;
  /** Compares two times and returns -1, 0, or 1 */
  static compare(one: PlainTimeLike, two: PlainTimeLike): ComparisonResult;
  /** Constructs a new PlainTime */
  constructor(hour?: number, minute?: number, second?: number, millisecond?: number, microsecond?: number, nanosecond?: number);

  // Time component properties
  readonly hour: number;
  readonly minute: number;
  readonly second: number;
  readonly millisecond: number;
  readonly microsecond: number;
  readonly nanosecond: number;

  // Time manipulation methods
  /** Returns a new PlainTime with the duration added */
  add(duration: DurationLike): PlainTime;
  /** Returns a new PlainTime with the duration subtracted */
  subtract(duration: DurationLike): PlainTime;
  /** Returns a new PlainTime with the specified fields changed */
  with(timeLike: PlainTimeLike, options?: AssignmentOptions): PlainTime;

  // Comparison and difference methods
  /** Returns the duration from this time until the other time */
  until(other: PlainTimeLike, options?: DifferenceOptions<TimeUnit>): Duration;
  /** Returns the duration from the other time since this time */
  since(other: PlainTimeLike, options?: DifferenceOptions<TimeUnit>): Duration;
  /** Rounds this time to the specified unit or precision */
  round(roundTo: TimeUnit | RoundingOptions<TimeUnit>): PlainTime;
  /** Tests if this time equals another time */
  equals(other: PlainTimeLike): boolean;

  // Conversion methods
  /** Combines this time with a date to create a PlainDateTime */
  toPlainDateTime(plainDate: PlainDateLike): PlainDateTime;
  /** Converts this time to a ZonedDateTime with the specified date and timezone */
  toZonedDateTime(options: {timeZone: TimeZoneLike, plainDate: PlainDateLike}): ZonedDateTime;

  // String representation methods
  /** Returns a locale-formatted string representation */
  toLocaleString(locales?: string | string[], options?: Intl.DateTimeFormatOptions): string;
  /** Returns an ISO 8601 string representation */
  toString(options?: ToStringPrecisionOptions): string;
  /** Returns a JSON representation (same as toString) */
  toJSON(): string;
  /** Throws a TypeError when used in comparison operators */
  valueOf(): never;
}

import { Temporal } from "temporal-polyfill";

// Creating times
const now = Temporal.Now.plainTimeISO();
const meetingTime = new Temporal.PlainTime(14, 30, 0);
const fromString = Temporal.PlainTime.from("09:00:00");
const fromObject = Temporal.PlainTime.from({ hour: 9, minute: 0 });

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

// Modifying times
const topOfHour = meetingTime.with({ minute: 0, second: 0 });
const precise = meetingTime.with({ millisecond: 500 });

// Rounding
const rounded = now.round({ smallestUnit: "minute" });
const hourly = now.round("hour");

// Comparisons
const duration = meetingTime.until(laterTime);
const isLater = Temporal.PlainTime.compare(laterTime, meetingTime) > 0;

// Conversions
const today = Temporal.Now.plainDateISO();
const dateTime = meetingTime.toPlainDateTime(today);

/**
 * Represents a date and time without timezone information
 */
class PlainDateTime {
  /** Creates a PlainDateTime from various inputs */
  static from(item: PlainDateTimeLike | string, options?: AssignmentOptions): PlainDateTime;
  /** Compares two date-times and returns -1, 0, or 1 */
  static compare(one: PlainDateTimeLike, two: PlainDateTimeLike): ComparisonResult;
  /** Constructs a new PlainDateTime */
  constructor(isoYear: number, isoMonth: number, isoDay: number, hour?: number, minute?: number, second?: number, millisecond?: number, microsecond?: number, nanosecond?: number, calendar?: CalendarLike);

  // All PlainDate properties
  readonly calendarId: string;
  readonly year: number;
  readonly month: number;
  readonly monthCode: string;
  readonly day: number;
  readonly era: string | undefined;
  readonly eraYear: number | undefined;
  readonly dayOfWeek: number;
  readonly dayOfYear: number;
  readonly weekOfYear: number;
  readonly yearOfWeek: number;
  readonly daysInWeek: number;
  readonly daysInMonth: number;
  readonly daysInYear: number;
  readonly monthsInYear: number;
  readonly inLeapYear: boolean;

  // All PlainTime properties
  readonly hour: number;
  readonly minute: number;
  readonly second: number;
  readonly millisecond: number;
  readonly microsecond: number;
  readonly nanosecond: number;

  // DateTime manipulation methods
  /** Returns a new PlainDateTime with the duration added */
  add(duration: DurationLike, options?: ArithmeticOptions): PlainDateTime;
  /** Returns a new PlainDateTime with the duration subtracted */
  subtract(duration: DurationLike, options?: ArithmeticOptions): PlainDateTime;
  /** Returns a new PlainDateTime with the specified fields changed */
  with(dateTimeLike: PlainDateTimeLike, options?: AssignmentOptions): PlainDateTime;
  /** Changes the calendar system of this date-time */
  withCalendar(calendar: CalendarLike): PlainDateTime;
  /** Changes the time portion of this date-time */
  withPlainTime(plainTime?: PlainTimeLike): PlainDateTime;

  // Comparison and difference methods
  /** Returns the duration from this date-time until the other date-time */
  until(other: PlainDateTimeLike, options?: DifferenceOptions<DateTimeUnit>): Duration;
  /** Returns the duration from the other date-time since this date-time */
  since(other: PlainDateTimeLike, options?: DifferenceOptions<DateTimeUnit>): Duration;
  /** Rounds this date-time to the specified unit or precision */
  round(roundTo: DateTimeUnit | RoundingOptions<DateTimeUnit>): PlainDateTime;
  /** Tests if this date-time equals another date-time */
  equals(other: PlainDateTimeLike): boolean;

  // Conversion methods
  /** Converts this date-time to a ZonedDateTime in the specified timezone */
  toZonedDateTime(options: TimeZoneLike | {timeZone: TimeZoneLike, disambiguation?: DisambiguationMode}): ZonedDateTime;
  /** Extracts the date portion */
  toPlainDate(): PlainDate;
  /** Extracts the time portion */
  toPlainTime(): PlainTime;
  /** Extracts the year-month portion */
  toPlainYearMonth(): PlainYearMonth;
  /** Extracts the month-day portion */
  toPlainMonthDay(): PlainMonthDay;

  // String representation methods
  /** Returns a locale-formatted string representation */
  toLocaleString(locales?: string | string[], options?: Intl.DateTimeFormatOptions): string;
  /** Returns an ISO 8601 string representation */
  toString(options?: CalendarDisplayOptions & ToStringPrecisionOptions): string;
  /** Returns a JSON representation (same as toString) */
  toJSON(): string;
  /** Throws a TypeError when used in comparison operators */
  valueOf(): never;
}

import { Temporal } from "temporal-polyfill";

// Creating date-times
const now = Temporal.Now.plainDateTimeISO();
const meeting = new Temporal.PlainDateTime(2024, 3, 15, 14, 30, 0);
const fromString = Temporal.PlainDateTime.from("2024-03-15T14:30:00");
const combined = Temporal.PlainDate.from("2024-03-15").toPlainDateTime("14:30:00");

// DateTime arithmetic
const nextWeek = meeting.add({ weeks: 1 });
const twoHoursEarlier = meeting.subtract({ hours: 2 });

// Modifying date-times
const sameTimeTomorrow = meeting.add({ days: 1 });
const topOfHour = meeting.with({ minute: 0, second: 0 });
const newTime = meeting.withPlainTime({ hour: 16, minute: 0 });

// Rounding
const roundedToHour = meeting.round("hour");
const roundedToMinute = meeting.round({ smallestUnit: "minute" });

// Comparisons
const duration = meeting.until(nextWeek);
const hoursUntil = meeting.until(nextWeek, { largestUnit: "hour" }).hours;

// Conversions
const inNewYork = meeting.toZonedDateTime("America/New_York");
const justDate = meeting.toPlainDate();
const justTime = meeting.toPlainTime();

// Core type definitions for date and time classes
type PlainDateLike = PlainDate | PlainDateFields;
type PlainTimeLike = PlainTime | PlainTimeFields;
type PlainDateTimeLike = PlainDateTime | PlainDateTimeFields;
type CalendarLike = string | Calendar;

interface PlainDateFields {
  era?: string;
  eraYear?: number;
  year: number;
  month?: number;
  monthCode?: string;
  day: number;
  calendar?: CalendarLike;
}

interface PlainTimeFields {
  hour?: number;
  minute?: number;
  second?: number;
  millisecond?: number;
  microsecond?: number;
  nanosecond?: number;
}

interface PlainDateTimeFields extends PlainDateFields, PlainTimeFields {}

// Unit types for date and time operations
type DateUnit = 'year' | 'month' | 'week' | 'day';
type TimeUnit = 'hour' | 'minute' | 'second' | 'millisecond' | 'microsecond' | 'nanosecond';
type DateTimeUnit = DateUnit | TimeUnit;

// Display and precision options
interface ShowCalendarOption {
  calendarName?: 'auto' | 'always' | 'never' | 'critical';
}

interface ToStringPrecisionOptions {
  fractionalSecondDigits?: 'auto' | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9;
  smallestUnit?: TimeUnit;
  roundingMode?: RoundingMode;
}

interface CalendarDisplayOptions {
  calendarName?: 'auto' | 'always' | 'never' | 'critical';
}