npm package: @mahbub_ali/prayer-times
Description: A comprehensive TypeScript package for calculating Islamic prayer times and Islamic calendar (Hijri) with accurate timezone detection for countries worldwide
Latest version: 1.1.91

# @mahbub_ali/prayer-times

A comprehensive TypeScript package for calculating Islamic prayer times and managing Islamic calendar (Hijri) with accurate timezone detection for countries worldwide.

## 📱 Demo & Implementation

A complete demo application showcasing this package is available at:

**🔗 [GitHub Repository: test-sala-time](https://github.com/Mahbub192/test-sala-time)**

The demo app includes:

- ✅ Real-time prayer times display
- ✅ Current and next prayer highlighting
- ✅ Hijri calendar integration
- ✅ Date navigation (Previous/Next day)
- ✅ Islamic events display
- ✅ Beautiful UI with React Native/Expo

<table>
  <tr>
    <td><img src="./assets/1.png" width="200" /></td>
    <td><img src="./assets/2.png" width="200" /></td>
    <td><img src="./assets/3.png" width="200" /></td>
  </tr>
  <tr>
    <td><img src="./assets/4.png" width="200" /></td>
    <td><img src="./assets/5.png" width="200" /></td>
    <td></td>
  </tr>
</table>

## Features

- ✅ **Prayer Times Calculation** - Accurate calculations using multiple methods
- ✅ **Automatic Timezone Detection** - Supports 50+ countries
- ✅ **DST Handling** - Automatic Daylight Saving Time for USA, Canada, UK, Australia
- ✅ **Half-hour Timezones** - Support for India (GMT+5:30), Australia (GMT+9:30, GMT+10:30)
- ✅ **Multiple Calculation Methods** - 7 different methods (MWL, ISNA, Egypt, Makkah, Karachi, Tehran, Jafari)
- ✅ **Multiple Madhabs** - 5 different madhabs (Shafi, Hanafi, Maliki, Hanbali, Standard)
- ✅ **Islamic Calendar (Hijri)** - Convert between Gregorian and Hijri dates
- ✅ **Islamic Events** - Get Islamic holidays and important dates
- ✅ **Full Month Calendar** - Get complete calendar data for any Hijri month
- ✅ **TypeScript Support** - Full type definitions and IntelliSense

## Installation

```bash
npm install @mahbub_ali/prayer-times
```

## Quick Start

### Calculate Prayer Times

```typescript
import {
  calculatePrayerTimes,
  CalculationMethod,
  Madhab,
} from "@mahbub_ali/prayer-times";

const date = new Date();
const coordinates: [number, number] = [23.8103, 90.4125]; // Dhaka, Bangladesh

const prayerTimes = calculatePrayerTimes(
  date,
  coordinates,
  CalculationMethod.Karachi,
  Madhab.Hanafi,
  "Dhaka, Bangladesh",
  "12h"
);

console.log(prayerTimes);
// {
//   imsak: "4:18 am",
//   fajr: "4:28 am",
//   sunrise: "5:47 am",
//   dhuhr: "12:05 pm",
//   asr: "3:29 pm",
//   sunset: "6:19 pm",
//   maghrib: "6:19 pm",
//   isha: "7:32 pm",
//   midnight: "11:59 pm"
// }
```

### Get Hijri Date

```typescript
import { getHijriDateString, gregorianToHijri } from "@mahbub_ali/prayer-times";

// Simple string format
const hijriDate = getHijriDateString();
console.log(hijriDate); // "15 Ramadan 1446 AH"

// Full date object
const hijri = gregorianToHijri(new Date());
console.log(hijri.day); // 15
console.log(hijri.month); // 9
console.log(hijri.year); // 1446
console.log(hijri.monthName); // "Ramadan"
console.log(hijri.monthNameArabic); // "رمضان"
```

## API Reference

### Prayer Times

#### `calculatePrayerTimes()`

Calculate prayer times for a given location and date.

```typescript
function calculatePrayerTimes(
  date: Date,
  coordinates: [number, number, number?],
  method?: CalculationMethod,
  madhab?: Madhab,
  cityName?: string,
  format?: "12h" | "24h" | "Float"
): PrayerTimes;
```

**Example:**

```typescript
import {
  calculatePrayerTimes,
  CalculationMethod,
  Madhab,
} from "@mahbub_ali/prayer-times";

const times = calculatePrayerTimes(
  new Date(),
  [40.7128, -74.006], // New York coordinates
  CalculationMethod.ISNA,
  Madhab.Hanafi,
  "New York, USA",
  "12h"
);
```

#### `getRecommendedMethod()`

Get recommended calculation method based on location.

```typescript
function getRecommendedMethod(
  cityName: string,
  latitude: number,
  longitude: number
): CalculationMethod;
```

**Example:**

```typescript
import {
  getRecommendedMethod,
  calculatePrayerTimes,
} from "@mahbub_ali/prayer-times";

const method = getRecommendedMethod("Dhaka, Bangladesh", 23.8103, 90.4125);
console.log(method); // CalculationMethod.Karachi

const times = calculatePrayerTimes(
  new Date(),
  [23.8103, 90.4125],
  method,
  undefined,
  "Dhaka, Bangladesh"
);
```

#### `getLocationTimezone()`

Get timezone offset for a location.

```typescript
function getLocationTimezone(
  cityName: string,
  latitude: number,
  longitude: number,
  date: Date
): number;
```

**Example:**

```typescript
import { getLocationTimezone } from "@mahbub_ali/prayer-times";

const timezone = getLocationTimezone(
  "Lahore, Pakistan",
  31.5204,
  74.3587,
  new Date()
);
console.log(timezone); // 5 (GMT+5)
```

#### `isDSTActive()`

Check if Daylight Saving Time is active for a location.

```typescript
function isDSTActive(date: Date, latitude: number): boolean;
```

**Example:**

```typescript
import { isDSTActive } from "@mahbub_ali/prayer-times";

const dstActive = isDSTActive(new Date(), 40.7128); // New York latitude
console.log(dstActive); // true or false
```

### Islamic Calendar (Hijri)

The package provides comprehensive Hijri calendar functionality including date conversion, month calendars, Islamic events, and more. All calculations use the Astronomical Calculation method for accuracy.

#### Date Conversion

##### `gregorianToHijri()`

Convert Gregorian date to Hijri date.

```typescript
function gregorianToHijri(date: Date): HijriDate;
```

**Example:**

```typescript
import { gregorianToHijri } from "@mahbub_ali/prayer-times";

const hijri = gregorianToHijri(new Date());
console.log(hijri.formatted); // "15 Ramadan 1446 AH"
console.log(hijri.day); // 15
console.log(hijri.month); // 9
console.log(hijri.year); // 1446
console.log(hijri.monthName); // "Ramadan"
console.log(hijri.monthNameArabic); // "رمضان"

// Convert a specific date
const specificDate = new Date(2025, 2, 15); // March 15, 2025
const hijriDate = gregorianToHijri(specificDate);
console.log(hijriDate.formatted); // "15 Ramadan 1446 AH"
```

##### `hijriToGregorian()`

Convert Hijri date to Gregorian date.

```typescript
function hijriToGregorian(
  hijriYear: number,
  hijriMonth: number,
  hijriDay: number
): Date;
```

**Example:**

```typescript
import { hijriToGregorian } from "@mahbub_ali/prayer-times";

// Convert 15 Ramadan 1446 to Gregorian
const gregorian = hijriToGregorian(1446, 9, 15);
console.log(gregorian.toLocaleDateString()); // "3/15/2025"

// Convert Eid al-Fitr 1446 (1 Shawwal 1446)
const eidDate = hijriToGregorian(1446, 10, 1);
console.log(eidDate.toLocaleDateString());
```

#### Date Formatting

##### `getHijriDateString()`

Get formatted Hijri date string with "AH" suffix.

```typescript
function getHijriDateString(date?: Date): string;
```

**Example:**

```typescript
import { getHijriDateString } from "@mahbub_ali/prayer-times";

const hijriString = getHijriDateString();
console.log(hijriString); // "15 Ramadan 1446 AH"

// For a specific date
const date = new Date(2025, 2, 15);
const formatted = getHijriDateString(date);
console.log(formatted); // "15 Ramadan 1446 AH"
```

##### `getShortHijriDate()`

Get short Hijri date format without "AH".

```typescript
function getShortHijriDate(date?: Date): string;
```

**Example:**

```typescript
import { getShortHijriDate } from "@mahbub_ali/prayer-times";

const short = getShortHijriDate();
console.log(short); // "15 Ramadan 1446"
```

##### `getCurrentHijriDate()`

Get current Hijri date as a full object.

```typescript
function getCurrentHijriDate(): HijriDate;
```

**Example:**

```typescript
import { getCurrentHijriDate } from "@mahbub_ali/prayer-times";

const today = getCurrentHijriDate();
console.log(today.formatted); // "15 Ramadan 1446 AH"
console.log(today.day); // 15
console.log(today.month); // 9
console.log(today.year); // 1446
console.log(today.monthName); // "Ramadan"
console.log(today.monthNameArabic); // "رمضان"
```

##### `formatHijriDate()`

Format Hijri date in different styles.

```typescript
function formatHijriDate(
  date?: Date,
  format?: "full" | "short" | "numeric"
): string;
```

**Example:**

```typescript
import { formatHijriDate } from "@mahbub_ali/prayer-times";

const full = formatHijriDate(new Date(), "full");
console.log(full); // "15 Ramadan 1446 AH"

const short = formatHijriDate(new Date(), "short");
console.log(short); // "15 Ramadan 1446"

const numeric = formatHijriDate(new Date(), "numeric");
console.log(numeric); // "15/9/1446"
```

#### Month Calendar

##### `getHijriMonthCalendar()`

Get full calendar for a Hijri month with all days, including Gregorian equivalents, day names, and events.

```typescript
function getHijriMonthCalendar(
  hijriYear: number,
  hijriMonth: number
): CalendarDay[];
```

**Example - Basic Usage:**

```typescript
import {
  getHijriMonthCalendar,
  getCurrentHijriDate,
} from "@mahbub_ali/prayer-times";

const currentHijri = getCurrentHijriDate();
const calendar = getHijriMonthCalendar(currentHijri.year, currentHijri.month);

calendar.forEach((day) => {
  console.log(`Day ${day.hijriDay}: ${day.dayName}`);
  console.log(`Gregorian: ${day.gregorianDate.toLocaleDateString()}`);
  if (day.hasEvent) {
    console.log(`Events: ${day.events.map((e) => e.name).join(", ")}`);
  }
  if (day.isToday) {
    console.log("⭐ Today!");
  }
});
```

**Example - Building a Calendar UI:**

```typescript
import { getHijriMonthCalendar, HIJRI_MONTHS } from "@mahbub_ali/prayer-times";

function renderCalendar(hijriYear: number, hijriMonth: number) {
  const calendar = getHijriMonthCalendar(hijriYear, hijriMonth);

  console.log(`\n${HIJRI_MONTHS[hijriMonth - 1]} ${hijriYear} AH\n`);
  console.log("Sun  Mon  Tue  Wed  Thu  Fri  Sat");

  // Group days by week
  const weeks: CalendarDay[][] = [];
  let currentWeek: CalendarDay[] = [];

  calendar.forEach((day, index) => {
    // Start new week on Sunday (dayOfWeek === 0)
    if (day.dayOfWeek === 0 && currentWeek.length > 0) {
      weeks.push(currentWeek);
      currentWeek = [];
    }

    // Add padding for days before the first day of month
    if (index === 0 && day.dayOfWeek !== 0) {
      for (let i = 0; i < day.dayOfWeek; i++) {
        currentWeek.push(null as any);
      }
    }

    currentWeek.push(day);

    // End week on Saturday or last day
    if (day.dayOfWeek === 6 || index === calendar.length - 1) {
      weeks.push(currentWeek);
      currentWeek = [];
    }
  });

  // Render calendar grid
  weeks.forEach((week) => {
    const weekStr = week
      .map((day) => {
        if (!day) return "     ";
        const dayStr = day.hijriDay.toString().padStart(2, " ");
        const marker = day.isToday ? "⭐" : day.hasEvent ? "•" : " ";
        return `${dayStr}${marker} `;
      })
      .join("");
    console.log(weekStr);
  });
}

// Render current month
const today = new Date();
const hijri = gregorianToHijri(today);
renderCalendar(hijri.year, hijri.month);
```

**Example - Calendar with Events:**

```typescript
import { getHijriMonthCalendar } from "@mahbub_ali/prayer-times";

const calendar = getHijriMonthCalendar(1446, 9); // Ramadan 1446

calendar.forEach((day) => {
  const dateStr = `${day.hijriDay}/${day.hijriMonth}/${day.hijriYear}`;
  const gregStr = day.gregorianDate.toLocaleDateString();

  console.log(`${dateStr} (${gregStr}) - ${day.dayName}`);

  if (day.hasEvent) {
    day.events.forEach((event) => {
      console.log(`  🎉 ${event.name}: ${event.description}`);
      if (event.arabicName) {
        console.log(`     ${event.arabicName}`);
      }
    });
  }
});
```

#### Islamic Events

##### `getIslamicEvents()`

Get Islamic events for a specific date.

```typescript
function getIslamicEvents(date?: Date): IslamicEvent[];
```

**Example:**

```typescript
import { getIslamicEvents } from "@mahbub_ali/prayer-times";

const events = getIslamicEvents(new Date());
if (events.length > 0) {
  events.forEach((event) => {
    console.log(`🎉 ${event.name}`);
    console.log(`   ${event.description}`);
    if (event.arabicName) {
      console.log(`   ${event.arabicName}`);
    }
  });
} else {
  console.log("No Islamic events today");
}
```

##### `getEventsForMonth()`

Get all Islamic events for a specific Hijri month.

```typescript
function getEventsForMonth(hijriMonth: number): IslamicEvent[];
```

**Example:**

```typescript
import { getEventsForMonth } from "@mahbub_ali/prayer-times";

// Get all events in Ramadan (month 9)
const ramadanEvents = getEventsForMonth(9);
console.log(`Ramadan has ${ramadanEvents.length} events:`);
ramadanEvents.forEach((event) => {
  console.log(`- ${event.date}: ${event.name}`);
});

// Get all events in Dhul-Hijjah (month 12) for Hajj season
const hajjEvents = getEventsForMonth(12);
hajjEvents.forEach((event) => {
  console.log(`${event.name} - ${event.description}`);
});
```

##### `getNextIslamicEvent()`

Get the next upcoming Islamic event from a given date.

```typescript
function getNextIslamicEvent(fromDate?: Date): IslamicEvent | null;
```

**Example:**

```typescript
import { getNextIslamicEvent } from "@mahbub_ali/prayer-times";

const nextEvent = getNextIslamicEvent(new Date());
if (nextEvent) {
  console.log(`Next Islamic event: ${nextEvent.name}`);
  console.log(`Description: ${nextEvent.description}`);
  console.log(`Date: ${nextEvent.date}`);
} else {
  console.log("No upcoming events found");
}
```

##### `getDaysUntilEvent()`

Get number of days until a specific Islamic event.

```typescript
function getDaysUntilEvent(eventName: string, fromDate?: Date): number | null;
```

**Example:**

```typescript
import { getDaysUntilEvent } from "@mahbub_ali/prayer-times";

const daysUntilEid = getDaysUntilEvent("Eid al-Fitr", new Date());
if (daysUntilEid !== null) {
  console.log(`Days until Eid al-Fitr: ${daysUntilEid}`);
  if (daysUntilEid === 0) {
    console.log("🎉 Eid Mubarak!");
  } else if (daysUntilEid === 1) {
    console.log("Tomorrow is Eid!");
  }
} else {
  console.log("Event not found or already passed this year");
}

// Check days until other events
const daysUntilHajj = getDaysUntilEvent("Hajj", new Date());
const daysUntilRamadan = getDaysUntilEvent("Start of Ramadan", new Date());
```

##### `isIslamicEventToday()`

Check if today is an Islamic event.

```typescript
function isIslamicEventToday(date?: Date): boolean;
```

**Example:**

```typescript
import {
  isIslamicEventToday,
  getIslamicEvents,
} from "@mahbub_ali/prayer-times";

if (isIslamicEventToday()) {
  const events = getIslamicEvents();
  console.log("🎉 Today is an Islamic event!");
  events.forEach((event) => {
    console.log(`- ${event.name}`);
  });
}
```

##### `getAllIslamicEvents()`

Get all available Islamic events.

```typescript
function getAllIslamicEvents(): IslamicEvent[];
```

**Example:**

```typescript
import { getAllIslamicEvents } from "@mahbub_ali/prayer-times";

const allEvents = getAllIslamicEvents();
console.log(`Total Islamic events: ${allEvents.length}`);

// Group events by month
const eventsByMonth: { [key: number]: IslamicEvent[] } = {};
allEvents.forEach((event) => {
  const month = parseInt(event.date.split("/")[0]);
  if (!eventsByMonth[month]) {
    eventsByMonth[month] = [];
  }
  eventsByMonth[month].push(event);
});

// Display events by month
Object.keys(eventsByMonth).forEach((month) => {
  console.log(`\nMonth ${month}:`);
  eventsByMonth[parseInt(month)].forEach((event) => {
    console.log(`  - ${event.name}`);
  });
});
```

#### Month Information

##### `isRamadan()`

Check if a date is in Ramadan (month 9).

```typescript
function isRamadan(date?: Date): boolean;
```

**Example:**

```typescript
import { isRamadan, gregorianToHijri } from "@mahbub_ali/prayer-times";

if (isRamadan(new Date())) {
  const hijri = gregorianToHijri(new Date());
  console.log(`🌙 Ramadan Mubarak! Day ${hijri.day} of Ramadan`);
} else {
  console.log("Not currently Ramadan");
}
```

##### `getHijriMonthInfo()`

Get comprehensive information about a Hijri month including name, Arabic name, days, and description.

```typescript
function getHijriMonthInfo(
  month: number,
  year?: number
): {
  name: string;
  arabicName: string;
  days: number;
  description: string;
};
```

**Example:**

```typescript
import { getHijriMonthInfo } from "@mahbub_ali/prayer-times";

// Get Ramadan info
const ramadanInfo = getHijriMonthInfo(9, 1446);
console.log(ramadanInfo.name); // "Ramadan"
console.log(ramadanInfo.arabicName); // "رمضان"
console.log(ramadanInfo.days); // 30 (or 29 depending on year)
console.log(ramadanInfo.description); // Month description

// Get info for all months
for (let month = 1; month <= 12; month++) {
  const info = getHijriMonthInfo(month);
  console.log(`${info.name} (${info.arabicName}): ${info.days} days`);
}
```

##### `getArabicMonthName()`

Get Arabic name for a Hijri month.

```typescript
function getArabicMonthName(month: number): string;
```

**Example:**

```typescript
import { getArabicMonthName, HIJRI_MONTHS } from "@mahbub_ali/prayer-times";

// Get Arabic name for Ramadan
const arabicName = getArabicMonthName(9);
console.log(arabicName); // "رمضان"

// Display all months with Arabic names
HIJRI_MONTHS.forEach((month, index) => {
  const arabic = getArabicMonthName(index + 1);
  console.log(`${month} - ${arabic}`);
});
```

##### `getDaysInHijriMonth()`

Get number of days in a Hijri month. For accurate calculation, provide the year.

```typescript
function getDaysInHijriMonth(month: number, year?: number): number;
```

**Example:**

```typescript
import { getDaysInHijriMonth } from "@mahbub_ali/prayer-times";

// Get days in Ramadan (approximate, without year)
const daysApprox = getDaysInHijriMonth(9);
console.log(daysApprox); // 30

// Get accurate days for a specific year
const days1446 = getDaysInHijriMonth(9, 1446);
console.log(days1446); // 30 or 29 (accurate based on leap year)

// Get days for Dhul-Hijjah (varies by leap year)
const dhulHijjahDays = getDaysInHijriMonth(12, 1446);
console.log(dhulHijjahDays); // 29 or 30 (depends on leap year)
```

#### Calendar Constants

The package exports useful constants for working with the Hijri calendar:

```typescript
import {
  HIJRI_MONTHS,
  HIJRI_MONTHS_ARABIC,
  ISLAMIC_EVENTS,
  HIJRI_MONTH_DESCRIPTIONS,
} from "@mahbub_ali/prayer-times";

// Month names in English
console.log(HIJRI_MONTHS);
// ["Muharram", "Safar", "Rabi al-Awwal", ...]

// Month names in Arabic
console.log(HIJRI_MONTHS_ARABIC);
// ["محرم", "صفر", "ربيع الأول", ...]

// All Islamic events
console.log(ISLAMIC_EVENTS.length); // Total number of events

// Month descriptions
console.log(HIJRI_MONTH_DESCRIPTIONS[9]); // Ramadan description
```

### Advanced Usage

#### Custom PrayTimes Instance

```typescript
import { PrayTimes, CalculationMethod, Madhab } from "@mahbub_ali/prayer-times";

const prayTimes = new PrayTimes(CalculationMethod.MWL, Madhab.Shafi);

const times = prayTimes.getTimes(
  new Date(),
  [31.5204, 74.3587], // [latitude, longitude]
  5, // timezone
  0, // DST offset
  "12h" // format
);
```

#### Different Time Formats

```typescript
import { calculatePrayerTimes } from "@mahbub_ali/prayer-times";

// 12-hour format (default)
const times12h = calculatePrayerTimes(
  new Date(),
  [23.8103, 90.4125],
  undefined,
  undefined,
  "Dhaka, Bangladesh",
  "12h"
);
console.log(times12h.fajr); // "4:28 am"

// 24-hour format
const times24h = calculatePrayerTimes(
  new Date(),
  [23.8103, 90.4125],
  undefined,
  undefined,
  "Dhaka, Bangladesh",
  "24h"
);
console.log(times24h.fajr); // "04:28"

// Float format (for calculations)
const timesFloat = calculatePrayerTimes(
  new Date(),
  [23.8103, 90.4125],
  undefined,
  undefined,
  "Dhaka, Bangladesh",
  "Float"
);
console.log(timesFloat.fajr); // 4.466666666666667
```

#### Complete Calendar Example

Here's a comprehensive example showing how to build a full-featured Islamic calendar application:

```typescript
import {
  calculatePrayerTimes,
  gregorianToHijri,
  hijriToGregorian,
  getHijriMonthCalendar,
  getIslamicEvents,
  getEventsForMonth,
  getNextIslamicEvent,
  getDaysUntilEvent,
  isRamadan,
  getHijriMonthInfo,
  getCurrentHijriDate,
  formatHijriDate,
  CalculationMethod,
  Madhab,
  HIJRI_MONTHS,
} from "@mahbub_ali/prayer-times";

// Get today's information
const today = new Date();
const coords: [number, number] = [23.8103, 90.4125]; // Dhaka, Bangladesh

// 1. Get current Hijri date
const hijriDate = getCurrentHijriDate();
console.log(`Today: ${hijriDate.formatted}`);
console.log(`Arabic: ${hijriDate.monthNameArabic} ${hijriDate.year}`);

// 2. Get prayer times
const prayerTimes = calculatePrayerTimes(
  today,
  coords,
  CalculationMethod.Karachi,
  Madhab.Hanafi,
  "Dhaka, Bangladesh"
);

console.log("\nPrayer Times:");
console.log(`Fajr: ${prayerTimes.fajr}`);
console.log(`Dhuhr: ${prayerTimes.dhuhr}`);
console.log(`Asr: ${prayerTimes.asr}`);
console.log(`Maghrib: ${prayerTimes.maghrib}`);
console.log(`Isha: ${prayerTimes.isha}`);

// 3. Check if Ramadan
if (isRamadan(today)) {
  console.log("\n🌙 Ramadan Mubarak!");
  console.log(`Day ${hijriDate.day} of Ramadan`);
}

// 4. Get today's Islamic events
const todayEvents = getIslamicEvents(today);
if (todayEvents.length > 0) {
  console.log("\nToday's Islamic Events:");
  todayEvents.forEach((event) => {
    console.log(`🎉 ${event.name}`);
    console.log(`   ${event.description}`);
  });
}

// 5. Get next upcoming event
const nextEvent = getNextIslamicEvent(today);
if (nextEvent) {
  const daysUntil = getDaysUntilEvent(nextEvent.name, today);
  console.log(`\nNext Event: ${nextEvent.name}`);
  console.log(`Days until: ${daysUntil}`);
}

// 6. Get full month calendar
const calendar = getHijriMonthCalendar(hijriDate.year, hijriDate.month);
const monthInfo = getHijriMonthInfo(hijriDate.month, hijriDate.year);

console.log(`\n${monthInfo.name} ${hijriDate.year} AH Calendar`);
console.log(`Total days: ${monthInfo.days}`);
console.log(`Description: ${monthInfo.description}`);

// 7. Get all events for current month
const monthEvents = getEventsForMonth(hijriDate.month);
if (monthEvents.length > 0) {
  console.log(`\nEvents this month (${monthEvents.length}):`);
  monthEvents.forEach((event) => {
    console.log(`- ${event.date}: ${event.name}`);
  });
}

// 8. Display calendar with events
console.log("\nCalendar View:");
calendar.forEach((day) => {
  const dateStr = formatHijriDate(day.gregorianDate, "numeric");
  const gregStr = day.gregorianDate.toLocaleDateString();
  let dayInfo = `${day.hijriDay} ${
    HIJRI_MONTHS[day.hijriMonth - 1]
  } (${gregStr})`;

  if (day.isToday) {
    dayInfo = `⭐ ${dayInfo} - TODAY`;
  }

  if (day.hasEvent) {
    dayInfo += ` - ${day.events.map((e) => e.name).join(", ")}`;
  }

  console.log(dayInfo);
});
```

#### Date Conversion Examples

```typescript
import {
  gregorianToHijri,
  hijriToGregorian,
  formatHijriDate,
} from "@mahbub_ali/prayer-times";

// Convert Gregorian to Hijri
const gregorianDate = new Date(2025, 2, 15); // March 15, 2025
const hijri = gregorianToHijri(gregorianDate);
console.log(`${gregorianDate.toLocaleDateString()} = ${hijri.formatted}`);

// Convert Hijri to Gregorian
const eidDate = hijriToGregorian(1446, 10, 1); // 1 Shawwal 1446 (Eid al-Fitr)
console.log(`Eid al-Fitr 1446 = ${eidDate.toLocaleDateString()}`);

// Format in different styles
console.log(formatHijriDate(gregorianDate, "full")); // "15 Ramadan 1446 AH"
console.log(formatHijriDate(gregorianDate, "short")); // "15 Ramadan 1446"
console.log(formatHijriDate(gregorianDate, "numeric")); // "15/9/1446"
```

## Calculation Methods

- **MWL** - Muslim World League (default, used globally)
- **ISNA** - Islamic Society of North America (North America)
- **Egypt** - Egyptian General Authority (Africa)
- **Makkah** - Umm al-Qura, Makkah (Saudi Arabia, Middle East)
- **Karachi** - University of Islamic Sciences, Karachi (Pakistan, Bangladesh, India)
- **Tehran** - Institute of Geophysics, Tehran (Iran)
- **Jafari** - Shia Ithna Ashari (Shia communities)

## Madhabs

- **Shafi** - Standard Asr calculation (default)
- **Hanafi** - Asr when shadow = 2x object length (later)
- **Maliki** - Standard Asr calculation
- **Hanbali** - Standard Asr calculation

## Supported Countries

The package automatically detects timezones for:

- **South Asia**: Bangladesh, India, Pakistan
- **Middle East**: Saudi Arabia, UAE, Egypt, Turkey
- **Southeast Asia**: Malaysia, Singapore, Indonesia
- **North America**: USA (all timezones), Canada (all timezones)
- **Europe**: UK (with DST)
- **Australia**: Multiple timezones with DST
- **And many more...**

## TypeScript Types

```typescript
interface PrayerTimes {
  imsak: string;
  fajr: string;
  sunrise: string;
  dhuhr: string;
  asr: string;
  sunset: string;
  maghrib: string;
  isha: string;
  midnight: string;
}

interface HijriDate {
  day: number;
  month: number;
  year: number;
  monthName: string;
  monthNameArabic: string;
  formatted: string;
}

interface CalendarDay {
  hijriDay: number;
  hijriMonth: number;
  hijriYear: number;
  gregorianDate: Date;
  dayOfWeek: number;
  dayName: string;
  hasEvent: boolean;
  events: IslamicEvent[];
  isToday?: boolean;
}

interface IslamicEvent {
  date: string;
  name: string;
  description: string;
  arabicName?: string;
}

enum CalculationMethod {
  MWL = "MWL",
  ISNA = "ISNA",
  Egypt = "Egypt",
  Makkah = "Makkah",
  Karachi = "Karachi",
  Tehran = "Tehran",
  Jafari = "Jafari",
}

enum Madhab {
  Shafi = "Shafi",
  Hanafi = "Hanafi",
  Maliki = "Maliki",
  Hanbali = "Hanbali",
  Standard = "Standard",
}
```

## Use Cases

- ✅ **Mobile Apps** - React Native, Expo apps
- ✅ **Web Apps** - React, Next.js, Vue.js applications
- ✅ **Backend APIs** - Node.js, Express APIs
- ✅ **Desktop Apps** - Electron applications
- ✅ **Any JavaScript/TypeScript Project** - Works everywhere

## 📱 Real-World Implementation

### Demo Application

A complete, production-ready demo application is available that showcases all features of this package:

**Repository:** [https://github.com/Mahbub192/test-sala-time](https://github.com/Mahbub192/test-sala-time)

**Features demonstrated:**

- Real-time prayer times calculation
- Current and next prayer detection
- Hijri calendar display alongside Gregorian dates
- Date navigation (Previous/Next day buttons)
- Islamic events integration
- Beautiful, modern UI built with React Native and Expo
- Automatic timezone detection
- DST handling

**Tech Stack:**

- React Native / Expo
- TypeScript
- `@mahbub_ali/prayer-times` (this package)
- Moment.js with Hijri calendar support

The demo app serves as a perfect reference implementation for integrating this package into your own applications.

## How It Works

### Prayer Times Calculation

This package calculates prayer times using **mathematical formulas** (not pre-calculated data). It works for any date, any location, in real-time. The calculations are based on astronomical formulas that consider:

- Latitude and longitude
- Date and time
- Timezone and DST
- Calculation method (MWL, ISNA, etc.)
- Madhab (for Asr calculation)

### Hijri Calendar Conversion

The Hijri calendar conversion uses the **Astronomical Calculation method** (also known as the Umm al-Qura algorithm). This is the same method used by popular Islamic libraries worldwide.

**How it works:**

1. Converts Gregorian date → Julian Day Number (JDN)
2. Converts JDN → Hijri date using 30-year cycle algorithm
3. Handles leap years automatically (11 leap years per 30-year cycle)
4. Pure mathematical calculation - no internet required

**Advantages:**

- ✅ No internet connection needed
- ✅ Works for any date (past, present, future)
- ✅ Location independent
- ✅ Fast and lightweight
- ✅ Accurate to within 1 day (acceptable for most applications)

**Note:** Moon sighting differences between countries are not accounted for. The calculated date may vary by ±1 day from actual moon-sighted dates in some regions. This is standard for astronomical calculation methods and acceptable for most applications.

## Calendar Quick Reference

### Date Conversion Functions

| Function                             | Description                    | Returns     |
| ------------------------------------ | ------------------------------ | ----------- |
| `gregorianToHijri(date)`             | Convert Gregorian to Hijri     | `HijriDate` |
| `hijriToGregorian(year, month, day)` | Convert Hijri to Gregorian     | `Date`      |
| `getCurrentHijriDate()`              | Get today's Hijri date         | `HijriDate` |
| `getHijriDateString(date?)`          | Get formatted string with "AH" | `string`    |
| `getShortHijriDate(date?)`           | Get short format without "AH"  | `string`    |
| `formatHijriDate(date?, format?)`    | Format in different styles     | `string`    |

### Calendar Functions

| Function                             | Description             | Returns         |
| ------------------------------------ | ----------------------- | --------------- |
| `getHijriMonthCalendar(year, month)` | Get full month calendar | `CalendarDay[]` |
| `getHijriMonthInfo(month, year?)`    | Get month information   | `MonthInfo`     |
| `getDaysInHijriMonth(month, year?)`  | Get days in month       | `number`        |
| `getArabicMonthName(month)`          | Get Arabic month name   | `string`        |

### Event Functions

| Function                         | Description               | Returns                |
| -------------------------------- | ------------------------- | ---------------------- |
| `getIslamicEvents(date?)`        | Get events for a date     | `IslamicEvent[]`       |
| `getEventsForMonth(month)`       | Get events for a month    | `IslamicEvent[]`       |
| `getNextIslamicEvent(date?)`     | Get next upcoming event   | `IslamicEvent \| null` |
| `getDaysUntilEvent(name, date?)` | Days until specific event | `number \| null`       |
| `isIslamicEventToday(date?)`     | Check if today has event  | `boolean`              |
| `getAllIslamicEvents()`          | Get all events            | `IslamicEvent[]`       |
| `isRamadan(date?)`               | Check if date is Ramadan  | `boolean`              |

### Constants

| Constant                   | Description                    |
| -------------------------- | ------------------------------ |
| `HIJRI_MONTHS`             | Array of English month names   |
| `HIJRI_MONTHS_ARABIC`      | Array of Arabic month names    |
| `ISLAMIC_EVENTS`           | Array of all Islamic events    |
| `HIJRI_MONTH_DESCRIPTIONS` | Object with month descriptions |

### Hijri Month Numbers

| Number | English Name    | Arabic Name   |
| ------ | --------------- | ------------- |
| 1      | Muharram        | محرم          |
| 2      | Safar           | صفر           |
| 3      | Rabi al-Awwal   | ربيع الأول    |
| 4      | Rabi al-Thani   | ربيع الثاني   |
| 5      | Jumada al-Awwal | جمادى الأولى  |
| 6      | Jumada al-Thani | جمادى الثانية |
| 7      | Rajab           | رجب           |
| 8      | Shaban          | شعبان         |
| 9      | Ramadan         | رمضان         |
| 10     | Shawwal         | شوال          |
| 11     | Dhul-Qadah      | ذو القعدة     |
| 12     | Dhul-Hijjah     | ذو الحجة      |

## License

MIT