calendaryjs-plugin-hijriv0.1.5

Gregorian ↔ Hijri date conversion plus Hijri recurring events. Uses the tabular (civil) Islamic calendar — arithmetic, deterministic, round-trip safe.

Install

npm i calendaryjs calendaryjs-plugin-hijri

Usage

The plugin adds a hijri.date(month, day) builder selector:

import { calendary } from "calendaryjs";
import { every } from "calendaryjs/builder";
import { hijri } from "calendaryjs-plugin-hijri";

const cal = calendary().use(hijri());

cal.addGroup({
  id: "islamic-holidays",
  events: [
    every("year").on(hijri.date(10, 1)).title("Eid al-Fitr"),
    every("year").on(hijri.date(12, 10)).title("Eid al-Adha"),
  ],
});

hijri.date(month, day) compiles to a plain hijri event ({ type: "hijri", hijriMonth, hijriDay }) — the storage form.

Date conversion

import {
  gregorianToHijri,
  hijriToGregorian,
  isValidHijriDate,
  isHijriLeapYear,
  hijriMonthLength,
} from "calendaryjs-plugin-hijri";

gregorianToHijri({ year: 2024, month: 7, day: 8 }); // → { year: 1446, month: 1, day: 1 }
hijriToGregorian({ year: 1446, month: 1, day: 1 }); // → { year: 2024, month: 7, day: 8 }

isValidHijriDate({ year: 1446, month: 9, day: 30 }); // → true (Ramadan 1446 has 30 days)
isHijriLeapYear(1446); // → false
hijriMonthLength(1446, 9); // → 30

Because a Hijri date drifts ~11 days earlier each Gregorian year, an event may occur 0, 1, or 2 times in a given Gregorian year; the engine returns every occurrence.

Day enrichment

Opt in with enrichDays: true and every day from getDay() / getDays() carries a hijri object:

const cal = calendary().use(hijri({ enrichDays: true }));

cal.getDay("2024-07-08").hijri;
// → { year: 1446, month: 1, day: 1 }

Reference

Plugin options — enrichDays?: boolean (default false).

Event type hijri — hijriMonth (1–12) · hijriDay (1–30), plus every standard event property.

Exports — hijri() · hijri.date(month, day) · gregorianToHijri · hijriToGregorian · isValidHijriDate · isHijriLeapYear · hijriMonthLength.