Azan JavaScript

A high-precision, well-tested JavaScript library for calculating Islamic prayer times (Azan/Adhan) with support for Node.js and web browsers. Built with TypeScript and featuring comprehensive astronomical calculations from "Astronomical Algorithms" by Jean Meeus.

Features

• 🎯 High Precision Calculations - Based on astronomical algorithms recommended by the U.S. Naval Observatory
• 📱 Cross-Platform - Works in Node.js, browsers, and React Native/Expo
• 🌍 Multiple Calculation Methods - Support for 12+ calculation methods worldwide
• 🔔 Prayer Notifications - Built-in notification system with customizable reminders
• 🧭 Qibla Compass - Calculate Qibla direction with device orientation support
• 📅 Calendar Generation - Generate prayer time calendars for any date range
• 🌐 Internationalization - Multi-language support for prayer names and methods
• ⚡ Performance Optimized - Web Worker support for non-blocking calculations
• 📦 Tree-Shakeable - Optimized bundle sizes with ES modules
• 🔧 TypeScript - Full TypeScript support with comprehensive type definitions
• 🎨 Flexible API - Both simple high-level API and detailed low-level API

Installation

npm install @calgiellc/azan

Quick Start

Simple API (Recommended for Beginners)

import { AzanApp } from '@calgiellc/azan';

// Create an instance with your location
const azan = new AzanApp({
  coordinates: { latitude: 35.7897507, longitude: -78.6912485 },
  calculationMethod: 'MoonsightingCommittee',
  timezone: 'America/New_York',
});

// Get current prayer information
const prayerInfo = azan.getCurrentPrayer();
console.log('Current prayer:', prayerInfo.current);
console.log('Next prayer:', prayerInfo.next);
console.log('Time until next:', prayerInfo.timeUntilNext);

// Get all prayer times for today
const times = azan.getPrayerTimes();
console.log('Fajr:', times.fajr);
console.log('Dhuhr:', times.dhuhr);
console.log('Asr:', times.asr);
console.log('Maghrib:', times.maghrib);
console.log('Isha:', times.isha);

// Get Qibla direction
const qibla = azan.getQibla();
console.log(`Qibla direction: ${qibla.toFixed(1)}° from North`);

Advanced API (Full Control)

import {
  Coordinates,
  CalculationMethod,
  PrayerTimes,
  SunnahTimes,
  Qibla,
} from '@calgiellc/azan';

// Create coordinates
const coordinates = new Coordinates(35.7897507, -78.6912485);

// Select calculation method
const params = CalculationMethod.MoonsightingCommittee();

// Calculate prayer times for a specific date
const date = new Date(2024, 3, 20);
const prayerTimes = new PrayerTimes(coordinates, date, params);

// Access prayer times
console.log('Fajr:', prayerTimes.fajr);
console.log('Sunrise:', prayerTimes.sunrise);
console.log('Dhuhr:', prayerTimes.dhuhr);
console.log('Asr:', prayerTimes.asr);
console.log('Maghrib:', prayerTimes.maghrib);
console.log('Isha:', prayerTimes.isha);

// Get Sunnah times
const sunnahTimes = new SunnahTimes(prayerTimes);
console.log('Middle of the night:', sunnahTimes.middleOfTheNight);
console.log('Last third of the night:', sunnahTimes.lastThirdOfTheNight);

// Get Qibla direction
const qiblaDirection = Qibla(coordinates);
console.log(`Qibla: ${qiblaDirection}°`);

Core Concepts

Coordinates

Specify the location using latitude and longitude:

import { Coordinates } from '@calgiellc/azan';

// Create coordinates object
const coordinates = new Coordinates(35.7897507, -78.6912485);

// Or use object literal with AzanApp
const azan = new AzanApp({
  coordinates: { latitude: 35.7897507, longitude: -78.6912485 },
});

Calculation Methods

Choose from 12+ calculation methods:

import { CalculationMethod } from '@calgiellc/azan';

// Available methods:
CalculationMethod.MuslimWorldLeague();
CalculationMethod.Egyptian();
CalculationMethod.Karachi();
CalculationMethod.UmmAlQura();
CalculationMethod.Dubai();
CalculationMethod.MoonsightingCommittee();
CalculationMethod.NorthAmerica(); // ISNA
CalculationMethod.Kuwait();
CalculationMethod.Qatar();
CalculationMethod.Singapore();
CalculationMethod.Tehran();
CalculationMethod.Turkey();
CalculationMethod.Other(); // Custom parameters

// Or use string with AzanApp
const azan = new AzanApp({
  calculationMethod: 'MoonsightingCommittee',
});

Prayer Times

Prayer times are returned as JavaScript Date objects in UTC. Format them for your timezone:

import { PrayerTimes } from '@calgiellc/azan';
import moment from 'moment-timezone';

const prayerTimes = new PrayerTimes(coordinates, date, params);

// Format for specific timezone
const fajrFormatted = moment(prayerTimes.fajr)
  .tz('America/New_York')
  .format('h:mm A');
console.log(`Fajr: ${fajrFormatted}`);

Advanced Features

Prayer Time Notifications

Set up automatic prayer time notifications:

import { AzanApp } from '@calgiellc/azan';

const azan = new AzanApp({
  coordinates: { latitude: 35.7897507, longitude: -78.6912485 },
  reminderMinutes: 15, // Notify 15 minutes before each prayer
  autoStartNotifications: true,
});

// Custom notification handler
azan.onNotification((prayer, time) => {
  console.log(`Reminder: ${prayer} prayer in 15 minutes at ${time}`);
});

// Start/stop notifications
azan.startNotifications();
azan.stopNotifications();

Calendar Generation

Generate prayer time calendars:

import { PrayerTimesCalendar, Coordinates, CalculationMethod } from '@calgiellc/azan';

const calendar = new PrayerTimesCalendar(
  new Coordinates(35.7897507, -78.6912485),
  CalculationMethod.MoonsightingCommittee()
);

// Generate calendar for a year
const yearCalendar = calendar.generateCalendar(2024, {
  timezone: 'America/New_York',
  format: '12h', // or '24h'
});

// Export to JSON
const json = calendar.export(yearCalendar, { format: 'json' });

Batch Calculations

Calculate prayer times for multiple dates efficiently:

import { PrayerTimesBatch, Coordinates, CalculationMethod } from '@calgiellc/azan';

const batch = new PrayerTimesBatch(
  new Coordinates(35.7897507, -78.6912485),
  CalculationMethod.MoonsightingCommittee()
);

// Calculate for date range
const results = await batch.calculateBatch(
  new Date(2024, 0, 1),
  new Date(2024, 11, 31),
  {
    timezone: 'America/New_York',
    onProgress: (progress) => {
      console.log(`Progress: ${progress.percentage}%`);
    },
  }
);

Qibla Compass

Get Qibla direction with device orientation support:

import { QiblaCompass, Coordinates } from '@calgiellc/azan';

const compass = new QiblaCompass(new Coordinates(35.7897507, -78.6912485));

// Get Qibla direction
const qibla = compass.getQibla();
console.log(`Qibla: ${qibla}° from North`);

// With device orientation (browser only)
compass.startTracking((heading) => {
  const relativeDirection = compass.getRelativeDirection(heading);
  console.log(`Turn ${relativeDirection}° to face Qibla`);
});

Web Worker Support

Perform calculations in a background thread:

import { PrayerTimesWorkerAPI } from '@calgiellc/azan';

// In main thread
const worker = new PrayerTimesWorkerAPI();

// Calculate prayer times without blocking UI
const result = await worker.calculatePrayerTimes({
  coordinates: { latitude: 35.7897507, longitude: -78.6912485 },
  date: new Date(),
  method: 'MoonsightingCommittee',
  timezone: 'America/New_York',
});

console.log('Prayer times:', result);

Internationalization

Support for multiple languages:

import { I18n, setLocale, translatePrayerName } from '@calgiellc/azan';

// Set locale
setLocale('ar'); // Arabic
setLocale('en'); // English
setLocale('tr'); // Turkish
setLocale('ur'); // Urdu

// Translate prayer names
const fajr = translatePrayerName('fajr', 'ar');
console.log(fajr); // "الفجر"

// Get all translations
const translations = I18n.getTranslations('ar');

Prayer Adjustments

Apply custom adjustments to prayer times:

import { PrayerAdjustmentsManager } from '@calgiellc/azan';

const manager = new PrayerAdjustmentsManager();

// Apply adjustments
manager.applyAdjustments({
  fajr: 5, // Add 5 minutes to Fajr
  maghrib: -3, // Subtract 3 minutes from Maghrib
  isha: 10, // Add 10 minutes to Isha
});

// Get adjusted times
const adjustedTimes = manager.getAdjustedTimes(prayerTimes);

CLI Tool

The library includes a command-line interface:

# Install globally
npm install -g @calgiellc/azan

# Calculate prayer times
azan calculate -l 35.7897507 -L -78.6912485 -t America/New_York

# Generate calendar
azan calendar -l 35.7897507 -L -78.6912485 -y 2024 -o calendar.json

# Compare calculation methods
azan compare -l 35.7897507 -L -78.6912485 -m moonsighting-committee,muslim-world-league

# Interactive mode
azan calculate --interactive

Browser Usage

ESM (Recommended)

<script type="module">
  import { AzanApp } from './node_modules/@calgiellc/azan/lib/bundles/azan.esm.js';
  
  const azan = new AzanApp({
    coordinates: { latitude: 35.7897507, longitude: -78.6912485 },
  });
  
  console.log(azan.getPrayerTimes());
</script>

UMD

<script src="./node_modules/@calgiellc/azan/lib/bundles/azan.umd.min.js"></script>
<script>
  const azan = new azan.AzanApp({
    coordinates: { latitude: 35.7897507, longitude: -78.6912485 },
  });
  
  console.log(azan.getPrayerTimes());
</script>

Web Worker

<script>
  const worker = new Worker('./node_modules/@calgiellc/azan/lib/bundles/azan.worker.js');
  
  worker.postMessage({
    type: 'calculate',
    coordinates: { latitude: 35.7897507, longitude: -78.6912485 },
    date: new Date(),
  });
  
  worker.onmessage = (event) => {
    console.log('Prayer times:', event.data);
  };
</script>

TypeScript Support

Full TypeScript support with comprehensive type definitions:

import {
  Coordinates,
  CalculationMethod,
  PrayerTimes,
  Prayer,
  type PrayerTimeResult,
  type AzanAppConfig,
} from '@calgiellc/azan';

// All types are fully typed
const config: AzanAppConfig = {
  coordinates: { latitude: 35.7897507, longitude: -78.6912485 },
  calculationMethod: 'MoonsightingCommittee',
};

const azan = new AzanApp(config);
const result: PrayerTimeResult = azan.getPrayerTimes();

React Native / Expo Integration

import { AzanApp } from '@calgiellc/azan';
import * as Notifications from 'expo-notifications';

const azan = new AzanApp({
  coordinates: { latitude: 35.7897507, longitude: -78.6912485 },
  reminderMinutes: 15,
});

// Set up Expo notifications
azan.onNotification(async (prayer, time) => {
  await Notifications.scheduleNotificationAsync({
    content: {
      title: 'Prayer Reminder',
      body: `${prayer} prayer in 15 minutes`,
    },
    trigger: time,
  });
});

API Reference

Core Classes

• AzanApp - High-level API for easy prayer time calculations
• PrayerTimes - Core prayer time calculation engine
• Coordinates - Geographic coordinates wrapper
• CalculationMethod - Prayer time calculation methods
• SunnahTimes - Sunnah prayer times (Qiyam, etc.)
• Qibla - Qibla direction calculator
• QiblaCompass - Qibla compass with device orientation

Utility Classes

• PrayerTimesCalendar - Generate prayer time calendars
• PrayerTimesBatch - Batch prayer time calculations
• PrayerTimesFormatter - Format prayer times for display
• PrayerTimeNotifier - Prayer time notification system
• LocationManager - Location management utilities
• CalculationMethodComparator - Compare calculation methods
• PrayerAdjustmentsManager - Apply prayer time adjustments

Types

• Prayer - Prayer type enum (Fajr, Dhuhr, Asr, Maghrib, Isha)
• Madhab - Juristic method (Shafi, Hanafi)
• HighLatitudeRule - High latitude adjustment rules
• Rounding - Time rounding methods
• Shafaq - Shafaq type for Isha calculation

Examples

Check the examples/ directory for comprehensive usage examples:

• simple-usage.ts - Basic usage examples
• comprehensive-usage.ts - Advanced features
• expo-notification-integration.ts - React Native/Expo integration
• worker-example.html - Web Worker usage

Contributing

We welcome contributions! Please ensure that:

1. Code follows the existing style and conventions
2. All tests pass (npm test)
3. New features include appropriate tests
4. Documentation is updated
5. Commit messages follow the conventional commits format

Use npm run commit for interactive commit message generation.

License

MIT License - see LICENSE file for details.

Support

• Issues: GitHub Issues
• Email: [email protected]
• Website: Calgie LLC

Acknowledgments

• Astronomical calculations based on "Astronomical Algorithms" by Jean Meeus
• Recommended by the U.S. Naval Observatory and NOAA
• Developed and maintained by Calgie LLC

Made with ❤️ by Calgie LLC