@tabby_ai/hijri-converter

hijri-converter

A Javascript package to convert accurately between Hijri and Gregorian dates using the Umm al-Qura calendar.

This project uses a Typescript interpretation of a date conversion algorithm written in Python by Mohammed H Alshehri - hijri-converter.

Therefore, it has the same accuracy and limitations.

Limitations

• The date range supported by converter is limited to the period from the beginning of 1343 AH (1 August 1924 CE) to the end of 1500 AH (16 November 2077 CE).
• The conversion is not intended for religious purposes where sighting of the lunar crescent at the beginning of Hijri month is still preferred.

Comparison

Item	hijri-converter	moment-hijri
Conversion range	1343-1500 AH	1356-1500 AH
Accuracy	100%	91,8%
Input validation	Yes	No
Typescript support	Typescript first	Types declarations
Functionality	Only convert dates	Parse, manipulate, display, etc.
Dependencies	Zero-dependency	moment
Size (minified + gzipped)	11.4 kB	74.4 kB

Installation

npm install @tabby.ai/hijri-converter

Basic usage

// CommonJS modules
const { gregorianToHijri } = require('@tabby.ai/hijri-converter');

const date = new Date();
const hijriDate = gregorianToHijri({
  year: date.getFullYear(),
  month: date.getMonth() + 1, // Month number in Javascript Date API is zero-based.
  day: date.getDay(),
});

console.log(hijriDate); // { year: 1444, month: 7, day: 15 }

// or ESModules
import { hijriToGregorian } from '@tabby.ai/hijri-converter';

const gregorianDate = hijriToGregorian({ year: 1444, month: 7, day: 15 });

console.log(gregorianDate); // { year: 2023, month: 2, day: 6 }

What about date formatting?

This library only converts dates. But you might not need any specific date libraries if you want to format dates. Browsers and Node.js widely support date formatting: Date.prototype.toLocaleDateString, Intl.DateTimeFormat

const date = new Date(Date.UTC(2012, 11, 20, 3, 0, 0));

const options = {
  timeZone: 'UTC',
  weekday: 'short',
  year: 'numeric',
  month: 'long',
  day: 'numeric',
};

// using Date.prototype.toLocaleDateString method
console.log(date.toLocaleDateString('ar-SA-u-ca-islamic-umalqura', options)); // -> "الخميس، ٧ صفر ١٤٣٤ هـ"
console.log(date.toLocaleDateString('en-SA-u-ca-islamic-umalqura', options)); // -> "Thu, Safar 7, 1434 AH"

// or using Intl.DateTimeFormat API
const arSaFormatter = new Intl.DateTimeFormat(
  'ar-SA-u-ca-islamic-umalqura',
  options
);
const enSaFormatter = new Intl.DateTimeFormat(
  'en-SA-u-ca-islamic-umalqura',
  options
);

console.log(arSaFormatter.format(date)); // -> 'الخميس، ٧ صفر ١٤٣٤ هـ'
console.log(enSaFormatter.format(date)); // -> "Thu, Safar 7, 1434 AH"

License

This project is licensed under the terms of the MIT license.