@internationalized/date 3.0.0-alpha.1 → 3.0.0-alpha.4

package/src/CalendarDate.ts

@@ -11,7 +11,7 @@
  */
 
 import {add, addTime, addZoned, constrain, constrainTime, cycleDate, cycleTime, cycleZoned, set, setTime, setZoned, subtract, subtractTime, subtractZoned} from './manipulation';
-import {AnyCalendarDate, AnyTime, Calendar, CycleOptions, CycleTimeOptions, DateField, DateFields, Disambiguation, Duration, TimeField, TimeFields} from './types';
+import {AnyCalendarDate, AnyTime, Calendar, CycleOptions, CycleTimeOptions, DateDuration, DateField, DateFields, DateTimeDuration, Disambiguation, TimeDuration, TimeField, TimeFields} from './types';
 import {compareDate, compareTime} from './queries';
 import {dateTimeToString, dateToString, timeToString, zonedDateTimeToString} from './string';
 import {GregorianCalendar} from './calendars/GregorianCalendar';
@@ -37,15 +37,25 @@ function shiftArgs(args: any[]) {
   return [calendar, era, year, month, day];
 }
 
+/** A CalendarDate represents a date without any time components in a specific calendar system. */
 export class CalendarDate {
   // This prevents TypeScript from allowing other types with the same fields to match.
   // i.e. a ZonedDateTime should not be be passable to a parameter that expects CalendarDate.
   // If that behavior is desired, use the AnyCalendarDate interface instead.
   #type;
+  /** The calendar system associated with this date, e.g. Gregorian. */
   public readonly calendar: Calendar;
+  /** The calendar era for this date, e.g. "BC" or "AD". */
   public readonly era: string;
+  /** The year of this date within the era. */
   public readonly year: number;
+  /**
+   * The month number within the year. Note that some calendar systems such as Hebrew
+   * may have a variable number of months per year. Therefore, month numbers may not
+   * always correspond to the same month names in different years.
+   */
   public readonly month: number;
+  /** The day number within the month. */
   public readonly day: number;
 
   constructor(year: number, month: number, day: number);
@@ -62,6 +72,7 @@ export class CalendarDate {
     constrain(this);
   }
 
+  /** Returns a copy of this date. */
   copy(): CalendarDate {
     if (this.era) {
       return new CalendarDate(this.calendar, this.era, this.year, this.month, this.day);
@@ -70,88 +81,135 @@ export class CalendarDate {
     }
   }
 
-  add(duration: Duration) {
+  /** Returns a new `CalendarDate` with the given duration added to it. */
+  add(duration: DateDuration): CalendarDate {
     return add(this, duration);
   }
 
-  subtract(duration: Duration) {
+  /** Returns a new `CalendarDate` with the given duration subtracted from it. */
+  subtract(duration: DateDuration): CalendarDate {
     return subtract(this, duration);
   }
 
-  set(fields: DateFields) {
+  /** Returns a new `CalendarDate` with the given fields set to the provided values. Other fields will be constrained accordingly. */
+  set(fields: DateFields): CalendarDate {
     return set(this, fields);
   }
 
-  cycle(field: DateField, amount: number, options?: CycleOptions) {
+  /**
+   * Returns a new `CalendarDate` with the given field adjusted by a specified amount.
+   * When the resulting value reaches the limits of the field, it wraps around.
+   */
+  cycle(field: DateField, amount: number, options?: CycleOptions): CalendarDate {
     return cycleDate(this, field, amount, options);
   }
 
-  toDate(timeZone: string) {
+  /** Converts the date to a native JavaScript Date object, with the time set to midnight in the given time zone. */
+  toDate(timeZone: string): Date {
     return toDate(this, timeZone);
   }
 
-  toString() {
+  /** Converts the date to an ISO 8601 formatted string. */
+  toString(): string {
     return dateToString(this);
   }
 
-  compare(b: AnyCalendarDate) {
+  /** Compares this date with another. A negative result indicates that this date is before the given one, and a positive date indicates that it is after. */
+  compare(b: AnyCalendarDate): number {
     return compareDate(this, b);
   }
 }
 
+/** A Time represents a clock time without any date components. */
 export class Time {
   // This prevents TypeScript from allowing other types with the same fields to match.
   #type;
+  /** The hour, numbered from 0 to 23. */
+  public readonly hour: number;
+  /** The minute in the hour. */
+  public readonly minute: number;
+  /** The second in the minute. */
+  public readonly second: number;
+  /** The millisecond in the second. */
+  public readonly millisecond: number;
 
   constructor(
-    public readonly hour: number = 0,
-    public readonly minute: number = 0,
-    public readonly second: number = 0,
-    public readonly millisecond: number = 0
+    hour: number = 0,
+    minute: number = 0,
+    second: number = 0,
+    millisecond: number = 0
   ) {
+    this.hour = hour;
+    this.minute = minute;
+    this.second = second;
+    this.millisecond = millisecond;
     constrainTime(this);
   }
 
+  /** Returns a copy of this time. */
   copy(): Time {
     return new Time(this.hour, this.minute, this.second, this.millisecond);
   }
 
-  add(duration: Duration) {
+  /** Returns a new `Time` with the given duration added to it. */
+  add(duration: TimeDuration) {
     return addTime(this, duration);
   }
 
-  subtract(duration: Duration) {
+  /** Returns a new `Time` with the given duration subtracted from it. */
+  subtract(duration: TimeDuration) {
     return subtractTime(this, duration);
   }
 
+  /** Returns a new `Time` with the given fields set to the provided values. Other fields will be constrained accordingly. */
   set(fields: TimeFields) {
     return setTime(this, fields);
   }
 
+  /**
+   * Returns a new `Time` with the given field adjusted by a specified amount.
+   * When the resulting value reaches the limits of the field, it wraps around.
+   */
   cycle(field: TimeField, amount: number, options?: CycleTimeOptions) {
     return cycleTime(this, field, amount, options);
   }
 
+  /** Converts the time to an ISO 8601 formatted string. */
   toString() {
     return timeToString(this);
   }
 
+  /** Compares this time with another. A negative result indicates that this time is before the given one, and a positive time indicates that it is after. */
   compare(b: AnyTime) {
     return compareTime(this, b);
   }
 }
 
+/** A CalendarDateTime represents a date and time without a time zone, in a specific calendar system. */
 export class CalendarDateTime {
   // This prevents TypeScript from allowing other types with the same fields to match.
   #type;
+  /** The calendar system associated with this date, e.g. Gregorian. */
   public readonly calendar: Calendar;
+  /** The calendar era for this date, e.g. "BC" or "AD". */
   public readonly era: string;
+  /** The year of this date within the era. */
   public readonly year: number;
+  /**
+   * The month number within the year. Note that some calendar systems such as Hebrew
+   * may have a variable number of months per year. Therefore, month numbers may not
+   * always correspond to the same month names in different years.
+   */
   public readonly month: number;
+  /** The day number within the month. */
   public readonly day: number;
+  /** The hour in the day, numbered from 0 to 23. */
   public readonly hour: number;
+  /** The minute in the hour. */
   public readonly minute: number;
+  /** The second in the minute. */
   public readonly second: number;
+  /** The millisecond in the second. */
   public readonly millisecond: number;
 
   constructor(year: number, month: number, day: number, hour?: number, minute?: number, second?: number, millisecond?: number);
@@ -172,6 +230,7 @@ export class CalendarDateTime {
     constrain(this);
   }
 
+  /** Returns a copy of this date. */
   copy(): CalendarDateTime {
     if (this.era) {
       return new CalendarDateTime(this.calendar, this.era, this.year, this.month, this.day, this.hour, this.minute, this.second, this.millisecond);
@@ -180,19 +239,26 @@ export class CalendarDateTime {
     }
   }
 
-  add(duration: Duration) {
+  /** Returns a new `CalendarDateTime` with the given duration added to it. */
+  add(duration: DateTimeDuration): CalendarDateTime {
     return add(this, duration);
   }
 
-  subtract(duration: Duration) {
+  /** Returns a new `CalendarDateTime` with the given duration subtracted from it. */
+  subtract(duration: DateTimeDuration): CalendarDateTime {
     return subtract(this, duration);
   }
 
-  set(fields: DateFields & TimeFields) {
+  /** Returns a new `CalendarDateTime` with the given fields set to the provided values. Other fields will be constrained accordingly. */
+  set(fields: DateFields & TimeFields): CalendarDateTime {
     return set(setTime(this, fields), fields);
   }
 
-  cycle(field: DateField | TimeField, amount: number, options?: CycleTimeOptions) {
+  /**
+   * Returns a new `CalendarDateTime` with the given field adjusted by a specified amount.
+   * When the resulting value reaches the limits of the field, it wraps around.
+   */
+  cycle(field: DateField | TimeField, amount: number, options?: CycleTimeOptions): CalendarDateTime {
     switch (field) {
       case 'era':
       case 'year':
@@ -204,15 +270,18 @@ export class CalendarDateTime {
     }
   }
 
-  toDate(timeZone: string) {
-    return toDate(this, timeZone);
+  /** Converts the date to a native JavaScript Date object in the given time zone. */
+  toDate(timeZone: string, disambiguation?: Disambiguation): Date {
+    return toDate(this, timeZone, disambiguation);
   }
 
-  toString() {
+  /** Converts the date to an ISO 8601 formatted string. */
+  toString(): string {
     return dateTimeToString(this);
   }
 
-  compare(b: CalendarDate | CalendarDateTime | ZonedDateTime) {
+  /** Compares this date with another. A negative result indicates that this date is before the given one, and a positive date indicates that it is after. */
+  compare(b: CalendarDate | CalendarDateTime | ZonedDateTime): number {
     let res = compareDate(this, b);
     if (res === 0) {
       return compareTime(this, toCalendarDateTime(b));
@@ -222,19 +291,35 @@ export class CalendarDateTime {
   }
 }
 
+/** A ZonedDateTime represents a date and time in a specific time zone and calendar system. */
 export class ZonedDateTime {
   // This prevents TypeScript from allowing other types with the same fields to match.
   #type;
+  /** The calendar system associated with this date, e.g. Gregorian. */
   public readonly calendar: Calendar;
+  /** The calendar era for this date, e.g. "BC" or "AD". */
   public readonly era: string;
+  /** The year of this date within the era. */
   public readonly year: number;
+  /**
+   * The month number within the year. Note that some calendar systems such as Hebrew
+   * may have a variable number of months per year. Therefore, month numbers may not
+   * always correspond to the same month names in different years.
+   */
   public readonly month: number;
+  /** The day number within the month. */
   public readonly day: number;
+  /** The hour in the day, numbered from 0 to 23. */
   public readonly hour: number;
+  /** The minute in the hour. */
   public readonly minute: number;
+  /** The second in the minute. */
   public readonly second: number;
+  /** The millisecond in the second. */
   public readonly millisecond: number;
+  /** The IANA time zone identifier that this date and time is represented in. */
   public readonly timeZone: string;
+  /** The UTC offset for this time, in seconds. */
   public readonly offset: number;
 
   constructor(year: number, month: number, day: number, timeZone: string, offset: number, hour?: number, minute?: number, second?: number, millisecond?: number);
@@ -259,6 +344,7 @@ export class ZonedDateTime {
     constrain(this);
   }
 
+  /** Returns a copy of this date. */
   copy(): ZonedDateTime {
     if (this.era) {
       return new ZonedDateTime(this.calendar, this.era, this.year, this.month, this.day, this.timeZone, this.offset, this.hour, this.minute, this.second, this.millisecond);
@@ -267,34 +353,45 @@ export class ZonedDateTime {
     }
   }
 
-  add(duration: Duration) {
+  /** Returns a new `ZonedDateTime` with the given duration added to it. */
+  add(duration: DateTimeDuration) {
     return addZoned(this, duration);
   }
 
-  subtract(duration: Duration) {
+  /** Returns a new `ZonedDateTime` with the given duration subtracted from it. */
+  subtract(duration: DateTimeDuration) {
     return subtractZoned(this, duration);
   }
 
+  /** Returns a new `ZonedDateTime` with the given fields set to the provided values. Other fields will be constrained accordingly. */
   set(fields: DateFields & TimeFields, disambiguation?: Disambiguation) {
     return setZoned(this, fields, disambiguation);
   }
 
+  /**
+   * Returns a new `ZonedDateTime` with the given field adjusted by a specified amount.
+   * When the resulting value reaches the limits of the field, it wraps around.
+   */
   cycle(field: DateField | TimeField, amount: number, options?: CycleTimeOptions) {
     return cycleZoned(this, field, amount, options);
   }
 
+  /** Converts the date to a native JavaScript Date object. */
   toDate() {
     return zonedToDate(this);
   }
 
+   /** Converts the date to an ISO 8601 formatted string, including the UTC offset and time zone identifier. */
   toString() {
     return zonedDateTimeToString(this);
   }
 
+   /** Converts the date to an ISO 8601 formatted string in UTC. */
   toAbsoluteString() {
     return this.toDate().toISOString();
   }
 
+  /** Compares this date with another. A negative result indicates that this date is before the given one, and a positive date indicates that it is after. */
   compare(b: CalendarDate | CalendarDateTime | ZonedDateTime) {
     // TODO: Is this a bad idea??
     return this.toDate().getTime() - toZoned(b, this.timeZone).toDate().getTime();

package/src/DateFormatter.ts

@@ -20,6 +20,7 @@ interface DateRangeFormatPart extends Intl.DateTimeFormatPart {
   source: 'startRange' | 'endRange' | 'shared'
 }
 
+/** A wrapper around Intl.DateTimeFormat that fixes various browser bugs, and polyfills new features. */
 export class DateFormatter implements Intl.DateTimeFormat {
   private formatter: Intl.DateTimeFormat;
   private options: Intl.DateTimeFormatOptions;
@@ -30,14 +31,17 @@ export class DateFormatter implements Intl.DateTimeFormat {
     this.options = options;
   }
 
+  /** Formats a date as a string according to the locale and format options passed to the constructor. */
   format(value: Date): string {
     return this.formatter.format(value);
   }
 
+  /** Formats a date to an array of parts such as separators, numbers, punctuation, and more. */
   formatToParts(value: Date): Intl.DateTimeFormatPart[] {
     return this.formatter.formatToParts(value);
   }
 
+  /** Formats a date range as a string. */
   formatRange(start: Date, end: Date): string {
     // @ts-ignore
     if (typeof this.formatter.formatRange === 'function') {
@@ -53,6 +57,7 @@ export class DateFormatter implements Intl.DateTimeFormat {
     return `${this.formatter.format(start)} – ${this.formatter.format(end)}`;
   }
 
+  /** Formats a date range as an array of parts. */
   formatRangeToParts(start: Date, end: Date): DateRangeFormatPart[] {
     // @ts-ignore
     if (typeof this.formatter.formatRangeToParts === 'function') {
@@ -73,6 +78,7 @@ export class DateFormatter implements Intl.DateTimeFormat {
     ];
   }
 
+  /** Returns the resolved formatting options based on the values passed to the constructor. */
   resolvedOptions(): ResolvedDateTimeFormatOptions {
     let resolvedOptions = this.formatter.resolvedOptions() as ResolvedDateTimeFormatOptions;
     if (hasBuggyResolvedHourCycle()) {

package/src/calendars/BuddhistCalendar.ts

@@ -20,6 +20,11 @@ import {Mutable} from '../utils';
 
 const BUDDHIST_ERA_START = -543;
 
+/**
+ * The Buddhist calendar is the same as the Gregorian calendar, but counts years
+ * starting from the birth of Buddha in 543 BC (Gregorian). It supports only one
+ * era, identified as 'BE'.
+ */
 export class BuddhistCalendar extends GregorianCalendar {
   identifier = 'buddhist';
 
@@ -30,16 +35,22 @@ export class BuddhistCalendar extends GregorianCalendar {
   }
 
   toJulianDay(date: AnyCalendarDate) {
-    return super.toJulianDay(
-      new CalendarDate(
-        date.year + BUDDHIST_ERA_START,
-        date.month,
-        date.day
-      )
-    );
+    return super.toJulianDay(toGregorian(date));
   }
 
   getEras() {
     return ['BE'];
   }
+
+  getDaysInMonth(date: AnyCalendarDate): number {
+    return super.getDaysInMonth(toGregorian(date));
+  }
+}
+
+function toGregorian(date: AnyCalendarDate) {
+  return new CalendarDate(
+    date.year + BUDDHIST_ERA_START,
+    date.month,
+    date.day
+  );
 }

package/src/calendars/EthiopicCalendar.ts

@@ -61,6 +61,11 @@ function getDaysInMonth(year: number, month: number) {
   }
 }
 
+/**
+ * The Ethiopic calendar system is the official calendar used in Ethiopia.
+ * It includes 12 months of 30 days each, plus 5 or 6 intercalary days depending
+ * on whether it is a leap year. Two eras are supported: 'AA' and 'AM'.
+ */
 export class EthiopicCalendar implements Calendar {
   identifier = 'ethiopic';
 
@@ -111,6 +116,10 @@ export class EthiopicCalendar implements Calendar {
   }
 }
 
+/**
+ * The Ethiopic (Amete Alem) calendar is the same as the modern Ethiopic calendar,
+ * except years were measured from a different epoch. Only one era is supported: 'AA'.
+ */
 export class EthiopicAmeteAlemCalendar extends EthiopicCalendar {
   identifier = 'ethioaa'; // also known as 'ethiopic-amete-alem' in ICU
 
@@ -126,6 +135,11 @@ export class EthiopicAmeteAlemCalendar extends EthiopicCalendar {
   }
 }
 
+/**
+ * The Coptic calendar is similar to the Ethiopic calendar.
+ * It includes 12 months of 30 days each, plus 5 or 6 intercalary days depending
+ * on whether it is a leap year. Two eras are supported: 'BCE' and 'CE'.
+ */
 export class CopticCalendar extends EthiopicCalendar {
   identifier = 'coptic';
 

package/src/calendars/GregorianCalendar.ts

@@ -47,6 +47,10 @@ const daysInMonth = {
   leapyear: [31, 29, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31]
 };
 
+/**
+ * The Gregorian calendar is the most commonly used calendar system in the world. It supports two eras: BC, and AD.
+ * Years always contain 12 months, and 365 or 366 days depending on whether it is a leap year.
+ */
 export class GregorianCalendar implements Calendar {
   identifier = 'gregory';
 

package/src/calendars/HebrewCalendar.ts

@@ -122,6 +122,11 @@ function getDaysInMonth(year: number, month: number): number {
   return 30;
 }
 
+/**
+ * The Hebrew calendar is used in Israel and around the world by the Jewish faith.
+ * Years include either 12 or 13 months depending on whether it is a leap year.
+ * In leap years, an extra month is inserted at month 6.
+ */
 export class HebrewCalendar implements Calendar {
   identifier = 'hebrew';
 

package/src/calendars/IndianCalendar.ts

@@ -24,6 +24,11 @@ const INDIAN_ERA_START = 78;
 // The Indian year starts 80 days later than the Gregorian year.
 const INDIAN_YEAR_START = 80;
 
+/**
+ * The Indian National Calendar is similar to the Gregorian calendar, but with
+ * years numbered since the Saka era in 78 AD (Gregorian). There are 12 months
+ * in each year, with either 30 or 31 days. Only one era identifier is supported: 'saka'.
+ */
 export class IndianCalendar extends GregorianCalendar {
   identifier = 'indian';
 

package/src/calendars/IslamicCalendar.ts

@@ -42,6 +42,13 @@ function isLeapYear(year: number): boolean {
   return (14 + 11 * year) % 30 < 11;
 }
 
+/**
+ * The Islamic calendar, also known as the "Hijri" calendar, is used throughout much of the Arab world.
+ * The civil variant uses simple arithmetic rules rather than astronomical calculations to approximate
+ * the traditional calendar, which is based on sighting of the crescent moon. It uses Friday, July 16 622 CE (Julian) as the epoch.
+ * Each year has 12 months, with either 354 or 355 days depending on whether it is a leap year.
+ * Learn more about the available Islamic calendars [here](https://cldr.unicode.org/development/development-process/design-proposals/islamic-calendar-types).
+ */
 export class IslamicCivilCalendar implements Calendar {
   identifier = 'islamic-civil';
 
@@ -79,6 +86,13 @@ export class IslamicCivilCalendar implements Calendar {
   }
 }
 
+/**
+ * The Islamic calendar, also known as the "Hijri" calendar, is used throughout much of the Arab world.
+ * The tabular variant uses simple arithmetic rules rather than astronomical calculations to approximate
+ * the traditional calendar, which is based on sighting of the crescent moon. It uses Thursday, July 15 622 CE (Julian) as the epoch.
+ * Each year has 12 months, with either 354 or 355 days depending on whether it is a leap year.
+ * Learn more about the available Islamic calendars [here](https://cldr.unicode.org/development/development-process/design-proposals/islamic-calendar-types).
+ */
 export class IslamicTabularCalendar extends IslamicCivilCalendar {
   identifier = 'islamic-tbla';
 
@@ -122,6 +136,13 @@ function umalquraYearLength(year: number): number {
   return UMALQURA_YEAR_START_TABLE[year + 1 - UMALQURA_YEAR_START] - UMALQURA_YEAR_START_TABLE[year - UMALQURA_YEAR_START];
 }
 
+/**
+ * The Islamic calendar, also known as the "Hijri" calendar, is used throughout much of the Arab world.
+ * The Umalqura variant is primarily used in Saudi Arabia. It is a lunar calendar, based on astronomical
+ * calculations that predict the sighting of a crescent moon. Month and year lengths vary between years
+ * depending on these calculations.
+ * Learn more about the available Islamic calendars [here](https://cldr.unicode.org/development/development-process/design-proposals/islamic-calendar-types).
+ */
 export class IslamicUmalquraCalendar extends IslamicCivilCalendar {
   identifier = 'islamic-umalqura';
 

package/src/calendars/JapaneseCalendar.ts

@@ -64,6 +64,11 @@ function toGregorian(date: AnyCalendarDate) {
   );
 }
 
+/**
+ * The Japanese calendar is based on the Gregorian calendar, but with eras for the reign of each Japanese emperor.
+ * Whenever a new emperor ascends to the throne, a new era begins and the year starts again from 1.
+ * Note that eras before 1868 (Gregorian) are not currently supported by this implementation.
+ */
 export class JapaneseCalendar extends GregorianCalendar {
   identifier = 'japanese';
 
@@ -141,6 +146,10 @@ export class JapaneseCalendar extends GregorianCalendar {
     return years;
   }
 
+  getDaysInMonth(date: AnyCalendarDate): number {
+    return super.getDaysInMonth(toGregorian(date));
+  }
+
   getMinimumMonthInYear(date: AnyCalendarDate): number {
     let start = getMinimums(date);
     return start ? start[1] : 1;

package/src/calendars/PersianCalendar.ts

@@ -42,6 +42,12 @@ function persianToJulianDay(year: number, month: number, day: number): number {
   );
 }
 
+/**
+ * The Persian calendar is the main calendar used in Iran and Afghanistan. It has 12 months
+ * in each year, the first 6 of which have 31 days, and the next 5 have 30 days. The 12th month
+ * has either 29 or 30 days depending on whether it is a leap year. The Persian year starts
+ * around the March equinox.
+ */
 export class PersianCalendar implements Calendar {
   identifier = 'persian';
 

package/src/calendars/TaiwanCalendar.ts

@@ -37,6 +37,11 @@ function gregorianToTaiwan(year: number, date: Mutable<AnyCalendarDate>) {
   }
 }
 
+/**
+ * The Taiwanese calendar is the same as the Gregorian calendar, but years
+ * are numbered starting from 1912 (Gregorian). Two eras are supported:
+ * 'before_minguo' and 'minguo'.
+ */
 export class TaiwanCalendar extends GregorianCalendar {
   identifier = 'roc'; // Republic of China
 
@@ -47,13 +52,7 @@ export class TaiwanCalendar extends GregorianCalendar {
   }
 
   toJulianDay(date: AnyCalendarDate) {
-    return super.toJulianDay(
-      new CalendarDate(
-        gregorianYear(date),
-        date.month,
-        date.day
-      )
-    );
+    return super.toJulianDay(toGregorian(date));
   }
 
   getEras() {
@@ -67,4 +66,16 @@ export class TaiwanCalendar extends GregorianCalendar {
   getYearsToAdd(date: Mutable<AnyCalendarDate>, years: number) {
     return date.era === 'before_minguo' ? -years : years;
   }
+
+  getDaysInMonth(date: AnyCalendarDate): number {
+    return super.getDaysInMonth(toGregorian(date));
+  }
+}
+
+function toGregorian(date: AnyCalendarDate) {
+  return new CalendarDate(
+    gregorianYear(date),
+    date.month,
+    date.day
+  );
 }