c02f197ece
Complete rewrite from plain JavaScript to TypeScript with dual CJS/ESM output via tsup. Removes all legacy .js source files and the old CommonJS-only index. Key changes: - Full TypeScript source in src/ with strict mode and declaration maps - tsup build: dist/index.cjs + dist/index.mjs + dual .d.ts / .d.mts types - 14 traditional fixed-angle methods (UOIF through MUIS) + MSC seasonal method - PCD dynamic algorithm: MSC seasonal base + Earth-Sun distance correction + ecliptic geometry + atmospheric refraction + observer elevation - getTimesAll() batches all 14x2 zenith angles into a single SPA call - getMscFajr() / getMscIsha() expose MSC seasonal reference directly - getAngles() returns the PCD-computed fajrAngle and ishaAngle - High-latitude bounds: angles clipped to [10, 20] above 55N - 106 tests across ESM and CJS (test.mjs + test-cjs.cjs) - CI matrix: Node 20/22/24, typecheck, pack-check - Wiki: 12 reference pages + 6-page research section with global accuracy study, home-territory comparison, observational evidence, and field observation matrix - Moon functions removed (migrated to moon-sighting package) - pnpm-only, Node >=20, sideEffects: false
3.7 KiB
pray-calc Wiki
pray-calc is a TypeScript library for computing Islamic prayer times. Its primary feature is a physics-grounded dynamic twilight angle algorithm that adjusts Fajr and Isha angles for latitude, season, and atmospheric conditions. Fourteen traditional fixed-angle methods are included for comparison.
Pages
| Page | Description |
|---|---|
| API Reference | Full function signatures, parameters, return types |
| Dynamic Algorithm | How Fajr/Isha angles are computed dynamically |
| Traditional Methods | All 14 supported methods and their parameters |
| Architecture | Module structure, data flow, design decisions |
| High-Latitude Handling | MSC rules for latitudes above 55° |
| Twilight Physics | Astronomical and atmospheric background |
| Asr Calculation | Shadow-ratio math, Shafi'i vs Hanafi |
| Moon Migration | Moon functions moved to moon-sighting (v2 migration guide) |
| Changelog | Version history |
Research & Accuracy
| Page | Description |
|---|---|
| Research Overview | Study summary, headline results, PCD algorithm description |
| Methodology | Reference standard, measurement approach, test infrastructure |
| Global Accuracy Study | 18-city comparison across latitudes 6°S–51.5°N and all seasons |
| Home-Territory Study | Each method tested at its own calibration city — PCD wins 13/14 |
| Observational Evidence | Field observations, published studies, academic literature |
| Field Observation Comparison | Systematic comparison of PCD vs real-world verified Fajr measurements |
Quick Start
pnpm add pray-calc
ESM
import { calcTimes } from 'pray-calc';
const times = calcTimes(
new Date('2024-06-21'),
40.7128, // New York
-74.0060,
);
console.log(times.Fajr); // "03:51:24"
console.log(times.Sunrise); // "05:25:08"
console.log(times.Maghrib); // "20:31:17"
console.log(times.Isha); // "22:07:43"
console.log(times.angles); // { fajrAngle: 14.8, ishaAngle: 14.6 }
CJS
const { calcTimes } = require('pray-calc');
What Makes This Different
Most prayer time libraries ask you to pick a method (ISNA, MWL, etc.) and use its fixed angle for every location and every date. That works tolerably near the equator, but produces increasingly wrong results as latitude increases or seasons shift.
This library computes the depression angle that matches the observable astronomical phenomenon for the specific location and date. The Moonsighting Committee Worldwide (Khalid Shaukat) validated this approach against field observations across a wide range of latitudes. Their piecewise seasonal algorithm is the foundation; this library adds corrections for the Earth-Sun distance, ecliptic geometry, atmospheric refraction, and observer elevation.
The result is a dynamic primary method that generally agrees with MSC, MWL, and ISNA at low latitudes, diverges from fixed-angle methods at high latitudes in summer, and never produces the "Isha never ends" failure that 18°-everywhere causes above 51.5°N.
Related Packages
- nrel-spa — NREL Solar Position Algorithm (solar position foundation)
- luxon-hijri — Hijri/Gregorian calendar conversion
- moon-sighting — Crescent visibility (Yallop/Odeh criteria)