islam.js

islam.js is a comprehensive JavaScript/TypeScript library designed for Islamic applications. It provides functionalities related to the Quran, Hadith, Dua & Azkar, Prayer Timings, and Hijri Calendar. This package offers multilingual support, a wide range of Tafseers, Hadith collections, and tools to enhance the development of Islamic software solutions.

Features

• Quran:

  • Support for Dialects: Hafs and Warsh
  • 20 Language Translations
  • 28 Tafseers (Commentaries) in different languages

• Hadith:

  • Collections: Kutub al-Sittah (Six Authentic Books) with 5+ Translations

• Dua & Azkar:

  • 134 categories with over 360 Azkars (supplications)

• Prayer Timings:

  • Accurate prayer timings for any location worldwide

• Hijri Calendar:

  • Hijri date conversion and calendar utilities

Installation

To install islam.js, use npm or yarn:

npm install islam.js
# or
yarn add islam.js

Getting Started

Import the library into your JavaScript or TypeScript project and start using the available features.

import { Quran, Hadith } from 'islam.js';

Usage

1. Quran

Get a chapter by index

import { Quran } from 'islam.js';
const quran = new Quran();
const chapter = quran.getChapterByIndex(108);
console.log(chapter);

//Output
{
   "name": "الكوثر",
   "type": "مكيّة",
   "englishName": "Al-Kawthar",
   "number": 108,
   "numberOfLetters": 42,
   "numberOfVerses": 3,
   "numberOfWords": 10,
   "verses": [
      "إِنَّا أَعْطَيْنَاكَ الْكَوْثَرَ",
      "فَصَلِّ لِرَبِّكَ وَانْحَرْ",
      "إِنَّ شَانِئَكَ هُوَ الْأَبْتَرُ"
   ]
}

Get a chapter by name

By default the dialect will be Hafs but we can change it to Warsh as well.

import { Quran, DialectEnum } from 'islam.js';
const quran = new Quran(DialectEnum.Warsh);
const chapter = quran.getChapterByName('Al-Ekhlas');
console.log(chapter);

//Output
{
   "name": "الإخلاص",
   "type": "مكيّة",
   "englishName": "Al-Ekhlas",
   "number": 112,
   "numberOfLetters": 47,
   "numberOfVerses": 4,
   "numberOfWords": 15,
    "verses": [
      "قُلْ هُوَ اللَّهُ أَحَدٌ",
      "اللَّهُ الصَّمَدُ",
      "لَمْ يَلِدْ وَلَمْ يُولَدْ",
      "وَلَمْ يَكُن لَّهُ كُفُوًا أَحَدٌ"
   ]
}

Get a verse by chapterNo and verseNo

import { Quran } from 'islam.js';
const quran = new Quran();
const verse = quran.getVerse(21, 107);
console.log(verse);

//Output
'وَمَا أَرْسَلْنَاكَ إِلَّا رَحْمَةً لِّلْعَالَمِينَ'

Get multiple verses with translation

import { Quran } from 'islam.js';
const quran = new Quran();
const verse =  quran.getMultipleVersesWithTranslation([{ chapterNo: 21, verseNo: 107 }]);
console.log(verse);

//Output
[
   {
      "verse": "وَمَا أَرْسَلْنَاكَ إِلَّا رَحْمَةً لِّلْعَالَمِينَ",
      "translation": "And We have not sent you, [O Muhammad], except as a mercy to the worlds."
   }
]

We can specify a different language for translation as well.

import { Quran, TranslationEnum } from 'islam.js';
const quran = new Quran();
const verse =  quran.getMultipleVersesWithTranslation([{ chapterNo: 21, verseNo: 107 }], TranslationEnum.French);
console.log(verse);

//Output
[
   {
      "verse": "وَمَا أَرْسَلْنَاكَ إِلَّا رَحْمَةً لِّلْعَالَمِينَ",
      "translation": "Et Nous ne t'avons envoyé qu'en miséricorde pour l'univers."
   }
]

Get random verse with translation

import { Quran } from 'islam.js';
const quran = new Quran();
const verse =  quran.getRandomVerseWithTranslation();
console.log(verse);

//Output
{
   "chapter": "الزمر",
   "verseNo": 53,
   "verse": "۞ قُلْ يَا عِبَادِيَ الَّذِينَ أَسْرَفُوا عَلَىٰ أَنفُسِهِمْ لَا تَقْنَطُوا مِن رَّحْمَةِ اللَّهِ ۚ إِنَّ اللَّهَ يَغْفِرُ الذُّنُوبَ جَمِيعًا ۚ إِنَّهُ هُوَ الْغَفُورُ الرَّحِيمُ",
   "translation": "Say, 'O My servants who have transgressed against themselves [by sinning], do not despair of the mercy of Allah.Indeed, Allah forgives all sins. Indeed, it is He who is the Forgiving, the Merciful.'"
}

Get a verse with translation and tafseer

import { Quran, TranslationEnum, TafseerEnum } from 'islam.js';
const quran = new Quran();
const verse = await quran.getVerseWithTranslationAndTafseer(53, 39, TranslationEnum.Urdu, TafseerEnum.TafsirBayanulQuran)
console.log(verse);

//Output
{
   "verse": "وَأَن لَّيْسَ لِلْإِنسَانِ إِلَّا مَا سَعَىٰ",
   "translation": "اور یہ کہ انسان کو وہی ملتا ہے جس کی وہ کوشش کرتا ہے",
   "tafseer": "آیت 39{ وَاَنْ لَّــیْسَ لِلْاِنْسَانِ اِلَّا مَا سَعٰی۔ } ”اور یہ کہ انسان کے لیے نہیں ہے مگر وہی کچھ جس کی اس نے سعی کی ہوگی۔“ انسان کو جو کچھ کرنا ہوگا اپنی محنت اور کوشش کے بل پر کرنا ہوگا ‘ خواہشوں اور تمنائوں سے کچھ نہیں ہوگا۔ قبل ازیں آیت 24 میں سوال کیا گیا تھا کہ ”کیا انسان کو وہی کچھ مل جائے گا جس کی وہ تمنا کرے گا ؟“ یہ آیت گویا مذکورہ سوال کا جواب ہے۔"
}

2. Hadith

Get a hadith by book and hadithNo

import { Hadith, HadithBook } from 'islam.js';
const hadith = new Hadith();
const engHadith =  await hadith.getHadith(HadithBook.AbuDawud, 7)
console.log(engHadith);

//Output
{
   "metadata": {
      "name": "Sunan Abu Dawud",
      "section": "Purification (Kitab Al-Taharah)",
      "sectionDetails": {
        "arabicNumberFirst": 1,
        "arabicNumberLast": 390,
        "hadithNumberFirst": 1,
        "hadithNumberLast": 390
       }
   },
   "hadith": {

        "text": "Narrated Salman al-Farsi: It was said to Salman: Your Prophet teaches you everything, even about excrement. He replied: Yes. He has forbidden us to face the qiblah at the time of easing or urinating, and cleansing with right hand, and cleansing with less than three stones, or cleansing with dung or bone",
        "hadithNumber": 7,
        "arabicNumber": 7,
        "grades": [
            {
                "name": "Al-Albani",
                "grade": "Sahih"
            },
            {
                "name": "Muhammad Muhyi Al-Din Abdul Hamid",
                "grade": "Sahih"
            },
            {
                "name": "Shuaib Al Arnaut",
                "grade": "Sahih"
            },
            {
                "name": "Zubair Ali Zai",
                "grade": "Sahih Muslim (262)"
            }
        ]
   }
}

Get a complete section from a book by sectionNo

By default the language will be English but We can specify a different language as well.

import { Hadith, HadithBook, HadithLangEnum } from 'islam.js';
const hadith = new Hadith();
const section =  await hadith.getSection(HadithBook.Bukhari, 6, HadithLangEnum.Russian);
console.log(section);

//Output
{
   "metadata": {
      "name":"Sahih al Bukhari",
      "section":"Menstrual Periods",
      "sectionDetails":{
            "arabicNumberFirst":294,
            "arabicNumberLast":333,
            "hadithNumberFirst":294,
            "hadithNumberLast":333
       }
   },
   "hadiths":[
        {
            "arabicNumber": 294,
            "grades": [],
            "hadithNumber": 294,
            "reference": { "book": 6, "hadith": 1 },
            "text": "Сообщается, что ‘Аиша, да будет доволен ею Аллах, сказала: «Мы покинули (Медину) с единственной целью совершить хаджж, а в Сарифе, у меня начались месячные. Зайдя ко мне, Посланник Аллаха ﷺ (увидел, что) я плачу, и спросил: “Что с тобой? У тебя начались месячные?” Я ответила: “Да”. Тогда он сказал: “Поистине, это предопределено Аллахом дочерям Адама. Совершай же всё, что совершает паломник, но только не обходи Дом (Каабу)!”»\\n(‘Аиша) сказала: «И Посланник Аллаха ﷺ принёс в жертву коров за своих жён»"
        },
        ...
        ...
        ...
   ]
}

3. Dua & Azkar

Get a random supplication

import { Azkar } from 'islam.js';
const azkar = new Azkar();
const supplication = azkar.getRandom();
console.log(supplication);

//Output
{
   "id":2669,
   "description":{
      
   },
   "count":"",
   "zikr":"((يُصَلِّي عَلَى النَّبِيِّ صلى الله عليه وسلم بَعْدَ فَرَاغِهِ مِنْ إِجَابَةِ الْمُؤَذِّنِ)).",
   "reference":"",
   "category":"أذكار الآذان"
}

Get a random supplication by category

import { Azkar } from 'islam.js';
const azkar = new Azkar();
const supplication = azkar.getRandomByCategory(AzkarCategoriesEnum.Anxiety);
console.log(supplication);

//Output
{
   "id":809,
   "description":{},
   "count":"",
   "zikr":"((اللَّهُمَّ إِنِّي أَعُوذُ بِكَ مِنَ الْهَمِّ وَالْحَزَنِ، وَالْعَجْزِ وَالْكَسَلِ، وَالْبُخْلِ وَالْجُبْنِ، وَضَلَعِ الدَّيْنِ وَغَلَبَةِ الرِّجَالِ)).",
   "reference":"",
   "category":"دعاء الهم والحزن"
}

Get all supplications by category

import { Azkar } from 'islam.js';
const azkar = new Azkar();
const supplication = azkar.getByCategory(AzkarCategoriesEnum.Morning);
console.log(supplication);

//Output
[
   {
      "id":2338,
      "description":{},
      "count":"3",
      "zikr":"سُبْحـانَ اللهِ وَبِحَمْـدِهِ عَدَدَ خَلْـقِه ، وَرِضـا نَفْسِـه ، وَزِنَـةَ عَـرْشِـه ، وَمِـدادَ كَلِمـاتِـه.",
      "reference":"مسلم",
      "category":"أذكار الصباح"
   },
   ...
   ...
   ...
]

Get all supplications

import { Azkar } from 'islam.js';
const azkar = new Azkar();
const supplication = azkar.getAll();
console.log(supplication);

//Output
[
    {
    "category":"أذكار الصباح",
    "count":"1",
    "description":{},
    "id":2374,
    "reference":"أحمد",
    "zikr":"أَصْبَـحْـنا عَلَى فِطْرَةِ الإسْلاَمِ، وَعَلَى كَلِمَةِ الإِخْلاَصِ، وَعَلَى دِينِ نَبِيِّنَا مُحَمَّدٍ صَلَّى اللهُ عَلَيْهِ وَسَلَّمَ، وَعَلَى مِلَّةِ أَبِينَا إبْرَاهِيمَ حَنِيفاً مُسْلِماً وَمَا كَانَ مِنَ المُشْرِكِينَ."
    },
    ...
    ...
    ...
]

4. Prayer Timings

Get prayer timing by location

import { Prayer } from 'islam.js';
const prayer = new Prayer();
const date = '30-08-2024';
const latitude = 31.52037;
const longitude = 74.358749;

const prayerTimings = await prayer.getPrayerTimesByLocation(date, latitude, longitude);
console.log(prayerTimings);

//Output
{
  Fajr: "04:13",
  Sunrise: "05:37",
  Dhuhr: "12:03",
  Asr: "15:40",
  Sunset: "18:29",
  Maghrib: "18:29",
  Isha: "19:53",
  Imsak: "04:03",
  Midnight: "00:03",
  Firstthird: "22:11",
  Lastthird: "01:54",
}

Get prayer timing by city

import { Prayer } from 'islam.js';
const prayer = new Prayer();
const city = 'Dubai';
const country = 'United Arab Emirates';
const prayerTimings = await prayer.getPrayerTimesByCity(city, country)
console.log(prayerTimings);

//Output
{
  Fajr: "04:40",
  Sunrise: "05:59",
  Dhuhr: "12:22",
  Asr: "15:49",
  Sunset: "18:42",
  Maghrib: "18:42",
  Isha: "19:59",
  Imsak: "04:30",
  Midnight: "00:19",
  Firstthird: "22:26",
  Lastthird: "02:12",
}

5. Hijri Calander

Get hijri calander date by location

import { HijriCalendar } from 'islam.js';
const calender = new HijriCalendar();
const date = '30-08-2024';
const latitude = 31.52037;
const longitude = 74.358749;
const hijriDate = await calander.getHijriDateByLocation(date, latitude, longitude)
console.log(hijriDate);

//Output
{
   "date":"24-02-1446",
   "format":"DD-MM-YYYY",
   "day":"24",
   "weekday":{
      "en":"Al Juma'a",
      "ar":"الجمعة"
   },
   "month":{
      "number":2,
      "en":"Ṣafar",
      "ar":"صَفَر"
   },
   "year":"1446",
   "designation":{
      "abbreviated":"AH",
      "expanded":"Anno Hegirae"
   },
   "holidays":[]
}

Get hijri calander date by city

import { HijriCalendar } from 'islam.js';
const calender = new HijriCalendar();
const city = 'Dubai';
const country = 'United Arab Emirates';
const hijriDate = await calander.getHijriDateByCity(city, country);
console.log(hijriDate);

//Output
{
   "date":"24-02-1446",
   "format":"DD-MM-YYYY",
   "day":"24",
   "weekday":{
      "en":"Al Juma'a",
      "ar":"الجمعة"
   },
   "month":{
      "number":2,
      "en":"Ṣafar",
      "ar":"صَفَر"
   },
   "year":"1446",
   "designation":{
      "abbreviated":"AH",
      "expanded":"Anno Hegirae"
   },
   "holidays":[]
}

Disclaimer

islam.js is an open-source package created to provide easy access to various Islamic resources such as Quran, Hadith, Dua, and Azkar. This package is not an authoritative source on Islam and should not be taken as a definitive representation of the religion.

I have made every effort to use authentic sources, but as with any human endeavor, there may be mistakes or inaccuracies. Users are encouraged to consult scholars or authentic religious sources for comprehensive understanding and verification.

By using this package, you acknowledge that it is provided as-is, and you agree to use it responsibly.

Future Roadmap

Asset Management Optimization

Currently, the islam.js package includes a large assets folder, which increases the package size to approximately 33MB. To improve the efficiency of package distribution and installation, the following steps are planned:

1. Compression of Assets:

   • Objective: Reduce the overall package size by compressing the assets folder before publishing the package.
   • Approach: Implement a compression strategy to package assets into a compressed format (e.g., ZIP, GZIP) that will be included in the published package.
   • Benefit: This will significantly decrease the package size, making it more manageable and quicker to download for users.

2. Automatic Decompression on Installation:

   • Objective: Automatically decompress the assets folder during the installation process.
   • Approach: Develop a post-install script or use existing tools to decompress the assets once the package is installed.
   • Benefit: This ensures that users receive the full set of assets without manual intervention while maintaining a smaller initial package size.

Test Coverage

I have setup the baseline for tests but currently the test coverage is 38%. We need to increase it to at least 80%.

1. Unit Tests:
   • Objective: Enhance unit test coverage.
   • Approach: Implement comprehensive unit tests using frameworks like Jest or Mocha. Focus on critical functionalities and edge cases to ensure robust testing.
   • Benefit: Improved test coverage will increase confidence in code stability and reliability, ensuring that all functionalities perform as expected.

These enhancements aim to streamline the package management process, improve user experience, and ensure that islam.js remains a robust and efficient tool for Islamic applications. I welcome contributions to help me achieve these goals. If you're interested in contributing, please check out our contributing guidelines and get in touch!

License

This package is freely available for everyone to use. If you find it beneficial, please remember me in your prayers.
May Allah forgive my sins and have mercy on all of us. Ameen.

Contact

If you have any questions, suggestions, or would like to collaborate, please feel free to reach out:

• Email: [email protected]
• LinkedIn: Ahmad Bilal

I look forward to hearing from you!

Credits

This package utilizes the following resources:

• Quran and Translations: Surah Quran
• Tafseer (Commentaries): Tafsir API by spa5k
• Hadith Collections: Hadith API by fawazahmed
• Hijri Calendar and Prayer Times: Aladhan Prayer Times API

I am grateful to these resources for making their data available for public use.