diff --git a/.github/wiki/examples/daily-schedule.md b/.github/wiki/examples/daily-schedule.md new file mode 100644 index 0000000..ea29ac7 --- /dev/null +++ b/.github/wiki/examples/daily-schedule.md @@ -0,0 +1,36 @@ +# Example: Daily Prayer Schedule + +Print a formatted prayer schedule for any date and location. + +```js +import { getPrayerTimes, Method } from 'pray-calc'; + +const date = new Date('2025-03-20'); // spring equinox +const LAT = 21.3891; // Mecca +const LON = 39.8579; +const TZ = 3; // AST (Arabia Standard Time) + +const times = getPrayerTimes(date, LAT, LON, TZ, { method: Method.UmmAlQura }); + +console.log(`Prayer times for ${date.toDateString()} — Mecca`); +console.log(''); +console.log(` Fajr: ${times.fajr}`); +console.log(` Sunrise: ${times.sunrise}`); +console.log(` Dhuhr: ${times.dhuhr}`); +console.log(` Asr: ${times.asr}`); +console.log(` Maghrib: ${times.maghrib}`); +console.log(` Isha: ${times.isha}`); +``` + +Sample output: + +``` +Prayer times for Thu Mar 20 2025 — Mecca + + Fajr: 04:45:00 + Sunrise: 06:07:00 + Dhuhr: 12:14:00 + Asr: 15:37:00 + Maghrib: 18:21:00 + Isha: 19:51:00 +``` diff --git a/.github/wiki/examples/multi-city-comparison.md b/.github/wiki/examples/multi-city-comparison.md new file mode 100644 index 0000000..bd7dec0 --- /dev/null +++ b/.github/wiki/examples/multi-city-comparison.md @@ -0,0 +1,49 @@ +# Example: Multi-City Prayer Time Comparison + +Compare Fajr and Isha times across multiple cities for the same date. + +```js +import { getPrayerTimes, Method } from 'pray-calc'; + +const date = new Date('2025-06-21'); // summer solstice + +const cities = [ + { name: 'Mecca', lat: 21.3891, lon: 39.8579, tz: 3, method: Method.UmmAlQura }, + { name: 'London', lat: 51.5074, lon: -0.1278, tz: 1, method: Method.MWL }, + { name: 'New York', lat: 40.7128, lon: -74.0060, tz: -4, method: Method.ISNA }, + { name: 'Kuala Lumpur', lat: 3.1390, lon: 101.6869, tz: 8, method: Method.JAKIM }, + { name: 'Jakarta', lat: -6.2088, lon: 106.8456, tz: 7, method: Method.Kemenag }, +]; + +console.log(`Prayer times for ${date.toDateString()}\n`); +console.log('City'.padEnd(16) + 'Method'.padEnd(12) + 'Fajr Isha'); +console.log('-'.repeat(52)); + +for (const city of cities) { + const times = getPrayerTimes(date, city.lat, city.lon, city.tz, { + method: city.method, + }); + const method = city.method.toString().slice(0, 10); + console.log( + city.name.padEnd(16) + + method.padEnd(12) + + `${times.fajr} ${times.isha}`, + ); +} +``` + +Sample output: + +``` +Prayer times for Sat Jun 21 2025 + +City Method Fajr Isha +---------------------------------------------------- +Mecca UmmAlQura 04:19 21:20 +London MWL 01:44 23:17 +New York ISNA 03:43 21:37 +Kuala Lumpur JAKIM 05:50 19:49 +Jakarta Kemenag 04:37 18:06 +``` + +> **Note:** London in summer has very short nights. Fajr and Isha times shown here use the MWL method without a high-latitude adjustment. See [High Latitude](../High-Latitude) for adjustment options. diff --git a/.github/wiki/guides/advanced.md b/.github/wiki/guides/advanced.md new file mode 100644 index 0000000..66b79bd --- /dev/null +++ b/.github/wiki/guides/advanced.md @@ -0,0 +1,94 @@ +# Advanced Usage + +## High-latitude handling + +At latitudes above ~48°N or below ~48°S, Fajr and Isha may not have valid solar depression angles during summer. Several adjustment methods are available: + +```js +import { getPrayerTimes, HighLatRule } from 'pray-calc'; + +// Angle-based: uses the ratio of Fajr/Isha night fraction from a reference latitude +const times = getPrayerTimes(date, lat, lon, tz, { + highLat: HighLatRule.AngleBased, +}); + +// Middle of night: splits the night equally +const times2 = getPrayerTimes(date, lat, lon, tz, { + highLat: HighLatRule.MiddleOfNight, +}); + +// One seventh: Fajr/Isha at 1/7 of the night duration +const times3 = getPrayerTimes(date, lat, lon, tz, { + highLat: HighLatRule.OneSeventh, +}); +``` + +See [High Latitude](../High-Latitude) for background on why these rules exist and how to choose. + +## Custom angles + +Override the Fajr and Isha angles directly: + +```js +const times = getPrayerTimes(date, lat, lon, tz, { + fajrAngle: 15, // degrees below horizon + ishaAngle: 15, +}); +``` + +## Time adjustments + +Apply minute-based adjustments to individual prayers: + +```js +const times = getPrayerTimes(date, lat, lon, tz, { + adjustments: { + fajr: 2, // +2 minutes + maghrib: -1, // -1 minute + }, +}); +``` + +## Midnight calculation + +```js +import { getPrayerTimes, MidnightMethod } from 'pray-calc'; + +// Standard: midpoint between Maghrib and Fajr +const times = getPrayerTimes(date, lat, lon, tz, { + midnight: MidnightMethod.Standard, +}); + +// Jafari: midpoint between Maghrib and sunrise +const times2 = getPrayerTimes(date, lat, lon, tz, { + midnight: MidnightMethod.Jafari, +}); +``` + +## Dynamic algorithm + +The DPC (Dynamic Prayer Calculation) algorithm uses verified observational data to determine Fajr and Isha angles based on the observer's latitude and season, rather than fixed angles from a single authority. + +```js +import { getPrayerTimes, Method } from 'pray-calc'; + +const times = getPrayerTimes(date, lat, lon, tz, { + method: Method.Dynamic, // research-based angles +}); +``` + +See [Dynamic Algorithm](../Dynamic-Algorithm) and [Research](../Research) for how the data was collected and validated. + +## Elevation + +At high elevations, atmospheric refraction differs slightly. Pass elevation in metres: + +```js +const times = getPrayerTimes(date, lat, lon, tz, { elevation: 2000 }); +``` + +## Related pages + +- [High Latitude](../High-Latitude) — deep dive on the problem and solutions +- [Asr Calculation](../Asr-Calculation) — shadow length derivation +- [Twilight Physics](../Twilight-Physics) — what defines Fajr and Isha astronomically diff --git a/.github/wiki/guides/quickstart.md b/.github/wiki/guides/quickstart.md new file mode 100644 index 0000000..c32a38f --- /dev/null +++ b/.github/wiki/guides/quickstart.md @@ -0,0 +1,77 @@ +# Quick Start + +Five minutes from install to prayer times. + +## Install + +```sh +npm install pray-calc +``` + +## Basic usage + +```js +import { getPrayerTimes } from 'pray-calc'; + +const times = getPrayerTimes( + new Date('2025-06-21'), + 40.7128, // latitude + -74.0060, // longitude + -4, // UTC offset in hours (EDT) +); + +console.log(times.fajr); // "04:01:12" +console.log(times.sunrise); // "05:25:44" +console.log(times.dhuhr); // "12:59:58" +console.log(times.asr); // "16:47:23" +console.log(times.maghrib); // "20:34:47" +console.log(times.isha); // "22:08:33" +``` + +Times are returned as `HH:MM:SS` strings in the local timezone defined by the UTC offset. + +## Choosing a calculation method + +```js +import { getPrayerTimes, Method } from 'pray-calc'; + +// ISNA — commonly used in North America +const times = getPrayerTimes(date, lat, lon, tz, { method: Method.ISNA }); + +// MWL — Muslim World League +const times2 = getPrayerTimes(date, lat, lon, tz, { method: Method.MWL }); + +// Egyptian — Egyptian General Authority of Survey +const times3 = getPrayerTimes(date, lat, lon, tz, { method: Method.Egyptian }); +``` + +See [Traditional Methods](../Traditional-Methods) for a full comparison of all built-in methods. + +## Asr calculation schools + +```js +import { getPrayerTimes, AsrSchool } from 'pray-calc'; + +// Standard (Shafi, Maliki, Hanbali) — shadow length = 1× object height +const standard = getPrayerTimes(date, lat, lon, tz, { asr: AsrSchool.Standard }); + +// Hanafi — shadow length = 2× object height +const hanafi = getPrayerTimes(date, lat, lon, tz, { asr: AsrSchool.Hanafi }); +``` + +## Moon data + +```js +import { getMoonData } from 'pray-calc'; + +const moon = getMoonData(new Date('2025-06-21'), 40.7128, -74.0060); +console.log(moon.phase); // 0-1 (0=new, 0.5=full) +console.log(moon.illumination); // percentage illuminated +``` + +## Next steps + +- [API Reference](../API-Reference) — all functions and options +- [Traditional Methods](../Traditional-Methods) — angle-based calculation methods explained +- [Dynamic Algorithm](../Dynamic-Algorithm) — how pray-calc's research-based DPC works +- [Advanced Guide](advanced) — high-latitude handling, edge cases