pray-calc

A high-precision prayer times calculator using NREL-SPA (Solar Position Algorithm) and a dynamic Fajr and Isha angle algorithm, refined with empirical data and machine learning. Also supports traditional static-angle methods for comparison.

Live Demo: PrayCalc.com
Documentation & Wiki: PrayCalc.net

📌 This library is in active development and is currently in beta. Please test and submit feedback or issues, inshaa’ Allah.

---

🚀 Version 1.7 Highlights

Version 1.7 introduces major improvements:

• ✅ Fixed a bug in the core NREL-SPA JavaScript implementation that caused times to be off by up to several minutes.
• ✅ Custom dynamic angle calculation has been completely rewritten using scientific modeling, atmospheric inputs, and ML-trained empirical data. It now generates Fajr and Isha angles that are accurate across all locations and seasons, instead of a simple offset from 18°.

Traditional calculators (based on suncalc or fixed-angle approximations) are known to have timing errors of 2–7 minutes or more, especially at higher latitudes. Our implementation aims for sub-minute accuracy by default.

---

📦 Installation

npm install pray-calc

---

🛠️ Usage Example

const { getTimes, calcTimesAll } = require('pray-calc');

// Example for New York City (minimal params)
const date = new Date('2024-01-01T00:00:00Z');
const city = "New York";
const lat = 40.7128;
const lng = -74.006;
const tz = -5;

// Full example for Jakarta:
/*
const city = "Jakarta";
const lat = -6.2088;
const lng = 106.8456;
const tz = 7;
const elevation = 18;
const temperature = 26.56;
const pressure = 1017;
*/

const get = getTimes(date, lat, lng); // Minimal args
const calc = calcTimesAll(date, lat, lng, tz); // Full formatting

console.log(`\nTest: ${city} on ${date.toISOString()}:\n`);
console.log("getTimes =", get, "\n");
console.log("calcTimesAll =", calc, "\n");

---

🔧 Functions Overview

getTimes(date, lat, lng, tz?, elevation?, temperature?, pressure?, standard?)

Returns prayer times as decimal/fractional hours using dynamic twilight angles.

calcTimesAll(date, lat, lng, tz?, elevation?, temperature?, pressure?)

Returns prayer times as formatted HH:MM:SS and includes traditional methods under a .methods key.

getMoon(date, accuracy = false)

Returns:

• fraction – moon illumination (0–1)
• phase – moon phase (e.g., Full Moon)
• angle – angle from the sun (for visibility estimation)

Helpful for determining moon visibility after Maghrib.

---

🔢 Parameters

• date: JavaScript Date object
• lat: Latitude (decimal degrees)
• lng: Longitude (decimal degrees)
• tz: Timezone offset from UTC (optional, defaults to Date object)
• elevation: Meters above sea level (default: 50)
• temperature: Ambient °C (default: 15)
• pressure: mbar / hPa (default: 1013.25)
• standard: true = Shāfiʿī (Asr shadow = 1), false = Ḥanafī (shadow = 2)

---

📚 Static vs. Dynamic Methods

The All functions return both:

• The custom dynamic method (default)
• Multiple legacy methods:
  • Muslim World League (MWL)
  • Egyptian General Authority of Survey (EGAS)
  • ISNA, Umm al-Qura, Gulf, etc.

This lets developers compare traditional fixed-angle results to the more accurate dynamic calculation.

---

🤝 Contributing

Contributions, observations, and validations are welcome!

• GitHub: acamarata/pray-calc
• NREL-SPA JS Engine: acamarata/nrel-spa

---

🧪 Accuracy Notes

This package is built for high-precision use cases:

• Real-time applications (e.g., adhan clocks)
• Scientific Islamic astronomy
• High-latitude and seasonal edge-case handling

All core calculations use NREL-SPA and angles dynamically generated to match observable twilight.

---

📄 License

MIT License