@internationalized/date - npm Package Compare versions

Comparing version 3.0.0-nightly.3134 to 3.0.0-nightly.3142

dist/types.d.ts

@@ -0,1 +1,2 @@
+/** An interface that is compatible with any object with date fields. */
 export interface AnyCalendarDate {
@@ -9,2 +10,3 @@ readonly calendar: Calendar;
 }
+/** An interface that is compatible with any object with time fields. */
 export interface AnyTime {
@@ -17,29 +19,71 @@ readonly hour: number;
 }
+/** An interface that is compatible with any object with both date and time fields. */
 export interface AnyDateTime extends AnyCalendarDate, AnyTime {
 }
+/**
+ * The Calendar interface represents a calendar system, including information
+ * about how days, months, years, and eras are organized, and methods to perform
+ * arithmetic on dates.
+ */
 export interface Calendar {
+    /** A string identifier for the calendar, as defined by Unicode CLDR. */
     identifier: string;
+    /** Creates a CalendarDate in this calendar from the given Julian day number. */
     fromJulianDay(jd: number): CalendarDate;
+    /** Converts a date in this calendar to a Julian day number. */
     toJulianDay(date: AnyCalendarDate): number;
+    /** Returns the number of days in the month of the given date. */
     getDaysInMonth(date: AnyCalendarDate): number;
+    /** Returns the number of months in the year of the given date. */
     getMonthsInYear(date: AnyCalendarDate): number;
+    /** Returns the number of years in the era of the given date. */
     getYearsInEra(date: AnyCalendarDate): number;
+    /** Returns a list of era identifiers for the calendar. */
     getEras(): string[];
+    /**
+     * Returns the minimum month number of the given date's year.
+     * Normally, this is 1, but in some calendars such as the Japanese,
+     * eras may begin in the middle of a year.
+     */
     getMinimumMonthInYear?(date: AnyCalendarDate): number;
+    /**
+     * Returns the minimum day number of the given date's month.
+     * Normally, this is 1, but in some calendars such as the Japanese,
+     * eras may begin in the middle of a month.
+     */
     getMinimumDayInMonth?(date: AnyCalendarDate): number;
+    /** @private */
     balanceDate?(date: AnyCalendarDate): void;
+    /** @private */
     balanceYearMonth?(date: AnyCalendarDate, previousDate: AnyCalendarDate): void;
+    /** @private */
     getYearsToAdd?(date: AnyCalendarDate, years: number): number;
+    /** @private */
     constrainDate?(date: AnyCalendarDate): void;
 }
-export interface Duration {
+/** Represents an amount of time in calendar-specific units, for use when performing arithmetic. */
+export interface DateDuration {
+    /** The number of years to add or subtract. */
     years?: number;
+    /** The number of months to add or subtract. */
     months?: number;
+    /** The number of weeks to add or subtract. */
     weeks?: number;
+    /** The number of days to add or subtract. */
     days?: number;
+}
+/** Represents an amount of time, for use whe performing arithmetic. */
+export interface TimeDuration {
+    /** The number of hours to add or subtract. */
     hours?: number;
+    /** The number of minutes to add or subtract. */
     minutes?: number;
+    /** The number of seconds to add or subtract. */
     seconds?: number;
+    /** The number of milliseconds to add or subtract. */
     milliseconds?: number;
 }
+/** Represents an amount of time with both date and time components, for use when performing arithmetic. */
+export interface DateTimeDuration extends DateDuration, TimeDuration {
+}
 export interface DateFields {
@@ -74,15 +118,32 @@ era?: string;
 type DateValue = CalendarDate | CalendarDateTime | ZonedDateTime;
+/** Returns whether the given dates occur on the same day, regardless of the time or calendar system. */
 export function isSameDay(a: DateValue, b: DateValue): boolean;
+/** Returns whether the given dates occur in the same month, using the calendar system of the first date. */
 export function isSameMonth(a: DateValue, b: DateValue): boolean;
+/** Returns whether the given dates occur in the same year, using the calendar system of the first date. */
 export function isSameYear(a: DateValue, b: DateValue): boolean;
+/** Returns whether the given dates occur on the same day, and are of the same calendar system. */
 export function isEqualDay(a: DateValue, b: DateValue): boolean;
+/** Returns whether the given dates occur in the same month, and are of the same calendar system. */
 export function isEqualMonth(a: DateValue, b: DateValue): boolean;
+/** Returns whether the given dates occur in the same year, and are of the same calendar system. */
 export function isEqualYear(a: DateValue, b: DateValue): boolean;
+/** Returns whether the date is today in the given time zone. */
 export function isToday(date: DateValue, timeZone: string): boolean;
+/**
+ * Returns the day of week for the given date and locale. Days are numbered from zero to six,
+ * where zero is the first day of the week in the given locale. For example, in the United States,
+ * the first day of the week is Sunday, but in France it is Monday.
+ */
 export function getDayOfWeek(date: DateValue, locale: string): number;
+/** Returns the current time in the given time zone. */
 export function now(timeZone: string): ZonedDateTime;
+/** Returns today's date in the given time zone. */
 export function today(timeZone: string): CalendarDate;
-export function compareDate(a: AnyCalendarDate, b: AnyCalendarDate): number;
-export function compareTime(a: AnyTime, b: AnyTime): number;
+/**
+ * Returns the number of hours in the given date and time zone.
+ * Usually this is 24, but it could be 23 or 25 if the date is on a daylight saving transition.
+ */
 export function getHoursInDay(a: CalendarDate, timeZone: string): number;
+/** Returns the time zone identifier for the current user. */
 export function getLocalTimeZone(): string;
@@ -114,6 +175,11 @@ export function startOfMonth(date: ZonedDateTime): ZonedDateTime;
 export function endOfWeek(date: CalendarDate, locale: string): CalendarDate;
+/** Returns the number of weeks in the given month and locale. */
 export function getWeeksInMonth(date: DateValue, locale: string): number;
+/** Returns the lesser of the two provider dates. */
 export function minDate<A extends DateValue, B extends DateValue>(a: A, b: B): A | B;
+/** Returns the greater of the two provider dates. */
 export function maxDate<A extends DateValue, B extends DateValue>(a: A, b: B): A | B;
+/** Returns whether the given date is on a weekend in the given locale. */
 export function isWeekend(date: DateValue, locale: string): boolean;
+/** Returns whether the given date is on a weekday in the given locale. */
 export function isWeekday(date: DateValue, locale: string): boolean;
@@ -123,2 +189,6 @@ type Mutable<T> = {
 };
+/**
+ * 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 {
@@ -136,19 +206,21 @@ identifier: string;
 }
-export function epochFromDate(date: AnyDateTime): number;
-export function getTimeZoneOffset(ms: number, timeZone: string): number;
-export function possibleAbsolutes(date: CalendarDateTime, timeZone: string): number[];
-export function toAbsolute(date: CalendarDate | CalendarDateTime, timeZone: string, disambiguation?: Disambiguation): number;
-export function toDate(dateTime: CalendarDate | CalendarDateTime, timeZone: string, disambiguation?: Disambiguation): Date;
-export function fromAbsolute(ms: number, timeZone: string): ZonedDateTime;
-export function fromDate(date: Date, timeZone: string): ZonedDateTime;
-export function fromDateToLocal(date: Date): ZonedDateTime;
+/** Converts a value with date components such as a `CalendarDateTime` or `ZonedDateTime` into a `CalendarDate`. */
 export function toCalendarDate(dateTime: AnyCalendarDate): CalendarDate;
-export function toDateFields(date: AnyCalendarDate): DateFields;
-export function toTimeFields(date: AnyTime): TimeFields;
+/**
+ * Converts a date value to a `CalendarDateTime`. An optional `Time` value can be passed to set the time
+ * of the resulting value, otherwise it will default to midnight.
+ */
 export function toCalendarDateTime(date: CalendarDate | CalendarDateTime | ZonedDateTime, time?: AnyTime): CalendarDateTime;
-export function toTime(dateTime: CalendarDateTime): Time;
+/** Extracts the time components from a value containing a date and time. */
+export function toTime(dateTime: CalendarDateTime | ZonedDateTime): Time;
+/** Converts a date from one calendar system to another. */
 export function toCalendar<T extends AnyCalendarDate>(date: T, calendar: Calendar): T;
+/**
+ * Converts a date value to a `ZonedDateTime` in the provided time zone. The `disambiguation` option can be set
+ * to control how values that fall on daylight saving time changes are interpreted.
+ */
 export function toZoned(date: CalendarDate | CalendarDateTime | ZonedDateTime, timeZone: string, disambiguation?: Disambiguation): ZonedDateTime;
-export function zonedToDate(date: ZonedDateTime): Date;
+/** Converts a `ZonedDateTime` from one time zone to another. */
 export function toTimeZone(date: ZonedDateTime, timeZone: string): ZonedDateTime;
+/** Converts the given `ZonedDateTime` into the user's local time zone. */
 export function toLocalTimeZone(date: ZonedDateTime): ZonedDateTime;
@@ -161,12 +233,18 @@ export function parseTime(value: string): Time;
 export function parseAbsoluteToLocal(value: string): ZonedDateTime;
-export function timeToString(time: Time): string;
-export function dateToString(date: CalendarDate): string;
-export function dateTimeToString(date: AnyDateTime): string;
-export function zonedDateTimeToString(date: ZonedDateTime): string;
+/** A CalendarDate represents a date without any time components in a specific calendar system. */
 export class CalendarDate {
     #private;
+    /** 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. 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.
+     */
     readonly month: number;
+    /** The day number within the month. */
     readonly day: number;
@@ -176,36 +254,76 @@ constructor(year: number, month: number, day: number);
     constructor(calendar: Calendar, era: string, year: number, month: number, day: number);
+    /** Returns a copy of this date. */
     copy(): CalendarDate;
-    add(duration: Duration): CalendarDate;
-    subtract(duration: Duration): 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. Other fields will be constrained accordingly. */
     set(fields: DateFields): CalendarDate;
+    /**
+     * 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;
+    /** 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, and a positive date indicates that it is after. */
     compare(b: AnyCalendarDate): number;
 }
+/** A Time represents a clock time without any date components. */
 export class Time {
     #private;
+    /** 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;
     constructor(hour?: number, minute?: number, second?: number, millisecond?: number);
+    /** Returns a copy of this time. */
     copy(): Time;
-    add(duration: Duration): Time;
-    subtract(duration: Duration): 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. Other fields will be constrained accordingly. */
     set(fields: TimeFields): Time;
+    /**
+     * 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): 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, and a positive time indicates that it is after. */
     compare(b: AnyTime): number;
 }
+/** A CalendarDateTime represents a date and time without a time zone, in a specific calendar system. */
 export class CalendarDateTime {
     #private;
+    /** 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. 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.
+     */
     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;
@@ -215,23 +333,50 @@ constructor(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);
+    /** Returns a copy of this date. */
     copy(): CalendarDateTime;
-    add(duration: Duration): CalendarDateTime;
-    subtract(duration: Duration): 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. Other fields will be constrained accordingly. */
     set(fields: DateFields & TimeFields): CalendarDateTime;
+    /**
+     * 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;
-    toDate(timeZone: string): Date;
+    /** Converts the date to a native JavaScript Date object in the given time zone. */
+    toDate(timeZone: string, disambiguation?: Disambiguation): 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, and a positive date indicates that it is after. */
     compare(b: CalendarDate | CalendarDateTime | ZonedDateTime): number;
 }
+/** A ZonedDateTime represents a date and time in a specific time zone and calendar system. */
 export class ZonedDateTime {
     #private;
+    /** 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. 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.
+     */
     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 seconds. */
     readonly offset: number;
@@ -241,12 +386,29 @@ constructor(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);
+    /** Returns a copy of this date. */
     copy(): ZonedDateTime;
-    add(duration: Duration): ZonedDateTime;
-    subtract(duration: Duration): 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. Other fields will be constrained accordingly. */
     set(fields: DateFields & TimeFields, disambiguation?: Disambiguation): ZonedDateTime;
+    /**
+     * 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): 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. 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;
 }
+/**
+ * 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 {
@@ -263,2 +425,7 @@ identifier: string;
 }
+/**
+ * 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 {
@@ -270,2 +437,7 @@ identifier: string;
 }
+/**
+ * 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 {
@@ -279,2 +451,8 @@ identifier: string;
 }
+/**
+ * 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 {
@@ -289,2 +467,7 @@ identifier: string;
 }
+/**
+ * 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 {
@@ -298,2 +481,9 @@ identifier: string;
 }
+/**
+ * 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 {
@@ -309,2 +499,9 @@ identifier: string;
 }
+/**
+ * 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 {
@@ -315,2 +512,9 @@ identifier: string;
 }
+/**
+ * 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 {
@@ -324,2 +528,7 @@ identifier: string;
 }
+/**
+ * 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 {
@@ -336,2 +545,7 @@ identifier: string;
 }
+/**
+ * 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 {
@@ -347,2 +561,6 @@ identifier: string;
 }
+/**
+ * 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 {
@@ -353,2 +571,7 @@ identifier: string;
 }
+/**
+ * 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 {
@@ -369,8 +592,14 @@ identifier: string;
 }
+/** A wrapper around Intl.DateTimeFormat that fixes various browser bugs, and polyfills new features. */
 export class DateFormatter implements Intl.DateTimeFormat {
     constructor(locale: string, options?: Intl.DateTimeFormatOptions);
+    /** Formats a date as a string according to the locale and format options passed to the constructor. */
     format(value: Date): string;
+    /** Formats a date to an array of parts such as separators, numbers, punctuation, and more. */
     formatToParts(value: Date): Intl.DateTimeFormatPart[];
+    /** Formats a date range as a string. */
     formatRange(start: Date, end: Date): string;
+    /** Formats a date range as an array of parts. */
     formatRangeToParts(start: Date, end: Date): DateRangeFormatPart[];
+    /** Returns the resolved formatting options based on the values passed to the constructor. */
     resolvedOptions(): ResolvedDateTimeFormatOptions;
@@ -377,0 +606,0 @@ }

package.json

 {
   "name": "@internationalized/date",
-  "version": "3.0.0-nightly.3134+6fa5706ef",
+  "version": "3.0.0-nightly.3142+51ff50c6f",
   "description": "Internationalized calendar and date manipulation utilities",
@@ -25,3 +25,3 @@ "license": "Apache-2.0",
   },
-  "gitHead": "6fa5706efb7bb7d8c322b8f756c451378ca962ce"
+  "gitHead": "51ff50c6fed6df76c22467622b17b2af2d9380e0"
 }

src/CalendarDate.ts

@@ -14,3 +14,3 @@ /*
 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';
@@ -41,2 +41,3 @@ import {dateTimeToString, dateToString, timeToString, zonedDateTimeToString} from './string';
 
+/** A CalendarDate represents a date without any time components in a specific calendar system. */
 export class CalendarDate {
@@ -47,6 +48,15 @@ // 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;
@@ -68,2 +78,3 @@
 
+  /** Returns a copy of this date. */
   copy(): CalendarDate {
@@ -77,27 +88,37 @@ if (this.era) {
 
-  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);
@@ -107,15 +128,29 @@ }
 
+/** 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 {
@@ -125,10 +160,13 @@ 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) {
@@ -138,2 +176,6 @@ 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) {
@@ -143,2 +185,3 @@ return cycleTime(this, field, amount, options);
 
+  /** Converts the time to an ISO 8601 formatted string. */
   toString() {
@@ -148,2 +191,3 @@ 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) {
@@ -154,13 +198,27 @@ 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;
@@ -186,2 +244,3 @@
 
+  /** Returns a copy of this date. */
   copy(): CalendarDateTime {
@@ -195,15 +254,22 @@ if (this.era) {
 
-  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) {
@@ -220,11 +286,14 @@ case 'era':
 
-  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);
@@ -239,15 +308,31 @@ if (res === 0) {
 
+/** 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;
@@ -277,2 +362,3 @@
 
+  /** Returns a copy of this date. */
   copy(): ZonedDateTime {
@@ -286,10 +372,13 @@ if (this.era) {
 
-  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) {
@@ -299,2 +388,6 @@ 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) {
@@ -304,2 +397,3 @@ return cycleZoned(this, field, amount, options);
 
+  /** Converts the date to a native JavaScript Date object. */
   toDate() {
@@ -309,2 +403,3 @@ return zonedToDate(this);
 
+   /** Converts the date to an ISO 8601 formatted string, including the UTC offset and time zone identifier. */
   toString() {
@@ -314,2 +409,3 @@ return zonedDateTimeToString(this);
 
+   /** Converts the date to an ISO 8601 formatted string in UTC. */
   toAbsoluteString() {
@@ -319,2 +415,3 @@ 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) {
@@ -321,0 +418,0 @@ // TODO: Is this a bad idea??

src/calendars/BuddhistCalendar.ts

@@ -23,2 +23,7 @@ /*
 
+/**
+ * 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 {
@@ -25,0 +30,0 @@ identifier = 'buddhist';

src/calendars/EthiopicCalendar.ts

@@ -64,2 +64,7 @@ /*
 
+/**
+ * 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 {
@@ -115,2 +120,6 @@ identifier = 'ethiopic';
 
+/**
+ * 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 {
@@ -131,2 +140,7 @@ identifier = 'ethioaa'; // also known as 'ethiopic-amete-alem' in ICU
 
+/**
+ * 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 {
@@ -133,0 +147,0 @@ identifier = 'coptic';

src/calendars/GregorianCalendar.ts

@@ -50,2 +50,6 @@ /*
 
+/**
+ * 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 {
@@ -52,0 +56,0 @@ identifier = 'gregory';

src/calendars/HebrewCalendar.ts

@@ -125,2 +125,7 @@ /*
 
+/**
+ * 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 {
@@ -127,0 +132,0 @@ identifier = 'hebrew';

src/calendars/IndianCalendar.ts

@@ -27,2 +27,7 @@ /*
 
+/**
+ * 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 {
@@ -29,0 +34,0 @@ identifier = 'indian';

src/calendars/IslamicCalendar.ts

@@ -45,2 +45,9 @@ /*
 
+/**
+ * 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 {
@@ -83,2 +90,9 @@ identifier = 'islamic-civil';
 
+/**
+ * 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 {
@@ -127,2 +141,9 @@ identifier = 'islamic-tbla';
 
+/**
+ * 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 {
@@ -129,0 +150,0 @@ identifier = 'islamic-umalqura';

src/calendars/JapaneseCalendar.ts

@@ -67,2 +67,7 @@ /*
 
+/**
+ * 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 {
@@ -69,0 +74,0 @@ identifier = 'japanese';

src/calendars/PersianCalendar.ts

@@ -45,2 +45,8 @@ /*
 
+/**
+ * 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 {
@@ -47,0 +53,0 @@ identifier = 'persian';

src/calendars/TaiwanCalendar.ts

@@ -40,2 +40,7 @@ /*
 
+/**
+ * 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 {
@@ -42,0 +47,0 @@ identifier = 'roc'; // Republic of China

src/conversion.ts

@@ -183,2 +183,3 @@ /*
 
+/** Converts a value with date components such as a `CalendarDateTime` or `ZonedDateTime` into a `CalendarDate`. */
 export function toCalendarDate(dateTime: AnyCalendarDate): CalendarDate {
@@ -206,2 +207,6 @@ return new CalendarDate(dateTime.calendar, dateTime.era, dateTime.year, dateTime.month, dateTime.day);
 
+/**
+ * Converts a date value to a `CalendarDateTime`. An optional `Time` value can be passed to set the time
+ * of the resulting value, otherwise it will default to midnight.
+ */
 export function toCalendarDateTime(date: CalendarDate | CalendarDateTime | ZonedDateTime, time?: AnyTime): CalendarDateTime {
@@ -232,6 +237,8 @@ let hour = 0, minute = 0, second = 0, millisecond = 0;
 
-export function toTime(dateTime: CalendarDateTime): Time {
+/** Extracts the time components from a value containing a date and time. */
+export function toTime(dateTime: CalendarDateTime | ZonedDateTime): Time {
   return new Time(dateTime.hour, dateTime.minute, dateTime.second, dateTime.millisecond);
 }
 
+/** Converts a date from one calendar system to another. */
 export function toCalendar<T extends AnyCalendarDate>(date: T, calendar: Calendar): T {
@@ -252,3 +259,7 @@ if (date.calendar.identifier === calendar.identifier) {
 
-export function toZoned(date: CalendarDate | CalendarDateTime | ZonedDateTime, timeZone: string, disambiguation?: Disambiguation) {
+/**
+ * Converts a date value to a `ZonedDateTime` in the provided time zone. The `disambiguation` option can be set
+ * to control how values that fall on daylight saving time changes are interpreted.
+ */
+export function toZoned(date: CalendarDate | CalendarDateTime | ZonedDateTime, timeZone: string, disambiguation?: Disambiguation): ZonedDateTime {
   if (date instanceof ZonedDateTime) {
@@ -271,2 +282,3 @@ if (date.timeZone === timeZone) {
 
+/** Converts a `ZonedDateTime` from one time zone to another. */
 export function toTimeZone(date: ZonedDateTime, timeZone: string): ZonedDateTime {
@@ -277,4 +289,5 @@ let ms = epochFromDate(date) - date.offset;
 
-export function toLocalTimeZone(date: ZonedDateTime) {
+/** Converts the given `ZonedDateTime` into the user's local time zone. */
+export function toLocalTimeZone(date: ZonedDateTime): ZonedDateTime {
   return toTimeZone(date, getLocalTimeZone());
 }

src/DateFormatter.ts

@@ -23,2 +23,3 @@ /*
 
+/** A wrapper around Intl.DateTimeFormat that fixes various browser bugs, and polyfills new features. */
 export class DateFormatter implements Intl.DateTimeFormat {
@@ -34,2 +35,3 @@ private formatter: Intl.DateTimeFormat;
 
+  /** Formats a date as a string according to the locale and format options passed to the constructor. */
   format(value: Date): string {
@@ -39,2 +41,3 @@ 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[] {
@@ -44,2 +47,3 @@ return this.formatter.formatToParts(value);
 
+  /** Formats a date range as a string. */
   formatRange(start: Date, end: Date): string {
@@ -60,2 +64,3 @@ // @ts-ignore
 
+  /** Formats a date range as an array of parts. */
   formatRangeToParts(start: Date, end: Date): DateRangeFormatPart[] {
@@ -81,2 +86,3 @@ // @ts-ignore
 
+  /** Returns the resolved formatting options based on the values passed to the constructor. */
   resolvedOptions(): ResolvedDateTimeFormatOptions {
@@ -83,0 +89,0 @@ let resolvedOptions = this.formatter.resolvedOptions() as ResolvedDateTimeFormatOptions;

src/index.ts

@@ -13,3 +13,3 @@ /*
 
-export * from './CalendarDate';
+export {CalendarDate, CalendarDateTime, Time, ZonedDateTime} from './CalendarDate';
 export {GregorianCalendar} from './calendars/GregorianCalendar';
@@ -25,6 +25,39 @@ export {JapaneseCalendar} from './calendars/JapaneseCalendar';
 export {createCalendar} from './createCalendar';
-export * from './conversion';
-export * from './queries';
+export {toCalendarDate, toCalendarDateTime, toTime, toCalendar, toZoned, toTimeZone, toLocalTimeZone} from './conversion';
+export {
+  isSameDay,
+  isSameMonth,
+  isSameYear,
+  isEqualDay,
+  isEqualMonth,
+  isEqualYear,
+  isToday,
+  getDayOfWeek,
+  now,
+  today,
+  getHoursInDay,
+  getLocalTimeZone,
+  startOfMonth,
+  startOfWeek,
+  startOfYear,
+  endOfMonth,
+  endOfWeek,
+  endOfYear,
+  getMinimumMonthInYear,
+  getMinimumDayInMonth,
+  getWeeksInMonth,
+  minDate,
+  maxDate,
+  isWeekend,
+  isWeekday
+} from './queries';
 export * from './types';
-export * from './string';
-export * from './DateFormatter';
+export {
+  parseDate,
+  parseDateTime,
+  parseTime,
+  parseAbsolute,
+  parseAbsoluteToLocal,
+  parseZonedDateTime
+} from './string';
+export {DateFormatter} from './DateFormatter';

src/manipulation.ts

@@ -13,3 +13,3 @@ /*
 
-import {AnyCalendarDate, AnyTime, CycleOptions, CycleTimeOptions, DateField, DateFields, Disambiguation, Duration, TimeField, TimeFields} from './types';
+import {AnyCalendarDate, AnyTime, CycleOptions, CycleTimeOptions, DateDuration, DateField, DateFields, DateTimeDuration, Disambiguation, TimeDuration, TimeField, TimeFields} from './types';
 import {CalendarDate, CalendarDateTime, Time, ZonedDateTime} from './CalendarDate';
@@ -22,6 +22,6 @@ import {epochFromDate, fromAbsolute, toAbsolute, toCalendar, toCalendarDateTime} from './conversion';
 
-export function add(date: CalendarDateTime, duration: Duration): CalendarDateTime;
-export function add(date: CalendarDate, duration: Duration): CalendarDate;
-export function add(date: CalendarDate | CalendarDateTime, duration: Duration): CalendarDate | CalendarDateTime;
-export function add(date: CalendarDate | CalendarDateTime, duration: Duration) {
+export function add(date: CalendarDateTime, duration: DateTimeDuration): CalendarDateTime;
+export function add(date: CalendarDate, duration: DateDuration): CalendarDate;
+export function add(date: CalendarDate | CalendarDateTime, duration: DateTimeDuration): CalendarDate | CalendarDateTime;
+export function add(date: CalendarDate | CalendarDateTime, duration: DateTimeDuration) {
   let mutableDate: Mutable<AnyCalendarDate> = date.copy();
@@ -102,3 +102,3 @@ let days = 'hour' in date ? addTimeFields(date, duration) : 0;
 
-export function invertDuration(duration: Duration): Duration {
+export function invertDuration(duration: DateTimeDuration): DateTimeDuration {
   let inverseDuration = {};
@@ -114,5 +114,5 @@ for (let key in duration) {
 
-export function subtract(date: CalendarDateTime, duration: Duration): CalendarDateTime;
-export function subtract(date: CalendarDate, duration: Duration): CalendarDate;
-export function subtract(date: CalendarDate | CalendarDateTime, duration: Duration): CalendarDate | CalendarDateTime {
+export function subtract(date: CalendarDateTime, duration: DateTimeDuration): CalendarDateTime;
+export function subtract(date: CalendarDate, duration: DateDuration): CalendarDate;
+export function subtract(date: CalendarDate | CalendarDateTime, duration: DateTimeDuration): CalendarDate | CalendarDateTime {
   return add(date, invertDuration(duration));
@@ -202,3 +202,3 @@ }
 
-function addTimeFields(time: Mutable<AnyTime>, duration: Duration): number {
+function addTimeFields(time: Mutable<AnyTime>, duration: TimeDuration): number {
   time.hour += duration.hours || 0;
@@ -211,3 +211,3 @@ time.minute += duration.minutes || 0;
 
-export function addTime(time: Time, duration: Duration): Time {
+export function addTime(time: Time, duration: TimeDuration): Time {
   let res = time.copy();
@@ -218,3 +218,3 @@ addTimeFields(res, duration);
 
-export function subtractTime(time: Time, duration: Duration): Time {
+export function subtractTime(time: Time, duration: TimeDuration): Time {
   return addTime(time, invertDuration(duration));
@@ -342,3 +342,3 @@ }
 
-export function addZoned(dateTime: ZonedDateTime, duration: Duration): ZonedDateTime {
+export function addZoned(dateTime: ZonedDateTime, duration: DateTimeDuration): ZonedDateTime {
   let ms: number;
@@ -372,3 +372,3 @@ if ((duration.years != null && duration.years !== 0) || (duration.months != null && duration.months !== 0) || (duration.days != null && duration.days !== 0)) {
 
-export function subtractZoned(dateTime: ZonedDateTime, duration: Duration): ZonedDateTime {
+export function subtractZoned(dateTime: ZonedDateTime, duration: DateTimeDuration): ZonedDateTime {
   return addZoned(dateTime, invertDuration(duration));
@@ -375,0 +375,0 @@ }

src/queries.ts

@@ -20,2 +20,3 @@ /*
 
+/** Returns whether the given dates occur on the same day, regardless of the time or calendar system. */
 export function isSameDay(a: DateValue, b: DateValue): boolean {
@@ -26,2 +27,3 @@ b = toCalendar(b, a.calendar);
 
+/** Returns whether the given dates occur in the same month, using the calendar system of the first date. */
 export function isSameMonth(a: DateValue, b: DateValue): boolean {
@@ -35,2 +37,3 @@ b = toCalendar(b, a.calendar);
 
+/** Returns whether the given dates occur in the same year, using the calendar system of the first date. */
 export function isSameYear(a: DateValue, b: DateValue): boolean {
@@ -43,2 +46,3 @@ b = toCalendar(b, a.calendar);
 
+/** Returns whether the given dates occur on the same day, and are of the same calendar system. */
 export function isEqualDay(a: DateValue, b: DateValue): boolean {
@@ -48,2 +52,3 @@ return a.calendar.identifier === b.calendar.identifier && a.era === b.era && a.year === b.year && a.month === b.month && a.day === b.day;
 
+/** Returns whether the given dates occur in the same month, and are of the same calendar system. */
 export function isEqualMonth(a: DateValue, b: DateValue): boolean {
@@ -55,2 +60,3 @@ a = startOfMonth(a);
 
+/** Returns whether the given dates occur in the same year, and are of the same calendar system. */
 export function isEqualYear(a: DateValue, b: DateValue): boolean {
@@ -62,2 +68,3 @@ a = startOfYear(a);
 
+/** Returns whether the date is today in the given time zone. */
 export function isToday(date: DateValue, timeZone: string): boolean {
@@ -67,3 +74,8 @@ return isSameDay(date, today(timeZone));
 
-export function getDayOfWeek(date: DateValue, locale: string) {
+/**
+ * Returns the day of week for the given date and locale. Days are numbered from zero to six,
+ * where zero is the first day of the week in the given locale. For example, in the United States,
+ * the first day of the week is Sunday, but in France it is Monday.
+ */
+export function getDayOfWeek(date: DateValue, locale: string): number {
   let julian = date.calendar.toJulianDay(date);
@@ -81,2 +93,3 @@
 
+/** Returns the current time in the given time zone. */
 export function now(timeZone: string): ZonedDateTime {
@@ -86,2 +99,3 @@ return fromAbsolute(Date.now(), timeZone);
 
+/** Returns today's date in the given time zone. */
 export function today(timeZone: string): CalendarDate {
@@ -103,2 +117,6 @@ return toCalendarDate(now(timeZone));
 
+/**
+ * Returns the number of hours in the given date and time zone.
+ * Usually this is 24, but it could be 23 or 25 if the date is on a daylight saving transition.
+ */
 export function getHoursInDay(a: CalendarDate, timeZone: string): number {
@@ -112,2 +130,4 @@ let ms = toAbsolute(a, timeZone);
 let localTimeZone = null;
+
+/** Returns the time zone identifier for the current user. */
 export function getLocalTimeZone(): string {
@@ -126,3 +146,4 @@ // TODO: invalidate this somehow?
 export function startOfMonth(date: DateValue): DateValue;
-export function startOfMonth(date: DateValue) {
+/** Returns the first date of the month for the given date. */
+export function startOfMonth(date: DateValue): DateValue {
   // Use `subtract` instead of `set` so we don't get constrained in an era.
@@ -136,3 +157,4 @@ return date.subtract({days: date.day - 1});
 export function endOfMonth(date: DateValue): DateValue;
-export function endOfMonth(date: DateValue) {
+/** Returns the last date of the month for the given date. */
+export function endOfMonth(date: DateValue): DateValue {
   return date.add({days: date.calendar.getDaysInMonth(date) - date.day});
@@ -145,3 +167,4 @@ }
 export function startOfYear(date: DateValue): DateValue;
-export function startOfYear(date: DateValue) {
+/** Returns the first day of the year for the given date. */
+export function startOfYear(date: DateValue): DateValue {
   return startOfMonth(date.subtract({months: date.month - 1}));
@@ -154,3 +177,4 @@ }
 export function endOfYear(date: DateValue): DateValue;
-export function endOfYear(date: DateValue) {
+/** Returns the last day of the year for the given date. */
+export function endOfYear(date: DateValue): DateValue {
   return endOfMonth(date.add({months: date.calendar.getMonthsInYear(date) - date.month}));
@@ -179,3 +203,4 @@ }
 export function startOfWeek(date: DateValue, locale: string): DateValue;
-export function startOfWeek(date: DateValue, locale: string) {
+/** Returns the first date of the week for the given date and locale. */
+export function startOfWeek(date: DateValue, locale: string): DateValue {
   let dayOfWeek = getDayOfWeek(date, locale);
@@ -188,3 +213,4 @@ return date.subtract({days: dayOfWeek});
 export function endOfWeek(date: CalendarDate, locale: string): CalendarDate;
-export function endOfWeek(date: DateValue, locale: string) {
+/** Returns the last date of the week for the given date and locale. */
+export function endOfWeek(date: DateValue, locale: string): DateValue {
   return startOfWeek(date, locale).add({days: 6});
@@ -224,3 +250,4 @@ }
 
-export function getWeeksInMonth(date: DateValue, locale: string) {
+/** Returns the number of weeks in the given month and locale. */
+export function getWeeksInMonth(date: DateValue, locale: string): number {
   let days = date.calendar.getDaysInMonth(date);
@@ -230,2 +257,3 @@ return Math.ceil((getDayOfWeek(startOfMonth(date), locale) + days) / 7);
 
+/** Returns the lesser of the two provider dates. */
 export function minDate<A extends DateValue, B extends DateValue>(a: A, b: B): A | B {
@@ -235,2 +263,3 @@ return a.compare(b) <= 0 ? a : b;
 
+/** Returns the greater of the two provider dates. */
 export function maxDate<A extends DateValue, B extends DateValue>(a: A, b: B): A | B {
@@ -260,3 +289,4 @@ return a.compare(b) >= 0 ? a : b;
 
-export function isWeekend(date: DateValue, locale: string) {
+/** Returns whether the given date is on a weekend in the given locale. */
+export function isWeekend(date: DateValue, locale: string): boolean {
   let julian = date.calendar.toJulianDay(date);
@@ -278,4 +308,5 @@
 
-export function isWeekday(date: DateValue, locale: string) {
+/** Returns whether the given date is on a weekday in the given locale. */
+export function isWeekday(date: DateValue, locale: string): boolean {
   return !isWeekend(date, locale);
 }

src/types.ts

@@ -15,2 +15,3 @@ /*
 
+/** An interface that is compatible with any object with date fields. */
 export interface AnyCalendarDate {
@@ -25,2 +26,3 @@ readonly calendar: Calendar,
 
+/** An interface that is compatible with any object with time fields. */
 export interface AnyTime {
@@ -34,35 +36,78 @@ readonly hour: number,
 
+/** An interface that is compatible with any object with both date and time fields. */
 export interface AnyDateTime extends AnyCalendarDate, AnyTime {}
 
+/**
+ * The Calendar interface represents a calendar system, including information
+ * about how days, months, years, and eras are organized, and methods to perform
+ * arithmetic on dates.
+ */
 export interface Calendar {
+  /** A string identifier for the calendar, as defined by Unicode CLDR. */
   identifier: string,
 
+  /** Creates a CalendarDate in this calendar from the given Julian day number. */
   fromJulianDay(jd: number): CalendarDate,
+  /** Converts a date in this calendar to a Julian day number. */
   toJulianDay(date: AnyCalendarDate): number,
 
+  /** Returns the number of days in the month of the given date. */
   getDaysInMonth(date: AnyCalendarDate): number,
+  /** Returns the number of months in the year of the given date. */
   getMonthsInYear(date: AnyCalendarDate): number,
+  /** Returns the number of years in the era of the given date. */
   getYearsInEra(date: AnyCalendarDate): number,
+  /** Returns a list of era identifiers for the calendar. */
   getEras(): string[],
 
+  /**
+   * Returns the minimum month number of the given date's year.
+   * Normally, this is 1, but in some calendars such as the Japanese,
+   * eras may begin in the middle of a year.
+   */
   getMinimumMonthInYear?(date: AnyCalendarDate): number,
+  /**
+   * Returns the minimum day number of the given date's month.
+   * Normally, this is 1, but in some calendars such as the Japanese,
+   * eras may begin in the middle of a month.
+   */
   getMinimumDayInMonth?(date: AnyCalendarDate): number,
 
+  /** @private */
   balanceDate?(date: AnyCalendarDate): void,
+  /** @private */
   balanceYearMonth?(date: AnyCalendarDate, previousDate: AnyCalendarDate): void,
+  /** @private */
   getYearsToAdd?(date: AnyCalendarDate, years: number): number,
+  /** @private */
   constrainDate?(date: AnyCalendarDate): void
 }
 
-export interface Duration {
+/** Represents an amount of time in calendar-specific units, for use when performing arithmetic. */
+export interface DateDuration {
+  /** The number of years to add or subtract. */
   years?: number,
+  /** The number of months to add or subtract. */
   months?: number,
+  /** The number of weeks to add or subtract. */
   weeks?: number,
-  days?: number,
+  /** The number of days to add or subtract. */
+  days?: number
+}
+
+/** Represents an amount of time, for use whe performing arithmetic. */
+export interface TimeDuration {
+  /** The number of hours to add or subtract. */
   hours?: number,
+  /** The number of minutes to add or subtract. */
   minutes?: number,
+  /** The number of seconds to add or subtract. */
   seconds?: number,
+  /** The number of milliseconds to add or subtract. */
   milliseconds?: number
 }
 
+/** Represents an amount of time with both date and time components, for use when performing arithmetic. */
+export interface DateTimeDuration extends DateDuration, TimeDuration {}
+
 export interface DateFields {
@@ -69,0 +114,0 @@ era?: string,

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Manifest confusion

Supply chain risk

This package has inconsistent metadata. This could be malicious or caused by an error when publishing the package.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Manifest confusion

Supply chain risk

This package has inconsistent metadata. This could be malicious or caused by an error when publishing the package.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

787846

increased by9.07%

Lines of code

7847

increased by6.03%

No dependency changes