Calendar values

Every value in this package is a CalendarDate from @internationalized/date, in the Gregorian or Umm al-Qura calendar.

CalendarDate

A CalendarDate is a year, month, and day in a calendar, with no time and no time zone. A JavaScript Date is not a calendar value. The helpers create, convert, compare, and add to these dates. Their months are 1-indexed.

import { CalendarCode, convertCalendarDate, createCalendarDate } from 'ngx-mat-hijri-adapter';

const hijri = createCalendarDate(CalendarCode.umalqura, 1445, 9, 1); // 1 Ramadan 1445
const gregorian = convertCalendarDate(hijri, CalendarCode.gregorian); // 11 March 2024

The other helpers are calendarOf, compareCalendarDates, addCalendarDate, daysInCalendarMonth, monthsInCalendarYear, and calendarToday.

calendarOf() reads the package calendar of a CalendarDate. gregory becomes gregorian. islamic-umalqura stays islamic-umalqura. Any other identifier throws.

import { calendarOf, createCalendarDate } from 'ngx-mat-hijri-adapter';

calendarOf(createCalendarDate('gregorian', 2024, 3, 11)); // 'gregorian'
calendarOf(createCalendarDate('islamic-umalqura', 1445, 9, 1)); // 'islamic-umalqura'

CalendarCode and CalendarLocale

CalendarCode names the supported calendars, so string literals are not needed. SupportedCalendar is the type of its values. CalendarLocale holds the locales used as defaults. Any BCP 47 locale works wherever a locale is accepted.

import { CalendarCode, CalendarLocale, provideHijriDateAdapter } from 'ngx-mat-hijri-adapter';

CalendarCode.gregorian; // 'gregorian'
CalendarCode.umalqura; // 'islamic-umalqura'
CalendarLocale.arSA; // 'ar-SA'
CalendarLocale.enUS; // 'en-US'

provideHijriDateAdapter({ calendar: CalendarCode.gregorian, locale: CalendarLocale.enUS });

The Umm al-Qura range

Umm al-Qura years are limited to AH 1300–1599 ( UMALQURA_MIN_YEAR and UMALQURA_MAX_YEAR). AH 1600 is rejected because the underlying table falls back to the civil Islamic calendar there.

• Creating, converting, or adding to a date outside that range throws UmalquraDateRangeError.
• Creating a day that does not exist, such as 30 in a 29-day month, throws InvalidCalendarDateError.