aric/pray-calc
1
0
Fork 0
mirror of https://github.com/acamarata/pray-calc.git synced 2026-06-30 19:04:26 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Update to readme and meta

Browse source
This commit is contained in:
acamarata 2025-05-14 15:12:52 -04:00
parent 01e7e3487a
commit 2f9155b567
3 changed files with 106 additions and 55 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

11
CHANGELOG.md
View file

@ -24,21 +24,24 @@ All notable changes to this project will be documented in this file.
- Renamed to "pray-calc" and removed old package
- Improved Synodic accuracy slightly and lastKnownMoon
## [1.4.1] = 2023-12-01
### [1.4.1] = 2023-12-01
- Modified getMoonVisibility to use adjusted moon phase for end of cycle
## [1.6.0] = 2025-05-04
- Major fixes for core files and calculations
- Updated to use the new "nrel-spa" v1.3.0
## [1.6.1] - 2025-05-04
### [1.6.1] - 2025-05-04
- Fixed missing modules and types definitions lost in last update
- Locked `suncalc` dependency to `^1.9.0`
- Clarified scripts: `build`, `test`, and `prepublishOnly` in `package.json`
## [1.6.2] - 2025-05-04
### [1.6.2] - 2025-05-04
- Fixed Package issues
## [1.7.0] = 2025-05-04
- Major update to main algorithm
- Fixes to syntax and bugs
- Fixes to syntax and bugs
### [1.7.1] = 2025-05-14
- Update to package meta and location

142
README.md
View file

@ -1,84 +1,132 @@
# pray-calc
Prayer times calculator using nrel-spa and custom formula for Fajr and Isha angles (as well as traditional static angle methods in the All function).
A high-precision prayer times calculator using [NREL-SPA](https://midcdmz.nrel.gov/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.
See PrayCalc.com for a fully functional implementation of this NPM Package.
**Live Demo**: [PrayCalc.com](https://praycalc.com)
**Documentation & Wiki**: [PrayCalc.net](https://praycalc.net)
See PrayCalc.net for our Wiki which goes into depth about what prayer times are, their definitions in Islam, how they are calculated, the explanation of the available legacy prayer time methods (using problematic static angles), issues with these in practice, and some detailed research into how we developed our custom formula for Fajr and Isha angles that should* work for any location or date dynamically with a single always working formula.
> 📌 This library is in active development and is currently in **beta**. Please test and submit feedback or issues, inshaa’ Allah.
* This is still in Beta and actively being developed, inshaa' Allah.
---
## Version 1.7
## 🚀 Version 1.7 Highlights
With the release of version 1.6 and 1.7 today many improvements have been implemented.
Version 1.7 introduces major improvements:
Firstly, the core nrel-spa npm package implemenation fixed a major bug that made times off by up to a few minutes. We originally dedicated to making the first JS implementation of this algorithm (NREL-SPA) because it is the golden standard and most accurate algorithm out there but we saw no open-source release (or even references to proprietary) anywhere. This leads to the assumption that none of the available prayer calculators used this and relied on ones like "suncalc" which could cause errors of up to a few minutes.
- ✅ **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°.
Secondly, we completely remade our dynamic custom angle calculation that made it many folds more accurate. The old formula was a rough approximation offsetting from the base 18° while this new algorithm completely calculates the angle based on scientific formulations refined using ML/AI on real-world data to come to something more ready for the public to review and give feedback on, inshaa' Allah.
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
---
## 📦 Installation
```bash
npm install pray-calc
```
## Usage
---
Example of using pray-calc to get prayer times:
## 🛠️ Usage Example
```js
const { getTimes, calcTimesAll } = require('./index');
const { getTimes, calcTimesAll } = require('pray-calc');
// Manually setting the date to January 1, 2024
// Example for New York City (minimal params)
const date = new Date('2024-01-01T00:00:00Z');
// NYC - minimum params
const city = "New York"
const city = "New York";
const lat = 40.7128;
const lng = -74.006;
const tz = -5
const elevation = null
const temperature = null
const pressure = null
const tz = -5;
/* Jakarta - all params
const city = "Jakarta"
const lat = -6.2088
const lng = 106.8456
const tz = 7
const elevation = 18
const temperature = 26.56
const pressure = 1017
// 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;
*/
// Get results
const get = getTimes(date, lat, lng); // minimal args
const calc = calcTimesAll(date, lat, lng, tz, elevation, temperature, pressure);
const get = getTimes(date, lat, lng); // Minimal args
const calc = calcTimesAll(date, lat, lng, tz); // Full formatting
// Print results
console.log(`\nTest: ${city} with current Date():\n`)
console.log(`\nTest: ${city} on ${date.toISOString()}:\n`);
console.log("getTimes =", get, "\n");
console.log("calcTimesAll =", calc, "\n");
```
Exported functions include getTimes, calcTimes, getTimesAll, calcTimesAll where the "get" functions return fractal or decimal times directly from the source nrel-spa calculator and the "calc" functions return formatted times in HH:MM:SS.sss format. The functions will give results including our custom angle but the "All" functions will include a methods key with all traditional static angle methods (Muslim World League, Egyptian General Authority of Survey, ISNA, etc.) included as well for their Fajr and Isha times.
---
Additionally we included the function "getMoon" which takes only the date object and an optional "accuracy=false" if you wish to avoid the Earth to Sun Distance calculation. The result back will give you fraction:, phase, and angle. This can assist in calculating the moon's illumination at specific times such as after Maghrib in a location's timezone to know the possibility of seeing the moon.
## 🔧 Functions Overview
### Parameters:
### `getTimes(date, lat, lng, tz?, elevation?, temperature?, pressure?, standard?)`
Returns prayer times as **decimal/fractional hours** using dynamic twilight angles.
- date: Javascript Date object for the date to calculate prayer times for.
- lat: Latitude of the location.
- lng: Longitude of the location.
- elevation: Elevation in meters (optional, default 50).
- temperature: Temperature in Celsius (optional, default 15).
- pressure: Atmospheric pressure in millibars (optional, default 1013.25).
### `calcTimesAll(date, lat, lng, tz?, elevation?, temperature?, pressure?)`
Returns prayer times as **formatted HH:MM:SS** and includes traditional methods under a `.methods` key.
## Contributing
### `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)
Contributions are welcome!
Helpful for determining moon visibility after Maghrib.
## License
---
MIT License
## 🔢 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](https://github.com/acamarata/pray-calc)
- NREL-SPA JS Engine: [acamarata/nrel-spa](https://github.com/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](./LICENSE)

8
package.json
View file

@ -1,6 +1,6 @@
{
"name": "pray-calc",
"version": "1.7.0",
"version": "1.7.1",
"description": "Accurate prayer times using custom algorithm for dynamic angles and nrel-spa for extreme precision",
"main": "index.js",
"types": "index.d.ts",
@ -32,12 +32,12 @@
},
"repository": {
"type": "git",
"url": "https://github.com/ummeco/pray-calc.git"
"url": "https://github.com/acamarata/pray-calc.git"
},
"bugs": {
"url": "https://github.com/ummeco/pray-calc/issues"
"url": "https://github.com/acamarata/pray-calc/issues"
},
"homepage": "https://github.com/ummeco/pray-calc#readme",
"homepage": "https://github.com/acamarata/pray-calc#readme",
"keywords": [
"prayer-times",
"islamic-prayer-times",