@internationalized/date 3.7.0 → 3.8.0

package/src/calendars/EthiopicCalendar.ts

@@ -13,7 +13,7 @@
 // Portions of the code in this file are based on code from ICU.
 // Original licensing can be found in the NOTICE file in the root directory of this source tree.
 
-import {AnyCalendarDate, Calendar} from '../types';
+import {AnyCalendarDate, Calendar, CalendarIdentifier} from '../types';
 import {CalendarDate} from '../CalendarDate';
 import {Mutable} from '../utils';
 
@@ -66,7 +66,7 @@ function getDaysInMonth(year: number, month: number) {
  * on whether it is a leap year. Two eras are supported: 'AA' and 'AM'.
  */
 export class EthiopicCalendar implements Calendar {
-  identifier = 'ethiopic';
+  identifier: CalendarIdentifier = 'ethiopic';
 
   fromJulianDay(jd: number): CalendarDate {
     let [year, month, day] = julianDayToCE(ETHIOPIC_EPOCH, jd);
@@ -79,7 +79,7 @@ export class EthiopicCalendar implements Calendar {
     return new CalendarDate(this, era, year, month, day);
   }
 
-  toJulianDay(date: AnyCalendarDate) {
+  toJulianDay(date: AnyCalendarDate): number {
     let year = date.year;
     if (date.era === 'AA') {
       year -= AMETE_MIHRET_DELTA;
@@ -107,7 +107,7 @@ export class EthiopicCalendar implements Calendar {
     return date.era === 'AA' ? 9999 : 9991;
   }
 
-  getEras() {
+  getEras(): string[] {
     return ['AA', 'AM'];
   }
 }
@@ -117,7 +117,7 @@ export class EthiopicCalendar implements 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
+  identifier: CalendarIdentifier = 'ethioaa'; // also known as 'ethiopic-amete-alem' in ICU
 
   fromJulianDay(jd: number): CalendarDate {
     let [year, month, day] = julianDayToCE(ETHIOPIC_EPOCH, jd);
@@ -125,7 +125,7 @@ export class EthiopicAmeteAlemCalendar extends EthiopicCalendar {
     return new CalendarDate(this, 'AA', year, month, day);
   }
 
-  getEras() {
+  getEras(): string[] {
     return ['AA'];
   }
 
@@ -141,7 +141,7 @@ export class EthiopicAmeteAlemCalendar extends EthiopicCalendar {
  * on whether it is a leap year. Two eras are supported: 'BCE' and 'CE'.
  */
 export class CopticCalendar extends EthiopicCalendar {
-  identifier = 'coptic';
+  identifier: CalendarIdentifier = 'coptic';
 
   fromJulianDay(jd: number): CalendarDate {
     let [year, month, day] = julianDayToCE(COPTIC_EPOCH, jd);
@@ -154,7 +154,7 @@ export class CopticCalendar extends EthiopicCalendar {
     return new CalendarDate(this, era, year, month, day);
   }
 
-  toJulianDay(date: AnyCalendarDate) {
+  toJulianDay(date: AnyCalendarDate): number {
     let year = date.year;
     if (date.era === 'BCE') {
       year = 1 - year;
@@ -176,14 +176,14 @@ export class CopticCalendar extends EthiopicCalendar {
     return date.era === 'BCE';
   }
 
-  balanceDate(date: Mutable<AnyCalendarDate>) {
+  balanceDate(date: Mutable<AnyCalendarDate>): void {
     if (date.year <= 0) {
       date.era = date.era === 'BCE' ? 'CE' : 'BCE';
       date.year = 1 - date.year;
     }
   }
 
-  getEras() {
+  getEras(): string[] {
     return ['BCE', 'CE'];
   }
 

package/src/calendars/GregorianCalendar.ts

@@ -13,7 +13,7 @@
 // Portions of the code in this file are based on code from ICU.
 // Original licensing can be found in the NOTICE file in the root directory of this source tree.
 
-import {AnyCalendarDate, Calendar} from '../types';
+import {AnyCalendarDate, Calendar, CalendarIdentifier} from '../types';
 import {CalendarDate} from '../CalendarDate';
 import {mod, Mutable} from '../utils';
 
@@ -68,7 +68,7 @@ const daysInMonth = {
  * 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';
+  identifier: CalendarIdentifier = 'gregory';
 
   fromJulianDay(jd: number): CalendarDate {
     let jd0 = jd;
@@ -118,7 +118,7 @@ export class GregorianCalendar implements Calendar {
     return 9999;
   }
 
-  getEras() {
+  getEras(): string[] {
     return ['BC', 'AD'];
   }
 
@@ -126,7 +126,7 @@ export class GregorianCalendar implements Calendar {
     return date.era === 'BC';
   }
 
-  balanceDate(date: Mutable<AnyCalendarDate>) {
+  balanceDate(date: Mutable<AnyCalendarDate>): void {
     if (date.year <= 0) {
       date.era = date.era === 'BC' ? 'AD' : 'BC';
       date.year = 1 - date.year;

package/src/calendars/HebrewCalendar.ts

@@ -13,7 +13,7 @@
 // Portions of the code in this file are based on code from ICU.
 // Original licensing can be found in the NOTICE file in the root directory of this source tree.
 
-import {AnyCalendarDate, Calendar} from '../types';
+import {AnyCalendarDate, Calendar, CalendarIdentifier} from '../types';
 import {CalendarDate} from '../CalendarDate';
 import {mod, Mutable} from '../utils';
 
@@ -128,7 +128,7 @@ function getDaysInMonth(year: number, month: number): number {
  * In leap years, an extra month is inserted at month 6.
  */
 export class HebrewCalendar implements Calendar {
-  identifier = 'hebrew';
+  identifier: CalendarIdentifier = 'hebrew';
 
   fromJulianDay(jd: number): CalendarDate {
     let d = jd - HEBREW_EPOCH;
@@ -159,7 +159,7 @@ export class HebrewCalendar implements Calendar {
     return new CalendarDate(this, year, month, day);
   }
 
-  toJulianDay(date: AnyCalendarDate) {
+  toJulianDay(date: AnyCalendarDate): number {
     let jd = startOfYear(date.year);
     for (let month = 1; month < date.month; month++) {
       jd += getDaysInMonth(date.year, month);
@@ -185,11 +185,11 @@ export class HebrewCalendar implements Calendar {
     return 9999;
   }
 
-  getEras() {
+  getEras(): string[] {
     return ['AM'];
   }
 
-  balanceYearMonth(date: Mutable<AnyCalendarDate>, previousDate: AnyCalendarDate) {
+  balanceYearMonth(date: Mutable<AnyCalendarDate>, previousDate: AnyCalendarDate): void {
     // Keep date in the same month when switching between leap years and non leap years
     if (previousDate.year !== date.year) {
       if (isLeapYear(previousDate.year) && !isLeapYear(date.year) && previousDate.month > 6) {

package/src/calendars/IndianCalendar.ts

@@ -13,7 +13,7 @@
 // Portions of the code in this file are based on code from ICU.
 // Original licensing can be found in the NOTICE file in the root directory of this source tree.
 
-import {AnyCalendarDate} from '../types';
+import {AnyCalendarDate, CalendarIdentifier} from '../types';
 import {CalendarDate} from '../CalendarDate';
 import {fromExtendedYear, GregorianCalendar, gregorianToJulianDay, isLeapYear} from './GregorianCalendar';
 
@@ -29,7 +29,7 @@ const INDIAN_YEAR_START = 80;
  * in each year, with either 30 or 31 days. Only one era identifier is supported: 'saka'.
  */
 export class IndianCalendar extends GregorianCalendar {
-  identifier = 'indian';
+  identifier: CalendarIdentifier = 'indian';
 
   fromJulianDay(jd: number): CalendarDate {
     // Gregorian date for Julian day
@@ -75,7 +75,7 @@ export class IndianCalendar extends GregorianCalendar {
     return new CalendarDate(this, indianYear, indianMonth, indianDay);
   }
 
-  toJulianDay(date: AnyCalendarDate) {
+  toJulianDay(date: AnyCalendarDate): number {
     let extendedYear = date.year + INDIAN_ERA_START;
     let [era, year] = fromExtendedYear(extendedYear);
 
@@ -121,9 +121,9 @@ export class IndianCalendar extends GregorianCalendar {
     return 9919;
   }
 
-  getEras() {
+  getEras(): string[] {
     return ['saka'];
   }
 
-  balanceDate() {}
+  balanceDate(): void {}
 }

package/src/calendars/IslamicCalendar.ts

@@ -13,7 +13,7 @@
 // Portions of the code in this file are based on code from ICU.
 // Original licensing can be found in the NOTICE file in the root directory of this source tree.
 
-import {AnyCalendarDate, Calendar} from '../types';
+import {AnyCalendarDate, Calendar, CalendarIdentifier} from '../types';
 import {CalendarDate} from '../CalendarDate';
 
 const CIVIL_EPOC = 1948440; // CE 622 July 16 Friday (Julian calendar) / CE 622 July 19 (Gregorian calendar)
@@ -50,13 +50,13 @@ function isLeapYear(year: number): boolean {
  * 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';
+  identifier: CalendarIdentifier = 'islamic-civil';
 
   fromJulianDay(jd: number): CalendarDate {
     return julianDayToIslamic(this, CIVIL_EPOC, jd);
   }
 
-  toJulianDay(date: AnyCalendarDate) {
+  toJulianDay(date: AnyCalendarDate): number {
     return islamicToJulianDay(CIVIL_EPOC, date.year, date.month, date.day);
   }
 
@@ -82,7 +82,7 @@ export class IslamicCivilCalendar implements Calendar {
     return 9665;
   }
 
-  getEras() {
+  getEras(): string[] {
     return ['AH'];
   }
 }
@@ -95,13 +95,13 @@ export class IslamicCivilCalendar implements Calendar {
  * 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';
+  identifier: CalendarIdentifier = 'islamic-tbla';
 
   fromJulianDay(jd: number): CalendarDate {
     return julianDayToIslamic(this, ASTRONOMICAL_EPOC, jd);
   }
 
-  toJulianDay(date: AnyCalendarDate) {
+  toJulianDay(date: AnyCalendarDate): number {
     return islamicToJulianDay(ASTRONOMICAL_EPOC, date.year, date.month, date.day);
   }
 }
@@ -145,7 +145,7 @@ function umalquraYearLength(year: number): number {
  * 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';
+  identifier: CalendarIdentifier = 'islamic-umalqura';
 
   constructor() {
     super();

package/src/calendars/JapaneseCalendar.ts

@@ -13,7 +13,7 @@
 // Portions of the code in this file are based on code from the TC39 Temporal proposal.
 // Original licensing can be found in the NOTICE file in the root directory of this source tree.
 
-import {AnyCalendarDate} from '../types';
+import {AnyCalendarDate, CalendarIdentifier} from '../types';
 import {CalendarDate} from '../CalendarDate';
 import {GregorianCalendar} from './GregorianCalendar';
 import {Mutable} from '../utils';
@@ -70,7 +70,7 @@ function toGregorian(date: AnyCalendarDate) {
  * Note that eras before 1868 (Gregorian) are not currently supported by this implementation.
  */
 export class JapaneseCalendar extends GregorianCalendar {
-  identifier = 'japanese';
+  identifier: CalendarIdentifier = 'japanese';
 
   fromJulianDay(jd: number): CalendarDate {
     let date = super.fromJulianDay(jd);
@@ -85,11 +85,11 @@ export class JapaneseCalendar extends GregorianCalendar {
     );
   }
 
-  toJulianDay(date: AnyCalendarDate) {
+  toJulianDay(date: AnyCalendarDate): number {
     return super.toJulianDay(toGregorian(date));
   }
 
-  balanceDate(date: Mutable<AnyCalendarDate>) {
+  balanceDate(date: Mutable<AnyCalendarDate>): void {
     let gregorianDate = toGregorian(date);
     let era = findEraFromGregorianDate(gregorianDate);
 
@@ -102,7 +102,7 @@ export class JapaneseCalendar extends GregorianCalendar {
     this.constrainDate(date);
   }
 
-  constrainDate(date: Mutable<AnyCalendarDate>) {
+  constrainDate(date: Mutable<AnyCalendarDate>): void {
     let idx = ERA_NAMES.indexOf(date.era);
     let end = ERA_END_DATES[idx];
     if (end != null) {
@@ -131,7 +131,7 @@ export class JapaneseCalendar extends GregorianCalendar {
     }
   }
 
-  getEras() {
+  getEras(): string[] {
     return ERA_NAMES;
   }
 

package/src/calendars/PersianCalendar.ts

@@ -13,7 +13,7 @@
 // Portions of the code in this file are based on code from ICU.
 // Original licensing can be found in the NOTICE file in the root directory of this source tree.
 
-import {AnyCalendarDate, Calendar} from '../types';
+import {AnyCalendarDate, Calendar, CalendarIdentifier} from '../types';
 import {CalendarDate} from '../CalendarDate';
 import {mod} from '../utils';
 
@@ -42,7 +42,7 @@ const MONTH_START = [
  * around the March equinox.
  */
 export class PersianCalendar implements Calendar {
-  identifier = 'persian';
+  identifier: CalendarIdentifier = 'persian';
 
   fromJulianDay(jd: number): CalendarDate {
     let daysSinceEpoch = jd - PERSIAN_EPOCH;
@@ -80,7 +80,7 @@ export class PersianCalendar implements Calendar {
     return isLeapYear ? 30 : 29;
   }
 
-  getEras() {
+  getEras(): string[] {
     return ['AP'];
   }
 

package/src/calendars/TaiwanCalendar.ts

@@ -13,7 +13,7 @@
 // Portions of the code in this file are based on code from ICU.
 // Original licensing can be found in the NOTICE file in the root directory of this source tree.
 
-import {AnyCalendarDate} from '../types';
+import {AnyCalendarDate, CalendarIdentifier} from '../types';
 import {CalendarDate} from '../CalendarDate';
 import {fromExtendedYear, getExtendedYear, GregorianCalendar} from './GregorianCalendar';
 import {Mutable} from '../utils';
@@ -41,7 +41,7 @@ function gregorianToTaiwan(year: number): [string, number] {
  * 'before_minguo' and 'minguo'.
  */
 export class TaiwanCalendar extends GregorianCalendar {
-  identifier = 'roc'; // Republic of China
+  identifier: CalendarIdentifier = 'roc'; // Republic of China
 
   fromJulianDay(jd: number): CalendarDate {
     let date = super.fromJulianDay(jd);
@@ -50,15 +50,15 @@ export class TaiwanCalendar extends GregorianCalendar {
     return new CalendarDate(this, era, year, date.month, date.day);
   }
 
-  toJulianDay(date: AnyCalendarDate) {
+  toJulianDay(date: AnyCalendarDate): number {
     return super.toJulianDay(toGregorian(date));
   }
 
-  getEras() {
+  getEras(): string[] {
     return ['before_minguo', 'minguo'];
   }
 
-  balanceDate(date: Mutable<AnyCalendarDate>) {
+  balanceDate(date: Mutable<AnyCalendarDate>): void {
     let [era, year] = gregorianToTaiwan(gregorianYear(date));
     date.era = era;
     date.year = year;

package/src/conversion.ts

@@ -17,16 +17,16 @@ import {AnyCalendarDate, AnyDateTime, AnyTime, Calendar, DateFields, Disambiguat
 import {CalendarDate, CalendarDateTime, Time, ZonedDateTime} from './CalendarDate';
 import {constrain} from './manipulation';
 import {getExtendedYear, GregorianCalendar} from './calendars/GregorianCalendar';
-import {getLocalTimeZone} from './queries';
+import {getLocalTimeZone, isEqualCalendar} from './queries';
 import {Mutable} from './utils';
 
-export function epochFromDate(date: AnyDateTime) {
+export function epochFromDate(date: AnyDateTime): number {
   date = toCalendar(date, new GregorianCalendar());
   let year = getExtendedYear(date.era, date.year);
   return epochFromParts(year, date.month, date.day, date.hour, date.minute, date.second, date.millisecond);
 }
 
-function epochFromParts(year: number, month: number, day: number, hour: number, minute: number, second: number, millisecond: number) {
+function epochFromParts(year: number, month: number, day: number, hour: number, minute: number, second: number, millisecond: number): number {
   // Note: Date.UTC() interprets one and two-digit years as being in the
   // 20th century, so don't use it
   let date = new Date();
@@ -35,7 +35,7 @@ function epochFromParts(year: number, month: number, day: number, hour: number,
   return date.getTime();
 }
 
-export function getTimeZoneOffset(ms: number, timeZone: string) {
+export function getTimeZoneOffset(ms: number, timeZone: string): number {
   // Fast path for UTC.
   if (timeZone === 'UTC') {
     return 0;
@@ -260,7 +260,7 @@ 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 {
-  if (date.calendar.identifier === calendar.identifier) {
+  if (isEqualCalendar(date.calendar, calendar)) {
     return date;
   }
 
@@ -292,7 +292,7 @@ export function toZoned(date: CalendarDate | CalendarDateTime | ZonedDateTime, t
   return fromAbsolute(ms, timeZone);
 }
 
-export function zonedToDate(date: ZonedDateTime) {
+export function zonedToDate(date: ZonedDateTime): Date {
   let ms = epochFromDate(date) - date.offset;
   return new Date(ms);
 }

package/src/createCalendar.ts

@@ -11,7 +11,7 @@
  */
 
 import {BuddhistCalendar} from './calendars/BuddhistCalendar';
-import {Calendar} from './types';
+import {Calendar, CalendarIdentifier} from './types';
 import {CopticCalendar, EthiopicAmeteAlemCalendar, EthiopicCalendar} from './calendars/EthiopicCalendar';
 import {GregorianCalendar} from './calendars/GregorianCalendar';
 import {HebrewCalendar} from './calendars/HebrewCalendar';
@@ -22,7 +22,7 @@ import {PersianCalendar} from './calendars/PersianCalendar';
 import {TaiwanCalendar} from './calendars/TaiwanCalendar';
 
 /** Creates a `Calendar` instance from a Unicode calendar identifier string. */
-export function createCalendar(name: string): Calendar {
+export function createCalendar(name: CalendarIdentifier): Calendar {
   switch (name) {
     case 'buddhist':
       return new BuddhistCalendar();

package/src/index.ts

@@ -15,6 +15,7 @@ export type {
   AnyTime,
   AnyDateTime,
   Calendar,
+  CalendarIdentifier,
   DateDuration,
   TimeDuration,
   DateTimeDuration,
@@ -74,7 +75,8 @@ export {
   minDate,
   maxDate,
   isWeekend,
-  isWeekday
+  isWeekday,
+  isEqualCalendar
 } from './queries';
 export {
   parseDate,

package/src/manipulation.ts

@@ -21,7 +21,7 @@ const ONE_HOUR = 3600000;
 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) {
+export function add(date: CalendarDate | CalendarDateTime, duration: DateTimeDuration): Mutable<AnyCalendarDate | AnyDateTime> {
   let mutableDate: Mutable<AnyCalendarDate | AnyDateTime> = date.copy();
   let days = 'hour' in mutableDate ? addTimeFields(mutableDate, duration) : 0;
 
@@ -118,7 +118,7 @@ function constrainMonthDay(date: Mutable<AnyCalendarDate>) {
   date.day = Math.max(1, Math.min(date.calendar.getDaysInMonth(date), date.day));
 }
 
-export function constrain(date: Mutable<AnyCalendarDate>) {
+export function constrain(date: Mutable<AnyCalendarDate>): void {
   if (date.calendar.constrainDate) {
     date.calendar.constrainDate(date);
   }
@@ -146,7 +146,7 @@ export function subtract(date: CalendarDate | CalendarDateTime, duration: DateTi
 
 export function set(date: CalendarDateTime, fields: DateFields): CalendarDateTime;
 export function set(date: CalendarDate, fields: DateFields): CalendarDate;
-export function set(date: CalendarDate | CalendarDateTime, fields: DateFields) {
+export function set(date: CalendarDate | CalendarDateTime, fields: DateFields): Mutable<AnyCalendarDate> {
   let mutableDate: Mutable<AnyCalendarDate> = date.copy();
 
   if (fields.era != null) {
@@ -171,7 +171,7 @@ export function set(date: CalendarDate | CalendarDateTime, fields: DateFields) {
 
 export function setTime(value: CalendarDateTime, fields: TimeFields): CalendarDateTime;
 export function setTime(value: Time, fields: TimeFields): Time;
-export function setTime(value: Time | CalendarDateTime, fields: TimeFields) {
+export function setTime(value: Time | CalendarDateTime, fields: TimeFields): Mutable<Time | CalendarDateTime> {
   let mutableValue: Mutable<Time | CalendarDateTime> = value.copy();
 
   if (fields.hour != null) {
@@ -210,7 +210,7 @@ function balanceTime(time: Mutable<AnyTime>): number {
   return days;
 }
 
-export function constrainTime(time: Mutable<AnyTime>) {
+export function constrainTime(time: Mutable<AnyTime>): void {
   time.millisecond = Math.max(0, Math.min(time.millisecond, 1000));
   time.second = Math.max(0, Math.min(time.second, 59));
   time.minute = Math.max(0, Math.min(time.minute, 59));
@@ -245,7 +245,7 @@ export function subtractTime(time: Time, duration: TimeDuration): Time {
 
 export function cycleDate(value: CalendarDateTime, field: DateField, amount: number, options?: CycleOptions): CalendarDateTime;
 export function cycleDate(value: CalendarDate, field: DateField, amount: number, options?: CycleOptions): CalendarDate;
-export function cycleDate(value: CalendarDate | CalendarDateTime, field: DateField, amount: number, options?: CycleOptions) {
+export function cycleDate(value: CalendarDate | CalendarDateTime, field: DateField, amount: number, options?: CycleOptions): Mutable<CalendarDate | CalendarDateTime> {
   let mutable: Mutable<CalendarDate | CalendarDateTime> = value.copy();
 
   switch (field) {
@@ -300,7 +300,7 @@ export function cycleDate(value: CalendarDate | CalendarDateTime, field: DateFie
 
 export function cycleTime(value: CalendarDateTime, field: TimeField, amount: number, options?: CycleTimeOptions): CalendarDateTime;
 export function cycleTime(value: Time, field: TimeField, amount: number, options?: CycleTimeOptions): Time;
-export function cycleTime(value: Time | CalendarDateTime, field: TimeField, amount: number, options?: CycleTimeOptions) {
+export function cycleTime(value: Time | CalendarDateTime, field: TimeField, amount: number, options?: CycleTimeOptions): Mutable<Time | CalendarDateTime> {
   let mutable: Mutable<Time | CalendarDateTime> = value.copy();
 
   switch (field) {

package/src/queries.ts

@@ -10,7 +10,7 @@
  * governing permissions and limitations under the License.
  */
 
-import {AnyCalendarDate, AnyTime} from './types';
+import {AnyCalendarDate, AnyTime, Calendar} from './types';
 import {CalendarDate, CalendarDateTime, ZonedDateTime} from './CalendarDate';
 import {fromAbsolute, toAbsolute, toCalendar, toCalendarDate} from './conversion';
 import {weekStartData} from './weekStartData';
@@ -42,21 +42,22 @@ 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 {
-  return a.calendar.identifier === b.calendar.identifier && a.era === b.era && a.year === b.year && a.month === b.month && a.day === b.day;
+  return isEqualCalendar(a.calendar, b.calendar) && isSameDay(a, b);
 }
 
 /** 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 {
-  a = startOfMonth(a);
-  b = startOfMonth(b);
-  return a.calendar.identifier === b.calendar.identifier && a.era === b.era && a.year === b.year && a.month === b.month;
+  return isEqualCalendar(a.calendar, b.calendar) && isSameMonth(a, b);
 }
 
 /** 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 {
-  a = startOfYear(a);
-  b = startOfYear(b);
-  return a.calendar.identifier === b.calendar.identifier && a.era === b.era && a.year === b.year;
+  return isEqualCalendar(a.calendar, b.calendar) && isSameYear(a, b);
+}
+
+/** Returns whether two calendars are the same. */
+export function isEqualCalendar(a: Calendar, b: Calendar): boolean {
+  return a.isEqual?.(b) ?? b.isEqual?.(a) ?? a.identifier === b.identifier;
 }
 
 /** Returns whether the date is today in the given time zone. */
@@ -177,7 +178,7 @@ export function endOfYear(date: DateValue): DateValue {
   return endOfMonth(date.add({months: date.calendar.getMonthsInYear(date) - date.month}));
 }
 
-export function getMinimumMonthInYear(date: AnyCalendarDate) {
+export function getMinimumMonthInYear(date: AnyCalendarDate): number {
   if (date.calendar.getMinimumMonthInYear) {
     return date.calendar.getMinimumMonthInYear(date);
   }
@@ -185,7 +186,7 @@ export function getMinimumMonthInYear(date: AnyCalendarDate) {
   return 1;
 }
 
-export function getMinimumDayInMonth(date: AnyCalendarDate) {
+export function getMinimumDayInMonth(date: AnyCalendarDate): number {
   if (date.calendar.getMinimumDayInMonth) {
     return date.calendar.getMinimumDayInMonth(date);
   }

package/src/types.ts

@@ -34,14 +34,19 @@ export interface AnyTime {
 /** An interface that is compatible with any object with both date and time fields. */
 export interface AnyDateTime extends AnyCalendarDate, AnyTime {}
 
+export type CalendarIdentifier = 'gregory' | 'buddhist' | 'chinese' | 'coptic' | 'dangi' | 'ethioaa' | 'ethiopic' | 'hebrew' | 'indian' | 'islamic' | 'islamic-umalqura' | 'islamic-tbla' | 'islamic-civil' | 'islamic-rgsa' | 'iso8601' | 'japanese' | 'persian' | 'roc';
+
 /**
  * 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,
+  /**
+   * A string identifier for the calendar, as defined by Unicode CLDR.
+   * See [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/supportedValuesOf#supported_calendar_types).
+   */
+  identifier: CalendarIdentifier,
 
   /** Creates a CalendarDate in this calendar from the given Julian day number. */
   fromJulianDay(jd: number): CalendarDate,
@@ -69,6 +74,16 @@ export interface Calendar {
    * eras may begin in the middle of a month.
    */
   getMinimumDayInMonth?(date: AnyCalendarDate): number,
+  /**
+   * Returns a date that is the first day of the month for the given date.
+   * This is used to determine the month that the given date falls in, if
+   * the calendar has months that do not align with the standard calendar months 
+   * (e.g. fiscal calendars).
+   */
+  getFormattableMonth?(date: AnyCalendarDate): CalendarDate,
+
+  /** Returns whether the given calendar is the same as this calendar. */
+  isEqual?(calendar: Calendar): boolean,
 
   /** @private */
   balanceDate?(date: AnyCalendarDate): void,