@yassabdulrhman/hijri-gregorian-calendar

A TypeScript library for converting between Gregorian and Hijri dates, with support for full month calendars and prediction awareness for future Hijri dates.

This package uses the AlAdhan Islamic Calendar API.

Features

• Convert Gregorian date to Hijri date
• Convert Hijri date to Gregorian date
• Get Gregorian month with Hijri dates
• Get Hijri month with Gregorian dates
• Detect future Hijri dates as predicted
• Block future predicted dates using confirmed mode
• TypeScript support

Installation

npm install @yassabdulrhman/hijri-gregorian-calendar

Usage

import {
  toHijri,
  toGregorian,
  getGregorianMonth,
  getHijriMonth,
} from "@yassabdulrhman/hijri-gregorian-calendar";

Gregorian to Hijri

const result = await toHijri("13-06-2026");

console.log(result.hijri.date);

Hijri to Gregorian

const result = await toGregorian("27-12-1447");

console.log(result.gregorian.date);

Gregorian Month Calendar

const month = await getGregorianMonth(6, 2026);

console.log(month.days);

Hijri Month Calendar

const month = await getHijriMonth(12, 1447);

console.log(month.days);

Future Date Prediction

Hijri months depend on moon sighting, so future Hijri dates may not be final.

By default, future dates are allowed and marked as predicted:

const result = await toHijri("01-01-2030");

console.log(result.confidence);
// "predicted"

To block future predicted dates:

await toHijri("01-01-2030", {
  mode: "confirmed",
});

This will throw an error if the date is in the future.

Result Model

{
  gregorian: {
    date: "13-06-2026",
    day: "13",
    month: "June",
    year: "2026"
  },
  hijri: {
    date: "27-12-1447",
    day: "27",
    month: "Dhū al-Ḥijjah",
    year: "1447"
  },
  confidence: "confirmed",
  source: "aladhan",
  isFuture: false
}

API Source

This package uses the AlAdhan Islamic Calendar API:

• gToH — Convert Gregorian date to Hijri date
• hToG — Convert Hijri date to Gregorian date
• gToHCalendar/:month/:year — Gregorian month with Hijri dates
• hToGCalendar/:month/:year — Hijri month with Gregorian dates

API base URL:

https://api.aladhan.com/v1

AlAdhan provides REST APIs for Gregorian/Hijri conversion and full Islamic calendar month data.

Important Note About Accuracy

Past Hijri dates are generally fixed.

Future Hijri dates are predictions because the Hijri calendar follows moon sighting. A future date may shift by one day depending on official moon-sighting announcements.

For this reason, this package marks future dates as:

confidence: "predicted"

License

MIT