@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

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

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

npm install @mahbub_ali/prayer-times

Quick Start

Calculate Prayer Times

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

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.

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

Example:

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.

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

Example:

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.

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

Example:

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.

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

Example:

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.

function gregorianToHijri(date: Date): HijriDate;

Example:

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.

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

Example:

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.

function getHijriDateString(date?: Date): string;

Example:

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

function getShortHijriDate(date?: Date): string;

Example:

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.

function getCurrentHijriDate(): HijriDate;

Example:

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.

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

Example:

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.

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

Example - Basic Usage:

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:

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:

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.

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

Example:

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.

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

Example:

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.

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

Example:

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.

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

Example:

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.

function isIslamicEventToday(date?: Date): boolean;

Example:

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.

function getAllIslamicEvents(): IslamicEvent[];

Example:

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

function isRamadan(date?: Date): boolean;

Example:

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.

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

Example:

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.

function getArabicMonthName(month: number): string;

Example:

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.

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

Example:

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:

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

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

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:

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

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

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

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