Implementation of the Hijri Week Calendar Standard proposal which is a counterpart of ISO 8601 week calendar for the Hijri calendar. It is based on the Hijri Calendar and the ISO 8601 standard. dates generated by this calendar are referred to as Hijri Week Dates.
Since Hijri (islamic) calendars are lunar calendars, it was necessary to define a standard for them which has slightly modified rules from that of the ISO week based on the Gregorian calendar. Not withstanding the foregoing, the system shares many of the rules defined by the ISO 8601 making it compliant with the ISO standard.
This implementation aims to standardise rules across all varieties of Hijri (islamic) calendars. For detailed information on specific compatibility requirements, please refer to the Compatible Calendars section.
The implementation is an extension of the Calendar
class from Temporal
import { HWCUmalqura } from 'hijri-week-calendar'
const calendar = new HWCUmalqura()
const HWCZonedDate = Temporal.ZonedDateTime.from({ year: 1444, month: 2, day: 3, timeZone: 'Asia/Riyadh', calendar: new HWCUmalqura() })
// the calendar can be used directly
console.log(customCalendar.HWCRepresentation(HWCZonedDate)) // { calendar: 'islamic-umalqura', dayOfWeek: 4, weekOfYear: 5, yearOfWeek: 1444, }
// or it can be used as a calendar in the Temporal Objects that support a calendar
console.log(HWCZonedDate.HWCRepresentation) // { calendar: 'islamic-umalqura', dayOfWeek: 4, weekOfYear: 5, yearOfWeek: 1444, }
The proposed rules (which follow the ISO week standards) are designed to be applicable to all types of Hijri (islamic) Calendars, not limited to just the tabular varieties. This includes compatibility with calendars such as the Umm al-Qura calendar. For more information on non-compatible calendars, see Compatible Calendars section.
Week Definition:
Weekday Numbering:
Year Length:
Midweek Day:
First Week Identification:
4th Muharram Placement:
The above rule is compliant with the ISO standard.
Week 51 Extension:
Week 50 Limitation:
Date Placement in Weeks 51 and 1:
Note on Terminology: Within this Hijri week calendar system, years are categorized as 'short' or 'long.' The terms 'leap' and 'common' years are not applicable.
To ensure compatibility with this implementation, a Hijri calendar must adhere to the following rules:
Year Length:
Long and Short Years:
Given these rules, the following calendars are found as of today incompatible with this implementation:
Islamic Calendar:
Rgsa-Islamic Calendar:
pnpm add hijri-week-calendar
The tests on this repo are dependent on generating dates that the tests can run against. To generate the dates, run the following command
pnpm run data:generate
The script should prompt you to enter the start and end years for the generation. The default values are 1443 and 1444 respectively. The script will generate the data in the data
folder (which is ignored by git) for the following calendars (in order): islamic-umalqura
, islamic-tbla
, islamic-civil
To run the tests, run the following command
npm run test
To run the test with a user interface, run the following command (this will open a browser window and generate a coverage report as well)
npm run test:ui
To generate the coverage report along with running the tests, run the following command
npm run test:coverage
MIT License © 2023-PRESENT Mohsen Alyafei and Al-Kawarizmi