
`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:**](#1-quran)
  - Support for Dialects: Hafs and Warsh
  - 20 Language Translations
  - 28 Tafseers (Commentaries) in different languages

- [**Hadith:**](#2-hadith)
  - Collections: Kutub al-Sittah (Six Authentic Books) with 5+ Translations

- [**Dua & Azkar:**](#3-dua--azkar)
  - 134 categories with over 360 Azkars (supplications)

- [**Prayer Timings:**](#4-prayer-timings)
  - Accurate prayer timings for any location worldwide

- [**Hijri Calendar:**](#5-hijri-calander)
  - Hijri date conversion and calendar utilities

## Installation

To install `islam.js`, use npm or yarn:

```bash
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.
```ts
import { Quran, Hadith } from 'islam.js';
```

## Usage

### 1. Quran
#### Get a chapter by index
```ts
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. 
```ts
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
```ts
import { Quran } from 'islam.js';
const quran = new Quran();
const verse = quran.getVerse(21, 107);
console.log(verse);

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

#### Get multiple verses with translation
```ts
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.
```ts
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
```ts
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
```ts
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
```ts
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.
```ts
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
```ts
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
```ts
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
```ts
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
```ts
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
```ts
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
```ts
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
```ts
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
```ts
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.

## 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.

## Credits

This package utilizes the following resources:

- **Quran and Translations:** [Surah Quran](https://surahquran.com)  
- **Tafseer (Commentaries):** [Tafsir API by spa5k](https://github.com/spa5k/tafsir_api)  
- **Hadith Collections:** [Hadith API by fawazahmed](https://github.com/fawazahmed0/hadith-api)  
- **Hijri Calendar and Prayer Times:** [Aladhan Prayer Times API](https://aladhan.com/prayer-times-api)

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

A comprehensive JavaScript/TypeScript library designed for Islamic applications. It provides functionalities related to the Quran, Hadith, Dua & Azkar, Prayer Timings, and Hijri Calendar.

Islam.js


**Let the AI read the news — You read the bulletin.**

  ## 🚀 Overview

  **AI Bulletin** is a self-operating newsletter system designed to:

  * 🧠 Use **CrewAI** agents to generate insightful, structured content
  * 📨 Deliver formatted newsletters via **SendGrid**
  * ⚡ Run on a lightweight **FastAPI** backend
  * 🗓️ Schedule and automate weekly generation and delivery using **APScheduler**

  Built for AI-curious hackers who want to stay informed.

  ### 📊 Ai Bulletin - Week 2025-W23

  ![Ai Bulletin - Week 2025-W23](/images/projects/ai-bulletin.jpg)

  ---

  ## 🎯 Project Goal

  To automate every part of a newsletter workflow:

  1. ✍️ Curate and plan relevant content
  2. 🔍 Summarize and analyze top stories
  3. 🖋️ Format a professional-grade newsletter
  4. 📤 Email it to all subscribers

  Without any human in the loop. Just subscribe and enjoy.

  ---

  ## 🧠 Agents & Responsibilities

  | Agent                        | Responsibility                                   |
  | ---------------------------- | ------------------------------------------------ |
  | **TopicPlannerAgent**        | Plans weekly theme and outlines subtopics        |
  | **TopStoriesAgent**          | Summarizes the top 3 tech/AI stories             |
  | **DeepDiveAgent**            | Provides in-depth analysis on a major topic      |
  | **ToolOfTheWeekAgent**       | Recommends trending AI tool with summary         |
  | **QuoteAgent**               | Picks a relevant quote or tweet                  |
  | **AIInTheWildAgent**         | Highlights a real-world AI use case              |
  | **HotTakesAgent**            | Adds quick, opinionated commentary               |
  | **EditorsNoteAgent**         | Writes a personalized closing note               |
  | **NewsletterEditorAgent**    | Edits and compiles all section drafts            |
  | **HTMLFormatterAgent**       | Styles and formats final HTML for email delivery |

  ---

  ## 🧱 Architecture

  ### 🔁 System Flow

  1. `PlanTopicsTask` ← Done by TopicPlannerAgent
  2. `[Parallel]` TopStoriesTask, DeepDiveTask, ToolTask, QuoteTask, AIWildTask, HotTakesTask, EditorsNoteTask
  3. `EditNewsletterTask` ← NewsletterEditorAgent
  4. `FormatHTMLTask` ← HTMLFormatterAgent
  5. 🚀 Email is sent via SendGrid

  ### 📊 Architectural Diagram (Textual)

  ```
  CrewManagerAgent
    │
    ▼
  TopicPlannerAgent
        │
        ▼
  ┌────────────────────────────────────────────────────┐
  │    Runs in Parallel                                │
  │ ┌────────────┬────────────┬────────────┬─────────┐ │
  │ │TopStories  │ DeepDive   │ ToolOfWeek │ Quote   │ │
  │ │Agent       │ Agent      │ Agent      │ Agent   │ │
  │ └────────────┴────────────┴────────────┴─────────┘ │
  │ ┌────────────┬────────────┐                        │
  │ │ AIWild     │ HotTakes   │                        │
  │ │ Agent      │ Agent      │                        │
  │ └────────────┴────────────┘                        │
  └────────────────────────────────────────────────────┘
        │
        ▼
  NewsletterEditorAgent
        │
        ▼
  HTMLFormatterAgent
  ```

  ---

  ## 🧩 Tech Stack

  * **Language**: Python 3.12+
  * **Framework**: FastAPI + Jinja2 templates
  * **Task Automation**: APScheduler
  * **Agents & LLM**: CrewAI (GPT-4 or Deepseek)
  * **Database**: SQLite (via SQLAlchemy ORM)
  * **Email Services**: SendGrid or any other service (configurable)

  ---

  ## 📁 Folder Structure

  ```
  ai-bulletin/
  ├── main.py              # FastAPI app entry point
  ├── database.py          # SQLite engine + session config
  ├── models.py            # SQLAlchemy models
  ├── schemas.py           # Pydantic schemas for validation
  ├── admin.py             # Admin interface or manual overrides
  ├── newsletter/          # CrewAI agents, tasks, orchestration
  ├── crew/                # Crew definitions and configuration
  ├── jobs/                # APScheduler jobs (weekly trigger)
  ├── utils/               # Email sender wrappers
  ├── templates/           # HTML pages for subscription/unsubscribe
  ├── requirements.txt     # Project dependencies
  └── subscribers.db       # SQLite DB (auto-created)
  ```

  ---

  ## ⚙️ Getting Started

  ### 📦 Prerequisites

  * Python 3.10+
  * [`uv`](https://github.com/astral-sh/uv): ultra-fast package manager

  ```bash
  curl -Ls https://astral.sh/uv/install.sh | bash
  ```

  ### 🛠️ Setup & Installation

  ```bash
  # Clone the repo
  $ git clone https://github.com/dev-ahmadbilal/ai-bulletin.git
  $ cd ai-bulletin

  # Create virtual environment
  $ uv venv .venv
  $ source .venv/bin/activate

  # Install dependencies
  $ uv pip install -r requirements.txt
  ```

  ### 🚀 Run Locally

  ```bash
  uvicorn main:app --reload
  ```

  ### 🌐 Test Email Subscription

  ```bash
  curl -X POST http://localhost:8000/subscribe \
    -H "Content-Type: application/json" \
    -d '{"email": "example@domain.com"}'
  ```

  ---

  ## 📬 API Endpoints

  | Method | Route          | Description             |
  | ------ | -------------- | ----------------------- |
  | POST   | `/subscribe`   | Subscribe a new email   |
  | GET    | `/health`      | Check API health status |
  | GET    | `/unsubscribe` | Show unsubscribe form   |
  | POST   | `/unsubscribe` | Unsubscribe from list   |

  ---

  ## 🗓️ Automation with APScheduler

  * The `newsletter_job` is triggered every Sunday at 10 AM:

  ```python
  CronTrigger(day_of_week="sun", hour=10, minute=0)
  ```

  * You can change the schedule in `jobs/newsletter_job.py`

  ---

  ## 🧹 How It Works for Subscribers

  * ✉️ When a new user subscribes, they **instantly receive the latest edition** of the newsletter.  
  * 📫 We recommend checking your **spam or junk folder** if you don't see the email.  
  * 🗓️ After that, new editions are delivered to all subscribers **automatically every week**.  

  ---

  ## 🎁 Sponsors

  **AI Bulletin is currently looking for sponsors!**

  If you're a company or individual who believes in the power of open-source, agentic AI systems, and automated media — let's collaborate.

  Want to sponsor AI Bulletin?  
  ➡️ [ahmadbilal.3491@gmail.com](mailto:ahmadbilal.3491@gmail)

  ---

  ## ☕ Support Ahmad

  If you enjoy AI Bulletin, consider buying me a coffee:

  ➡️ [https://buymeacoffee.com/ahmad.bilal](https://buymeacoffee.com/ahmad.bilal)

  ---

  ## 📄 License

  This project is licensed under the [MIT License](LICENSE)

  ---

  ## 🤝 Contributing

  Feel free to fork and submit PRs for enhancements, fixes, or new agent ideas.

  ---

  ## 🙌 Acknowledgements
  * Shoutout to Ed Donner for an amazing Agentic ai course. 
  * CrewAI by Vercel & LangChain community
  * APScheduler for painless job scheduling
  * SendGrid for simple transactional email delivery

A fully autonomous, AI-powered weekly tech newsletter that summarizes the top stories, dives deep into trends, and delivers beautifully formatted content straight to your inbox.

Ai Bulletin


`Currency Master` is a comprehensive TypeScript library that provides utilities for working with various currency-related tasks, such as formatting currency strings, converting amounts between different currencies, converting numerical values to words, and mapping country codes to their respective currency codes.

## Table of Contents

- [Installation](#installation)
- [Usage](#usage)
  - [Currency](#currency-class)
  - [ToWords](#towords)
  - [CountryCurrencyCode](#countrycurrencycode)
  - [CurrencyConversion](#currencyconversion)
  - [UsefulEnums](#useful-enums)
- [Contributing](#contributing)
- [License](#license)
- [Credits](#credits)


## Installation

To install the package, use npm:

```bash
npm install currency-master
```

## Usage

You can use any of the four classes provided by Currency Master to perform various currency-related tasks.

### `Currency` Class

The `Currency` class provides a comprehensive set of utilities for handling currency values with various operations such as addition, subtraction, multiplication, division, formatting, and converting values to words. This class is designed to handle different currency formats and supports customizable settings.

#### Features

- **Arithmetic Operations**: Add, subtract, multiply, and divide currency values.
- **Formatting**: Convert currency values to formatted strings.
- **Distribution**: Evenly distribute a currency value into parts.
- **Conversion to Words**: Convert currency values to their word representation.
- **Customizable Settings**: Configure symbol, decimal separator, precision, grouping, and more.

#### Constructor

##### `Currency(value: number | string | Currency, options?: Partial<CurrencySettings>)`

Initializes a new instance of the `Currency` class.

- **`value`**: The initial value for the currency. It can be a number, string, or another `Currency` instance.
- **`options`**: An optional configuration object to customize currency settings.

##### Example

```typescript
const currency1 = new Currency(1234.56);
const currency2 = new Currency('1234.56');
const currency3 = new Currency(new Currency(1234.56));
```

#### Methods

##### `add(amount: number | string | Currency): Currency`

Adds a specified amount to the currency value.

**Example:**

```typescript
const currency = new Currency(10);
const result = currency.add(5); // Result is a new Currency instance with value 15
```

##### `subtract(amount: number | string | Currency): Currency`

Subtracts a specified amount from the currency value.

**Example:**

```typescript
const currency = new Currency(10);
const result = currency.subtract(5); // Result is a new Currency instance with value 5
```

##### `multiply(factor: number): Currency`

Multiplies the currency value by a specified factor.

**Example:**

```typescript
const currency = new Currency(10);
const result = currency.multiply(2); // Result is a new Currency instance with value 20
```

##### `divide(divisor: number): Currency`

Divides the currency value by a specified divisor.

**Example:**

```typescript
const currency = new Currency(10);
const result = currency.divide(2); // Result is a new Currency instance with value 5
```

##### `distribute(parts: number): Currency[]`

Distributes the currency value evenly into an array of `Currency` instances.

**Example:**

```typescript
const currency = new Currency(100);
const parts = currency.distribute(3); // an array of 3 Currency instances with values [33.34, 33.33, 33.33]
```

##### `dollars(): number`

Returns the dollar portion of the currency value.

**Example:**

```typescript
const currency = new Currency(123.45);
const dollars = currency.dollars(); // 123
```

##### `cents(): number`

Returns the cent portion of the currency value.

**Example:**

```typescript
const currency = new Currency(123.45);
const cents = currency.cents(); // 45
```

##### `format(options?: Partial<CurrencySettings>): string`

Formats the currency value as a string according to the specified settings.

**Example:**

```typescript
const currency = new Currency(1234.56);
const formatted = currency.format(); // '$1,234.56'
```

##### `toString(): string`

Converts the currency value to a string.

**Example:**

```typescript
const currency = new Currency(1234.56);
const value = currency.toString(); // '1234.56'
```

##### `toWords(): string`

Converts the currency value into its word representation.

**Default Behavior:**

By default, the `toWords` method converts the currency amount to words using US dollars:
```typescript
const currency = new Currency(1234.56);
const words = currency.toWords(); // 'one thousand two hundred thirty-four dollars and fifty-six cents'
```

**Customizing Currency Type:**

You can customize the currency type and locale in the constructor by passing `toWords` options:
```typescript
const c1 = new Currency('1234.56', {
  toWords: {
    locale: LocaleEnum.EnglishUnitedKingdom, // Specify the locale
  },
});
console.log(c1.toWords()); // 'One Thousand Two Hundred Thirty Four Pounds And Fifty Six Pence Only'
```

**Support for Multiple Locales:**

The `toWords` method supports various locales for diverse languages and regions:

**Urdu (Pakistan):**
```typescript
const c2 = new Currency('1234.56', {
  toWords: {
    locale: LocaleEnum.UrduPakistan,
  },
});
console.log(c2.toWords()); // 'ایک ہزار دو سو چونتیس روپے اور چھپن پیسے صرف'
```

**Hindi (India):**
```typescript
const c3 = new Currency('1234.56', {
  toWords: {
    locale: LocaleEnum.HindiIndia,
  },
});
console.log(c3.toWords()); // 'एक हज़ार दो सौ चौंतीस रुपये और छप्पन पैसे'
```

The `toWords` method is highly versatile and supports various locales, enabling you to format numbers into words in different languages and regional formats.
#### Configuration

The `Currency` class supports various configuration options through the `CurrencySettings` type:

- **`symbol`**: Currency symbol (default: `$`).
- **`separator`**: Thousands separator (default: `,`).
- **`decimal`**: Decimal separator (default: `.`).
- **`errorOnInvalid`**: Whether to throw an error on invalid input (default: `false`).
- **`precision`**: Number of decimal places (default: `2`).
- **`pattern`**: Format pattern for positive values (default: `!#`).
- **`negativePattern`**: Format pattern for negative values (default: `-!#`).
- **`fromCents`**: Whether the initial value is in cents (default: `false`).
- **`groups`**: Regular expression for grouping digits (default: `/(\d)(?=(\d{3})+(?!\d))/g`).
- **`format`**: Function to format the currency object (default: `formatCurrency`).
- **`toWords`**: Custom settings for currency to words (optional).

#### Example: Using Custom Currency Settings

In this example, we'll create a `Currency` instance with custom settings and perform various operations.

#### Custom Settings

Let's define custom settings for the `Currency` class:

```typescript
const customSettings: CurrencySettings = {
  symbol: '€',
  separator: '.',
  decimal: ',',
  precision: 2,
  pattern: '!# €',
  negativePattern: '-!# €',
  fromCents: false,
  groups: /(\d)(?=(\d{3})+(?!\d))/g,
};
```

#### Creating a Currency Instance with Custom Settings

Now we'll create a `Currency` instance using the custom settings and perform some operations:

```typescript
import Currency from './currency';

// Create a Currency instance with a value of 1234.56 and custom settings
const customCurrency = new Currency(1234.56, customSettings);

// Display the value formatted according to the custom settings
console.log(customCurrency.format()); // '1.234,56 €'

// Perform arithmetic operations
const addedCurrency = customCurrency.add(765.44);
console.log(addedCurrency.format()); // '2.000,00 €'

const subtractedCurrency = customCurrency.subtract(234.56);
console.log(subtractedCurrency.format()); // '1.000,00 €'

// Multiply and divide
const multipliedCurrency = customCurrency.multiply(1.5);
console.log(multipliedCurrency.format()); // '1.851,84 €'

const dividedCurrency = customCurrency.divide(2);
console.log(dividedCurrency.format()); // '617,28 €'

// Distribute the currency into 3 parts
const distributedCurrencies = customCurrency.distribute(3);
distributedCurrencies.forEach((currency, index) => {
  console.log("Part " + (index + 1) + ": " + currency.format());
});
//
// Part 1: '411,52 €'
// Part 2: '411,52 €'
// Part 3: '411,52 €'

// Convert to words
console.log(customCurrency.toWords()); // 'one thousand two hundred thirty-four euros and fifty-six cents'
```

### ToWords

The `ToWords` class provides methods to convert numerical values to their word representations.

#### Example

```typescript
import { ToWords } from 'currency-master';

// Convert a number to words
const words = ToWords.convert(123);
console.log(words); // "one hundred and twenty-three"

// Convert a negative number
const negativeWords = ToWords.convert(-123);
console.log(negativeWords); // "minus one hundred and twenty-three"
```
Options can be set at instance level, or along with individual call to `convert` method.

```ts
const toWords = new ToWords();

words = toWords1.convert(123.045, { currency: false, ignoreDecimal: false });
console.log(words); //  One Hundred Twenty Three Point Zero Four Five

words = toWords1.convert(123.045, { currency: false, ignoreDecimal: true });
console.log(words); //  One Hundred Twenty Three
```

#### Config Options

The `ToWords` class suppose following custom options 

- `locale` (LocaleEnum, default: `LocaleEnum.EnglishUnitedStates`):
  - Sets the locale for internationalization (i18n), determining the language and regional formatting for the words.

- `currency` (boolean, default: `true`):
  - Indicates if the number should be converted into words formatted as currency.
  - When set to `true`, the number will be rounded to two decimal places before conversion.
  - Includes currency symbols and adjusts pluralization of currency units.

- `ignoreDecimal` (boolean, default: `false`):
  - Determines whether to disregard the fractional (decimal) part of the number during conversion.
  - When `true`, only the integer part is converted to words, ignoring the decimal portion.

- `ignoreZeroCurrency` (boolean, default: `false`):
  - Specifies whether to omit zero value in the currency portion of the words.
  - When `true`, zero currency units will not be included in the output, avoiding redundant mentions.

- `doNotAddOnly` (boolean, default: `false`):
  - Controls whether to append the word "only" at the end of the converted currency words.
  - Works only when `currency` is `true`. When `true`, "only" is not included in the output.

- `currencyOptions` (object, default: `undefined`):
  - Allows customization of currency options while retaining the language settings from the locale.
  - Useful for specifying different currencies (e.g., using EUR instead of USD) while converting to words in a specific language.
  - Supports dynamic currency changes for each conversion call, applicable only when `currency` is `true`.

```ts
const toWords = new ToWords({
  locale: LocaleEnum.EnglisUnitedStates,
  converterOptions: {
    currency: true,
    ignoreDecimal: false,
    ignoreZeroCurrency: false,
    doNotAddOnly: false,
    currencyOptions: {
      name: 'Dollar',
      plural: 'Dollars',
      symbol: '$',
      fractionalUnit: {
        name: 'Cent',
        plural: 'Cents',
        symbol: '',
      },
    },
  },
});
```
#### Supported Locales

  | Country             | Language   | Locale          |
  | ------------------- | ---------- | --------------- |
  | UAE                 | English    | en-AE           |
  | Bangladesh          | English    | en-BD           |
  | UK                  | English    | en-GB           |
  | Ghana               | English    | en-GH           |
  | Ireland             | English    | en-IE           |
  | India               | English    | en-IN           |
  | Myanmar             | English    | en-MM           |
  | Mauritius           | English    | en-MU           |
  | Nigeria             | English    | en-NG           |
  | Nepal               | English    | en-NP           |
  | USA                 | English    | en-US (default) |
  | Philippines         | English    | en-PH           |
  | Estonia             | Estonian   | ee-EE           |
  | Iran                | Persian    | fa-IR           |
  | Belgium             | French     | fr-BE           |
  | France              | French     | fr-FR           |
  | India               | Gujarati   | gu-IN           |
  | India               | Hindi      | hi-IN           |
  | India               | Marathi    | mr-IN           |
  | Suriname            | Dutch      | nl-SR           |
  | Brazil              | Portuguese | pt-BR           |
  | Turkey              | Turkish    | tr-TR           |
  | Korean, Republic    | Hangul     | ko-KR           |
  | Pakistan            | English    | en-PK           |
  | Pakistan            | Urdu       | ur-PK           |

### CountryCurrencyCode

The `CountryCurrencyCode` class provides utility methods to map country codes to their respective currency codes.

#### Example

```typescript
import { CountryCurrencyCode } from 'currency-master';

// Get the currency code by country code
const currency = CountryCurrencyCode.getCurrencyByCountryCode('US');
console.log(currency); // 'USD'

// Get all country codes using a specific currency
const countries = CountryCurrencyCode.getCountriesByCurrencyCode('USD');
console.log(countries); // ['US', 'UM']

// Get all the country codes
const countryCodes = CountryCurrencyCode.getAllCountryCodes();
console.log(countryCodes); // List of all all country codes

// Get all currency codes
const currencyCodes = CountryCurrencyCode.getAllCurrencyCodes();
console.log(currencyCodes); // List of all currency codes
```
### CurrencyConversion

The `CurrencyConversion` class provides methods for fetching real-time or historical exchange rates and converting currency from one type to another. It interacts with the [Fawaz Ahmed Currency API](https://github.com/fawazahmed0/currency-api) to retrieve exchange rates.

#### Fetching Currency Rates

You can fetch the latest exchange rates for a specific currency, or fetch historical rates by specifying a date in the `YYYY-MM-DD` format.

#### Fetching Latest Rates

```ts
const rates = await CurrencyConversion.getCurrencyRates(CurrencyEnum.UnitedStatesDollar);
console.log(rates); // Output: { "eur": 0.92, "gbp": 0.80, ... }
```

#### Fetching Historical Rates

```ts
const historicalRates = await CurrencyConversion.getCurrencyRates(CurrencyEnum.UnitedStatesDollar, '2024-09-01');
console.log(historicalRates); // Output: { "eur": 0.90, "gbp": 0.78, ... }
```

#### Converting Currency

You can convert a specific amount from one currency to another using either real-time or historical exchange rates.

##### Real-Time Conversion

```ts
const convertedAmount = await CurrencyConversion.convert(CurrencyEnum.UnitedStatesDollar, CurrencyEnum.Euro, 100);
console.log(convertedAmount); // Output: "92.00" (depending on the exchange rate)
```

##### Historical Conversion

```ts
const historicalConversion = await CurrencyConversion.convert(CurrencyEnum.UnitedStatesDollar, CurrencyEnum.Euro, 100, '2024-09-01');
console.log(historicalConversion); // Output: "90.00" (depending on the historical rate)
```

#### API Reference

##### `CurrencyConversion`

- `getCurrencyRates(currency: CurrencyEnum, date?: string): Promise<CurrencyRates>`
  - **currency**: Base currency (e.g., `CurrencyEnum.USD`).
  - **date** (optional): Historical date in `YYYY-MM-DD` format. If omitted, the latest rates will be fetched.
  - **Returns**: A promise that resolves to the exchange rates for the base currency.

- `convert(from: CurrencyEnum, to: CurrencyEnum, amount: number, date?: string): Promise<string>`
  - **from**: Base currency.
  - **to**: Target currency.
  - **amount**: Amount to convert.
  - **date** (optional): Historical date for conversion. If omitted, the latest exchange rates will be used.
  - **Returns**: A promise that resolves to the converted amount (as a string with two decimal places).

### Useful Enums

#### `CurrencyEnum`

It contains a set of predefined currency codes to be used with the `CurrencyConversion` class.

Example:

```ts
CurrencyEnum.Euro                 // Euro
CurrencyEnum.UnitedStatesDollar   // US Dollar
```


#### `CountryCurrencyEnum`

It contains a mapping of country codes to currency codes.

Example:

```ts
CountryCurrencyEnum.US   // USD
CountryCurrencyEnum.AE   // AED
```

## Contributing

Contributions are welcome! Please see the [Contributing Guidelines](https://github.com/dev-ahmadbilal/currency-master/blob/develop/CONTRIBUTING.md) for more details.

## License

This project is licensed under the MIT License. See the [LICENSE](https://github.com/dev-ahmadbilal/currency-master/blob/develop/LICENSE) file for more information.

## Credits

I would like to acknowledge the following resources that were instrumental in the development of this package:

- [**currency.js**](https://www.npmjs.com/package/currency.js): This library provided valuable insights and inspiration for handling currency formatting and conversion.
- [**to-words**](https://www.npmjs.com/package/to-words): A useful package for converting numbers to words, which served as a reference for implementing similar functionality.
- [**country-to-currency**](https://www.npmjs.com/package/country-to-currency): A helpful resource for mapping countries to their respective currencies.
- [**exchange-api**](https://github.com/fawazahmed0/exchange-api): An open-source API used for currency exchange rates, which guided the implementation of currency conversion features.

Thank you to these projects for their contributions to the open-source community!
    

A versatile npm package for currency operations, including arithmetic, formatting, number-to-word conversion, and mapping currencies to country codes.

Currency Master

A comprehensive Typescript library for advanced string manipulation, including case conversion, text formatting, slugification, and more.

Ahmad Bilal

Projects