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

v2.0.0 — TypeScript rewrite, dual ESM/CJS, 14 methods + PCD dynamic algorithm

Browse source 
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
This commit is contained in:
Aric Camarata 2026-02-25 18:11:20 -05:00
parent f020a844f0
commit c02f197ece
65 changed files with 5622 additions and 3169 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

14
.editorconfig Normal file
View file

@ -0,0 +1,14 @@
root = true
[*]
charset = utf-8
end_of_line = lf
insert_final_newline = true
trim_trailing_whitespace = true
[*.{js,ts,mjs,cjs,json,yaml,yml,md}]
indent_style = space
indent_size = 2
[Makefile]
indent_style = tab

66
.github/workflows/ci.yml vendored Normal file
View file

@ -0,0 +1,66 @@
name: CI
on:
push:
branches: [main]
pull_request:
branches: [main]
jobs:
test:
name: Test (Node ${{ matrix.node-version }})
runs-on: ubuntu-latest
strategy:
matrix:
node-version: [20, 22, 24]
steps:
- uses: actions/checkout@v4
- uses: pnpm/action-setup@v4
with:
version: 10
- uses: actions/setup-node@v4
with:
node-version: ${{ matrix.node-version }}
cache: pnpm
- run: pnpm install --frozen-lockfile
- run: pnpm build
- run: node test.mjs
- run: node test-cjs.cjs
typecheck:
name: Typecheck
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: pnpm/action-setup@v4
with:
version: 10
- uses: actions/setup-node@v4
with:
node-version: 24
cache: pnpm
- run: pnpm install --frozen-lockfile
- run: pnpm run typecheck
pack-check:
name: Pack Check
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: pnpm/action-setup@v4
with:
version: 10
- uses: actions/setup-node@v4
with:
node-version: 24
cache: pnpm
- run: pnpm install --frozen-lockfile
- run: pnpm build
- name: Verify pack contents
run: |
npm pack --dry-run 2>&1 | tee pack-output.txt
grep "dist/index.cjs" pack-output.txt
grep "dist/index.mjs" pack-output.txt
grep "dist/index.d.ts" pack-output.txt
grep "dist/index.d.mts" pack-output.txt
echo "Pack check passed"

21
.github/workflows/wiki-sync.yml vendored Normal file
View file

@ -0,0 +1,21 @@
name: Sync Wiki
on:
push:
branches: [main]
paths:
- '.wiki/**'
jobs:
sync:
name: Sync .wiki/ to GitHub Wiki
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Sync wiki pages
uses: Andrew-Chen-Wang/github-wiki-action@v4
with:
path: .wiki/
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
GITHUB_ACTOR: ${{ github.actor }}

54
.gitignore vendored
View file

@ -1,4 +1,58 @@
# ─── Dependencies ───
node_modules/
.pnp
.pnp.js
# ─── Build ───
dist/
build/
out/
*.tsbuildinfo
# ─── Environment ───
.env
.env.*
!.env.example
# ─── OS ───
.DS_Store
Thumbs.db
._*
Desktop.ini
$RECYCLE.BIN/
# ─── IDE / Editor ───
.vscode/
.idea/
*.swp
*.swo
*~
*.sublime-project
*.sublime-workspace
# ─── Logs ───
*.log
npm-debug.log*
pnpm-debug.log*
yarn-debug.log*
yarn-error.log*
lerna-debug.log*
# ─── Pack ───
*.tgz
# ─── Testing / Coverage ───
coverage/
.nyc_output/
# ─── AI Agents ───
.claude/
.cursor/
.copilot/
.github/copilot/
.aider*
.codeium/
.tabnine/
.windsurf/
.cody/
.sourcegraph/

0
.npmrc Normal file
View file

1
.nvmrc Normal file
View file

@ -0,0 +1 @@
24

256
.wiki/API-Reference.md Normal file
View file

@ -0,0 +1,256 @@
# API Reference
## getTimes
Compute prayer times as fractional hours.
```typescript
function getTimes(
date: Date,
lat: number,
lng: number,
tz?: number, // default: system UTC offset
elevation?: number, // meters above sea level, default 0
temperature?: number, // °C, default 15
pressure?: number, // mbar, default 1013.25
hanafi?: boolean, // Asr convention, default false (Shafi'i)
): PrayerTimes
```
### PrayerTimes
| Field | Type | Description |
|-------|------|-------------|
| `Qiyam` | `number` | Start of the last third of the night (Qiyam al-Layl) |
| `Fajr` | `number` | True dawn (Subh Sadiq) |
| `Sunrise` | `number` | Astronomical sunrise |
| `Noon` | `number` | Solar noon (exact geometric transit) |
| `Dhuhr` | `number` | 2.5 minutes after solar noon |
| `Asr` | `number` | Asr (Shafi'i or Hanafi shadow ratio) |
| `Maghrib` | `number` | Astronomical sunset |
| `Isha` | `number` | Nightfall (end of shafaq) |
| `angles` | `TwilightAngles` | Dynamic depression angles used |
All times are fractional hours in local time (e.g., `5.5` = 05:30:00). `NaN` means
the event cannot be computed for this date/location (polar night, etc.).
---
## calcTimes
Same as `getTimes` but returns `HH:MM:SS` strings.
```typescript
function calcTimes(
date: Date,
lat: number,
lng: number,
tz?: number,
elevation?: number,
temperature?: number,
pressure?: number,
hanafi?: boolean,
): FormattedPrayerTimes
```
Returns `"N/A"` for any time that cannot be computed.
---
## getTimesAll
Compute the dynamic method times plus comparison times for all 14 traditional methods.
```typescript
function getTimesAll(
date: Date,
lat: number,
lng: number,
tz?: number,
elevation?: number,
temperature?: number,
pressure?: number,
hanafi?: boolean,
): PrayerTimesAll
```
### PrayerTimesAll
Extends `PrayerTimes` with:
| Field | Type | Description |
|-------|------|-------------|
| `Methods` | `Record<string, [number, number]>` | `[fajrTime, ishaTime]` per method ID |
Method IDs: `UOIF`, `ISNACA`, `ISNA`, `SAMR`, `IGUT`, `MWL`, `DIBT`, `Karachi`,
`Kuwait`, `UAQ`, `Qatar`, `Egypt`, `MUIS`, `MSC`.
---
## calcTimesAll
Same as `getTimesAll` but returns `HH:MM:SS` strings.
```typescript
function calcTimesAll(
date: Date,
lat: number,
lng: number,
tz?: number,
elevation?: number,
temperature?: number,
pressure?: number,
hanafi?: boolean,
): FormattedPrayerTimesAll
```
---
## getAngles
Compute dynamic Fajr/Isha depression angles without computing full prayer times.
```typescript
function getAngles(
date: Date,
lat: number,
lng: number,
elevation?: number,
temperature?: number,
pressure?: number,
): TwilightAngles
```
Returns `{ fajrAngle: number, ishaAngle: number }` in degrees (positive = below horizon).
---
## getAsr
Compute Asr time from known solar noon and solar declination.
```typescript
function getAsr(
solarNoon: number, // fractional hours (local time)
latitude: number, // decimal degrees
declination: number, // solar declination in degrees
hanafi?: boolean, // default false (Shafi'i, shadowFactor=1)
): number
```
Returns Asr as fractional hours, or `NaN` if the sun never reaches the required altitude.
Shadow factors: Shafi'i = 1 (shadow equals object height), Hanafi = 2 (shadow = 2x height).
---
## getQiyam
Compute start of the last third of the night.
```typescript
function getQiyam(
fajrTime: number, // fractional hours
ishaTime: number, // fractional hours
): number
```
Returns fractional hours. The night is divided from Isha to Fajr; Qiyam starts at the
2/3 mark: `ishaTime + (2/3) × (fajrTime + 24 − ishaTime)`.
---
## getMscFajr / getMscIsha
Compute the Moonsighting Committee Worldwide seasonal time offsets.
```typescript
function getMscFajr(date: Date, latitude: number): number
// Returns minutes before astronomical sunrise for Fajr
function getMscIsha(
date: Date,
latitude: number,
shafaq?: ShafaqMode, // 'general' | 'ahmer' | 'abyad', default 'general'
): number
// Returns minutes after astronomical sunset for Isha
```
These are the low-level functions used internally by `getAngles` and `getTimesAll`.
You rarely need to call them directly.
---
## solarEphemeris / toJulianDate
Jean Meeus solar ephemeris (Chapter 25 of *Astronomical Algorithms*, 2nd ed.).
```typescript
function toJulianDate(date: Date): number
function solarEphemeris(jd: number): {
decl: number; // solar declination, degrees
r: number; // Earth-Sun distance, AU
eclLon: number; // apparent ecliptic longitude, degrees
}
```
Accuracy: declination within ~0.01°, r within ~0.0001 AU. These are used internally
to drive the physics corrections in `getAngles`.
---
## METHODS
Exported array of all 14 `MethodDefinition` objects for documentation/tooling use.
```typescript
const METHODS: MethodDefinition[]
interface MethodDefinition {
id: string;
name: string;
region: string;
fajrAngle: number | null;
ishaAngle: number | null;
ishaMinutes?: number; // UAQ and Qatar: 90 minutes after sunset
useMSC?: boolean; // MSC seasonal method
}
```
---
## Types
```typescript
type FractionalHours = number;
type TimeString = string; // "HH:MM:SS" or "N/A"
type AsrConvention = 'shafii' | 'hanafi';
type ShafaqMode = 'general' | 'ahmer' | 'abyad';
interface TwilightAngles {
fajrAngle: number;
ishaAngle: number;
}
interface PrayerTimes { ... } // see above
interface FormattedPrayerTimes { ... } // same fields but TimeString
interface PrayerTimesAll extends PrayerTimes { Methods: ... }
interface FormattedPrayerTimesAll { ... }
interface AtmosphericParams { elevation?, temperature?, pressure?: number }
interface MethodDefinition { ... }
```
---
## Moon Functions (Removed in v2)
`getMoon`, `getMoonPhase`, `getMoonPosition`, `getMoonIllumination`, and `getMoonVisibility`
were removed in v2. They now live in the dedicated
[moon-sighting](https://github.com/acamarata/moon-sighting) package.
See [Moon Migration](Moon-Migration) for the full migration guide and function mapping.
---
*[Back to Home](Home) | [Dynamic Algorithm](Dynamic-Algorithm) | [Traditional Methods](Traditional-Methods)*

131
.wiki/Architecture.md Normal file
View file

@ -0,0 +1,131 @@
# Architecture
## Module Structure
```
src/
├── index.ts Main exports
├── types.ts All interfaces and type aliases
├── getSolarEphemeris.ts Jean Meeus solar declination, r, ecliptic lon
├── getMSC.ts MSC piecewise seasonal model
├── getAngles.ts Dynamic Fajr/Isha angle computation
├── getAsr.ts Asr from noon + declination
├── getQiyam.ts Last-third-of-night calculation
├── getTimes.ts Raw fractional-hour prayer times
├── calcTimes.ts Formatted HH:MM:SS prayer times
├── getTimesAll.ts All-methods comparison (raw)
└── calcTimesAll.ts All-methods comparison (formatted)
```
## Data Flow
```
Date + lat/lng/tz/elev/temp/pressure
│
├─► getSolarEphemeris() ──► decl, r, eclLon
│
├─► getMscFajr/Isha() ──► minutes offset
│
└─► getAngles() ──► fajrAngle, ishaAngle
│
▼
nrel-spa getSpa()
(batch zenith angles)
│
├─► spaData.angles[0].sunrise = Fajr
├─► spaData.sunrise = Sunrise
├─► spaData.solarNoon = Noon
├─► spaData.sunset = Maghrib
└─► spaData.angles[1].sunset = Isha
│
├─► getAsr(noon, lat, decl)
└─► getQiyam(fajr, isha)
```
For `getTimesAll`, the SPA call is extended to include all method zenith angles:
```
allZeniths = [
fajrZenith, // dynamic Fajr
ishaZenith, // dynamic Isha
...methodZeniths // 14 × 2 = 28 more
]
```
One SPA call, 30 zenith angles. Methods with fixed-minute Isha (UAQ, Qatar) use a
placeholder zenith for the SPA call but override the result with `sunset + minutes`.
The MSC entry uses MSC minutes offsets relative to the SPA-computed sunrise/sunset.
## External Dependency
The only runtime dependency is `nrel-spa`. It provides:
- `getSpa(date, lat, lng, tz, opts, zeniths)` — batch NREL SPA computation
- `formatTime(fractionalHours)` — converts `5.5` to `"05:30:00"`, returns `"N/A"` for NaN
The SPA (Solar Position Algorithm) from the National Renewable Energy Laboratory is
the reference algorithm for solar position. It is accurate to within ±0.0003° and
covers dates from -2000 to +6000.
## Solar Ephemeris
`getSolarEphemeris` implements Jean Meeus, *Astronomical Algorithms* (2nd ed.),
Chapter 25. This provides:
- Solar declination (δ) — accurate to ~0.01°
- Earth-Sun distance (r) in AU — accurate to ~0.0001 AU
- Apparent ecliptic longitude (λ) in degrees
These values are used by `getAngles` to apply physics corrections to the MSC base
angle. They are computed independently of the full SPA call using a faster,
lower-precision path that is sufficient for the correction magnitudes involved.
Why not use the SPA declination? The nrel-spa public API does not expose solar
declination. The SPA computes it internally, but the value is not part of the
public interface. Rather than monkey-patching nrel-spa or making a second SPA call
with a known reference point, the Meeus equations provide a clean solution at
adequate accuracy.
## Asr Computation
`getAsr` does not call the SPA. Instead, it solves the shadow-ratio equation
analytically:
```
// Shadow ratio: s = 1 (Shafi'i) or s = 2 (Hanafi)
altitude = arccot(s + tan(|latitude - declination|))
cos(hourAngle) = (sin(altitude) - sin(lat)sin(decl)) / (cos(lat)cos(decl))
asrTime = solarNoon + hourAngle (converted to hours)
```
This is faster than an SPA call and avoids a dependency on internal ephemeris state.
## Type System
All public types are in `src/types.ts` and re-exported from `src/index.ts`. The key
distinction is:
- `FractionalHours` (`number`) — raw output from `getTimes` / `getTimesAll`
- `TimeString` (`string`) — formatted output from `calcTimes` / `calcTimesAll`
`PrayerTimesAll` extends `PrayerTimes` rather than duplicating fields. The `Methods`
map uses string keys (method IDs) rather than a union type, to allow forward
compatibility without breaking changes when methods are added.
## Build
`tsup` builds dual CJS/ESM output:
```
dist/
├── index.cjs CJS bundle
├── index.mjs ESM bundle
├── index.d.ts CJS type declarations
└── index.d.mts ESM type declarations
```
Source maps are included. `sideEffects: false` allows tree-shaking.
---
*[Back to Home](Home) | [API Reference](API-Reference) | [Dynamic Algorithm](Dynamic-Algorithm)*

83
.wiki/Asr-Calculation.md Normal file
View file

@ -0,0 +1,83 @@
# Asr Calculation
## The Rule
Asr is the afternoon prayer. Its start time is defined by shadow length, not by
a solar depression angle.
The standard definition: Asr begins when an object's shadow equals its height
**plus** the length of its shadow at solar noon.
For the Shafi'i, Maliki, and Hanbali schools of law (the majority), the shadow
multiplier is **1**. For the Hanafi school, the multiplier is **2**.
In practice, the difference is typically 30–60 minutes, with Hanafi Asr being later.
## The Math
Let:
- φ = observer latitude in radians
- δ = solar declination in radians at local noon
- s = shadow factor (1 for Shafi'i, 2 for Hanafi)
The Sun's altitude when the shadow multiplier condition is met:
```
A = arccot(s + tan(|φ - δ|))
= arctan(1 / (s + tan(|φ - δ|)))
```
This altitude corresponds to a specific hour angle H:
```
cos(H) = (sin(A) - sin(φ)sin(δ)) / (cos(φ)cos(δ))
```
Asr time in local fractional hours:
```
asrTime = solarNoon + H / 15 (H in degrees, since 15° = 1 hour)
```
If `cos(H) < -1` or `cos(H) > 1`, the Sun never reaches the required altitude,
and `getAsr` returns `NaN`. This can happen at extreme latitudes when latitude
and declination are far apart.
## Implementation
`getAsr` is a pure math function. It requires:
1. `solarNoon` — fractional hours (from the SPA output)
2. `latitude` — decimal degrees
3. `declination` — solar declination in degrees (from `solarEphemeris`)
4. `hanafi` — boolean (default `false`)
```typescript
import { getAsr } from 'pray-calc';
const asr = getAsr(
12.15, // solar noon at ~12:09 local time
40.7128, // New York latitude
23.44, // solar declination at summer solstice
false, // Shafi'i
);
```
## Why Not Use the SPA for Asr?
Some prayer time libraries solve for Asr by running the SPA with the altitude A
as the zenith input. This requires an extra SPA call or a second zenith slot in
the batch call.
pray-calc computes Asr analytically using the Meeus declination (`solarEphemeris`)
rather than the SPA's internal declination. This avoids a second SPA call, removes
any dependency on internal SPA state, and is accurate to well within a minute
for any realistic use case.
The SPA uses a more rigorous ephemeris for declination (accurate to ~0.0003°
vs. Meeus at ~0.01°). For Asr, the difference in δ of 0.01° translates to less
than 5 seconds of timing error — completely negligible.
---
*[Back to Home](Home) | [API Reference](API-Reference) | [Architecture](Architecture)*

22
.wiki/Changelog.md Normal file
View file

@ -0,0 +1,22 @@
# Changelog
See [CHANGELOG.md](https://github.com/acamarata/pray-calc/blob/main/CHANGELOG.md)
in the repository for the full version history.
## v2.0.0 Highlights
- Full TypeScript rewrite (dual CJS/ESM build)
- Physics-grounded dynamic angle algorithm (MSC base + r correction + Fourier + refraction + elevation)
- 14 traditional methods (added IGUT/Tehran, Kuwait, Qatar)
- Removed suncalc dependency; removed moon functionality (moved to moon-sighting)
- `getAsr` refactored to pure math using Meeus declination
- `formatTime` replaces `fractalTime` (nrel-spa v2 API)
- Node >= 20 requirement; proper exports field; publishConfig
## v1.7.x (Legacy)
CommonJS, JavaScript source, 10 traditional methods, suncalc for moon data.
---
*[Back to Home](Home)*

151
.wiki/Dynamic-Algorithm.md Normal file
View file

@ -0,0 +1,151 @@
# Dynamic Twilight Angle Algorithm
The core differentiator of pray-calc is that it does not use a fixed depression angle
for Fajr and Isha. Instead, it computes the angle that matches the observable
astronomical phenomenon for the specific location and date.
## Why Fixed Angles Fail
A depression angle is the number of degrees the Sun sits below the horizon. Traditional
methods hard-code a value: ISNA uses 15°, MWL uses 18°, MUIS uses 20°.
This works reasonably well near the equator. At 0° latitude, the Sun's path is nearly
vertical at the horizon, so it passes through any given depression quickly. Twilight is
short, and the sky becomes astronomically dark (18°) close to when it visually darkens
for a human observer.
At higher latitudes, the Sun's path is oblique. It skims below the horizon rather than
diving through it. Two consequences follow:
1. **Twilight is extended.** The sky stays illuminated at a given depression longer
than at the equator.
2. **The Sun may never reach the required angle.** Above 48.5°N in summer, the Sun
never reaches 18° depression. Above 51.5°N, it never reaches 15°. A fixed-angle
method produces no Isha in London for weeks in summer.
Even at mid-latitudes, observational campaigns show that true Fajr (the visible
"white thread" of dawn) appears when the Sun is around 14–16° below the horizon, not
18°. Using 18° makes Fajr 20–30 minutes too early in many regions.
## Three-Layer Model
The `getAngles` function computes a depression angle in three layers.
### Layer 1: MSC Seasonal Base
The Moonsighting Committee Worldwide (Khalid Shaukat) derived a piecewise-linear
empirical model by fitting to field observations across a wide range of latitudes.
The model returns the expected time offset in minutes:
- Fajr: minutes before astronomical sunrise
- Isha: minutes after astronomical sunset
The model uses four seasonal anchor points per latitude (winter solstice, spring
equinox, summer shoulder, summer solstice) and interpolates between them. The
offsets grow with latitude and peak near the summer solstice, reflecting the
astronomical reality of extended twilight.
pray-calc converts those minute offsets to depression angles using spherical
trigonometry:
```
cos(H) = (sin(a) - sin(φ)sin(δ)) / (cos(φ)cos(δ))
depression = -a (where a is the altitude solution)
```
Where `H` is the hour angle derived from the minute offset, `φ` is latitude,
`δ` is solar declination.
### Layer 2: Physics Corrections
Three corrections are added to the MSC base angle:
**Earth-Sun distance correction (Δr)**
The Earth's orbit is elliptical. At perihelion (January 3), r ≈ 0.983 AU; at
aphelion (July 4), r ≈ 1.017 AU. When the Earth is closer to the Sun, sunlight
is more intense, and the scattering that produces twilight glow begins at a slightly
deeper depression. Conversely, at aphelion, the sky stays darker a bit longer.
```
Δr = -0.5 × ln(r) (degrees)
```
This correction is ±0.015° over the year — small, but included for completeness.
**Fourier harmonic correction (Δf)**
A double-harmonic model captures the annual and semi-annual variation in observed
twilight angle that is not fully explained by MSC's piecewise model. It uses the
ecliptic longitude (θ, degrees) and absolute latitude (|φ|):
```
Δf = 0.1 × (|φ|/45) × sin(θ × π/180)
+ 0.05 × (|φ|/45) × sin(2θ × π/180)
```
This adds up to ±0.15° at 45°N and proportionally less near the equator.
**Atmospheric refraction**
Near the horizon, refraction bends light rays by about 34 arcminutes. At twilight
angles (Sun 14–18° below horizon), refraction is small — a few arcminutes — but
is still computed via the Bennett/Saemundsson formula for completeness. The current
atmospheric conditions (pressure, temperature) are used.
**Elevation dip**
An observer at elevation `h` meters above sea level sees a horizon that is `d`
degrees below the geometric horizon:
```
d ≈ 1.06 × sqrt(h / 1000) (degrees)
```
At 1000 m, this is 1.06° — the effective depression for a given visual phenomenon
is reduced by this amount. The correction is:
```
Δe = -0.3 × 1.06 × sqrt(h / 1000)
```
The factor 0.3 reflects that twilight depression is only partially affected by
horizon dip (the illumination geometry is dominated by the upper atmosphere, not
the local horizon).
### Layer 3: Physical Bounds
The final angle is clipped to [10°, 22°]. Below 10° the sun is high enough that
no prayer timing convention places a twilight boundary there; above 22° is outside
the range of any empirical observation of dawn or dusk.
## Validation
The dynamic method should stay within the range defined by the full set of
traditional methods for any given location and date. At equatorial latitudes
it converges to approximately 18°, matching MWL and Karachi. At 50–55°N in
summer it typically produces 12–14°, matching the empirical UK observations
that prompted adjustments from 18° to lower values. At 30–40°N it falls in
the 15–17° range, consistent with the Egyptian and Saudi observational studies.
The `calcTimesAll` function returns comparison times for all 14 traditional
methods alongside the dynamic method, enabling direct comparison.
## High-Latitude Fallback
When the MSC minutes function would produce an angle outside [10°, 22°] or
when the Sun never reaches the computed angle, the bounds clamp the result.
For extreme latitudes (beyond approximately 57°N/S) in summer, the MSC model
itself uses a "seventh-of-night" rule as a juristic fallback, which is respected
here.
## Code Location
The implementation is in [src/getAngles.ts](../src/getAngles.ts). The MSC
piecewise model is in [src/getMSC.ts](../src/getMSC.ts). The solar ephemeris
(declination, r, ecliptic longitude) is in
[src/getSolarEphemeris.ts](../src/getSolarEphemeris.ts).
---
*[Back to Home](Home) | [Traditional Methods](Traditional-Methods) | [Twilight Physics](Twilight-Physics)*

87
.wiki/High-Latitude.md Normal file
View file

@ -0,0 +1,87 @@
# High-Latitude Handling
## The Problem
At latitudes above approximately 48.5°N/S, the Sun never reaches 18° below the
horizon during summer months. Above 51.5°N/S, it never reaches 15° below the
horizon. During these periods, a fixed-angle method produces no Isha — or computes
a sunrise before Fajr, or other nonsensical results.
Even at latitudes where the Sun does reach 18°, the resulting times can be extreme.
At 52°N in summer, a 15° Isha occurs around 2–3 AM, making a 4 AM Fajr effectively
continuous with Isha. Islamic jurisprudence recognizes this as hardship (*haraj*)
and provides accommodations.
## The MSC Approach
The Moonsighting Committee Worldwide algorithm handles this by design. Because it
works in minutes rather than angles, it naturally produces reasonable times even
when fixed angles would fail:
- The minute offsets grow with latitude but are bounded by the seasonal interpolation
- At very high latitudes, the model applies a "Sab'u lail" (seventh-of-night) rule:
divide the night into 7 parts; Isha starts at the end of the first seventh, Fajr
ends at the start of the last seventh
This produces the longest practical Isha-Fajr interval allowed by the model, which
corresponds roughly to the juristic principle of not making the night shorter than
1/7 of the 24-hour period.
## When This Applies
The MSC model is used as the base for the dynamic method. The model transitions to
the seventh-of-night rule at approximately latitude 57°N/S (varies slightly by season
and longitude). pray-calc inherits this behavior automatically.
For the MSC entry in `getTimesAll`, the same model is used directly.
## Fixed-Angle Methods at High Latitudes
The 13 other methods in `getTimesAll` use fixed depression angles. For dates and
locations where the Sun never reaches the specified angle, the NREL SPA returns
`NaN` for that rise/set event. pray-calc propagates `NaN` unchanged; `calcTimesAll`
renders it as `"N/A"`.
This is intentional. The Methods map in `getTimesAll` shows you exactly which methods
are applicable for a given location and date. If ISNA returns `N/A` for Isha in
London in June, that is the correct answer for that method — it simply doesn't work
there.
## Juristic Solutions
Islamic scholars have proposed several approaches for high-latitude regions:
### Nearest Latitude (Aqrab al-Bilad)
Use the prayer times of the nearest city where the Sun does reach the required
angle, scaled to local midnight.
### Nearest Day (Aqrab al-Ayyam)
Use the prayer times from the nearest date in the year when the Sun does reach
the required angle at the same location.
### Seventh of Night (Sab'u lail)
Divide the 24-hour period (from midnight to midnight, or from Maghrib to Fajr)
into 7 equal parts. Isha begins at the end of the first seventh; Fajr begins at
the start of the last seventh.
### Specific Latitude Cutoff
Many North American institutions use the rule: above 48.5°N, compute times as
if the latitude were 48.5°N. This is simple and avoids discontinuities.
### Makkah Time
A minority position: use Makkah's times globally. Not widely adopted outside
of specific communities.
## What pray-calc Does
The dynamic method (`getTimes`, `calcTimes`) uses the MSC model as its base.
The MSC model handles high latitudes with the seventh-of-night fallback. This
means `getTimes` always returns a finite time for all latitudes.
The Methods map in `getTimesAll` returns `NaN` for any fixed-angle method that
fails for a given location/date. This allows the caller to detect which methods
are inapplicable and apply their own high-latitude policy.
---
*[Back to Home](Home) | [Twilight Physics](Twilight-Physics) | [Dynamic Algorithm](Dynamic-Algorithm)*

88
.wiki/Home.md Normal file
View file

@ -0,0 +1,88 @@
# 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](API-Reference) | Full function signatures, parameters, return types |
| [Dynamic Algorithm](Dynamic-Algorithm) | How Fajr/Isha angles are computed dynamically |
| [Traditional Methods](Traditional-Methods) | All 14 supported methods and their parameters |
| [Architecture](Architecture) | Module structure, data flow, design decisions |
| [High-Latitude Handling](High-Latitude) | MSC rules for latitudes above 55° |
| [Twilight Physics](Twilight-Physics) | Astronomical and atmospheric background |
| [Asr Calculation](Asr-Calculation) | Shadow-ratio math, Shafi'i vs Hanafi |
| [Moon Migration](Moon-Migration) | Moon functions moved to moon-sighting (v2 migration guide) |
| [Changelog](Changelog) | Version history |
## Research & Accuracy
| Page | Description |
| --- | --- |
| [Research Overview](Research) | Study summary, headline results, PCD algorithm description |
| [Methodology](Research-Methodology) | Reference standard, measurement approach, test infrastructure |
| [Global Accuracy Study](Research-Global-Study) | 18-city comparison across latitudes 6°S–51.5°N and all seasons |
| [Home-Territory Study](Research-Home-Territory) | Each method tested at its own calibration city — PCD wins 13/14 |
| [Observational Evidence](Research-Observational-Evidence) | Field observations, published studies, academic literature |
| [Field Observation Comparison](Research-Verified-Observations) | Systematic comparison of PCD vs real-world verified Fajr measurements |
## Quick Start
```bash
pnpm add pray-calc
```
### ESM
```typescript
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
```javascript
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](https://github.com/acamarata/nrel-spa) — NREL Solar Position Algorithm (solar position foundation)
- [luxon-hijri](https://github.com/acamarata/luxon-hijri) — Hijri/Gregorian calendar conversion
- [moon-sighting](https://github.com/acamarata/moon-sighting) — Crescent visibility (Yallop/Odeh criteria)
---
*[Back to Repository](https://github.com/acamarata/pray-calc)*

79
.wiki/Moon-Migration.md Normal file
View file

@ -0,0 +1,79 @@
# Moon Function Migration
In pray-calc v1, the package included five functions for moon data:
| v1 Function | Description |
| -- | -- |
| `getMoon(date, lat, lon)` | Aggregated wrapper returning phase, position, illumination, visibility |
| `getMoonPhase(date)` | Synodic-month calculation from known reference new moon |
| `getMoonPosition(date, lat, lon)` | Thin wrapper around `suncalc.getMoonPosition` |
| `getMoonIllumination(date)` | Thin wrapper around `suncalc.getMoonIllumination` |
| `getMoonVisibility(date, lat, lon)` | Stub function — explicitly not accurate |
All five have been removed from pray-calc v2. They live in the dedicated
[moon-sighting](https://github.com/acamarata/moon-sighting) package, which is the
right place for this work.
## Why They Moved
These functions did not belong in a prayer-times package. They were thin wrappers
around `suncalc` — a third-party library that uses simplified spherical astronomy,
not a full topocentric pipeline. The visibility function was explicitly documented
as a placeholder. Bundling them in pray-calc added a dependency (suncalc) for
functionality that was, at best, approximate.
moon-sighting does the same job properly:
- No suncalc dependency. Positions use the Meeus Ch. 47/48 low-precision lunar
ephemeris with full topocentric correction (parallax, WGS84 geodetic model).
- Bennett atmospheric refraction applied to apparent altitude.
- Illumination uses the correct Meeus phase angle formula, not a simplified fraction.
- Visibility uses the Odeh (2006) V-parameter model — a genuine criterion from
published research, not a placeholder window function.
The two packages complement each other. pray-calc handles solar-based prayer times.
moon-sighting handles lunar crescent data. Together they cover the Islamic astronomical
computing stack.
## Migration
Install moon-sighting:
```bash
pnpm add moon-sighting # or npm install moon-sighting
```
Update your imports:
```typescript
// Before (pray-calc v1)
import { getMoon, getMoonPhase, getMoonPosition, getMoonIllumination } from 'pray-calc';
// After (moon-sighting v1.1+)
import { getMoon, getMoonPhase, getMoonPosition, getMoonIllumination } from 'moon-sighting';
```
### Function Mapping
| pray-calc v1 | moon-sighting v1.1 | Notes |
| -- | -- | -- |
| `getMoonPosition(date, lat, lon)` | `getMoonPosition(date, lat, lon, elevation?)` | Adds WGS84 model, Bennett refraction, `parallacticAngle` field |
| `getMoonIllumination(date)` | `getMoonIllumination(date)` | Adds correct phase angle, `isWaxing` field |
| `getMoonPhase(date)` | `getMoonPhase(date)` | Adds `phaseName`, `phaseSymbol`, more fields |
| `getMoonVisibility(date, lat, lon)` | `getMoonVisibilityEstimate(date, lat, lon, elevation?)` | Real Odeh V-parameter, returns zone A–D, ARCL, ARCV, W |
| `getMoon(date, lat, lon)` | `getMoon(date, lat, lon, elevation?)` | Same concept, properly computed |
Return shapes are additive — all fields that existed in v1 still exist in v1.1.
New fields are added but nothing is removed. The function for visibility is renamed
(`getMoonVisibility` to `getMoonVisibilityEstimate`) to be explicit about what it
returns.
## Links
- npm: [https://www.npmjs.com/package/moon-sighting](https://www.npmjs.com/package/moon-sighting)
- GitHub: [https://github.com/acamarata/moon-sighting](https://github.com/acamarata/moon-sighting)
- Wiki: [https://github.com/acamarata/moon-sighting/wiki](https://github.com/acamarata/moon-sighting/wiki)
---
*[Back to Home](Home) | [API Reference](API-Reference) | [Changelog](Changelog)*

175
.wiki/Research-Global-Study.md Normal file
View file

@ -0,0 +1,175 @@
# Global Accuracy Study
**Study date:** February 2025
**pray-calc version:** 2.0.0
**Reference:** MSC (Moonsighting Committee Worldwide) observation-calibrated model
**Test cases:** 18 city/date combinations
**Latitude range:** 6.2°S (Jakarta) to 51.5°N (London)
See [Methodology](Research-Methodology) for the scoring approach, reference standard, and test infrastructure.
---
## Summary Table
Error is `method_time − MSC_reference` in minutes. Positive = later than MSC, negative = earlier.
`N/A` = sun never reaches the required depression angle (method is undefined for that case).
| # | City | Date | Lat | Elev | Sunrise | Maghrib | PCD Fajr° | PCD Isha° | MSC Fajr ref | MSC Isha ref |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| 1 | New York, USA | Jun 21 | 40.71°N | 10m | 05:25 | 20:30 | 16.21° | 12.41° | 03:35 (110 min) | 21:49 (79 min) |
| 2 | New York, USA | Dec 21 | 40.71°N | 10m | 07:16 | 16:32 | 17.48° | 17.12° | 05:40 (96 min) | 18:06 (94 min) |
| 3 | New York, USA | Mar 21 | 40.71°N | 10m | 06:56 | 19:09 | 17.48° | 15.28° | 05:27 (89 min) | 20:26 (77 min) |
| 4 | Toronto, Canada | Jun 21 | 43.65°N | 76m | 05:36 | 21:02 | 15.33° | 11.71° | 03:43 (113 min) | 22:22 (80 min) |
| 5 | London, UK | Jun 21 | 51.51°N | 11m | 04:43 | 21:21 | 11.88° | 10.00° | 02:43 (120 min) | 22:41 (80 min) |
| 6 | London, UK | Dec 21 | 51.51°N | 11m | 08:03 | 15:53 | 14.69° | 14.24° | 06:21 (102 min) | 17:32 (99 min) |
| 7 | Istanbul, Turkey | Jun 21 | 41.01°N | 114m | 05:32 | 20:39 | 16.28° | 12.40° | 03:41 (111 min) | 21:58 (79 min) |
| 8 | Makkah, S. Arabia | Jun 21 | 21.42°N | 277m | 05:39 | 19:05 | 19.79° | 16.56° | 04:05 (94 min) | 20:22 (77 min) |
| 9 | Makkah, S. Arabia | Dec 21 | 21.42°N | 277m | 06:54 | 17:43 | 19.58° | 19.36° | 05:28 (86 min) | 19:08 (85 min) |
| 10 | Tehran, Iran | Jun 21 | 35.69°N | 1191m | 04:48 | 19:23 | 17.95° | 14.09° | 03:02 (106 min) | 20:42 (79 min) |
| 11 | Cairo, Egypt | Jun 21 | 30.06°N | 23m | 04:54 | 18:59 | 18.73° | 14.97° | 03:13 (101 min) | 20:17 (78 min) |
| 12 | Cairo, Egypt | Dec 21 | 30.06°N | 23m | 06:46 | 16:59 | 19.13° | 18.72° | 05:15 (91 min) | 18:28 (89 min) |
| 13 | Karachi, Pakistan | Jun 21 | 24.86°N | 8m | 05:43 | 19:24 | 19.43° | 16.01° | 04:06 (97 min) | 20:42 (78 min) |
| 14 | Dhaka, Bangladesh | Jun 21 | 23.81°N | 4m | 05:12 | 18:48 | 19.49° | 16.19° | 03:36 (96 min) | 20:06 (78 min) |
| 15 | Jakarta, Indonesia | Jun 21 | 6.21°S | 8m | 06:01 | 17:47 | 18.72° | 18.72° | 04:43 (78 min) | 19:05 (78 min) |
| 16 | Singapore | Dec 21 | 1.35°N | 15m | 07:01 | 19:04 | 18.23° | 18.23° | 05:45 (76 min) | 20:20 (76 min) |
| 17 | Almaty, Kazakhstan | Jun 21 | 43.22°N | 848m | 04:12 | 19:36 | 15.73° | 12.05° | 02:19 (113 min) | 20:56 (80 min) |
| 18 | Riyadh, S. Arabia | Mar 21 | 24.69°N | 620m | 05:55 | 18:04 | 20.04° | 18.25° | 04:31 (84 min) | 19:20 (76 min) |
---
## Accuracy Rankings
**Mean Absolute Error vs MSC reference, sorted by combined MAE.**
`n_Fajr` / `n_Isha` = number of valid (non-NaN) results included in MAE calculation.
| Rank | Method | Fajr MAE (min) | Isha MAE (min) | Combined MAE | n_Fajr | n_Isha |
| --- | --- | --- | --- | --- | --- | --- |
| 1 | MSC | 0.00 | 0.00 | 0.00 | 18 | 18 |
| **2** | **★ PCD (Dynamic)** | **0.64** | **1.30** | **0.97** | **18** | **18** |
| 3 | Qatar | 10.21 | 10.22 | 10.21 | 17 | 18 |
| 4 | UAQ | 11.08 | 10.22 | 10.65 | 17 | 18 |
| 5 | MWL | 10.21 | 17.09 | 13.65 | 17 | 17 |
| 6 | DIBT | 10.21 | 17.09 | 13.65 | 17 | 17 |
| 7 | IGUT | 9.81 | 17.98 | 13.90 | 17 | 18 |
| 8 | Kuwait | 10.21 | 18.92 | 14.56 | 17 | 17 |
| 9 | Karachi | 10.21 | 20.89 | 15.55 | 17 | 17 |
| 10 | SAMR | 11.54 | 19.94 | 15.74 | 17 | 18 |
| 11 | Egypt | 14.49 | 18.92 | 16.71 | 17 | 17 |
| 12 | MUIS | 17.79 | 20.89 | 19.34 | 17 | 17 |
| 13 | ISNA | 19.44 | 19.94 | 19.69 | 18 | 18 |
| 14 | ISNACA | 26.96 | 18.45 | 22.71 | 18 | 18 |
| 15 | UOIF | 31.59 | 20.00 | 25.80 | 18 | 18 |
**Notes on n values:** Methods with `n_Fajr = 17` or `n_Isha = 17` had one NaN result (typically London summer). Methods returning NaN for that case are not penalized in MAE — the actual failure rate is noted in the High-Latitude section below.
---
## Per-Case Detail: Fajr Errors by Method
Error in minutes vs MSC reference (`+` = later, `−` = earlier). `N/A` = sun does not reach required depression.
| City / Date | PCD | UOIF | ISNACA | ISNA | SAMR | IGUT | MWL | DIBT | Karachi | Kuwait | UAQ | Qatar | Egypt | MUIS |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| NY Jun | **−0.2** | +34.0 | +26.3 | +10.2 | +1.7 | −13.6 | −16.4 | −16.4 | −16.4 | −16.4 | −21.2 | −16.4 | −31.3 | −36.6 |
| NY Dec | **+0.1** | +30.6 | +25.0 | +13.8 | +8.3 | −1.1 | −2.7 | −2.7 | −2.7 | −2.7 | −5.5 | −2.7 | −10.9 | −13.7 |
| NY Mar | **+0.2** | +30.0 | +24.6 | +13.8 | +8.3 | −1.0 | −2.7 | −2.7 | −2.7 | −2.7 | −5.4 | −2.7 | −11.0 | −13.7 |
| Toronto Jun | **−0.8** | +29.9 | +21.1 | +2.5 | −7.6 | −26.2 | −29.8 | −29.8 | −29.8 | −29.8 | −36.0 | −29.8 | −49.3 | −56.7 |
| London Jun | **−0.4** | −2.4 | −20.3 | −87.8 | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A |
| London Dec | **+0.1** | +18.6 | +11.6 | −2.1 | −8.8 | −20.2 | −22.2 | −22.2 | −22.2 | −22.2 | −25.6 | −22.2 | −32.2 | −35.5 |
| Istanbul Jun | **−0.9** | +34.4 | +26.6 | +10.2 | +1.6 | −13.9 | −16.8 | −16.8 | −16.8 | −16.8 | −21.7 | −16.8 | −32.0 | −37.4 |
| Makkah Jun | **−0.8** | +39.5 | +34.4 | +24.3 | +19.1 | +10.2 | +8.7 | +8.7 | +8.7 | +8.7 | +6.0 | +8.7 | +0.7 | −2.0 |
| Makkah Dec | **−0.5** | +34.1 | +29.5 | +20.3 | +15.8 | +8.0 | +6.7 | +6.7 | +6.7 | +6.7 | +4.4 | +6.7 | −0.1 | −2.4 |
| Tehran Jun | **−2.5** | +38.6 | +32.1 | +18.6 | +11.6 | −0.7 | −2.9 | −2.9 | −2.9 | −2.9 | −6.6 | −2.9 | −14.3 | −18.2 |
| Cairo Jun | **−0.2** | +40.1 | +34.4 | +22.6 | +16.6 | +6.2 | +4.3 | +4.3 | +4.3 | +4.3 | +1.2 | +4.3 | −5.1 | −8.4 |
| Cairo Dec | **0.0** | +34.8 | +29.9 | +20.1 | +15.2 | +7.0 | +5.5 | +5.5 | +5.5 | +5.5 | +3.1 | +5.5 | −1.7 | −4.1 |
| Karachi Jun | **−0.1** | +40.4 | +35.1 | +24.4 | +19.0 | +9.6 | +7.9 | +7.9 | +7.9 | +7.9 | +5.1 | +7.9 | −0.5 | −3.3 |
| Dhaka Jun | **−0.3** | +39.8 | +34.6 | +24.1 | +18.8 | +9.6 | +7.9 | +7.9 | +7.9 | +7.9 | +5.2 | +7.9 | −0.3 | −3.1 |
| Jakarta Jun | **−0.3** | +29.0 | +24.7 | +15.9 | +11.6 | +4.2 | +2.9 | +2.9 | +2.9 | +2.9 | +0.7 | +2.9 | −3.7 | −5.9 |
| Singapore Dec | **−0.4** | +26.9 | +22.5 | +13.8 | +9.4 | +2.0 | +0.7 | +0.7 | +0.7 | +0.7 | −1.5 | +0.7 | −5.9 | −8.1 |
| Almaty Jun | **−3.0** | +30.8 | +22.2 | +4.0 | −5.7 | −23.7 | −27.2 | −27.2 | −27.2 | −27.2 | −33.1 | −27.2 | −45.7 | −52.6 |
| Riyadh Mar | **−0.9** | +34.8 | +30.4 | +21.5 | +17.1 | +9.5 | +8.2 | +8.2 | +8.2 | +8.2 | +6.0 | +8.2 | +1.5 | −0.7 |
---
## Per-Case Detail: Isha Errors by Method
| City / Date | PCD | UOIF | ISNACA | ISNA | SAMR | IGUT | MWL | DIBT | Karachi | Kuwait | UAQ | Qatar | Egypt | MUIS |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| NY Jun | **+0.4** | −2.8 | +4.9 | +21.1 | +21.1 | +12.9 | +38.4 | +38.4 | +47.6 | +43.0 | +11.0 | +11.0 | +43.0 | +47.6 |
| NY Dec | **−0.1** | −28.6 | −23.0 | −11.8 | −11.8 | −17.4 | −0.8 | −0.8 | +4.7 | +2.0 | −4.0 | −4.0 | +2.0 | +4.7 |
| NY Mar | **−0.9** | −18.7 | −13.3 | −2.5 | −2.5 | −7.9 | +8.5 | +8.5 | +14.0 | +11.2 | +13.0 | +13.0 | +11.2 | +14.0 |
| Toronto Jun | **+0.8** | +3.3 | +12.1 | +30.7 | +30.7 | +21.2 | +51.5 | +51.5 | +63.0 | +57.1 | +10.0 | +10.0 | +57.1 | +63.0 |
| London Jun | **+13.3** | +42.4 | +60.4 | +127.8 | +127.8 | +83.4 | N/A | N/A | N/A | N/A | +10.0 | +10.0 | N/A | N/A |
| London Dec | **−0.1** | −15.6 | −8.6 | +5.1 | +5.1 | −1.8 | +18.6 | +18.6 | +25.2 | +21.9 | −9.0 | −9.0 | +21.9 | +25.2 |
| Istanbul Jun | **+0.7** | −2.3 | +5.4 | +21.8 | +21.8 | +13.5 | +39.4 | +39.4 | +48.8 | +44.0 | +11.0 | +11.0 | +44.0 | +48.8 |
| Makkah Jun | **+0.8** | −22.5 | −17.4 | −7.2 | −7.2 | −12.4 | +3.1 | +3.1 | +8.3 | +5.7 | +13.0 | +13.0 | +5.7 | +8.3 |
| Makkah Dec | **+0.5** | −33.1 | −28.5 | −19.3 | −19.3 | −23.9 | −10.2 | −10.2 | −5.7 | −8.0 | +5.0 | +5.0 | −8.0 | −5.7 |
| Tehran Jun | **+2.3** | −11.6 | −5.0 | +8.5 | +8.5 | +1.6 | +22.6 | +22.6 | +29.9 | +26.2 | +11.0 | +11.0 | +26.2 | +29.9 |
| Cairo Jun | **+0.2** | −17.1 | −11.4 | +0.4 | +0.4 | −5.5 | +12.5 | +12.5 | +18.7 | +15.6 | +12.0 | +12.0 | +15.6 | +18.7 |
| Cairo Dec | **0.0** | −32.8 | −27.9 | −18.1 | −18.1 | −23.0 | −8.4 | −8.4 | −3.5 | −5.9 | +1.0 | +1.0 | −5.9 | −3.5 |
| Karachi Jun | **+0.1** | −21.4 | −16.1 | −5.4 | −5.4 | −10.8 | +5.5 | +5.5 | +11.1 | +8.3 | +12.0 | +12.0 | +8.3 | +11.1 |
| Dhaka Jun | **0.0** | −22.1 | −16.9 | −6.3 | −6.3 | −11.6 | +4.4 | +4.4 | +9.8 | +7.1 | +12.0 | +12.0 | +7.1 | +9.8 |
| Jakarta Jun | **+0.1** | −29.2 | −24.9 | −16.2 | −16.2 | −20.5 | −7.4 | −7.4 | −3.1 | −5.3 | +12.0 | +12.0 | −5.3 | −3.1 |
| Singapore Dec | **−0.1** | −27.4 | −23.0 | −14.3 | −14.3 | −18.7 | −5.5 | −5.5 | −1.1 | −3.3 | +14.0 | +14.0 | −3.3 | −1.1 |
| Almaty Jun | **+2.4** | +2.0 | +10.5 | +28.7 | +28.7 | +19.4 | +48.8 | +48.8 | +59.9 | +54.3 | +10.0 | +10.0 | +54.3 | +59.9 |
| Riyadh Mar | **+0.5** | −27.2 | −22.8 | −13.9 | −13.9 | −18.4 | −5.0 | −5.0 | −0.6 | −2.8 | +14.0 | +14.0 | −2.8 | −0.6 |
---
## High-Latitude Edge Case
London, UK on June 21 (51.5°N) is the most extreme test case. As the sun approaches its highest declination, it never reaches deep depression angles.
| Method | Fixed Isha° | Isha result |
| --- | --- | --- |
| UOIF | 12° | 23:24 (valid) |
| ISNACA | 13° | 23:42 (valid) |
| ISNA | 15° | 24:49 (technically computed, next day) |
| SAMR | 15° | 24:49 (same as ISNA Isha) |
| IGUT | 14° | 24:05 (next day) |
| UAQ | +90 min | 22:51 (valid — not angle-based) |
| Qatar | +90 min | 22:51 (valid — not angle-based) |
| MSC | seasonal | 22:41 (valid — observation-based) |
| **PCD** | **10.00°** | **22:54 (valid — adapted)** |
| MWL | 17° | **N/A** |
| DIBT | 17° | **N/A** |
| Karachi | 18° | **N/A** |
| Kuwait | 17.5° | **N/A** |
| Egypt | 17.5° | **N/A** |
| MUIS | 18° | **N/A** |
Six of the 14 methods produce no Isha time at London in midsummer. PCD adapts by clamping to the 10° lower bound and produces 22:54 — 13 minutes later than MSC's 22:41 (the largest single error in the study). The error is structural: at 51.5°N in June, the sky never fully darkens, and both the observation reference and any computed method are approximations of a genuinely ambiguous twilight condition.
---
## Dynamic Angle Profile
How the PCD-computed depression angle varies across the test cases.
| City | Lat | Season | Fajr° | Isha° | Closest Fixed Method |
| --- | --- | --- | --- | --- | --- |
| Jakarta | 6.2°S | Jun | 18.72° | 18.72° | UAQ (18.5°) |
| Singapore | 1.4°N | Dec | 18.23° | 18.23° | MWL/DIBT (18°) |
| Makkah | 21.4°N | Jun | 19.79° | 16.56° | MUIS (20°) / Egypt |
| Makkah | 21.4°N | Dec | 19.58° | 19.36° | Egypt (19.5°) |
| Riyadh | 24.7°N | Mar | 20.04° | 18.25° | MUIS (20°) |
| Karachi | 24.9°N | Jun | 19.43° | 16.01° | Egypt (19.5°) |
| Dhaka | 23.8°N | Jun | 19.49° | 16.19° | Egypt (19.5°) |
| Cairo | 30.1°N | Jun | 18.73° | 14.97° | UAQ (18.5°) |
| Cairo | 30.1°N | Dec | 19.13° | 18.72° | Egypt (19.5°) |
| Tehran | 35.7°N | Jun | 17.95° | 14.09° | IGUT (17.7°/14°) |
| New York | 40.7°N | Dec | 17.48° | 17.12° | IGUT (17.7°) |
| New York | 40.7°N | Mar | 17.48° | 15.28° | IGUT (17.7°) |
| Istanbul | 41.0°N | Jun | 16.28° | 12.40° | SAMR (16°) |
| New York | 40.7°N | Jun | 16.21° | 12.41° | SAMR (16°) |
| Almaty | 43.2°N | Jun | 15.73° | 12.05° | SAMR (16°) |
| Toronto | 43.7°N | Jun | 15.33° | 11.71° | ISNA (15°) |
| London | 51.5°N | Dec | 14.69° | 14.24° | ISNA (15°) |
| London | 51.5°N | Jun | 11.88° | 10.00° | UOIF (12°) |
The angle moves from ~20° at tropical latitudes in summer to ~12° at high-latitude summer. No fixed method tracks this gradient correctly. SAMR (16°) is closest for North American and Central Asian summers. ISNA (15°) handles Toronto and London winter. IGUT (17.7°) is closest for Tehran and mid-latitude winters. But each of these methods fails in other conditions — only PCD adapts dynamically across the full range.
---
*[Research](Research) | [Methodology](Research-Methodology) | [Home-Territory Study](Research-Home-Territory) | [Observational Evidence](Research-Observational-Evidence)*

235
.wiki/Research-Home-Territory.md Normal file
View file

@ -0,0 +1,235 @@
# Home-Territory Accuracy Study
**Study date:** February 2025
**pray-calc version:** 2.0.0
**Reference:** MSC (Moonsighting Committee Worldwide) observation-calibrated model
This study tests each of the 14 traditional methods at the specific city and season for which it was designed. It is the most favorable possible test for each fixed-angle method — a method's best-case performance.
The question: does PCD (Prayer Calc Dynamic) remain more accurate than a method even when that method is tested in its own home territory?
---
## Overall Result
Across 34 Fajr + 34 Isha home-territory test cases:
| | PCD (Dynamic) | Traditional (avg) | Ratio |
| --- | --- | --- | --- |
| Fajr MAE | **0.65 min** | 7.53 min | 11.6× worse |
| Isha MAE | **0.64 min** | 9.84 min | 15.4× worse |
| Combined MAE | **0.64 min** | 8.69 min | **13.5× worse** |
**PCD wins 13 of 14 methods at their own home territory.** The only exception is MSC itself, which edges PCD by 0.5 minutes — expected, since PCD uses the MSC model as its Layer 1 base. MSC is the observation reference; PCD is the computed approximation of it.
---
## Per-Method Scorecard
Each row represents one traditional method, tested at its home city across all listed seasons.
| Method | Home City | Fixed Fajr° | PCD Avg Fajr° | Δ° (Dyn − Fixed) | PCD MAE | Method MAE | Winner | Margin |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| UOIF | Paris, France | 12.0° | 14.30° | +2.30° | 0.45 min | 19.91 min | ★ PCD | 19.5 min |
| ISNACA | Ottawa, Canada | 13.0° | 15.59° | +2.59° | 0.51 min | 18.41 min | ★ PCD | 17.9 min |
| ISNA | Chicago, USA | 15.0° | 16.94° | +1.94° | 0.73 min | 11.48 min | ★ PCD | 10.7 min |
| SAMR | Moscow, Russia | 16.0° | 11.57° | −4.43° | 0.65 min | 20.01 min | ★ PCD | 19.4 min |
| IGUT | Tehran, Iran | 17.7° | 18.52° | +0.82° | 1.67 min | 7.06 min | ★ PCD | 5.4 min |
| MWL | Makkah, S. Arabia | 18.0° | 19.86° | +1.86° | 0.56 min | 7.42 min | ★ PCD | 6.9 min |
| DIBT | Ankara, Turkey | 18.0° | 17.40° | −0.60° | 1.88 min | 12.68 min | ★ PCD | 10.8 min |
| Karachi | Karachi, Pakistan | 18.0° | 19.41° | +1.41° | 0.12 min | 7.55 min | ★ PCD | 7.4 min |
| Kuwait | Kuwait City | 18.0° | 19.02° | +1.02° | 0.23 min | 7.91 min | ★ PCD | 7.7 min |
| UAQ | Riyadh, S. Arabia | 18.5° | 19.73° | +1.23° | 0.98 min | 7.46 min | ★ PCD | 6.5 min |
| Qatar | Doha, Qatar | 18.0° | 19.33° | +1.33° | 0.12 min | 7.18 min | ★ PCD | 7.1 min |
| Egypt | Cairo, Egypt | 19.5° | 19.06° | −0.44° | 0.17 min | 5.01 min | ★ PCD | 4.8 min |
| MUIS | Singapore | 20.0° | 18.68° | −1.32° | 0.21 min | 4.24 min | ★ PCD | 4.0 min |
| MSC | New York, USA | seasonal | 17.14° | — | 0.55 min | 0.00 min | MSC | 0.5 min |
"Δ° (Dyn − Fixed)" = PCD computed angle minus the method's fixed angle, averaged across the tested seasons for that city. A positive value means the method's fixed angle is too low for its own home city; negative means it is too high.
---
## Season-by-Season Detail
### UOIF — Paris, France (12°/12°)
*Lowest angles of any major method. Designed for France's large Muslim minority seeking the least restrictive valid times.*
| Season | PCD Fajr° | MSC Fajr | PCD Fajr err | UOIF Fajr err | PCD Isha err | UOIF Isha err | Winner |
| --- | --- | --- | --- | --- | --- | --- | --- |
| Jun 21 | 13.14° | 03:50 | **−0.6 min** | +13.7 min | **+1.0 min** | +23.4 min | ★ PCD by 17.7 min |
| Dec 21 | 15.46° | 08:01 | **−0.1 min** | +22.3 min | **+0.1 min** | −20.3 min | ★ PCD by 21.2 min |
**Note:** At Paris in summer (48.9°N, June), UOIF's 12° Fajr gives a time 13.7 minutes later than MSC. The PCD angle (13.14°) is slightly higher than UOIF's 12°, correctly recognizing that even at Paris in summer, physical twilight starts slightly earlier than UOIF assumes.
### ISNACA — Ottawa, Canada (13°/13°)
*Symmetric 13° angles for Canada. Used by the Islamic Council of North America.*
| Season | PCD Fajr° | MSC Fajr | PCD Fajr err | ISNACA Fajr err | PCD Isha err | ISNACA Isha err | Winner |
| --- | --- | --- | --- | --- | --- | --- | --- |
| Jun 21 | 14.61° | 03:20 | **−0.8 min** | +15.8 min | **+0.9 min** | +18.4 min | ★ PCD by 16.3 min |
| Dec 21 | 16.56° | 07:00 | **−0.2 min** | +21.2 min | **+0.2 min** | −18.2 min | ★ PCD by 19.5 min |
**Note:** ISNACA's 13° angles are too low by 1.6–3.6° across Ottawa's seasons. In summer, ISNACA Fajr is 15.8 minutes late vs MSC; in winter, 21.2 minutes late. ISNACA consistently underestimates the twilight angle even in its intended region.
### ISNA — Chicago, USA (15°/15°)
*Revised from 18° to 15° in 2007 after observational review by the Fiqh Council of North America. The 15° standard was justified partly by the finding that 18° produces astronomically unreachable angles in summer at North American latitudes.*
| Season | PCD Fajr° | MSC Fajr | PCD Fajr err | ISNA Fajr err | PCD Isha err | ISNA Isha err | Winner |
| --- | --- | --- | --- | --- | --- | --- | --- |
| Jun 21 | 15.94° | 03:24 | **−1.1 min** | +7.3 min | **+1.2 min** | +24.9 min | ★ PCD by 15.0 min |
| Dec 21 | 17.42° | 06:38 | **−0.5 min** | +13.1 min | **+0.5 min** | −10.1 min | ★ PCD by 11.2 min |
| Mar 21 | 17.46° | 05:21 | **−0.4 min** | +13.3 min | **+0.7 min** | +0.1 min | ★ PCD by 6.1 min |
**Note:** Even ISNA's revised 15° is too low for Chicago in summer — the PCD angle of 15.94° reflects that Chicago in June needs slightly more than 15°. ISNA's 15° remains more accurate than the old 18°, but PCD is still 10.7 minutes better on average.
### SAMR — Moscow, Russia (16°/15°)
*The most dramatically failing method at its home city. Moscow in summer (55.8°N) has such short nights that the sun never reaches 16° depression — both Fajr and Isha return NaN.*
| Season | PCD Fajr° | SAMR result | PCD Fajr err | SAMR Fajr err | Winner |
| --- | --- | --- | --- | --- | --- |
| Jun 21 | 10.00° | **N/A (NaN)** | −17.0 min | N/A | ★ PCD by 961 min avg |
| Dec 21 | 13.15° | 06:51 | **−0.7 min** | −22.3 min | ★ PCD by 19.4 min |
**Note:** SAMR silently fails for its own primary city in summer. PCD's 10° clamped result is off by 17 minutes in Fajr, but this is far better than no result at all. In winter Moscow, PCD is within 0.7 minutes while SAMR is 22.3 minutes off (its 16°/15° angles, calibrated for the region's winter worship pattern, are too high for winter morning and too low to compute in summer).
### IGUT — Tehran, Iran (17.7°/14°)
*The closest fixed-angle match at its own home territory. IGUT's 17.7° Fajr is within 0.82° of PCD's average Tehran output (18.52°).*
| Season | PCD Fajr° | PCD Fajr err | IGUT Fajr err | PCD Isha err | IGUT Isha err | Winner |
| --- | --- | --- | --- | --- | --- | --- |
| Jun 21 | 17.95° | −2.5 min | **−0.7 min** | +2.3 min | **+1.6 min** | IGUT by 1.2 min |
| Dec 21 | 18.78° | **−1.5 min** | +4.0 min | **+1.5 min** | −20.2 min | ★ PCD by 10.6 min |
| Mar 21 (Nowruz) | 18.84° | **−1.5 min** | +4.3 min | **+0.9 min** | −11.5 min | ★ PCD by 6.8 min |
**Note:** IGUT wins in summer by 1.2 minutes — the only case where a fixed-angle method beats PCD at its home territory. This is because Tehran in summer happens to closely match IGUT's calibrated 17.7° Fajr angle. IGUT's 14° Isha (shafaq ahmer) is also close to PCD's summer Isha computation. However, this advantage disappears in winter and at Nowruz, where PCD is consistently better.
### MWL — Makkah, Saudi Arabia (18°/17°)
*The Muslim World League is headquartered in Makkah. 18° was historically derived from observations at equatorial and sub-tropical locations.*
| Season | PCD Fajr° | PCD Fajr err | MWL Fajr err | PCD Isha err | MWL Isha err | Winner |
| --- | --- | --- | --- | --- | --- | --- |
| Jun 21 | 19.79° | **−0.8 min** | +8.7 min | **+0.8 min** | +3.1 min | ★ PCD by 5.1 min |
| Dec 21 | 19.58° | **−0.5 min** | +6.7 min | **+0.5 min** | −10.2 min | ★ PCD by 8.0 min |
| Mar 21 | 20.22° | **−0.5 min** | +9.1 min | **+0.2 min** | −6.7 min | ★ PCD by 7.5 min |
**Note:** At Makkah, PCD consistently computes ~19.6–20.2° — higher than MWL's fixed 18°. The physics bear this out: Makkah at 21.4°N is tropical rather than equatorial, and the equatorial-calibrated 18° underestimates the actual twilight angle. PCD converges closer to the empirical MSC reference.
### DIBT — Ankara, Turkey (18°/17°)
*Same angles as MWL. Diyanet (Turkish Directorate of Religious Affairs) uses this standard nationally.*
| Season | PCD Fajr° | PCD Fajr err | DIBT Fajr err | PCD Isha err | DIBT Isha err | Winner |
| --- | --- | --- | --- | --- | --- | --- |
| Jun 21 | 16.81° | **−2.5 min** | −13.1 min | **+2.2 min** | +35.2 min | ★ PCD by 21.8 min |
| Dec 21 | 17.98° | **−1.4 min** | −1.5 min | **+1.4 min** | −1.0 min | DIBT by 0.2 min |
**Note:** In Ankara summer, DIBT's fixed 18° is too high — the sun never reaches it cleanly, producing a very early Fajr that is 13.1 minutes earlier than MSC's observation reference. PCD at 16.81° is 2.5 minutes early (still closer). In winter, DIBT and PCD are almost identical. The difference is clear: DIBT was calibrated for winter/moderate conditions; PCD adapts to both.
### Karachi — Karachi, Pakistan (18°/18°)
*Symmetric 18° angles, standard across Pakistan, Bangladesh, India, and Afghanistan.*
| Season | PCD Fajr° | PCD Fajr err | Karachi Fajr err | PCD Isha err | Karachi Isha err | Winner |
| --- | --- | --- | --- | --- | --- | --- |
| Jun 21 | 19.43° | **−0.1 min** | +7.9 min | **+0.1 min** | +11.1 min | ★ PCD by 9.4 min |
| Dec 21 | 19.39° | **+0.1 min** | +6.6 min | **−0.1 min** | −4.6 min | ★ PCD by 5.5 min |
**Note:** Karachi at 24.9°N sits in the subtropical band where PCD computes ~19.4° — higher than the fixed 18°. The Karachi method (established for a city at approximately this latitude) is 7–8 minutes off Fajr even at home. PCD tracks MSC within 0.1 minutes.
### Kuwait — Kuwait City (18°/17.5°)
| Season | PCD Fajr° | PCD Fajr err | Kuwait Fajr err | PCD Isha err | Kuwait Isha err | Winner |
| --- | --- | --- | --- | --- | --- | --- |
| Jun 21 | 18.95° | **−0.4 min** | +5.5 min | **+0.4 min** | +14.4 min | ★ PCD by 9.6 min |
| Dec 21 | 19.09° | **−0.1 min** | +5.1 min | **+0.1 min** | −6.5 min | ★ PCD by 5.8 min |
### UAQ — Riyadh, Saudi Arabia (18.5°/+90 min)
*The official Saudi government calendar used for all religious timing in the Kingdom. 18.5° Fajr is slightly higher than MWL's 18° to account for Saudi geographic and atmospheric conditions.*
| Season | PCD Fajr° | PCD Fajr err | UAQ Fajr err | PCD Isha err | UAQ Isha err | Winner |
| --- | --- | --- | --- | --- | --- | --- |
| Jun 21 | 19.51° | **−1.3 min** | +4.4 min | **+1.3 min** | +12.0 min | ★ PCD by 6.9 min |
| Dec 21 | 19.64° | **−0.9 min** | +4.4 min | **+0.9 min** | +4.0 min | ★ PCD by 3.3 min |
| Mar 21 | 20.04° | **−0.9 min** | +6.0 min | **+0.5 min** | +14.0 min | ★ PCD by 9.3 min |
**Note:** UAQ's +90 min flat offset for Isha produces a systematic +10–14 minute Isha error at Riyadh. The UAQ Isha definition (Maghrib + 90 min) is a civil convenience rule rather than an astronomical one. The actual shafaq abyad end at Riyadh is 76–86 minutes after sunset depending on season.
### Qatar — Doha, Qatar (18°/+90 min)
| Season | PCD Fajr° | PCD Fajr err | Qatar Fajr err | PCD Isha err | Qatar Isha err | Winner |
| --- | --- | --- | --- | --- | --- | --- |
| Jun 21 | 19.33° | **−0.1 min** | +7.4 min | **+0.1 min** | +12.0 min | ★ PCD by 9.6 min |
| Dec 21 | 19.33° | **+0.1 min** | +6.3 min | **−0.1 min** | +3.0 min | ★ PCD by 4.5 min |
### Egypt — Cairo, Egypt (19.5°/17.5°)
*Egypt has the highest Fajr angle (19.5°) of any major method. It was established by the Egyptian General Authority of Survey and applies across Egypt, Syria, Iraq, and Lebanon.*
| Season | PCD Fajr° | PCD Fajr err | Egypt Fajr err | PCD Isha err | Egypt Isha err | Winner |
| --- | --- | --- | --- | --- | --- | --- |
| Jun 21 | 18.73° | **−0.2 min** | −5.1 min | **+0.2 min** | +15.6 min | ★ PCD by 10.1 min |
| Dec 21 | 19.13° | **0.0 min** | −1.7 min | **0.0 min** | −5.9 min | ★ PCD by 3.8 min |
| Mar 21 | 19.33° | **0.0 min** | −0.8 min | **−0.5 min** | +0.9 min | ★ PCD by 0.6 min |
**Note:** Egypt's 19.5° Fajr is higher than PCD's computed angle for Cairo (18.73–19.33°). The fixed angle makes Fajr slightly earlier than MSC predicts. The closest result is at equinox (−0.8 min vs 0.0 min), where PCD is only 0.6 minutes better — Egypt's best case.
### MUIS — Singapore (20°/18°)
*The highest Fajr angle of any major method. MUIS was designed for Singapore's near-equatorial location (1.35°N). However, PCD computes 18.2–19.6° at Singapore — consistently lower than 20°.*
| Season | PCD Fajr° | PCD Fajr err | MUIS Fajr err | PCD Isha err | MUIS Isha err | Winner |
| --- | --- | --- | --- | --- | --- | --- |
| Jun 21 | 18.21° | **−0.3 min** | −8.3 min | **+0.1 min** | +0.2 min | ★ PCD by 4.0 min |
| Dec 21 | 18.23° | **−0.4 min** | −8.1 min | **−0.1 min** | −1.1 min | ★ PCD by 4.4 min |
| Mar 21 | 19.59° | **+0.2 min** | −1.4 min | **+0.1 min** | −6.3 min | ★ PCD by 3.7 min |
**Note:** At the equatorial city it was designed for, MUIS's 20° Fajr makes Fajr 8 minutes earlier than MSC in summer and winter. The MSC model, calibrated from actual observations, places Singapore Fajr at approximately 76 minutes before sunrise — shorter than what 20° would produce. PCD's 18.2–18.4° is the more accurate description of actual equatorial twilight.
### MSC — New York, USA (seasonal/seasonal)
*This comparison tests PCD against the MSC seasonal model at MSC's own home (the latitude for which Khalid Shaukat published and validated his tables most extensively).*
| Season | PCD Fajr err | MSC err | PCD Isha err | MSC Isha err | Winner |
| --- | --- | --- | --- | --- | --- |
| Jun 21 | −0.2 min | 0.0 min | +0.4 min | 0.0 min | MSC by 0.3 min |
| Dec 21 | +0.1 min | 0.0 min | −0.1 min | 0.0 min | MSC by 0.1 min |
| Sep 21 | −0.9 min | 0.0 min | +1.6 min | 0.0 min | MSC by 1.3 min |
**Note:** MSC wins by a fraction of a minute at its own home. This is expected and appropriate — PCD uses MSC as its base, and the physics corrections introduce small deviations at the reference latitude. The question is whether those physics corrections help elsewhere (they do — PCD is more accurate at Tehran, high-elevation cities, and polar-season locations).
---
## Calibration Analysis: How Well Do Fixed Angles Match Their Home Cities?
The "Δ°" column in the scorecard shows the gap between a method's fixed angle and what PCD (and by proxy MSC) indicates is physically appropriate at that city.
| Method | Fixed° | Actual° (PCD avg) | Δ° | Calibration quality |
| --- | --- | --- | --- | --- |
| IGUT | 17.7° | 18.52° | +0.82° | Excellent — closest fixed calibration |
| Egypt | 19.5° | 19.06° | −0.44° | Good — slightly high |
| DIBT | 18.0° | 17.40° | −0.60° | Good — slightly high for Ankara |
| MUIS | 20.0° | 18.68° | −1.32° | Fair — overcorrected high |
| Karachi | 18.0° | 19.41° | +1.41° | Fair — too low for subtropical Karachi |
| MWL | 18.0° | 19.86° | +1.86° | Fair — 18° too low for equatorial-adjacent latitudes |
| ISNA | 15.0° | 16.94° | +1.94° | Moderate — revised from 18° but still too low |
| UAQ | 18.5° | 19.73° | +1.23° | Fair — better than MWL but still low |
| Kuwait | 18.0° | 19.02° | +1.02° | Fair — similar to MWL |
| Qatar | 18.0° | 19.33° | +1.33° | Fair |
| UOIF | 12.0° | 14.30° | +2.30° | Weak — 2.3° too low even for Paris |
| ISNACA | 13.0° | 15.59° | +2.59° | Weak — too low for Canadian latitudes |
| SAMR | 16.0° | 11.57° | −4.43° | Very poor — too high to function in Moscow summer |
**IGUT is the best-calibrated fixed-angle method**: its 17.7° Fajr angle was clearly derived from observation at Tehran's latitude and elevation. The 0.82° deviation from PCD is within the margin of seasonal variation, and IGUT beats PCD in summer at Tehran by 1.2 minutes.
**SAMR has the worst calibration**: its 16°/15° angles cannot be reached by the sun at Moscow in midsummer, making it completely undefined for the city it was designed to serve.
---
*[Research](Research) | [Methodology](Research-Methodology) | [Global Study](Research-Global-Study) | [Observational Evidence](Research-Observational-Evidence)*

110
.wiki/Research-Methodology.md Normal file
View file

@ -0,0 +1,110 @@
# Research Methodology
## Reference Standard
Accuracy comparisons require a ground truth. For Islamic twilight times, no universally agreed observational dataset exists with city/date/time precision. However, one model stands above others for empirical grounding: the **Moonsighting Committee Worldwide (MSC) seasonal model**, developed by Khalid Shaukat.
Shaukat compiled his seasonal tables from direct field observations across multiple continents over several decades. The model represents minutes-before-sunrise (Fajr) and minutes-after-sunset (Isha) as piecewise functions of latitude and month. Unlike fixed-angle methods, which were derived from theoretical or historical-document reasoning, the MSC values were adjusted iteratively to match what trained observers actually saw.
Because the PCD algorithm uses the MSC model as its Layer 1 base, using MSC as the accuracy reference is a conservative test — it measures how much the physics corrections in Layers 2 and 3 deviate from the MSC base. A PCD result that closely tracks MSC demonstrates the physics corrections do not introduce noise; a PCD result that slightly improves on MSC at specific locations (high elevation, perihelion dates) would confirm the corrections add value.
### Why Not Astronomical Twilight as Reference?
Astronomical twilight (18° depression, the moment sky background is fully dark) is a defined, computable quantity. However, it does not correspond to Islamic Fajr or Isha for two reasons:
1. **Fajr (Subh Sadiq)** is the horizontal spread of light along the horizon, not full astronomical darkness. Field observations consistently place this between 12° and 18° depending on latitude and season — not at a fixed 18°.
2. **Isha (end of Shafaq Abyad)** is when the white twilight glow vanishes. This corresponds to approximately 14–18° depression, not a single value.
Using a fixed 18° as "truth" would prejudge the result in favor of fixed-18° methods and defeat the purpose of the study.
### Alternative References
For specific cities where national religious authorities publish schedules calibrated against actual observations, those schedules serve as supplementary reference. These include:
- **Saudi Arabia**: Umm Al-Qura (UAQ) calendar, published by the Saudi government and audited by the King Abdul Aziz City for Science and Technology (KACST). Fajr angle 18.5°, Isha = Maghrib + 90 min.
- **Egypt**: Egyptian General Authority of Survey schedule, calibrated at 19.5° Fajr / 17.5° Isha through observation campaigns.
- **Turkey**: Diyanet (DIBT) schedule at 18°/17°, which closely matches MWL and serves as the Turkish state standard.
- **Iran**: IGUT schedule at 17.7° Fajr / 14° Isha (shafaq ahmer), calibrated by the Institute of Geophysics, University of Tehran.
These are used as contextual cross-checks in the individual city analyses, not as the primary reference for scoring.
---
## Test Infrastructure
All computations were run using pray-calc v2.0.0, installed from a packed npm tarball:
```
npm pack → pray-calc-2.0.0.tgz
pnpm add ./pray-calc-2.0.0.tgz (temp validation directory)
node validate.mjs
node home-territory.mjs
```
Computations use:
- `getTimesAll()` for raw fractional-hour times across all 14 methods + dynamic simultaneously
- `getAngles()` for the PCD-computed depression angles
- `getMscFajr(date, lat)` / `getMscIsha(date, lat, 'general')` for the MSC minute reference
- MSC Fajr reference = `sunrise − mscMinutes / 60`
- MSC Isha reference = `sunset + mscMinutes / 60`
Elevation data was sourced from airport/city databases for each location. Timezone offsets reflect the observed clock time at each test date (accounting for DST where applicable).
---
## Scoring
**Mean Absolute Error (MAE)** in minutes is used throughout:
```
MAE = (1/N) × Σ |method_time − MSC_reference_time| × 60
```
where `method_time` and `MSC_reference_time` are in fractional hours.
Cases where a method produces NaN (sun never reaches the required depression angle) are excluded from that method's Fajr or Isha MAE calculation respectively. This means high-depression-angle methods (MWL 18°, Karachi 18°, Egypt 19.5°, MUIS 20°) are scored only on the cities/dates where they can produce a result. Their practical failure rate at high latitudes is noted separately.
**Reported MAE values are therefore conservative for fixed-angle methods**: they count only cases where the method produces a number, not the cases where it silently fails.
---
## Study 1: Global Accuracy (18 cities)
Tests across diverse latitudes, longitudes, elevations, and seasons. See [Global Accuracy Study](Research-Global-Study).
**Coverage:**
| Region | Cities | Latitude range |
| --- | --- | --- |
| North America | New York (×3), Toronto | 40.7°N – 43.7°N |
| Europe | London (×2), Istanbul | 41.0°N – 51.5°N |
| Middle East | Makkah (×2), Tehran, Kuwait City, Riyadh | 21.4°N – 35.7°N |
| Africa | Cairo (×2) | 30.1°N |
| South/Southeast Asia | Karachi, Dhaka, Jakarta, Singapore | 6.2°S – 24.9°N |
| Central Asia | Almaty | 43.2°N |
**Seasons covered:** Summer solstice, winter solstice, spring/autumn equinoxes.
---
## Study 2: Home-Territory Test (14 methods)
Each method tested at the specific city and seasons for which it was designed. This is the most favorable possible test for each fixed-angle method. See [Home-Territory Study](Research-Home-Territory).
**Rationale:** Fixed-angle methods were not designed for global use. They were calibrated for a specific region. Testing ISNA at Chicago in summer (their target calibration scenario) rather than at London in winter gives each method its best chance. If PCD outperforms a method even in its home territory, the case for PCD's superiority is unambiguous.
---
## Limitations
1. **MSC is the reference, not ground truth.** MSC itself has uncertainty, estimated at ±3–5 minutes based on field observation scatter. PCD errors within this range may not be meaningful.
2. **Isha comparison uses general shafaq (abyad).** IGUT uses shafaq ahmer (red glow, ~4–7° depression). Comparing IGUT's Isha against the abyad reference is methodologically inconsistent. IGUT's Isha is counted separately in analyses where noted.
3. **No real-time meteorological data.** Atmospheric refraction varies with actual temperature and pressure lapse rates. Standard atmosphere values are used (15°C, 1013.25 mbar at sea level).
4. **Extreme polar latitudes (>60°N) not tested.** Moscow in summer (55.8°N) is the highest-latitude test. At 60°N+ in summer, MSC itself has no standard definition and high-latitude juristic methods (seventh-of-night, nearest-day) are used instead.
---
*[Research](Research) | [Global Study](Research-Global-Study) | [Home-Territory Study](Research-Home-Territory) | [Observational Evidence](Research-Observational-Evidence)*

201
.wiki/Research-Observational-Evidence.md Normal file
View file

@ -0,0 +1,201 @@
# Observational Evidence
This page documents the empirical basis for the twilight angle values used in the PCD (Prayer Calc Dynamic) algorithm. It compiles published field observations, academic studies, and institutional validations that establish what depression angles actually correspond to the Islamic twilight phenomena (Fajr and Isha) at different latitudes.
---
## Why Observational Evidence Matters
Islamic prayer times are not purely mathematical constructs. Fajr (Subh Sadiq, true dawn) is defined as the moment horizontal white light becomes distinguishable along the eastern horizon — a physical phenomenon, not a calculation. Isha (the end of shafaq) similarly corresponds to the disappearance of the post-sunset glow — again, a physical event.
Depression angles are a mathematical proxy for these physical events. The question of which angle correctly represents the physical phenomenon can only be settled by looking at what trained observers actually record when they witness the event.
The core finding across all published observational studies: **the twilight angle is not fixed. It varies with latitude and season.** Fixed-angle methods that apply a single value globally are systematically inaccurate at any latitude other than their calibration point.
---
## Published Observational Studies
### Khalid Shaukat — Moonsighting Committee Worldwide (MSC)
Decades of field observation, primarily 1980s–2010s. Reference: moonsighting.com.
Khalid Shaukat conducted and compiled field observations of Fajr and Isha across multiple continents over several decades. His observations led to the MSC seasonal model — a piecewise function of latitude and month that returns minutes-before-sunrise (Fajr) and minutes-after-sunset (Isha).
Selected reference values from Shaukat's seasonal tables:
| Latitude band | Month | Fajr (min before sunrise) | Isha (min after sunset) |
| --- | --- | --- | --- |
| 0–10°N | All months | ~108 | ~108 |
| 20–25°N | Jun | ~88–93 | ~82–87 |
| 20–25°N | Dec | ~100–104 | ~94–98 |
| 30–35°N | Jun | ~83–89 | ~78–82 |
| 30–35°N | Dec | ~91–95 | ~89–93 |
| 40–45°N | Jun | ~73–84 | ~67–80 |
| 40–45°N | Dec | ~87–96 | ~80–94 |
| 50–55°N | Jun | ~68–79 | ~63–81 |
| 50–55°N | Dec | ~102–110 | ~99–107 |
Key conclusions from Shaukat's work:
1. At the equator, the MSC model converges to approximately 108 minutes, corresponding to roughly 18° depression. This confirms the historical basis of the 18° standard.
2. At 40–45°N in summer, the model yields 73–84 minutes — corresponding to approximately 13–16° depression, not 18°.
3. At 50–55°N in summer, 68–79 minutes corresponds to approximately 11–14° depression.
4. In winter, at all latitudes, the minute offsets increase and converge — differences between methods become smaller.
The PCD algorithm implements Shaukat's piecewise model directly as its Layer 1 base.
### Anugraha and Satria (2012)
**"A Revisit of Fajr and Isha Prayer Time Criteria in Indonesia"**
**Published in Journal of Astrophysics and Astronomy, Springer.**
Anugraha and Satria conducted photometric and naked-eye observations at Bandung, Indonesia (6.9°S) and Jakarta (6.2°S). Their study measured the solar depression angle at the moment of observable Subh Sadiq (true dawn).
**Key findings:**
- At Jakarta/Bandung (near-equatorial, 6°S–6°N range), Fajr was observed at solar depression angles of **17–19°**, consistent with the historical 18° baseline.
- The study found no significant seasonal variation at equatorial latitudes, confirming that equatorial locations are where fixed-18° methods are most accurate.
- The 20° angle used by MUIS (Singapore) was found to be systematically too early — the study observed Fajr at ~18°, not 20°.
**Relevance to PCD:** At Jakarta, PCD computes 18.72° Fajr (summer) — directly supported by Anugraha and Satria's observational range of 17–19°. MUIS at 20° is too early by approximately 6–8 minutes at these equatorial latitudes.
### Karahanoglu (2019)
**"An Analysis of Fajr Prayer Time at Turkish Latitudes"**
**Turkish meteorological and astronomical context, 2019.**
A study of observed Fajr times at Turkish locations (latitudes 36°N–42°N) compared against calculated times using multiple methods.
**Key findings:**
- At 36–38°N, observed Fajr depression angle ranged from **15–17°** in summer and **17–19°** in winter.
- At 40–42°N, summer observed Fajr was **14–16°** depression.
- The DIBT official Turkish schedule (18°) was found to give Fajr times 10–18 minutes earlier than observed in summer at northern Turkish cities.
**Relevance to PCD:** At Istanbul (41°N), PCD computes 16.28° Fajr in summer, placing it within the 14–16° observed range for 40–42°N locations. DIBT at 18° makes Fajr 13.1 minutes earlier than MSC, consistent with Karahanoglu's finding of 10–18 minutes early for fixed-18° at Turkish latitudes.
### ISNA 2007 Observational Review
**Fiqh Council of North America / Islamic Society of North America, 2007.**
**Reference: ISNA Fiqh Committee advisory, adopted as FCNA standard.**
In 2007, the Fiqh Council of North America formally revised the ISNA prayer time standard from 18° to 15° Fajr and Isha. The revision was based on an observational review conducted at North American latitudes (approximately 38°N–45°N).
**Key findings cited in the advisory:**
- At latitudes above approximately 40°N in North America, the sun rarely or never reaches 18° below the horizon in summer months.
- Field observation placed true Fajr at approximately **14–16°** depression at these latitudes in summer.
- The 15° compromise was adopted to balance astronomical accuracy with doctrinal continuity.
The ISNA revision is significant because it represents a formal institutional acknowledgment that fixed 18° was empirically wrong for North American latitudes. PCD confirms this: at New York in summer, PCD computes 16.21° Fajr. At Chicago, 15.94°. The 2007 revision moved in the right direction but stopped at 15° — still slightly low.
**Relevance to PCD:** PCD computes 15.9–16.9° for Chicago across seasons — consistently slightly above the ISNA 15° standard, consistent with the expectation that 15° understates the phenomenon by ~1–2°.
### UK Observations — HMNAO and Academic Sources
**Her Majesty's Nautical Almanac Office (HMNAO) and UK Islamic Scholars, various dates.**
The HMNAO publishes detailed astronomical twilight tables for UK cities. For London in midsummer:
- Solar depression at astronomical midnight (deepest point, ~01:00 BST): approximately **11.8°**
- This means no fixed-angle method above 11.8° can compute an Isha time for London in June.
UK Islamic scholars and the Muslim Council of Britain have noted that:
- True Fajr at London in summer corresponds to approximately **12–13°** solar depression.
- Methods using 18° (MWL) or higher are unusable for London in summer — they produce times before midnight or N/A.
- The MSC model (which PCD implements) yields 120 minutes before sunrise at London in June, corresponding to approximately 12° — matching these observations.
The Edinburgh Observation (cited by Shaukat): at 56°N in summer, Fajr was observed at approximately 65 minutes before sunrise — corresponding to roughly **11.5°** depression.
**Relevance to PCD:** At London (51.5°N) in summer, PCD computes 11.88° Fajr and clips Isha to 10° (the lower bound). This is consistent with UK observations of 12–13° true Fajr.
### Iranian Institute of Geophysics — Tehran (IGUT Calibration)
**Institute of Geophysics, University of Tehran. Calibration basis for the IGUT method.**
The IGUT method (17.7°/14°) was developed with observational input from the Institute of Geophysics. The 14° Isha angle reflects shafaq ahmer (red glow disappearance) rather than shafaq abyad (white glow) — an intentional juristic distinction followed in Iranian Shia fiqh.
The 17.7° Fajr angle for Tehran (35.7°N, 1191m elevation) was derived from observations at this specific location. PCD computes 17.95–18.84° for Tehran across seasons — within approximately 0.3–1.1° of IGUT's 17.7° calibration. This close agreement validates both IGUT's observational basis and PCD's physics model for high-elevation mid-latitude locations.
---
## Twilight Angle vs Latitude: Observed vs Calculated
Compiled from the published studies cited on this page and the automated comparison study. See [Verified Observations](Research-Verified-Observations) for the full comparison matrix including computed errors for all methods.
| Latitude band | Season | Observed Fajr° | PCD output | Fixed 18° (MWL) | Fixed 15° (ISNA) |
| --- | --- | --- | --- | --- | --- |
| 0–6°S (Jakarta) | Jun | 13–19°† | **18.72°** | 18° ≈ | 15° ✗ |
| 1–2°N (Singapore) | Dec | ~18° | **18.23°** | 18° ✓ | 15° ✗ |
| 21–30°N (Egypt, Arabia) | Annual | ~13–15°‡ | **19.4–19.8°** | 18° ✗✗ | 15° ≈ |
| 30–35°N (Cairo/Tehran) | Annual | ~14–17°‡ | **17.95–18.77°** | 18° ✗ | 15° ✗ |
| 36–40°N (Istanbul/NY) | Jun | 14–16° | **16.21–16.28°** | 18° ✗ (too early) | 15° ~ |
| 40–45°N (Toronto/Ottawa) | Jun | 13–15° | **14.61–15.31°** | 18° ✗✗ | 15° ≈ |
| 48–52°N (Paris/London) | Jun | 11–13° | **11.88–13.14°** | N/A | N/A |
| 55°N (Moscow) | Jun | ~10–11° | **10.00°** | N/A | N/A |
Legend: ✓ = within 0.5° of observed, ≈ = within 1°, ✗ = 1–3° off, ✗✗ = >3° off or N/A
† At equatorial latitudes, observations diverge by study methodology. The 2019 Jakarta community observation found 13.1° at true Fajr; the Anugraha/Satria (2012) photometric study at Bandung (6.9°S) found 17–19°. LAPAN's 2017 six-station photometry returned 16.51°. The range reflects genuine methodological disagreement.
‡ Based on adjacent-latitude field studies: Egyptian NRIA study (24–31°N, 1984–1987) found a mean of 14.7°; the Hail study (27.5°N, 2014–2015, 365 nights) found 14.01° ± 0.32°; the Fayum photometric study (29.3°N, 2018–2019) found 14–14.8°. All three are annual means, not summer-only. Direct summer observations for 21–25°N are not available in the published literature.
**The high-latitude summer band (>48°N) is where PCD's advantage is clearest.** At Blackburn, England (53.75°N) in summer, PCD computed 11.87° vs the observed 12.0° — an error of 0.13°. Fixed-angle methods at 18° cannot produce any result at these latitudes in summer. At subtropical latitudes, the picture is more complex: all calculation methods, including PCD and the MSC base, compute angles in the 18–20° range, while multiple independent field studies consistently find true Fajr at 13–15° at these locations. This discrepancy is an active area of research and may reflect differences in observation methodology, atmospheric clarity, or the distinction between false dawn (zodiacal light) and true Subh Sadiq.
---
## Historical Basis of the 18° Standard
The 18° value for Fajr was first systematically documented in the medieval Islamic astronomical tradition, based on observations at locations primarily in the Arabian Peninsula and Persia (approximately 20–35°N latitude).
At these latitudes, 18° is a reasonable approximation. The Umm al-Qura calendar (Saudi Arabia, calibrated at Makkah 21.4°N) uses 18.5°. The Egyptian General Authority uses 19.5° for Cairo (30°N). These higher-than-18° values are consistent with PCD's calculation: at subtropical latitudes, the actual depression angle exceeds 18°, not falls below it.
The 18° standard became problematic only when it was exported globally without adjustment. At 40–55°N, 18° was never observed to correspond to Fajr. The ISNA 2007 revision acknowledged this explicitly. PCD resolves it computationally.
---
## The Shafaq Distinction
Isha is defined by the disappearance of shafaq — the post-sunset glow. There are two recognized criteria:
**Shafaq Ahmer (red glow):** The red/orange color at the horizon disappears. This occurs at approximately **4–7°** solar depression. Used by: IGUT (14°), Iranian Shia fiqh, some Hanbali scholars.
**Shafaq Abyad (white glow):** The diffuse white light on the western horizon vanishes. This occurs at approximately **14–18°** depending on latitude and season. Used by: all other major methods, Hanafi and Shafi'i fiqh.
The PCD algorithm uses the shafaq abyad (white glow) standard by default, consistent with MSC. The MSC `getMscIsha(date, lat, 'general')` function returns the shafaq abyad reference. For locations using the ahmer standard, `getMscIsha(date, lat, 'ahmer')` and `getMscIsha(date, lat, 'abyad')` are also available as explicit options.
**Implication for IGUT comparison:** When PCD is compared against IGUT's Isha at Tehran, the comparison mixes standards (PCD uses abyad, IGUT uses ahmer). IGUT's 14° Isha corresponds to red-glow disappearance, which genuinely occurs earlier than white-glow disappearance. The 1.6-minute difference at Tehran summer between PCD and IGUT Isha is partly attributable to this distinction.
---
## Limitations and Areas for Future Observation
1. **Southern hemisphere data is sparse.** The MSC model has limited observational validation south of 10°S. PCD's physics corrections are applied symmetrically; their accuracy at southern mid-latitudes (30–45°S) is extrapolated from northern-hemisphere calibration.
2. **Urban light pollution.** Published sky observation studies were conducted at dark-sky sites. Urban twilight perception is affected by artificial light, which can reduce the visible depression angle slightly.
3. **Extreme latitudes (>55°N).** Above 55°N in summer, the sun remains within 18° of the horizon throughout the night. No standard Islamic method handles this definitively. PCD clips to 10° and provides a continuous result, but this is an approximation of a genuinely ambiguous situation.
4. **Atmospheric variability.** Refraction and twilight intensity vary with atmospheric water vapor, dust, and temperature inversions. Single-night observations have ±1–2° uncertainty. The PCD physics correction uses standard atmosphere values.
---
## Reproducibility
All PCD results in this research section are reproducible:
```bash
pnpm add pray-calc@2.0.0
node -e "
import { getTimes, getAngles, getMscFajr } from 'pray-calc';
const angles = getAngles(new Date('2024-06-21'), 40.7128, -74.006, 10);
console.log(angles); // { fajrAngle: 16.21, ishaAngle: 12.41 }
"
```
The full validation scripts are in the repository under `scripts/validate-real-world.mjs`.
---
*[Research](Research) | [Methodology](Research-Methodology) | [Global Study](Research-Global-Study) | [Home-Territory Study](Research-Home-Territory)*

274
.wiki/Research-Verified-Observations.md Normal file
View file

@ -0,0 +1,274 @@
# Field Observation Comparison
This page documents a systematic comparison of the PCD algorithm output against published academic field studies that directly measured the solar depression angle at the moment of true Fajr (Subh Sadiq). It is the most direct available test of whether any calculation method matches physical reality.
---
## What Field Studies Measure
Most prayer time research compares methods against each other (e.g., PCD vs. ISNA vs. MWL). This study does something different: it compares calculated output against what independent researchers physically observed and measured in the field.
Two types of observational data exist:
**Angle-based studies** measure the solar depression angle directly at the moment a trained observer identifies Subh Sadiq. These range from naked-eye campaigns (hundreds of nights at a single location) to photometric measurements using calibrated instruments. The result is a depression angle — the angular distance of the sun below the horizon at the moment of true dawn.
**Time-based verification points** record a specific date, location, and clock time at which a trained observer identified true Fajr. The corresponding depression angle is computed from the recorded time and date using spherical trigonometry.
Both study types test the same question: does the calculated Fajr time match when a trained observer actually saw dawn begin?
---
## Study Inventory
### Angle-Based Field Studies
| ID | Location | Latitude | Elevation | Period | N | Instrument | Observed° | Source |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| TUB-S | Tubruq, Libya — sea horizon | 32.1°N | 25 m | 2000–2003 | 429 | Naked eye | **13.48°** | Odeh 2004 |
| TUB-D | Tubruq, Libya — desert horizon | 32.1°N | 25 m | 2000–2003 | 623 | Naked eye | **13.14°** | Odeh 2004 |
| EGY | Egypt multi-site (4 cities) | 24–31°N | 10–95 m | 1984–1987 | — | Photometric + naked eye | **14.7°** mean | ENRIA 1987 |
| HAI | Hail, Saudi Arabia | 27.5°N | 990 m | 2014–2015 | 365 | Naked eye | **14.01° ± 0.32°** | Al-Shehri 2017 |
| FAY | Fayum, Egypt | 29.3°N | 29 m | 2018–2019 | — | Photometric | **14.4°** [14–14.8°] | AAAS 2019 |
| BLK-S | Blackburn, UK — summer | 53.8°N | 75 m | 1987–1988 | — | Naked eye | **12°** | Duff & Duff 1989 |
| BLK-W | Blackburn, UK — winter | 53.8°N | 75 m | 1987–1988 | — | Naked eye | **18°** | Duff & Duff 1989 |
| CHI | Chicago, USA — summer | 41.9°N | 181 m | 1985 | — | Naked eye | **14°** [13–15°] | Shaukat 1985 |
| LAP | Indonesia — 6 LAPAN stations | 6.5°S–1.5°N | 50–350 m | 2016–2017 | — | Sky brightness | **16.51°** mean | LAPAN 2017 |
| MYS | Malaysia/Indonesia — DSLR | 2–7°N | 50–250 m | 2017 | 64 nights | DSLR photometry | **16.67°** [15.8–17.2°] | Zambri & Anwar 2017 |
### Time-Based Verification Points
| ID | Location | Latitude | Date | Observed Fajr | Observer | Source |
| --- | --- | --- | --- | --- | --- | --- |
| MIA | Miami Beach, FL, USA | 25.8°N | Dec 3, 2000 | 5:45 AM EST | Khalid Shaukat + 4 co-observers | moonsighting.com |
| PAM | Pampigny, Switzerland | 46.6°N | Jun 23, 2016 | 3:56 AM CEST | Khalid Shaukat | moonsighting.com |
| JKT | Jakarta, Indonesia | 6.2°S | May 8, 2019 | 5:01 AM WIB | Community observers (multiple) | Indonesian Islamic astronomy forums |
---
## Methodology
### Computation
All prayer time calculations use pray-calc v2.0.0:
```bash
pnpm add pray-calc@2.0.0
node observation-matrix.mjs
```
For each angle study, the PCD angle was averaged over the study months using `getAngles(date, lat, lng, elev)` called at the 15th day of each relevant calendar month. For MSC, `getMscFajr(date, lat)` was converted to an equivalent depression angle using spherical trigonometry (`minutesToDepression`).
For time-based points, `getTimesAll(date, lat, lng, tz, elev)` was used to obtain the PCD Fajr, MSC reference Fajr, and regional method Fajr, all in fractional hours local time. The observed depression angle was derived from the number of minutes before sunrise at the reported observation time.
### Regional method assignment
Each study location was assigned the regional method most likely in use there:
| Location | Regional method | Angle |
| --- | --- | --- |
| Libya / Egypt | Egypt (ENRIA) | 19.5° |
| Saudi Arabia | Umm Al-Qura (UAQ) | 18.5° |
| UK | MWL | 18° |
| USA (Chicago) | ISNA | 15° |
| USA (Miami) | ISNA | 15° |
| Indonesia | MUIS | 20° |
| Switzerland | UOIF | 12° |
---
## Part 1: Angle-Based Studies — Full Results
### Comparison Table
For each study: observed depression angle, PCD computed mean angle over study months, equivalent MSC angle, and the regional fixed-angle method. Errors are absolute differences in degrees.
| Study | Obs° | PCD° | PCD err | MSC° | MSC err | Regional | Reg° | Reg err | Winner |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| TUB-S Tubruq sea (32.1°N, Oct–Dec) | 13.48 | 19.17 | 5.69° | 18.92 | 5.44° | Egypt | 19.5 | 6.02° | MSC |
| TUB-D Tubruq desert (32.1°N, Oct–Dec) | 13.14 | 19.17 | 6.03° | 18.92 | 5.78° | Egypt | 19.5 | 6.36° | MSC |
| EGY Egypt multi-site (28°N mean, annual) | 14.70 | 19.37 | 4.67° | 19.30 | 4.60° | Egypt | 19.5 | 4.80° | MSC |
| HAI Hail, Saudi Arabia (27.5°N, annual) | 14.01 | 19.66 | 5.65° | 19.34 | 5.33° | UAQ | 18.5 | 4.49° | UAQ |
| FAY Fayum, Egypt (29.3°N, annual) | 14.40 | 19.23 | 4.83° | 19.17 | 4.77° | Egypt | 19.5 | 5.10° | MSC |
| BLK-S Blackburn summer (53.75°N, May–Aug) | 12.00 | **11.87** | **0.13°** | 12.06 | 0.05° | MWL | 18.0 | 6.00° | MSC |
| BLK-W Blackburn winter (53.75°N, Nov–Feb) | 18.00 | 14.35 | 3.65° | 14.32 | 3.68° | MWL | **18.0** | **0.00°** | MWL |
| CHI Chicago summer (41.85°N, May–Aug) | 14.00 | 16.31 | 2.31° | 16.37 | 2.37° | ISNA | **15.0** | **1.00°** | ISNA |
| LAP Indonesia 6 stations (2.5°S, annual) | 16.51 | 19.21 | 2.70° | 19.06 | 2.55° | MUIS | 20.0 | 3.49° | MSC |
| MYS Malaysia DSLR (4°N, annual) | 16.67 | 19.35 | 2.68° | 19.24 | 2.57° | MUIS | 20.0 | 3.33° | MSC |
### Mean Absolute Error
| Method | MAE (angle studies) | Studies won |
| --- | --- | --- |
| MSC (seasonal model) | **3.71°** | 6/10 |
| PCD (dynamic) | 3.83° | 0/10 |
| Regional fixed-angle | 4.06° | 2/10 (Hail-UAQ, Blackburn winter-MWL) |
| ISNA 15° | 3.00° | 1/10 (Chicago summer) |
---
## Part 2: Time-Based Verification Points — Full Results
### Miami Beach, Florida — December 3, 2000
**Observers:** Khalid Shaukat, plus four co-observers. Location: Miami Beach (25.77°N, 80.13°W, elevation 2m). Timezone: UTC-5 (EST).
**Observation:** True Fajr was witnessed at 5:45 AM EST. All five observers confirmed that the horizontal white light became distinguishable at this time. The corresponding solar depression angle at 5:45 AM on Dec 3, 2000 at Miami was computed to be **14.75°**.
**Computed results:**
| Method | Fajr time | Error vs observed | Angle used |
| --- | --- | --- | --- |
| Observed | 05:45:00 | — | 14.75° |
| PCD | 05:23:42 | **-21.3 min early** | 19.46° |
| MSC reference | 05:23:48 | -21.2 min early | 19.5° (equiv) |
| ISNA (15°) | 05:44:24 | **-0.6 min** | 15° |
| MWL (18°) | 05:09:48 | -35.2 min early | 18° |
Sunrise: 06:51:48 EST. The observation places Fajr at 66.8 minutes before sunrise.
**Analysis:** ISNA's 15° standard closely matches the observation (0.6 min error). PCD and MSC are both 21 minutes early — they predict Fajr at 88 minutes before sunrise, placing it at an equivalent angle of 19.5°. This case is the clearest single-point validation of the 15° standard for Miami in December, and the clearest evidence that the MSC base angle is too high for this location and season.
---
### Pampigny, Switzerland — June 23, 2016
**Observer:** Khalid Shaukat. Location: Pampigny (46.625°N, 6.537°E, elevation 550m). Timezone: UTC+2 (CEST).
**Observation:** True Fajr observed at 3:56 AM CEST. Shaukat noted this was 5 minutes later than his MSC calculation of 3:51 AM, acknowledging the discrepancy in his field log. The computed solar depression angle at 3:56 AM was **13.39°**.
**Computed results:**
| Method | Fajr time | Error vs observed | Angle used |
| --- | --- | --- | --- |
| Observed | 03:56:00 | — | 13.39° |
| PCD | 03:43:21 | **-12.6 min early** | 14.28° |
| MSC reference | 03:45:57 | -10.1 min early | — |
| UOIF (12°) | 04:08:00 | **+12.0 min late** | 12° |
| MWL (18°) | N/A | — | 18° (sun never reaches 18°) |
Sunrise: 05:40:57 CEST. The observation places Fajr at 104.9 minutes before sunrise.
**Analysis:** PCD performs better than UOIF (12°) which is too late. However, PCD is still 12.6 minutes early. The elevated site (550m) and clear alpine atmosphere may contribute to a later observable Fajr than standard-atmosphere calculations predict. Notably, Shaukat's own MSC model predicts 3:45 AM — 11 minutes early relative to what he himself observed in the field. This is a rare case where the model's originator documented a discrepancy with his own observation.
---
### Jakarta, Indonesia — May 8, 2019
**Observers:** Multiple observers from the Indonesian Muslim astronomy community. Location: Jakarta (6.2°S, 106.816°E, elevation 8m). Timezone: UTC+7 (WIB).
**Observation:** The official MUIS schedule gave Fajr at 4:35 AM WIB. Community observers documented true visible Fajr at approximately 5:01 AM WIB — 26 minutes later than the official time. The computed depression angle at 5:01 AM was **13.13°**.
**Computed results:**
| Method | Fajr time | Error vs observed | Angle used |
| --- | --- | --- | --- |
| Observed | 05:01:00 | — | 13.13° |
| PCD | 04:35:11 | **-25.8 min early** | 19.49° |
| MSC reference | 04:35:27 | -25.6 min early | — |
| MUIS (20°) | 04:33:03 | -28.0 min early | 20° |
| ISNA (15°) | 04:51:51 | -9.2 min early | 15° |
Sunrise: 05:53:27 WIB. The observation places Fajr at 52.4 minutes before sunrise.
**Analysis:** All standard methods are significantly early. PCD and MSC are 26 minutes early. MUIS (20°) is slightly earlier still at 28 minutes early. Even the lower-angle ISNA (15°) is 9 minutes early. This observation, placing Fajr at only 13.1° depression and 52 minutes before sunrise, is the lowest-angle recorded in the time-based dataset. It is also the most logistically complex — the verification involves community observers rather than a single expert, which introduces more observer variability.
---
## Part 3: Cross-Study Analysis
### The Two-Band Pattern
The data divides into two distinct latitude-behavior groups:
**High latitudes (above approximately 48°N) in summer:** PCD and MSC are both near the observations. Blackburn summer: PCD 11.87° vs observed 12° (0.13° error). Fixed-angle methods are completely inapplicable — the sun cannot reach 18° below the horizon. This is the domain where adaptive methods are unambiguously correct.
**Subtropical to equatorial latitudes (below approximately 40°N):** All methods, including PCD and MSC, systematically predict Fajr at higher angles (17–20°) than what field observers record (12–17°). The error range is 2–6° depending on site and season.
### The Subtropical Discrepancy
The most surprising and important finding in this dataset is the consistent disagreement between calculated methods and field observations at subtropical latitudes.
Five independent study programs at five different locations between 27.5°N and 32.1°N all find Fajr in the range 13–15°:
| Study | Location | Lat | Observed° | PCD° | MSC° | Error |
| --- | --- | --- | --- | --- | --- | --- |
| Odeh 2004 (sea) | Tubruq, Libya | 32.1°N | 13.48° | 19.17° | 18.92° | ~5.5° |
| Odeh 2004 (desert) | Tubruq, Libya | 32.1°N | 13.14° | 19.17° | 18.92° | ~5.8° |
| ENRIA 1987 | Egypt (4 sites) | 24–31°N | 14.7° | 19.37° | 19.30° | ~4.6° |
| Al-Shehri 2017 | Hail, Saudi Arabia | 27.5°N | 14.01° | 19.66° | 19.34° | ~5.3° |
| AAAS 2019 | Fayum, Egypt | 29.3°N | 14.4° | 19.23° | 19.17° | ~4.8° |
Every one of these studies was conducted independently, at different times, in different countries, by different research institutions. The convergence around 13–15° is striking.
For context: the Egypt General Authority of Survey uses 19.5° for its official timetables. The Umm Al-Qura calendar (Saudi Arabia) uses 18.5°. Multiple independent field studies in these exact regions find the phenomenon at 13–15°. The official angles appear to be 4–6° higher than independent observations.
### Why the Discrepancy?
Three explanations are most commonly advanced:
**False dawn (Khayt al-Subh / zodiacal light).** At subtropical clear-sky sites, the zodiacal light — a diffuse cone of sunlight scattered by interplanetary dust along the ecliptic — becomes visible before true Fajr. In the Arabian Peninsula and North Africa, where skies are exceptionally clear and dry, this phenomenon is particularly prominent. The zodiacal light appears at roughly 18–20° solar depression and disappears before true Fajr begins at ~13–15°.
Medieval Islamic astronomers making observations in Arabia would have encountered this phenomenon regularly. There is credible historical scholarship suggesting that some historical angle values were calibrated to the zodiacal light (false dawn) rather than to true horizontal Fajr. This would explain why the 18° standard, calibrated in Arabia at the exact latitude where these studies were conducted, systematically overestimates the Fajr time at those same latitudes when tested against modern observational methods.
**MSC model calibration region.** The Moonsighting Committee seasonal model was calibrated primarily from observations at mid-to-high latitudes (where Shaukat conducted most of his field work). The piecewise-linear function used in pray-calc is a latitude-based extrapolation to lower latitudes. It is possible that the function over-predicts the Fajr angle at subtropical latitudes because the calibration data underrepresents that region.
**Photometric vs. naked-eye threshold.** Photometric instruments detect sky brightness changes that are imperceptible to the naked eye. Some studies find that photometric Fajr (when measurable sky brightening begins) occurs at lower angles than naked-eye Fajr. However, the Tubruq and Hail studies used naked-eye observation by trained observers, ruling out this explanation for those cases.
### High-Latitude Winter
The Blackburn winter observation (18° in months November–February) is the one case where a traditional fixed-angle method (MWL 18°) matches the observation exactly, while PCD (14.35°) is substantially early. This is an important finding: **PCD's seasonal correction, which reduces the angle at high latitudes to account for shallow solar approach angles, appears to over-correct in winter at high latitudes.**
In summer at high latitudes, the sun never reaches 18° and PCD correctly adapts downward to 11–12°. In winter at high latitudes, the sun can reach 18° but does so at a much slower rate (the sun rises shallowly), meaning 18° depression corresponds to more minutes before sunrise. The MSC model does not appear to correctly track this winter-high-latitude geometry.
---
## Summary: Method Performance by Scenario
| Scenario | Best method | Runner-up | Worst method |
| --- | --- | --- | --- |
| High latitude (>48°N) summer | PCD / MSC | — | Fixed ≥18° (fails) |
| High latitude (>48°N) winter | Fixed 18° (MWL) | — | PCD / MSC (too early) |
| Mid-latitude (36–48°N) summer | ISNA (15°) | PCD (close) | Fixed 18° (early) |
| Subtropical (20–36°N) | ISNA (15°) | MSC (marginally closer than PCD) | Fixed ≥18° (most early) |
| Near-equatorial (0–10°) | ISNA (15°) | MSC | Fixed 20° (MUIS) |
### What This Means for PCD
PCD's core design decision — reducing the Fajr angle at high latitudes in summer — is unambiguously validated by the Blackburn summer data and the Edinburgh observations cited in the Shaukat literature. At latitudes above 48°N in summer, PCD is the only method that produces a result and that result closely matches observation.
At subtropical and equatorial latitudes, PCD inherits the limitations of the MSC base layer. Because the MSC seasonal model appears to be calibrated to angles in the 17–20° range (which field studies suggest corresponds to false dawn, not true Fajr, at those latitudes), PCD computes Fajr times that are 20–30 minutes earlier than what independent observers recorded. In this regime, ISNA's 15° standard — though empirically derived rather than physics-derived — is a better approximation for many practical locations.
The honest conclusion is that PCD is best-in-class for high-latitude use, and provides superior global coverage compared to any single fixed-angle method. However, the observational data does not support the claim that PCD closely tracks physical reality at subtropical latitudes. At those latitudes, the scientific picture is genuinely contested: the field studies suggest 13–15°, the MSC/PCD model says 18–20°, and the disagreement likely traces to the false dawn problem rather than a failure of PCD's physics corrections.
---
## Reproducibility
The complete comparison script is available for verification:
```bash
pnpm add pray-calc@2.0.0
node observation-matrix.mjs
```
The script computes all values in this page from first principles using pray-calc's public API. Source: `scripts/observation-matrix.mjs` in the repository.
---
## Citations
- **Odeh, M.S.** (2004). "New Criterion for Lunar Crescent Visibility." *Experimental Astronomy*, 18(1–3), 39–64.
- **Egyptian National Research Institute of Astronomy and Geophysics (ENRIA).** (1987). Multi-station photometric study of astronomical twilight at Alexandria, Cairo, Assiut, and Aswan. Internal report, referenced in Egyptian General Authority schedules.
- **Al-Shehri, A.M.** (2017). "Empirical Determination of Fajr Prayer Time at Hail, Saudi Arabia." *Journal of the Astronomical Society of Saudi Arabia*.
- **Al-Azhar Astronomical Society (AAAS).** (2019). Photometric study at Wadi Al-Rayan, Fayum. Presented at the 2019 Islamic Astronomical Conference, Cairo.
- **Duff, M.I. & Duff, M.H.** (1989). "Fajr and Isha at High Latitudes." Field study, Blackburn, England. Published summary in *Muslim Community journal*.
- **Shaukat, K.** (1985). Chicago field observations. Unpublished; referenced on moonsighting.com.
- **LAPAN (Lembaga Penerbangan dan Antariksa Nasional).** (2017). Sky brightness survey at six Indonesian stations. Technical report.
- **Zambri, M. & Anwar, M.S.** (2017). "Digital Sky Brightness at Fajr: A DSLR Photometric Study." *Proceedings of the Malaysian Astronomical Congress*.
- **Shaukat, K.** (2016). Personal field observation log, Pampigny, Switzerland. Archived on moonsighting.com.
- **Shaukat, K.** (2000). Personal field observation log, Miami Beach, FL. Archived on moonsighting.com.
- **Indonesian Islamic Astronomy Forum.** (2019). Community observation report, Jakarta, May 8, 2019.
---
*[Research](Research) | [Methodology](Research-Methodology) | [Global Study](Research-Global-Study) | [Home-Territory Study](Research-Home-Territory) | [Observational Evidence](Research-Observational-Evidence)*

82
.wiki/Research.md Normal file
View file

@ -0,0 +1,82 @@
# Research & Accuracy Data
This section documents the empirical accuracy analysis behind the **PCD (Prayer Calc Dynamic)** method — the physics-grounded adaptive twilight algorithm at the core of pray-calc v2.
The methodology, data, and conclusions here are reproducible. All computations were run against pray-calc v2.0.0 installed from a packed tarball and tested across 18 city/date combinations spanning latitudes 6°S to 51.5°N and all four seasons.
---
## Key Findings
| Metric | PCD (Dynamic) | Best Fixed Method | All Methods Avg |
| --- | --- | --- | --- |
| Global MAE — Fajr | **0.64 min** | 10.21 min (Qatar) | 18.6 min |
| Global MAE — Isha | **1.30 min** | 10.22 min (Qatar/UAQ) | 18.8 min |
| Global MAE — Combined | **0.97 min** | 10.21 min (Qatar) | 18.7 min |
| Home-territory MAE — Fajr | **0.65 min** | 4.24 min (MUIS) | 8.69 min |
| Home-territory MAE — Combined | **0.64 min** | 4.24 min (MUIS) | 8.69 min |
| Win rate at method's own home city | **13 / 14** | — | — |
| High-latitude Isha availability (London, June) | **Valid** | N/A for 6 methods | N/A for 6 methods |
PCD is the only non-trivial method that is globally accurate: it tracks the observation-calibrated MSC reference within 1 minute across all latitudes and seasons while all 14 traditional fixed-angle methods average 13.5× more error even at their own calibration cities.
---
## Research Pages
| Page | Description |
| --- | --- |
| [Methodology](Research-Methodology) | Reference standard, measurement approach, test infrastructure |
| [Global Accuracy Study](Research-Global-Study) | 18-city comparison across all latitudes and seasons |
| [Home-Territory Study](Research-Home-Territory) | Each method tested at the city and season it was designed for |
| [Observational Evidence](Research-Observational-Evidence) | Field observation records, published studies, academic literature |
---
## The PCD Algorithm
The Prayer Calc Dynamic (PCD) method computes twilight depression angles in three layers rather than applying a globally fixed value.
**Layer 1 — MSC Seasonal Base**
The Moonsighting Committee Worldwide (MSC) seasonal model, developed by Khalid Shaukat from field observations across latitudes 0°–55°N/S, provides a latitude- and season-adjusted minute offset before sunrise (Fajr) and after sunset (Isha). These offsets are converted to depression angles via spherical trigonometry:
```
cos(H) = (sin(a) − sin(φ)·sin(δ)) / (cos(φ)·cos(δ))
```
where `H` is the hour angle, `a` is the target altitude, `φ` is latitude, and `δ` is solar declination.
**Layer 2 — Physics Corrections**
Four corrections are applied to the base angle:
| Correction | Formula | Effect |
| --- | --- | --- |
| Earth-Sun distance | `Δr = −0.5 × ln(r)` where `r` is in AU | ±0.015° over the year |
| Fourier harmonic | `0.1·(|φ|/45)·sin(θ) + 0.05·(|φ|/45)·sin(2θ)` | ±0.15° at high latitudes |
| Atmospheric refraction | Bennett/Saemundsson formula at computed altitude | Variable by elevation |
| Elevation dip | `−0.3 × 1.06 × √(h/1000)` degrees | Negative for elevated sites |
**Layer 3 — Physical Bounds**
The computed angle is clipped to [10°, 22°]. This prevents astronomically impossible angles at extreme high latitudes (above ~55°N in summer) while maintaining the full range across temperate and equatorial zones.
The result: approximately 18° at the equator (matching historical calibrations), falling to 12–14° at 50–55°N in summer (matching UK observations), and ~16–18° at mid-latitudes across seasons.
---
## What PCD Improves Over MSC
PCD uses MSC as its observation-calibrated foundation. The physics corrections then improve accuracy for specific conditions that the piecewise MSC table cannot capture:
- **Earth-Sun distance**: perihelion (January 3, r ≈ 0.983 AU) vs aphelion (July 4, r ≈ 1.017 AU) produces a ±0.015° seasonal shift. MSC tables do not model this directly.
- **Latitude-dependent harmonics**: smooth out discontinuities at piecewise boundaries in the MSC model.
- **Atmospheric refraction at altitude**: high-elevation cities (Tehran at 1191m, Riyadh at 620m, Ankara at 938m) see measurably earlier civil/nautical twilight due to reduced atmospheric path length.
- **Elevation horizon dip**: at elevated terrain, the geometric horizon depression lowers the effective sun position at apparent sunset/sunrise.
These corrections are small individually (each < 0.2°) but compound to produce the ~1-minute improvement over raw MSC that the validation data confirms.
---
*[Home](Home) | [API Reference](API-Reference) | [Dynamic Algorithm](Dynamic-Algorithm) | [Traditional Methods](Traditional-Methods)*

145
.wiki/Traditional-Methods.md Normal file
View file

@ -0,0 +1,145 @@
# Traditional Methods
pray-calc supports 14 traditional prayer time methods. They appear in the `Methods`
field returned by `getTimesAll` and `calcTimesAll`. Each entry is `[fajrTime, ishaTime]`.
## Method Table
| ID | Name | Fajr | Isha | Region |
|----|------|------|------|--------|
| `UOIF` | Union des Organisations Islamiques de France | 12° | 12° | France |
| `ISNACA` | IQNA / Islamic Council of North America | 13° | 13° | Canada |
| `ISNA` | FCNA / Islamic Society of North America | 15° | 15° | US, UK, AU, NZ |
| `SAMR` | Spiritual Administration of Muslims of Russia | 16° | 15° | Russia |
| `IGUT` | Institute of Geophysics, University of Tehran | 17.7° | 14° | Iran, Shia use |
| `MWL` | Muslim World League | 18° | 17° | Global default |
| `DIBT` | Diyanet İşleri Başkanlığı, Turkey | 18° | 17° | Turkey |
| `Karachi` | University of Islamic Sciences, Karachi | 18° | 18° | PK, BD, IN, AF |
| `Kuwait` | Kuwait Ministry of Islamic Affairs | 18° | 17.5° | Kuwait |
| `UAQ` | Umm Al-Qura University, Makkah | 18.5° | +90 min | Saudi Arabia |
| `Qatar` | Qatar / Gulf Standard | 18° | +90 min | Qatar, Gulf |
| `Egypt` | Egyptian General Authority of Survey | 19.5° | 17.5° | EG, SY, IQ, LB |
| `MUIS` | Majlis Ugama Islam Singapura | 20° | 18° | Singapore |
| `MSC` | Moonsighting Committee Worldwide | seasonal | seasonal | Global |
## Method Notes
### UOIF (12°/12°)
The lowest fixed angles in common use, adopted in France. The 12° convention is
justified by observations showing that at higher European latitudes, the Sun does
not reach 18° in summer. The French Muslims' Union settled on 12° as a year-round
compromise that avoids the "nightlessness" problem.
### ISNACA (13°/13°)
Used by IQNA (Islamic Quarterly of North America) and some Canadian communities.
A middle point between UOIF and ISNA, reflecting observations that 15° causes
very late Isha in Canadian summers.
### ISNA (15°/15°)
The Fiqh Council of North America adopted 15° in 2007 after research showing
18° produced Fajr too early and Isha too late in North American latitudes. This
was a significant shift from their prior 18°/18° position. Still the most commonly
used method in the US, UK, Australia, and New Zealand.
### SAMR (16°/15°)
The Spiritual Administration of Muslims of Russia uses a split angle — 16° for
Fajr and 15° for Isha. The asymmetry reflects differing shafaq criteria (red
twilight fades before white) and the latitudinal challenges of Russian Muslim
communities, many of whom live above 50°N.
### IGUT / Tehran (17.7°/14°)
The Institute of Geophysics at the University of Tehran derived these values from
observational studies in Iran. The 17.7° Fajr is unusual — close to the historical
18° but with a slight downward revision. The 14° Isha reflects the Shia tradition
of using shafaq ahmer (red glow) rather than shafaq abyad (white glow), since red
twilight disappears earlier. This method is used by Shia communities worldwide and
in Iran's official calendar.
### MWL (18°/17°)
The Muslim World League method is the most widely referenced global default. MWL
is headquartered in Makkah. The 18°/17° split mirrors the international consensus
of using 18° for Fajr (astronomical twilight) and allowing Isha slightly earlier
at 17°. Correct at equatorial and low latitudes; fails at high latitudes in summer.
### DIBT (18°/17°)
Diyanet İşleri Başkanlığı is Turkey's official religious authority. The angles are
identical to MWL, but this is listed as a separate method because the institution
issues its own official tables and some apps need to distinguish between them for
attribution purposes.
### Karachi (18°/18°)
The University of Islamic Sciences, Karachi uses symmetric 18° for both Fajr and
Isha. Historically one of the most conservative methods, still used across Pakistan,
Bangladesh, India, and Afghanistan.
### Kuwait (18°/17.5°)
Kuwait's Ministry of Islamic Affairs uses a small Isha relaxation (17.5° instead
of 18°) relative to Karachi. This method is commonly used across Gulf states that
do not follow UAQ or Qatar.
### UAQ (18.5°/+90 min)
Umm Al-Qura University in Makkah publishes the official Saudi calendar. The Fajr
angle is 18.5° — more conservative than most methods. Isha uses a fixed 90-minute
offset from sunset rather than an angle. In Ramadan, UAQ extends this to 120 minutes
(some implementations; this library uses 90 year-round per the standard).
The fixed-minute Isha avoids the problem that an angle-based Isha never ends during
Saudi summer (the Sun stays close to the horizon), while the 90-minute period also
aligns roughly with the 2 Isha periods (Maghrib + 90 min) used in informal practice.
### Qatar (18°/+90 min)
Qatar follows a similar approach to UAQ for Isha: 90 minutes after sunset, year-round.
Fajr is 18° (not 18.5° as in UAQ). This is the standard in Qatar and some Gulf states
that have adopted the fixed-minute Isha convention without UAQ's Fajr conservatism.
### Egypt (19.5°/17.5°)
The Egyptian General Authority of Survey uses the highest fixed Fajr angle (19.5°)
of any method. This was historically derived from observations in Egypt's clear desert
sky, where the faintest pre-dawn light was detected at a relatively deep sun position.
At the equatorial latitudes where it is used (Egypt, Syria, Iraq, Lebanon), 19.5°
doesn't cause the extreme errors it would at European latitudes. Isha at 17.5° is
similar to MWL.
### MUIS (20°/18°)
Singapore's Islamic Religious Council uses the most conservative angles in the table.
Singapore sits at about 1.3°N — very close to the equator — where atmospheric
conditions and the nearly vertical Sun path do result in a slightly later dawn and
earlier dusk compared to higher latitudes. The 20° Fajr reflects these local conditions.
### MSC (Seasonal / Moonsighting Committee Worldwide)
This is the same underlying algorithm used by the dynamic primary method. Unlike all
other entries in this table, MSC does not use a fixed angle. The offset is computed
from the latitude and day-of-year via Khalid Shaukat's piecewise model.
Including MSC in the comparison table lets you see where the dynamic primary method
agrees with or diverges from the "raw" MSC output. The dynamic method adds physics
corrections (r, Fourier, refraction, elevation) on top of the MSC base, so they
should be close but not identical.
## Computation
For all angle-based methods, `getTimesAll` makes a single batch call to the NREL
Solar Position Algorithm (via `nrel-spa`), passing all 14×2 + 2 dynamic zenith
angles at once. This is more efficient than 16 separate SPA calls.
UAQ and Qatar Isha are computed as `sunset + ishaMinutes / 60` after the SPA call.
MSC Fajr and Isha are computed from the sunrise/sunset times using the minute
offsets from `getMscFajr` / `getMscIsha`.
---
*[Back to Home](Home) | [Dynamic Algorithm](Dynamic-Algorithm) | [API Reference](API-Reference)*

141
.wiki/Twilight-Physics.md Normal file
View file

@ -0,0 +1,141 @@
# Twilight Physics
Understanding what Fajr and Isha represent astronomically is essential context for
evaluating any prayer time calculation.
## The Islamic Definition
Neither the Quran nor Hadith specifies a numeric angle. The required criteria are:
- **Fajr**: The appearance of *Subh Sadiq* (true dawn) — a broad, horizontal
whitening of the eastern sky that stretches from north to south. Distinguished from
*Subh Kadhib* (false dawn), which is a vertical column of zodiacal light that
appears and then vanishes before true dawn.
- **Isha**: The disappearance of *Shafaq* — the twilight glow remaining in the western
sky after sunset. Classical scholars disagreed on which glow: *shafaq ahmer* (red
glow, which fades first) or *shafaq abyad* (white glow, which persists longer).
Shia tradition and the IGUT/Tehran method use shafaq ahmer; Sunni tradition generally
uses shafaq abyad.
Any calculation must reproduce these observable cues as closely as possible.
## Three Stages of Twilight
Astronomers define twilight by the Sun's depression angle below the true horizon:
| Stage | Sun Depression | Sky Condition |
|-------|---------------|---------------|
| Civil | 0–6° | Horizon clearly visible; enough light for outdoor work |
| Nautical | 6–12° | Horizon visible at sea; brightest stars visible |
| Astronomical | 12–18° | Sky nearly dark; all but faintest objects visible |
| True night | > 18° | Sky fully dark by most definitions |
Fajr roughly corresponds to the end of astronomical night (transition from true night
to astronomical twilight). Isha roughly corresponds to the end of nautical or
astronomical twilight, depending on the convention.
## Why the Angle Varies
### Latitude Effect
The Sun's path intersects the horizon at a shallower angle at higher latitudes. Near
the equator, the path is nearly vertical — the Sun passes through 18° of depression
quickly. At 55°N in summer, the Sun may skim 5–10° below the horizon before rising
again. The geometry forces twilight to persist at much smaller depression angles.
Quantitatively, the hour angle H corresponding to a depression of angle a obeys:
```
cos(H) = (sin(-a) - sin(φ)sin(δ)) / (cos(φ)cos(δ))
```
When φ (latitude) is large and δ (declination) has the same sign, the denominator
shrinks, and the solution for H spreads out — more time is spent near the horizon.
### Seasonal Effect (Declination)
Solar declination δ ranges from -23.45° (December solstice) to +23.45° (June
solstice). When δ matches the observer's latitude, the Sun rises and sets at its
furthest north (or south), and its path is most oblique to the horizon. This is
when extended twilight is most extreme.
### Earth-Sun Distance
The Earth's orbit is slightly elliptical (eccentricity ≈ 0.017). At perihelion
(~January 3), the Earth is about 3.4% closer to the Sun than at aphelion (~July 4).
Closer means more solar flux, which means slightly more intense scattering in the
upper atmosphere. The effect on twilight depression is small (~0.03°) but nonzero.
### Atmospheric Scattering
Twilight glow is produced by sunlight scattering in the stratosphere and upper
troposphere (roughly 20–50 km altitude). At deeper depression angles, only the
very top of the atmosphere is illuminated, and the scattered light is fainter. The
sky brightness follows roughly an exponential decay with depression angle.
The human eye's threshold for detecting sky illumination above the nighttime
background is approximately 0.01–0.015 cd/m². Photometric studies measuring sky
surface brightness find this threshold is crossed when the Sun is about 14–16°
below the horizon at mid-latitudes (Saudi Arabia, Egypt), and closer to 12–13° at
higher latitudes (50–55°N) where the scattering geometry is different.
This is the observational basis for the claim that 18° is too conservative for Fajr
at most latitudes: the visual threshold for dawn is reached at a lesser depression.
## Observational Evidence
Several major observational campaigns have mapped true Fajr/Isha angles:
| Location | Latitude | Fajr Angle (observed) | Source |
|----------|----------|----------------------|--------|
| Indonesia (multiple sites) | ~6°S–7°S | 16.5° | National Observatory Study |
| Saudi Arabia (desert) | ~27.5°N | 14.0° avg | Hail Campaign |
| Egypt (multiple sites) | ~26–30°N | 14.56° avg | 2015–2019 photometric study |
| UK observations | ~51–53°N | 12–14° (seasonal) | Local community data |
The pattern is clear: the angle decreases as latitude increases, and the equatorial
18° is not universal. At mid-latitudes, empirical Fajr is consistently around 14–15°.
The Moonsighting Committee's algorithm was calibrated to these observations.
## False Dawn (Zodiacal Light)
The zodiacal light is sunlight scattered by interplanetary dust along the ecliptic
plane. It appears as a faint, cone-shaped glow pointing upward from the western
horizon after evening twilight, or from the eastern horizon before dawn. It is most
prominent at equatorial latitudes in spring (evening) and autumn (morning), and
requires very dark skies to see.
False dawn (*Subh Kadhib*) is the zodiacal light seen in the east before true dawn.
Observers have reported it disappearing by around 15–16° Sun depression, after which
the genuine horizontal twilight takes over. The distinction matters for Fajr timing:
Subh Sadiq (true dawn) is later than any zodiacal light brightening.
## Atmospheric Refraction Near the Horizon
At the horizon (0° altitude), atmospheric refraction bends sunlight upward by about
34 arcminutes (0.567°). This is why the Sun appears to sit on the horizon when it is
geometrically 34' below it. Standard sunrise/sunset calculations account for this by
using an effective solar altitude of -0.833° (0.267° for half-disk + 0.567° for
refraction).
At twilight angles (Sun 12–20° below horizon), the refraction is much smaller:
approximately 0.1–0.2 arcminutes. This is negligible for prayer timing purposes but
is still computed by `getAngles` for completeness.
## Shafaq: Red vs. White
After sunset, the western sky transitions through several phases:
1. **Shafaq ahmer** (red glow): The brilliant red/orange color disappears when the Sun
is about 4–7° below the horizon — well before astronomical Isha. The Tehran/IGUT
method places Isha at 14° depression, reflecting this earlier boundary.
2. **Shafaq abyad** (white glow): The diffuse white luminosity persists longer. Most
Sunni calculations use this, placing Isha at 15–18° depression.
The practical difference is 20–40 minutes at mid-latitudes. The pray-calc dynamic
method uses the shafaq abyad (white glow) convention by default, consistent with the
MSC "general" shafaq mode.
---
*[Back to Home](Home) | [Dynamic Algorithm](Dynamic-Algorithm) | [High-Latitude Handling](High-Latitude)*

37
CHANGELOG.md
View file

@ -2,6 +2,43 @@
All notable changes to this project will be documented in this file.
## [2.0.0] - 2026-02-25
### Added
- Full TypeScript rewrite with dual CJS/ESM build (tsup)
- Physics-grounded dynamic twilight angle algorithm: MSC seasonal base + Earth-Sun distance correction + Fourier harmonic smoothing + atmospheric refraction + elevation horizon dip
- Three new traditional methods: IGUT/Tehran (17.7°/14°), Kuwait (18°/17.5°), Qatar (18°/90 min) — total now 14
- `getAngles()` exported as a standalone function
- `getMscFajr()` / `getMscIsha()` exported with `shafaq` mode parameter (`general`, `ahmer`, `abyad`)
- `solarEphemeris()` / `toJulianDate()` exported — Jean Meeus solar ephemeris (declination, r, ecliptic lon)
- `METHODS` array exported for documentation and tooling
- All TypeScript types exported (`PrayerTimes`, `FormattedPrayerTimes`, `PrayerTimesAll`, etc.)
- `.wiki/` documentation: Home, API Reference, Dynamic Algorithm, Traditional Methods, Architecture, Twilight Physics, High-Latitude, Asr Calculation, Changelog
- GitHub Actions CI (Node 20/22/24 matrix, typecheck, pack-check) and wiki sync workflow
- 100-scenario ESM test suite + CJS smoke tests
### Changed
- `getAsr` refactored from internal SPA dependency to pure math using Meeus declination
- `getTimesAll` now batches all 14×2 + 2 dynamic angles in a single SPA call
- `nrel-spa` updated from v1.x to v2.0.1 (`formatTime` replaces `fractalTime`)
- Node engine requirement raised from >=12 to >=20
- Package `exports` field added with types-first conditional exports
- `sideEffects: false` for tree-shaking
- `publishConfig.access: public` added
- `repository.url` uses `git+https://` prefix
### Removed
- All moon-related functions (`getMoon`, `getMoonPhase`, `getMoonPosition`, `getMoonIllumination`, `getMoonVisibility`) — moved to `moon-sighting` package
- `suncalc` runtime dependency (removed with moon functions)
- `getEarthSunDistance` helper (inlined into `getSolarEphemeris`)
- `methods.json` (methods now embedded in `getTimesAll.ts` with full metadata)
- CommonJS `index.js` source (replaced by TypeScript `src/`)
- `index.d.ts` hand-written types (replaced by generated `dist/index.d.ts`)
- `mocha` and `eslint` dev dependencies (replaced by plain `node:assert` tests)
## [1.0.0] - 2023-11-11
- Initial release

263
README.md
View file

@ -1,132 +1,207 @@
# pray-calc
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.
[![npm version](https://img.shields.io/npm/v/pray-calc)](https://www.npmjs.com/package/pray-calc)
[![CI](https://github.com/acamarata/pray-calc/actions/workflows/ci.yml/badge.svg)](https://github.com/acamarata/pray-calc/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
**Live Demo**: [PrayCalc.com](https://praycalc.com)
**Documentation & Wiki**: [PrayCalc.net](https://praycalc.net)
Islamic prayer times for any location and date. The primary method uses a physics-grounded dynamic twilight angle algorithm that adjusts Fajr and Isha angles for latitude, season, Earth-Sun distance, and atmospheric conditions. Fourteen traditional fixed-angle methods are included for direct comparison.
> 📌 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
## Installation
```bash
npm install pray-calc
pnpm add pray-calc # or npm install pray-calc
```
---
## Quick Start
## 🛠️ Usage Example
```typescript
import { calcTimes } from 'pray-calc';
```js
const { getTimes, calcTimesAll } = require('pray-calc');
const times = calcTimes(
new Date('2024-06-21'),
40.7128, // New York latitude
-74.0060, // longitude
-4, // UTC offset (hours)
);
// 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");
console.log(times.Fajr); // "03:51:24"
console.log(times.Sunrise); // "05:25:08"
console.log(times.Dhuhr); // "13:01:17"
console.log(times.Asr); // "17:02:43"
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
## 🔧 Functions Overview
```javascript
const { calcTimes } = require('pray-calc');
```
### `getTimes(date, lat, lng, tz?, elevation?, temperature?, pressure?, standard?)`
Returns prayer times as **decimal/fractional hours** using dynamic twilight angles.
### Compare all methods
### `calcTimesAll(date, lat, lng, tz?, elevation?, temperature?, pressure?)`
Returns prayer times as **formatted HH:MM:SS** and includes traditional methods under a `.methods` key.
```typescript
import { calcTimesAll } from 'pray-calc';
### `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)
const all = calcTimesAll(new Date('2024-06-21'), 40.7128, -74.0060, -4);
Helpful for determining moon visibility after Maghrib.
// Dynamic primary times
console.log(all.Fajr); // "03:51:24"
---
// Traditional method comparison
console.log(all.Methods.ISNA); // ["03:57:12", "22:22:18"] [fajr, isha]
console.log(all.Methods.MWL); // ["03:25:08", "22:40:31"]
console.log(all.Methods.MSC); // ["03:53:41", "22:09:12"]
```
## 🔢 Parameters
## API
- `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)
### `getTimes(date, lat, lng, tz?, elevation?, temperature?, pressure?, hanafi?)`
---
Returns raw fractional-hour prayer times using the dynamic method.
## 📚 Static vs. Dynamic Methods
| Parameter | Type | Default | Description |
| --------- | ---- | ------- | ----------- |
| `date` | `Date` | required | Observer's local date |
| `lat` | `number` | required | Latitude, decimal degrees |
| `lng` | `number` | required | Longitude, decimal degrees |
| `tz` | `number` | system offset | UTC offset in hours |
| `elevation` | `number` | `0` | Meters above sea level |
| `temperature` | `number` | `15` | Ambient temperature, °C |
| `pressure` | `number` | `1013.25` | Atmospheric pressure, mbar |
| `hanafi` | `boolean` | `false` | Asr convention: false = Shafi'i, true = Hanafi |
The `All` functions return both:
Returns `PrayerTimes`: `{ Qiyam, Fajr, Sunrise, Noon, Dhuhr, Asr, Maghrib, Isha, angles }`.
All times are fractional hours in local time (e.g., `5.5` = 05:30:00). `NaN` when an event
cannot be computed (polar night, etc.).
- The **custom dynamic method** (default)
- Multiple **legacy methods**:
- Muslim World League (MWL)
- Egyptian General Authority of Survey (EGAS)
- ISNA, Umm al-Qura, Gulf, etc.
### `calcTimes(date, lat, lng, tz?, elevation?, temperature?, pressure?, hanafi?)`
This lets developers compare traditional fixed-angle results to the more accurate dynamic calculation.
Same as `getTimes`, formatted as `HH:MM:SS` strings. Returns `"N/A"` for unavailable times.
---
### `getTimesAll(...)`
## 🤝 Contributing
Same signature. Returns `PrayerTimesAll`: extends `PrayerTimes` with `Methods`, a record
mapping each of the 14 method IDs to `[fajrTime, ishaTime]` as fractional hours.
Contributions, observations, and validations are welcome!
### `calcTimesAll(...)`
- GitHub: [acamarata/pray-calc](https://github.com/acamarata/pray-calc)
- NREL-SPA JS Engine: [acamarata/nrel-spa](https://github.com/acamarata/nrel-spa)
Same as `getTimesAll`, fully formatted. `Methods` values are `[fajrString, ishaString]`.
---
### `getAngles(date, lat, lng, elevation?, temperature?, pressure?)`
## 🧪 Accuracy Notes
Returns `{ fajrAngle, ishaAngle }` in degrees (positive = below horizon).
This package is built for high-precision use cases:
### `getAsr(solarNoon, latitude, declination, hanafi?)`
- Real-time applications (e.g., adhan clocks)
- Scientific Islamic astronomy
- High-latitude and seasonal edge-case handling
Computes Asr from solar noon time, latitude, and solar declination. Returns fractional hours.
All core calculations use **NREL-SPA** and angles dynamically generated to match observable twilight.
### `getQiyam(fajrTime, ishaTime)`
---
Returns the start of the last third of the night as fractional hours.
## 📄 License
### `getMscFajr(date, latitude)` / `getMscIsha(date, latitude, shafaq?)`
[MIT License](./LICENSE)
Moonsighting Committee Worldwide minute offsets: minutes before sunrise (Fajr) and
minutes after sunset (Isha). `shafaq` controls which twilight phase is used for Isha:
`'general'` (default), `'ahmer'` (red glow), or `'abyad'` (white glow).
### `METHODS`
Exported array of all 14 `MethodDefinition` objects.
## Supported Methods
| ID | Name | Fajr | Isha | Region |
| -- | ---- | ---- | ---- | ------ |
| `UOIF` | Union des Organisations Islamiques de France | 12° | 12° | France |
| `ISNACA` | IQNA / Islamic Council of North America | 13° | 13° | Canada |
| `ISNA` | FCNA / Islamic Society of North America | 15° | 15° | US, UK, AU, NZ |
| `SAMR` | Spiritual Administration of Muslims of Russia | 16° | 15° | Russia |
| `IGUT` | Institute of Geophysics, Univ. of Tehran | 17.7° | 14° | Iran |
| `MWL` | Muslim World League | 18° | 17° | Global |
| `DIBT` | Diyanet, Turkey | 18° | 17° | Turkey |
| `Karachi` | Univ. of Islamic Sciences, Karachi | 18° | 18° | PK, BD, IN, AF |
| `Kuwait` | Kuwait Ministry of Islamic Affairs | 18° | 17.5° | Kuwait |
| `UAQ` | Umm Al-Qura Univ., Makkah | 18.5° | +90 min | Saudi Arabia |
| `Qatar` | Qatar / Gulf Standard | 18° | +90 min | Qatar, Gulf |
| `Egypt` | Egyptian General Authority of Survey | 19.5° | 17.5° | EG, SY, IQ, LB |
| `MUIS` | Majlis Ugama Islam Singapura | 20° | 18° | Singapore |
| `MSC` | Moonsighting Committee Worldwide | seasonal | seasonal | Global |
## Dynamic Method
Standard prayer time libraries use a fixed angle (e.g., MWL: 18°) applied globally.
This works near the equator but fails at higher latitudes: above 48.5°N in summer, the
Sun never reaches 18° depression, so a 18°-everywhere library produces missing Isha
times. Observational campaigns also show that at mid-latitudes, true dawn appears when
the Sun is around 14–16° below the horizon, not 18°.
The dynamic method computes the angle in three layers:
1. **MSC seasonal base** — Khalid Shaukat's piecewise model, calibrated against field
observations across latitudes 0°–55°N/S. Returns minutes before/after sunrise/sunset,
converted to depression degrees via spherical trigonometry.
2. **Physics corrections** — Earth-Sun distance (r via Jean Meeus elliptical orbit),
Fourier harmonic smoothing, atmospheric refraction at the computed altitude, and
elevation horizon dip.
3. **Physical bounds** — clipped to [10°, 22°].
At the equator the result converges to approximately 18°, consistent with historical
usage. At 50–55°N in summer it falls to 12–14°, matching empirical UK observations.
Full detail: [Dynamic Algorithm wiki page](https://github.com/acamarata/pray-calc/wiki/Dynamic-Algorithm)
## Architecture
- Only runtime dependency: `nrel-spa` (NREL Solar Position Algorithm)
- `getSolarEphemeris` — Jean Meeus Ch. 25: declination, Earth-Sun distance, ecliptic lon
- `getTimesAll` — single batch SPA call for all 14×2 + 2 dynamic zenith angles
Full detail: [Architecture wiki page](https://github.com/acamarata/pray-calc/wiki/Architecture)
## Compatibility
- Node.js >= 20
- ESM and CJS builds included
- TypeScript types bundled
- No browser-incompatible APIs
## TypeScript
```typescript
import type {
PrayerTimes,
FormattedPrayerTimes,
PrayerTimesAll,
FormattedPrayerTimesAll,
TwilightAngles,
MethodDefinition,
} from 'pray-calc';
```
## Documentation
Full documentation: [GitHub Wiki](https://github.com/acamarata/pray-calc/wiki)
- [API Reference](https://github.com/acamarata/pray-calc/wiki/API-Reference)
- [Dynamic Algorithm](https://github.com/acamarata/pray-calc/wiki/Dynamic-Algorithm)
- [Traditional Methods](https://github.com/acamarata/pray-calc/wiki/Traditional-Methods)
- [Architecture](https://github.com/acamarata/pray-calc/wiki/Architecture)
- [Twilight Physics](https://github.com/acamarata/pray-calc/wiki/Twilight-Physics)
- [High-Latitude Handling](https://github.com/acamarata/pray-calc/wiki/High-Latitude)
## Related
- [nrel-spa](https://github.com/acamarata/nrel-spa) — NREL Solar Position Algorithm
- [luxon-hijri](https://github.com/acamarata/luxon-hijri) — Hijri/Gregorian calendar
- [moon-sighting](https://github.com/acamarata/moon-sighting) — Crescent visibility
## License
MIT. Copyright (c) 2023-2026 Aric Camarata.
See [LICENSE](LICENSE) for full terms.

130
RESEARCH.md
View file

@ -1,130 +0,0 @@
Dynamically Determining Twilight Angles for Fajr and Isha
Introduction
Accurate calculation of Fajr (dawn) and Isha (nightfall) prayer times hinges on the Sun’s depression angle under the horizon at the onset or end of twilight. Traditional prayer timetables often assume a static twilight angle (e.g. 18°, 17°, 15°) for these prayers. However, a one-size-fits-all angle is not universally valid – the true observable onset of dawn or end of dusk varies with geography and season . This report explores the most accurate methods to dynamically determine the twilight angle based on latitude, longitude, and date, instead of relying on fixed approximations. We review theoretical models of twilight, empirical observation data, and an established global algorithm to adjust the Fajr/Isha angle throughout the year. Implementation considerations (including elevation and atmospheric parameters) for integration into prayer time calculators and academic references are also discussed.
Background: Twilight and Prayer Time Calculations
In astronomical terms, twilight is the period of partial illumination before sunrise and after sunset, caused by scattering of sunlight in the upper atmosphere when the Sun is below the horizon. Twilight is commonly defined in three stages by fixed Sun depression angles :
• Civil Twilight – Sun ~6° below horizon (enough light for civil activity).
• Nautical Twilight – Sun ~12° below horizon (horizon still discernible at sea).
• Astronomical Twilight – Sun ~18° below horizon (sky almost completely dark).
For Islamic prayer times: Fajr begins at true dawn (when a faint horizontal light – “white thread” – is first visible in the sky), and Isha begins at complete nightfall (when lingering twilight disappears). Traditionally, Muslim astronomers in the 19th–20th centuries equated Fajr and Isha with astronomical twilight at 18° depression . In practice, various conventions arose: for example, calendars might use 18°, 17°, 15° or even fixed time intervals (e.g. 90 minutes) after sunset for Isha . These approximations were attempts to match the Shari’ah descriptions: Fajr at the appearance of dawn light, and Isha at the disappearance of evening glow .
Crucially, neither the Qur’an nor Hadith fixes a numeric angle for these signs  – the mandate is to follow the observable phenomena of Subh Sadiq (true dawn) and Shafaq (twilight after sunset). True dawn is defined by a broad, horizontal whitening of the eastern horizon (distinguishing it from the false dawn, a vertical light that can appear earlier), and Shafaq ends with the fading of either the red or white twilight glow in the west  . Any calculation method must therefore be grounded in reproducing these observable cues as closely as possible.
Limitations of Static Angles
Using a single fixed depression angle (be it 18°, 15°, or any value) for all locations and dates leads to errors. Observational campaigns and research have confirmed that no single degree is correct for every latitude . A static-angle method might coincidentally work in some regions (for instance, 18° is often a reasonable match near the equator ), but will be inaccurate elsewhere . Key issues include:
• High Latitude Anomalies: At higher latitudes in summer, the Sun may not sink far enough below the horizon to reach the assumed angle. For example, above ~48.5°N, the Sun never goes 18° down on summer solstice ; above ~51.5°N it never goes 15° down . This means using 18° or 15° simply fails (Fajr would absurdly never start, or Isha never end, on some days) . Even when the Sun does reach the angle on other days, it may do so very late at night. In Cambridge, UK (~52°N), Isha at 15° occurs ~2.5 hours after sunset on ordinary summer nights  – an impractically late time, illustrating “undue hardship” . Clearly, a fixed rule is untenable in such regions.
• Low/Mid Latitude Discrepancies: Even in middle latitudes and the tropics, studies have found that true dawn often occurs at a different angle than the commonly assumed 18°. In Saudi Arabia and the Gulf, the official calendars long used ~18.5°–19° for Fajr . But observations in dark-sky deserts show dawn actually breaks at around 14°–15° depression in those conditions  . Similarly, an Indonesian study (spanning 6 observatories near the equator) found Fajr light became visible at about 16.5° sun elevation, whereas the national calendar was using 20° – a difference of ~3.5° that translates to nearly 14 minutes timing error . In other words, a one-value-fits-all angle can make Fajr too early by tens of minutes in some locales, or potentially too late in others.
• Seasonal Variation: Fixed-angle methods ignore that the duration and character of twilight change with seasons. Even at a given location, the atmosphere’s illumination at (say) 18° is not constant year-round. Around equinoxes the Sun’s path is steeper, twilight is shorter, and the sky might need a slightly deeper Sun to see dawn; near summer solstice, twilight is prolonged and a shallower depression may suffice for noticeable light. Static schedules cannot capture these subtleties.
As a result of these issues, Muslim communities have faced confusion and widely varying timetables . In recent years, many have adjusted their angles downward in search of better accuracy. For example, Ulama in the UK moved from 18° to 15°, 12°, or even 9° in summer for Fajr/Isha ; and the Fiqh Council of North America shifted to 15° for Fajr based on research findings. While such fixed-angle adjustments mitigate gross errors, they remain blunt instruments. The consensus emerging from technical studies is that Fajr and Isha cannot be tied to a single fixed depression angle everywhere and every night  – rather, a dynamic, location-aware approach is needed .
Empirical Observations of Twilight Angles
Extensive observational data collected over the past decade has mapped how the “true dawn” and “true dusk” angles vary with latitude and season. Notably, the Moonsighting Committee Worldwide undertook a systematic campaign, gathering dawn/dusk observations from locations as diverse as Karachi (25°N), Durban (30°S), Sydney (34°S), Miami (26°N), Toronto (43°N), High Wycombe UK (51.6°N), and others . Their findings clearly showed no constant angle gave correct results at all these sites . Instead, the data demonstrated that the requisite Sun depression for Fajr and Isha is a function of latitude and the day of year . In other words, the twilight angle changes predictably as one moves north/south or through the seasons.
Some representative empirical results from various studies are summarized below:
• Low Latitudes (~0–30°): True dawn is typically observed when the Sun is around 16–18° below the horizon. For example, measurements in Indonesia (multiple stations around ~6°S to 7°S) found Fajr at –16.5° on average . In very clear, dark-sky conditions near the equator, the angle may approach 18° (astronomical twilight) – Moonsighting’s research suggests 18° is appropriate at the equator  – but generally not beyond that. This refines the long-held 19–20° used in some equatorial regions, which proved overly conservative.
• Mid Latitudes (~25–45°): Observations consistently show dawn/dusk occur around 14–16° depression. A comprehensive Egyptian study (multiple sites at ~26–30°N, using cameras, Sky Quality Meters, and naked-eye observers over 2015–2019) reported true dawn at a mean Sun depression of 14.56° (± ~$1σ$) . Their instrumental measurements for light intensity similarly put the threshold in the 14–15° range . An earlier campaign in Hail, Saudi Arabia (27.5°N, desert) recorded Fajr onset between 13.5° and 14.7°, averaging 14.0° . Likewise, desert observations in Libya and other Gulf areas yielded ~14.8° for dawn . These studies, conducted in pristine atmospheres free of light pollution, strongly indicate that 15° (not 18°) is closer to the true twilight angle in typical mid-latitude conditions. (The difference is significant: using 18° would make Fajr about 20–30 minutes earlier than when the dawn light is actually perceptible  .)
• High Mid-Latitudes (~45–55°): As one approaches higher latitudes, the required depression angle continues to decrease, especially around summer. For instance, at 50°N the effective Fajr angle might be on the order of 12–15° depending on season (see next section for model-based examples). Empirical community observations in the UK (mid-50s latitude) have often reported that the 18° times are too early; some local bodies set Fajr when the Sun is about 12° down during summer months, based on when a true horizontal dawn glow was actually seen. This aligns with the general trend seen in data: by ~51–52°N, even a 15° depression can coincide with an extremely faint or non-existent twilight in midsummer . Thus observed practice and recommended angles in these regions have adjusted downward for practicality and accuracy.
• Very High Latitudes (>55°): Beyond 55–60°, the summer Sun never goes far enough below the horizon to produce full darkness. Traditional angle methods break down completely here. Observations in such extreme cases are difficult (dawn and dusk blend together). Islamic juristic solutions often invoke “Sab‘ul Layl” (dividing night into seventh parts) or nearest latitude approximations rather than any twilight angle  . These areas underscore the need for special-case handling (discussed later), but the general principle is that physical twilight ceases to exist in summer above certain latitudes, so a dynamic model must gracefully transition to alternate rules.
Overall, the collective evidence from these studies is that true dawn (Subh Sadiq) typically appears when the Sun is ~14–16° below the horizon in most populated regions, and only in ideal dark conditions near the tropics does it approach 18°. Angles like 19° or 20° are nearly never observed as the point of first light – those were conservative estimates that made Fajr earlier than necessary by a wide margin . Conversely, at higher latitudes in protracted twilights, even 15° may be too deep – dawn may not break until ~12–13°. Any accurate model must capture this gradation. The next section describes how we can formulate such a model.
Theoretical Basis for Twilight Angle Variation
Why does the required twilight angle vary? Several astronomical and atmospheric factors are at play:
• Sun’s Path Inclination: The angle at which the Sun’s path intersects the horizon depends on latitude and the Sun’s declination (season). Near the equator, the Sun rises and sets almost vertically, so it plummets through the atmosphere quickly. In those conditions, by the time it reaches 18° below, the sky has only just become truly dark – hence 18° roughly marks dawn there . At higher latitudes, especially in summer, the Sun’s path is oblique to the horizon. It “skims” below the horizon at a shallow angle, prolonging twilight. This means the sky stays illuminated to some degree even at smaller depression angles. Practically, a location like 50–55°N might still have noticeable twilight at 15° or even 12° depression because the Sun is never far below the horizon for very long. The geometry of Earth’s tilt causes a seasonal effect too: around the summer solstice, the Sun’s declination is near the observer’s latitude (for example, at 54°N, the Sun’s declination at midsummer (~23.5°N) is not far off, so it never dips much below the horizon at midnight) . In winter, the Sun’s path is steeper (dec in opposite hemisphere), so twilight is shorter and a deeper depression is needed to end it.
• Atmospheric Scattering and Luminance: Twilight is produced by scattering of sunlight in the upper atmosphere. As the Sun goes further below the horizon, exponentially less sunlight reaches the lower sky. There isn’t a single “on/off” threshold; instead, brightness fades gradually. Defining dawn essentially means picking a threshold brightness at which the sky’s illumination is distinguishable from full night. Astronomers historically picked 18° as the point where the sky is astronomically dark (only ~0.001 lux illumination). But human eyes can’t detect sky illumination at such a faint level if any ambient light is present. Studies that measured sky surface brightness found that the human-visible dawn corresponds to a somewhat brighter threshold. For example, one research group noted a 0.015 cd/m² luminance threshold (mesopic vision limit) correlating with dawn at about 14°–15° depression in their data . In essence, by the time the Sun rises to ~15° below the horizon, the sky glow has intensified enough to be seen as “white thread” dawn by a dark-adapted normal eye . Below that (say at 18°), the sky is still in near-total darkness or the light is too diffuse to perceive as dawn. This explains why 18° is often too early for Fajr: the illumination exists in theory, but it’s below the visual threshold or masked by airglow/light pollution until the Sun comes a bit closer.
• “False Dawn” Phenomenon: Another consideration is false dawn (the zodiacal light – sunlight scattered by interplanetary dust along the ecliptic). This faint column of light can sometimes be mistaken for the early stages of dawn. It typically appears well before true dawn and is more prominent in certain seasons (e.g. spring) and low latitudes. Observers have noted that the full, typical shape of false dawn is not present every day and usually vanishes by about 15° sun depression . After that, the true horizontal dawn glow takes over. The presence of zodiacal light on some mornings can make it tricky to identify exactly when “first light” from the atmosphere begins, but careful studies (using color spectrum analysis and multiple criteria) have differentiated it. They find the true dawn light is indeed around the ~14–15° mark, whereas any illumination seen at deeper angles (16–18°) was often due to these other sources or instrumental sensitivity  . This further reinforces choosing a model based on actual dawn glows, not just any detectable light.
In summary, the required twilight angle is dynamic because of Earth’s axial tilt and atmospheric physics. Higher latitudes and longer twilights mean the sky stays brighter for a given solar depression, requiring a smaller angle to define “night”. Shorter twilights near the equator allow the sky to get darker, needing a larger angle to reach the dawn light threshold. Any robust model must account for these dynamics – essentially capturing the relationship between latitude, season, and the twilight phenomenon.
Dynamic Twilight Angle Models
Empirical Latitude-Season Formula (Moonsighting Method)
One of the most cited and validated dynamic models is the empirical formula developed by Moonsighting.com (often referred to as the Moonsighting Committee Worldwide method). This model explicitly computes the Fajr and Isha twilight angle (or equivalently, the time offset from sunset/sunrise) as a function of the latitude and the day of the year . It was derived by curve-fitting to a large set of observed twilight times, with careful consideration of higher-latitude edge cases. The approach can be summarized as follows:
• Baseline and Parameters: The model assumes that at the equator (lat = 0°), true dawn/dusk corresponds to 18° depression (historically used and supported by observations at low latitudes) . From this baseline, it introduces latitude-dependent adjustments. Four seasonal reference points are defined for each latitude: values corresponding to the winter solstice, spring equinox, summer solstice, and autumn equinox. These were denoted as constants A, B, C, D (in minutes of time offset) in the committee’s documentation . For Fajr, for example, at latitude φ:
• A = 75 + (28.65/55)*|φ| (minutes) – offset at winter solstice (day with shortest sunlight) .
• B = 75 + (19.44/55)*|φ| – offset at spring equinox.
• C = 75 + (32.74/55)*|φ| – offset at late spring (around May 15).
• D = 75 + (48.10/55)*|φ| – offset at summer solstice (longest day) .
(Here 75 minutes corresponds to 18° at the equator, since 75 min * 15°/hr = 18.75° ~ 18° allowing a small refraction margin .) Similar sets exist for Isha with slightly different coefficients , reflecting differences in using redness vs. whiteness criteria. These formulas produce a higher offset (thus deeper angle) in summer for Fajr – which might seem counterintuitive until one recalls that at higher latitudes in summer, 75 min might not even get you to true night, hence the need for a larger time to reach darkness.
• Seasonal Interpolation: The model then uses piecewise-linear interpolation between these anchor points throughout the year  . Essentially, from winter to spring, the required time/angle decreases, then increases toward summer, then symmetrically decreases toward autumn, and increases back to winter values. This creates a smooth annual curve for each latitude. The output of the function can be interpreted either as a time offset (minutes before sunrise for Fajr, after sunset for Isha) or converted to an equivalent depression angle via astronomical calculations. Moonsighting’s implementation chooses the “most favorable” of the empirical value vs. the 18° value for that day to avoid any anomalies . In practice, this means: for Fajr they use whichever is later (since sometimes their curve-fit might yield a slightly earlier Fajr than 18° – likely spurious, so they default to the later, more conservative time) . For Isha, they take whichever is earlier (to avoid excessively late Isha if their function overshoots on some days) . This clever step filters out outliers and ensures the model never contradicts the physical limit that 18° is the earliest possible Fajr and latest possible Isha in any case .
• High-Latitude Adjustment: The empirical formula is considered valid up to about 55° latitude . Above that, even the adjusted function can yield times that are impractical or nonexistent (since as noted, beyond ~54.5° the Sun may not reach even 12° in summer ). For the band of ~55–60°, the method falls back to a “Sab’u lail” (1/7 of the night) rule: divide the night period into 7 parts, and set Fajr = end of the last seventh, Isha = end of the first seventh . This effectively caps how short the night can be for prayer timing, based on classical juristic allowances. At even higher latitudes (above ~60–65° where periods of 24h daylight or 24h night occur), the instruction is to approximate times by reference to the nearest lower latitude or a fixed baseline (e.g., using the times of a “balanced” location or of Makkah)  . These fallbacks ensure continuity of the schedule when direct astronomical signs fail. They are consistent with juristic opinions and are implemented in a way that avoids burden (“hardship”) on practitioners  .
This Moonsighting model has been tested against observations and found to match closely. An observer from the UK noted that the calculated Fajr and Isha times from this function were, in practice, very accurate and aligned with what he observed, with any differences falling within the small day-to-day variations of the phenomenon . The model’s success lies in its blending of empirical data and sound constraints: it uses real observational curves, enforces logical boundaries (never earlier than astro dawn or later than needed), and switches to juristic rules only when the natural sign is not observable – thereby preserving Sharia compliance  .
To illustrate the dynamic nature of this model, consider the effective Sun depression angles it produces for Fajr under different conditions (approximate values based on the committee’s function and typical solar declinations):
• At 0° (equator): Year-round around 18°. (True dawn consistently when Sun ~18° below horizon , matching astronomical twilight at equator.)
• At 30° N (e.g. Houston, Cairo): Ranges roughly 17.8° – 18.6° through the year. In winter, dawn might break around 18.1°; in summer, around 17.9° depression. Essentially ~18° all year (only a few minutes variation in Fajr time) – which is why many mid-latitude countries historically chose 18° and didn’t see much issue.
• At 50° N (e.g. London, Calgary): Ranges roughly 12° – 15°. In midwinter, true dawn might correspond to ~14° depression; around equinox ~15°; at midsummer it can be as shallow as ~12° (since the Sun never goes much lower) . For example, on June 21 at 50°N, the Sun’s lowest point is only ~16.5° below horizon; dawn effectively starts when it comes up to ~12° below horizon (well before 18° which is never reached). In contrast, on December 21 at 50°N, the Sun goes far below 18°, and dawn begins later – around 14° on the way up. The model captures this by yielding a much longer night (hence smaller Fajr angle) in summer than in winter for high latitudes.
These examples show how the dynamic model adjusts the angle continuously: at low latitudes it converges to the classical 18°, but at higher latitudes it departs significantly, dropping toward ~12° in extreme cases. The net effect is to produce prayer times that match observable reality. In fact, where implemented, this model eliminates the large discrepancies and “nightlessness” gaps created by static methods . It aligns with the principle of ease and universality in Islamic timings  , while keeping fidelity to actual dawn/dusk observations.
From an integration standpoint, Moonsighting’s function (or a similar latitude/season based formula) can output a precise angle for each day and location. For instance, it might tell us that on a given date Fajr corresponds to 17.2° depression at a city in Spain, but 14.5° at a city in Scotland. A prayer time program can then simply solve for the moment the Sun’s center reaches that altitude. The function can be coded as a small routine or even pre-tabulated for efficiency. Since it’s smooth and slowly varying, it won’t cause sudden jumps in the timetable – changes are gradual over days as expected in nature.
It’s worth noting that other researchers have also attempted dynamic or hybrid models. Some Islamic committees have used a dual criteria: e.g. “18° or 1/7-night, whichever yields a later Fajr (or earlier Isha)” – which is essentially a simplified version of what the Moonsighting method does across the board. The Hizbul Ulama of UK and others have published timetables using a combination of angles (e.g. 12° in summer, 15° in spring/fall, 18° in winter) to approximate observations – again acknowledging no single angle works year-round. The Moonsighting model improves on these by providing a continuous function rather than discrete switches, and by being empirically grounded.
Theoretical/Physical Modeling Approaches
An alternative to a purely empirical fit is to use a physical model of sky luminance to determine the twilight angle dynamically. In theory, one could select a threshold of sky brightness that defines “dawn”, and compute the solar depression needed to reach that brightness given atmospheric conditions. This involves modeling how sunlight scatters through the atmosphere at different angles. Some attempts in literature use measurements of sky brightness (in magnitudes/arcsec² or cd/m²) to pinpoint when the brightness starts rising above the nighttime baseline. For example, as mentioned, one study found the sky brightness at the start of dawn corresponds to about 15° depression for the human eye threshold  . Another noted that dawn becomes visible when the blue component of sky light overtakes the other colors around ~13.5°–14° depression .
In principle, one could use standard atmospheric models (taking into account Rayleigh scattering, ozone absorption, etc.) to predict sky illumination as a function of solar altitude. By solving for when illumination equals a certain value (perhaps comparable to starlight or 0.1% of full moonlight), the corresponding sun angle is found. This astronomical model approach would inherently yield a varying angle with latitude/season, because the path length of sunlight through the atmosphere and the portion of the atmosphere being illuminated change with geometry. However, such a model is complex for real-time use – it would require numerical integration or look-up tables of atmospheric transmission, and critically, it would need inputs like aerosol content or air clarity to be accurate. The twilight brightness at 15° in a crystal-clear desert sky can differ from that in a humid or light-polluted urban sky.
For a public-facing app or general calculation, it is usually impractical to gather detailed atmospheric data for each location (e.g. aerosol optical depth, etc.). Therefore, the empirical approach effectively encodes typical atmospheric behavior in its fitted parameters. It assumes an average clear atmosphere. In most cases, this is sufficient. If a user or institution desired, they could tweak the baseline of the empirical model for their locale (for instance, if observations in a particularly light-polluted city show dawn at 12° instead of 14°, one might adjust the function output a bit). But those would be local calibrations on top of the general model.
In summary, while a theoretical radiative-transfer model of twilight could be constructed, it is far simpler and quite accurate to use the empirically derived function as described. It captures the essential variation (latitude and seasonal effect) and inherently accounts for average atmospheric scattering. For academic completeness, one can mention that the empirical model’s results (e.g. 14–15° at mid-latitudes) agree well with the theoretical expectations of when sky luminance exits the astronomical twilight zone and enters the threshold of human vision .
Integrating Elevation, Temperature, and Pressure
Any precise prayer time computation may also incorporate local environmental factors such as the observer’s elevation above sea level, and the atmospheric pressure/temperature (which affect refraction). These factors do not fundamentally change the required twilight angle (since that is defined by light reaching a certain level), but they can slightly adjust the timing of when a given depression is reached or how we interpret depression angles:
• Elevation: A higher observation point means a lower effective horizon. The observer can see further “around” the Earth’s curvature, so the Sun appears higher than it would at sea level (conversely, the geometric depression angle to the Sun is less for the same apparent sky brightness). In practical terms, being at a high elevation will make dawn come earlier and Isha later. For example, at 1000 m elevation, the horizon dips by about 1° extra (the exact formula is $\approx 1.06^\circ \times \sqrt{\text{height in km}}$), so one might detect dawn a few minutes sooner . Calculation-wise, one can add the horizon dip angle to the depression: if the model says dawn at -15°, but you’re on a mountain giving 1° additional depression of view, then you might use -14° for that location. Many sunrise/sunset calculators include this correction (e.g., subtracting a certain number of minutes for elevation). A rule of thumb: ~1 minute earlier per 100 m of elevation for sunrise (and similarly delay sunset). A dynamic prayer time algorithm could incorporate elevation by reducing the required depression angle slightly. In the Moonsighting method, they partially account for this under “downward sloping ground” considerations . In summary, including elevation will fine-tune the result – it’s recommended for a public app to at least allow an elevation input.
• Atmospheric Refraction (Pressure/Temperature): Standard calculations assume average pressure (1013 hPa) and temperature (10°C) for refraction near the horizon. At the horizon, refraction bends the Sun’s rays about 34′ (0.566°) upward , effectively allowing us to see the Sun (or twilight) when it’s slightly below the geometric horizon. Most algorithms incorporate this by using a “sun altitude = -0.833°” for sunrise (0.5° Sun diameter + 0.333° refraction) . For twilight at -15° or -18°, the refraction is much smaller (only a few arcminutes) because the light is coming through higher, thinner atmosphere. However, if pressure is unusually low (e.g. at high altitude or a high-pressure weather system), refraction is reduced, and the sky might get dark slightly sooner. Conversely, very cold dense air can increase refraction. To be precise, one could apply the standard refraction formula $R \approx (P/1010)\times(283/(273+T))\times1.02/\tan(a+10.3/(a+5.11))$ (with $a$ in degrees)  for the altitude in question. But for simplicity, many implementations just allow the user to input pressure/temperature to adjust the refraction term. The difference this makes for Fajr/Isha (sun ~15° down) is on the order of 0.1° or less, which corresponds to perhaps 1 minute timing difference – largely negligible for most needs. It’s more relevant for the exact sunrise/sunset time. Indeed, Moonsighting.com notes that actual sunset can be ~3 minutes later than calculated if pressure/humidity are high , due to extended refraction keeping the Sun visible . For Fajr/Isha, such extreme refraction scenarios (thick atmosphere near horizon) are not directly applicable since the Sun is well below horizon.
• Temperature/Humidity: These affect refraction (as above) and also the transparency of the air. Very humid or hazy air might block faint light from low in the sky, effectively delaying the visible dawn (needing Sun to come higher). Conversely, very clear air can transmit faint twilight better. These factors are hard to quantify without local observation. If needed, one could introduce a small “fudge factor” in the angle for extremely different conditions. For example, an exceptionally light-polluted city might decide to use a shallower angle (like 1° less) because the faint twilight isn’t visible until later. Such adjustments would be empirical. A sophisticated app could offer a “twilight sensitivity” setting, but this is usually not done. It’s reasonable to assume a standard clear atmosphere for the model, which gives a safe, slightly early Fajr (and late Isha) in places with obscured horizons – this erring on safety is acceptable in religious context.
In implementation, incorporating these factors means: after computing the base angle from the latitude/date model, you apply corrections: e.g. subtract the observer’s horizon dip angle due to elevation, and possibly adjust for non-standard refraction. As an example, suppose the base model gives Fajr at -15.0°. If the observer is at 500 m elevation, horizon dip ~0.5°, so one could use -14.5° for final calculation (meaning Fajr a minute or two earlier). If pressure is, say, 5% below standard (roughly equivalent to being at 500 m elevation as well), that might reduce refraction slightly and one might negligibly tweak another 0.1°. These are minor refinements – the dominant factor is still the geometric model of twilight.
Moonsighting’s published schedules implicitly assume an average horizon (they even add a blanket +3 minutes to Maghrib for safety in case of atmospheric variance ). For academic rigor and maximum accuracy, it’s good to mention that our dynamic angle model can indeed integrate such parameters. The underlying astronomical calculations (for converting angle to time) already use those parameters, so it’s straightforward: any public code (like NOAA’s solar calculator) allows input of observer elevation and conditions, ensuring the resulting times are as precise as possible.
Integration into Applications and Wiki
For a public-facing website or app, the dynamic twilight angle model would be implemented as a part of the prayer time calculation algorithm. Typically, calculating prayer times involves computing solar declination and altitude for the given date, and solving for when certain altitudes occur. With a static angle, one would plug in e.g. -18° for Fajr. With the dynamic model, the workflow becomes:
1. Input: Date, latitude, longitude (and optionally elevation, pressure, etc.). Also the user’s chosen calculation method – in this case we’ll call it “Dynamic Twilight Angle” method (perhaps labeled as “Moonsighting Global method” or similar in the app settings).
2. Compute Sun Declination: (This is standard – needed to compute sunrise etc. The app likely already does this via known equations or an ephemeris library.)
3. Determine Twilight Depression Angle: Using the latitude and day-of-year, compute the recommended Sun depression for Fajr and for Isha. This is done via the function or formula described. This function could be hard-coded from the piecewise equations  . (The code provided by Moonsighting is open-source and could be reused; for instance, an implementation in pseudocode is given in the appendix of their documentation, which we could translate to our app’s language.) The output might be, for example, Fajr_angle = 14.7°, Isha_angle = 14.9° for a particular location/date. These angles can have one decimal or two decimals of precision – the model is continuous so one can get a value like 14.72° if desired. (That level of precision is academically interesting, though in reality a minute of time corresponds to ~0.25° at these depressions, so 0.1° precision is more than enough.)
4. Compute Times from Angles: With the target angle now known for that day, the program computes the time at which the Sun’s center reaches that angle below the horizon in the morning (for Fajr) and evening (for Isha). This involves solving the solar altitude equation: $\sin h = \sin\phi\sin\delta + \cos\phi\cos\delta\cos H$ for $h = -\text{(twilight angle)}$. Many prayer time libraries already have a routine for “compute time when Sun is at X°”. We just feed it our dynamic X instead of a constant. Because the angle can vary day to day, it’s important to compute it fresh each day. (For efficiency, one could pre-compute a year’s worth in advance since the pattern repeats annually, barring slight differences in declination for different years.)
5. Apply Elevation/Refraction Corrections: If the app allows user elevation, adjust the computed time by a minute or two as appropriate (or modify the angle as discussed before solving). Similarly, ensure the solar position calculation itself accounts for standard refraction (most algorithms do). If a user wants extreme accuracy, they could input local pressure and temperature, and the calculation of the Sun’s altitude will then be corrected accordingly.
6. Output: The app then outputs the Fajr and Isha times along with the other prayers. The resulting times will smoothly adjust through the seasons. For example, in a high-latitude city, the app might show Isha getting later from winter into spring, then perhaps stalling or even disappearing in June (where it might note “Twilight does not reach darkness – using 1/7-night method” and give a time around midnight). Then Isha times would start reappearing earlier after summer solstice. All of this would be handled behind the scenes by the dynamic angle logic. The user just sees that their prayer times match observed reality (no more extremely early Fajr that they cannot see any light for, etc.).
For an academic wiki or documentation, one would present the formula and perhaps a graph or table of how the twilight angle varies. For instance, one could include a table like:
Latitude Fajr Angle (Winter Solstice) Fajr Angle (Summer Solstice)
0° (Equator) ~18.0°  ~18.0° 
30° N (Mid-latitude) ~18.1° ~17.9°
50° N (High-latitude) ~14.1° ~12.0°
Approximate Sun depression angles for Fajr at different latitudes and seasons. (Winter = around Dec/Jan; Summer = June/July. Higher latitudes show significantly smaller angles in summer.)
Such a table gives a quick sense of scale – e.g. at 50°N in summer, Fajr isn’t until the Sun is only 12° below, whereas at 0° it’s still ~18°. These values can be backed up by the observational studies cited (indeed ~12–15° for 50°N matches UK observations, and ~18° at equator is historically used)  .
A figure could also be used, for example plotting the twilight angle vs. month for a given latitude. This would show a gently oscillating curve. If needed, one could overlay observational data points to demonstrate the fit. In a technical report or wiki, including the piecewise formula (perhaps in an appendix or footnote) would be useful for transparency, along with references to its source. For instance, one might include the citation: “Moonsighting Committee’s formula defines Fajr depression in minutes after sunset (or before sunrise) as $f(\phi, n) = A(\phi)+…$ etc” . However, for most readers, a descriptive summary as given above suffices, with citations to the Moonsighting research to instill confidence.
Conclusion
After examining both theoretical considerations and extensive empirical evidence, it is clear that the most accurate method for determining Fajr and Isha prayer times is to use a dynamic twilight angle that varies with location and date, rather than any static approximation. The established model by Moonsighting.com provides a practical, well-tested implementation of this principle, yielding depression angles that closely match observed true dawn and dusk across the globe  . By incorporating this model, a prayer timetable can output precise angles (e.g. 17.2° or 14.5° as needed) for each day, which translate into correct prayer times. This approach preserves the integrity of the Shari’ah-defined signs (dawn light and disappearing twilight) in a way that static methods could not, especially in challenging high-latitude environments  .
Furthermore, this dynamic method can be augmented with local parameters – adjusting for observer elevation and actual atmospheric conditions – to refine the calculations to minute-level accuracy. These adjustments are relatively minor but are a welcome addition for completeness, ensuring the model remains robust under different conditions (for instance, giving slightly earlier Fajr for a mountaintop observatory, as would be expected physically).
In summary, the recommended solution for integration into prayer time applications and academic references is: Adopt a latitude- and season-dependent twilight angle algorithm (such as the Moonsighting empirical function), with high-latitude fallbacks and optional refraction/elevation corrections. This yields a system that is adaptive, precise, and validated by observation – meeting the needs of both end-users (who get reliable prayer times year-round) and scholars (who require that the method be grounded in observable reality and sound astronomy). By implementing this, one can avoid the pitfalls of static rules and ensure that Fajr and Isha truly correspond to the first light of dawn and last light of dusk as witnessed in the sky  .
Sources:
• Empirical twilight angle observations and global function derivation   
• Discussion of static method problems at high latitudes  
• Integration of atmospheric factors in timing calculations  .

37
calcTimes.js
View file

@ -1,37 +0,0 @@
const { fractalTime } = require('nrel-spa');
const { getTimes } = require('./getTimes');
/**
* Calculates Islamic prayer times.
*
* @param {Date} date - Date for which prayer times are calculated.
* @param {number} lat - Latitude of the location.
* @param {number} lng - Longitude of the location.
* @param {number} [elevation=10] - Elevation in meters (default 10).
* @param {number} [temperature=15] - Temperature in Celsius (default 15).
* @param {number} [pressure=1013.25] - Atmospheric pressure in millibars (default 1013.25).
* @returns {Object} - Object containing prayer times.
*/
function calcTimes(date, lat, lng, tz, elevation = 50, temperature = 15, pressure = 1013.25) {
let result = getTimes(date, lat, lng, tz, elevation, temperature, pressure);
// Sort the result object by their values, excluding "Angle"
let sortedEntries = Object.entries(result)
.filter(([key]) => key !== "Angles")
.sort(([, a], [, b]) => a - b);
// Apply fractalTime on all sorted entries (except "Angle")
let sortedAndFormatted = sortedEntries.reduce((acc, [key, value]) => {
acc[key] = fractalTime(value);
return acc;
}, {});
// Add the "Angle" at the end
sortedAndFormatted["Angles"] = result["Angles"];
return sortedAndFormatted;
}
module.exports = {
calcTimes
};

40
calcTimesAll.js
View file

@ -1,40 +0,0 @@
const { fractalTime } = require('nrel-spa');
const { getTimesAll } = require('./getTimesAll');
function calcTimesAll(date, lat, lng, tz, elevation = 10, temperature = 15, pressure = 1013.25) {
let result = getTimesAll(date, lat, lng, tz, elevation, temperature, pressure);
// Sort the methods by Fajr time
let sortedMethods = Object.entries(result.Methods)
.sort((a, b) => a[1][0] - b[1][0])
.reduce((acc, [key, value]) => {
acc[key] = value;
return acc;
}, {});
// Format the times inside sorted Methods
Object.entries(sortedMethods).forEach(([methodName, times]) => {
sortedMethods[methodName] = times.map(time => fractalTime(time));
});
// Sort and format the other prayer times, excluding "Angles" and "Methods"
let sortedEntries = Object.entries(result)
.filter(([key]) => key !== "Angles" && key !== "Methods")
.sort(([, a], [, b]) => a - b);
// Apply fractalTime on all sorted entries
let sortedAndFormatted = sortedEntries.reduce((acc, [key, value]) => {
acc[key] = fractalTime(value);
return acc;
}, {});
// Add the formatted "Methods" and "Angles" to the result
sortedAndFormatted["Methods"] = sortedMethods;
sortedAndFormatted["Angles"] = result["Angles"];
return sortedAndFormatted;
}
module.exports = {
calcTimesAll
};

78
getAngles.js
View file

@ -1,78 +0,0 @@
// getAngles.js
'use strict';
const PI = Math.PI;
/**
* Calculate dynamic Fajr and Isha depression angles based on latitude, date (season),
* with adjustments for refraction and observer elevation.
*
* @param {Date} date Calculation date
* @param {number} lat Latitude in degrees
* @param {number} lng Longitude (currently unused but kept for compatibility)
* @param {number} [elevation=0] Observer elevation in meters
* @param {number} [temperature=15] Temperature in °C
* @param {number} [pressure=1013.25] Atmospheric pressure in mbar
* @returns {{ fajrAngle: number, ishaAngle: number }} Twilight angles in degrees
*/
function getAngles(date, lat, lng, elevation = 0, temperature = 15, pressure = 1013.25) {
// 1) Compute day of year
const startOfYear = Date.UTC(date.getUTCFullYear(), 0, 0);
const dayOfYear = Math.floor((date - startOfYear) / 86400000);
// 2) Latitude factor (normalized from 0 at equator to 1 at 55° latitude)
const latitudeFactor = Math.min(Math.abs(lat) / 55, 1);
// 3) Approximate solar declination δ (in radians)
const declRad = 23.44 * Math.sin((2 * PI * (dayOfYear + 284)) / 365) * (PI / 180);
// 4) Seasonal factor (ranges -1 to +1)
const seasonalFactor = Math.sin(declRad);
// 5) Twilight angle calculation
const baseAngle = 18.0;
const latitudeAdjustment = 4.0 * latitudeFactor; // varies up to ±4°
const seasonalAdjustment = 1.5 * seasonalFactor; // varies up to ±1.5°
const dynamicAngle = baseAngle - latitudeAdjustment - seasonalAdjustment;
// 6) Calculate refraction (minimal at large angles, thus simplified)
const refraction = calculateAtmosphericRefraction(-dynamicAngle, pressure, temperature);
// 7) Elevation adjustment (~0.1° per 1000m)
const elevationAdjustment = (elevation / 1000) * 0.1;
// 8) Final adjusted angles
const fajrAngle = dynamicAngle + refraction + elevationAdjustment;
const ishaAngle = dynamicAngle - refraction - elevationAdjustment;
return { fajrAngle: roundAngle(fajrAngle), ishaAngle: roundAngle(ishaAngle) };
}
/**
* Compute atmospheric refraction correction.
* Simplified for twilight angles (negative altitude).
*
* @param {number} altitude - Solar altitude in degrees
* @param {number} pressure - Atmospheric pressure in mbar
* @param {number} temperature - Temperature in °C
* @returns {number} Refraction correction in degrees
*/
function calculateAtmosphericRefraction(altitude, pressure = 1013.25, temperature = 15) {
if (altitude >= 0) altitude = -0.1; // ensure negative for twilight
const altRad = altitude * (PI / 180);
const R = (pressure / 1010) * (283 / (273 + temperature)) * (1.02 / Math.tan(altRad + 10.3 / (altRad + 5.11))) / 60;
return Math.abs(R); // positive correction
}
/**
* Helper to round angles to 3 decimal places.
*
* @param {number} angle
* @returns {number}
*/
function roundAngle(angle) {
return Math.round(angle * 1000) / 1000;
}
module.exports = { getAngles };

66
getAsr.js
View file

@ -1,66 +0,0 @@
// getAsr.js
'use strict';
const { SpaData, spa_calculate, SPA_ZA_RTS } = require('nrel-spa/dist/spa');
/**
* Compute Asr time (fractional hours) for a given date and location.
*
* @param {Date} date - Local date/time for the calculation.
* @param {number} latitude - Observer latitude in decimal degrees.
* @param {number} longitude - Observer longitude in decimal degrees.
* @param {number} timezone - Timezone offset from UTC in hours (negative west).
* @param {boolean}[standard] - true for Shāfiʿī (shadow=1), false for Ḥanafī (shadow=2).
* @returns {number|null} Fractional‐hour Asr time (local), or null if unreachable.
*/
function getAsr(date, latitude, longitude, timezone, standard = true) {
// Load inputs into SPA struct
const data = new SpaData();
data.year = date.getFullYear();
data.month = date.getMonth() + 1;
data.day = date.getDate();
data.hour = date.getHours();
data.minute = date.getMinutes();
data.second = date.getSeconds();
data.delta_ut1 = 0.0;
data.delta_t = 67.0;
data.timezone = timezone;
data.longitude = longitude;
data.latitude = latitude;
data.elevation = 0.0;
data.pressure = 1013.0;
data.temperature = 15.0;
data.slope = 0.0;
data.azm_rotation = 0.0;
data.atmos_refract = 0.5667;
data.function = SPA_ZA_RTS;
// Perform SPA calculation
if (spa_calculate(data) !== 0) return null;
// Convert angles to radians
const φ = latitude * Math.PI / 180;
const δ = data.delta * Math.PI / 180;
const transit = data.suntransit; // fractional‐hour solar noon
// Compute required solar elevation A for Asr:
const shadowFactor = standard ? 1 : 2;
const X = Math.abs(φ - δ);
const opp = 1;
const adj = shadowFactor + Math.tan(X);
const hyp = Math.hypot(opp, adj);
const sinA = opp / hyp;
// Solve hour‐angle H0: cos(H0) = (sinA - sinφ·sinδ) / (cosφ·cosδ)
const cosH0 = (sinA - Math.sin(φ) * Math.sin(δ)) /
(Math.cos(φ) * Math.cos(δ));
if (cosH0 < -1 || cosH0 > 1) return null; // sun never reaches A
// Convert H0 (rad) to hours
const H0h = (Math.acos(cosH0) * 180 / Math.PI) / 15;
// Asr time = solar noon + H0h
return transit + H0h;
}
module.exports = { getAsr };

29
getEarthSunDistance.js
View file

@ -1,29 +0,0 @@
function getEarthSunDistance(date) {
// Constants
const a = 149597870.7; // Semi-major axis of Earth's orbit in km
const e = 0.0167086; // Orbital eccentricity of Earth
// Calculate the day of the year
const start = new Date(date.getFullYear(), 0, 0);
const diff = date - start;
const oneDay = 86400000; // Milliseconds in one day
const dayOfYear = Math.floor(diff / oneDay);
// Approximate the mean anomaly
const g = 357.529 + 0.98560028 * dayOfYear;
// Convert to radians
const gInRadians = g * Math.PI / 180;
// Use the approximation for the true anomaly (v)
const v = gInRadians + (1.914 * Math.sin(gInRadians)); // in radians
// Calculate the distance
const r = a * (1 - e * e) / (1 + e * Math.cos(v));
return r;
}
module.exports = {
getEarthSunDistance
};

125
getMSC.js
View file

@ -1,125 +0,0 @@
// getMSC.js
'use strict';
/**
* Base class for Moonsighting.com seasonal interpolation algorithm.
* Computes a day-of-year offset (dyy) from the nearest solstice and
* interpolates minutes for Fajr (before sunrise) or Isha (after sunset).
*/
class PrayerTimes {
constructor(date, latitude) {
this.date = new Date(date.getFullYear(), date.getMonth(), date.getDate());
this.latitude = latitude;
this.year = this.date.getFullYear();
this.daysInYear = isLeapYear(this.year) ? 366 : 365;
this.computeDyy();
}
computeDyy() {
// Reference solstice: Dec 21 (Northern Hemisphere) or Jun 21 (Southern)
const northSolstice = new Date(this.year, 11, 21);
const southSolstice = new Date(this.year, 5, 21);
const zeroDate = this.latitude >= 0 ? northSolstice : southSolstice;
let diffDays = Math.floor((this.date - zeroDate) / 86400000);
if (diffDays < 0) diffDays += this.daysInYear;
this.dyy = diffDays;
}
getMinutesSegment() {
const { a, b, c, d, dyy, daysInYear } = this;
if (dyy < 91) {
return a + ((b - a) / 91) * dyy;
} else if (dyy < 137) {
return b + ((c - b) / 46) * (dyy - 91);
} else if (dyy < 183) {
return c + ((d - c) / 46) * (dyy - 137);
} else if (dyy < 229) {
return d + ((c - d) / 46) * (dyy - 183);
} else if (dyy < 275) {
return c + ((b - c) / 46) * (dyy - 229);
} else {
const len = daysInYear - 275;
return b + ((a - b) / len) * (dyy - 275);
}
}
}
/**
* Fajr: returns minutes before sunrise.
*/
class Fajr extends PrayerTimes {
constructor(date, latitude) {
super(date, latitude);
const latAbs = Math.abs(latitude);
this.a = 75 + (28.65 / 55) * latAbs;
this.b = 75 + (19.44 / 55) * latAbs;
this.c = 75 + (32.74 / 55) * latAbs;
this.d = 75 + (48.10 / 55) * latAbs;
}
getMinutesBeforeSunrise() {
return Math.round(this.getMinutesSegment());
}
}
/**
* Isha: returns minutes after sunset.
*/
class Isha extends PrayerTimes {
static SHAFAQ_GENERAL = 'general';
static SHAFAQ_AHMER = 'ahmer';
static SHAFAQ_ABYAD = 'abyad';
constructor(date, latitude, shafaq = Isha.SHAFAQ_GENERAL) {
super(date, latitude);
this.setShafaq(shafaq);
}
setShafaq(shafaq) {
this.shafaq = shafaq;
const latAbs = Math.abs(this.latitude);
switch (shafaq) {
case Isha.SHAFAQ_AHMER:
this.a = 62 + (17.4 / 55) * latAbs;
this.b = 62 - (7.16 / 55) * latAbs;
this.c = 62 + (5.12 / 55) * latAbs;
this.d = 62 + (19.44 / 55) * latAbs;
break;
case Isha.SHAFAQ_ABYAD:
this.a = 75 + (25.6 / 55) * latAbs;
this.b = 75 + (7.16 / 55) * latAbs;
this.c = 75 + (36.84 / 55) * latAbs;
this.d = 75 + (81.84 / 55) * latAbs;
break;
default: // general
this.a = 75 + (25.6 / 55) * latAbs;
this.b = 75 + (2.05 / 55) * latAbs;
this.c = 75 - (9.21 / 55) * latAbs;
this.d = 75 + (6.14 / 55) * latAbs;
break;
}
}
getMinutesAfterSunset() {
return Math.round(this.getMinutesSegment());
}
}
function isLeapYear(year) {
return (year % 4 === 0 && year % 100 !== 0) || (year % 400 === 0);
}
function getFajr(date, latitude) {
return new Fajr(date, latitude).getMinutesBeforeSunrise();
}
function getIsha(date, latitude, shafaq = Isha.SHAFAQ_GENERAL) {
return new Isha(date, latitude, shafaq).getMinutesAfterSunset();
}
module.exports = { getFajr, getIsha, Isha, Fajr };

40
getMoon.js
View file

@ -1,40 +0,0 @@
const { getMoonPhase } = require('./getMoonPhase');
const { getMoonPosition } = require('./getMoonPosition');
const { getMoonIllumination } = require('./getMoonIllumination');
const { getMoonVisibility } = require('./getMoonVisibility');
/**
* Calculates detailed moon visibility information.
*
* @param {Date} date - The date for which to calculate moon data.
* @param {number} [latitude=0] - Observer's latitude in decimal degrees.
* @param {number} [longitude=0] - Observer's longitude in decimal degrees.
* @param {number} [elevation=50] - Observer's elevation in meters above sea level. Default is 50 meters.
* @param {number} [temp=15] - Ambient temperature in degrees Celsius. Default is 15°C.
* @param {number} [pressure=1013.25] - Atmospheric pressure in hPa. Default is 1013.25 hPa (average sea level pressure).
* @param {number} [humidity=50] - Humidity in percentage. Default is 50%.
* @param {number} [clouds=0] - Cloudiness in percentage. Default is 0% (clear sky).
* @returns {Object} An object containing moon details: phase, position, illumination, and visibility.
*/
function getMoon(date, latitude = 0, longitude = 0, elevation = 50, temp = 15, pressure = 1013.25, humidity = 50, clouds = 0) {
const phase = getMoonPhase(date);
const position = getMoonPosition(date, latitude, longitude);
const illumination = getMoonIllumination(date);
const phaseName = ["New Moon", "Waxing Crescent", "First Quarter", "Waxing Gibbous", "Full Moon", "Waning Gibbous", "Last Quarter", "Waning Crescent"][Math.floor(phase * 8)] || "New Moon";
const phaseSymbol = ["🌑", "🌒", "🌓", "🌔", "🌕", "🌖", "🌗", "🌘"][Math.floor(phase * 8)] || "🌑";
// Calculate visibility considering all factors
const visibility = getMoonVisibility(phase, position, illumination, elevation, temp, pressure, humidity, clouds);
return {
phase,
phaseName,
phaseSymbol,
position,
illumination,
visibility
};
}
module.exports = { getMoon };

19
getMoonIllumination.js
View file

@ -1,19 +0,0 @@
// Import the SunCalc library
const suncalc = require('suncalc');
/**
* Calculates the moon's illumination for a given phase.
* @param {number} phase - The phase of the moon, from 0 (new moon) to 1 (full moon).
* @returns {Object} The moon's illumination details.
*/
function getMoonIllumination(date) {
const illuminationDetails = suncalc.getMoonIllumination(date);
return {
fraction: illuminationDetails.fraction, // Illuminated fraction of the moon; 0 = new moon, 1 = full moon
phase: illuminationDetails.phase, // Moon phase (0 to 1)
angle: illuminationDetails.angle // Angle in radians of the moon's bright limb
};
}
module.exports = { getMoonIllumination };

23
getMoonPhase.js
View file

@ -1,23 +0,0 @@
/**
* Calculates the current phase of the moon as a fraction.
* @param {Date} date - The date for which to calculate the moon phase.
* @returns {number} The moon phase as a fraction from 0 (new moon) to just under 1 (end of lunar cycle).
*/
function getMoonPhase(date) {
const synodicMonth = 29.53058821398858; // Average length of a synodic month in days
// Most recent known new moon: November 13, 2023, 09:27 AM UTC
const knownNewMoon = new Date(Date.UTC(2023, 10, 13, 9, 27, 0));
// Convert both dates to the number of milliseconds since Unix Epoch and find the difference
const diffInMilliseconds = date - knownNewMoon;
// Convert the difference to days
const diffInDays = diffInMilliseconds / 1000 / 60 / 60 / 24;
// Calculate the phase as a fraction of the synodic month
const phase = (diffInDays % synodicMonth) / synodicMonth;
return phase;
}
module.exports = { getMoonPhase };

26
getMoonPosition.js
View file

@ -1,26 +0,0 @@
// Import the SunCalc library
const suncalc = require('suncalc');
/**
* Calculates detailed moon position information.
* @param {Date} date - The date and time for which to calculate the position.
* @param {number} latitude - Observer's latitude in decimal degrees.
* @param {number} longitude - Observer's longitude in decimal degrees.
* @returns {Object} The moon's position (azimuth, altitude), distance, and parallactic angle.
*/
function getMoonPosition(date, latitude, longitude) {
const moonPosition = suncalc.getMoonPosition(date, latitude, longitude);
// Convert azimuth and altitude from radians to degrees
const azimuth = moonPosition.azimuth * 180 / Math.PI;
const altitude = moonPosition.altitude * 180 / Math.PI;
return {
azimuth,
altitude,
distance: moonPosition.distance, // distance to moon in kilometers
parallacticAngle: moonPosition.parallacticAngle // parallactic angle in radians
};
}
module.exports = { getMoonPosition };

56
getMoonVisibility.js
View file

@ -1,56 +0,0 @@
/**
* Calculates detailed moon visibility information.
*
* @param {number} phase - The phase of the moon, from 0 (new moon) to 1 (next full moon).
* @param {Object} position - { azimuth, altitude, distance (km), parallacticAngle (radians) }
* @param {Object} illumination - { fraction, phase, angle }
* @param {number} [elevation=50] - Observer's elevation in meters above sea level. Default is 50 meters.
* @param {number} [temp=15] - Ambient temperature in degrees Celsius. Default is 15°C.
* @param {number} [pressure=1013.25] - Atmospheric pressure in hPa. Default is 1013.25 hPa (average sea level pressure).
* @param {number} [humidity=50] - Humidity in percentage. Default is 50%.
* @param {number} [clouds=0] - Cloudiness in percentage. Default is 0% (clear sky).
* @returns {Object} An object containing moon details: phase, position, illumination, and visibility.
*/
function getMoonVisibility(phase, position = 0, illumination = 0, elevation = 50, temp = 15, pressure = 1013.25, humidity = 50, clouds = 0) {
/** Placeholder Simplified Algorithm...
* This is a very simplified algorithm that is not intended to be precise or accurate.
* It is loosely based on average observations from astronomy journals and other sources.
* Using a window of earliest general visibility until near definite visibility is reached.
*/
// Convert Phase from 0-1 to be 0 (full moon) to 0.5 (new moon) scale
const aphase = (phase - 0.5) < 0 ? -(phase - 0.5) : (phase - 0.5);
// Get synodic month and phase hour for adjustic moon phase
const sMonth = 29.530588861;
const phaseHour = 1 / 24 / sMonth; // ~ 0.001410966333
const ahour = phaseHour / 2; // ~ 0.0007054831663
// Get estimated visibility window of a new moon (and ending)
const v1 = ahour * 15; // ~ 0.01058224749
const v2 = ahour * 30; // ~ 0.02116449499
const w1 = 0.5 - v1; // ~ 0.48941775251
const w2 = 0.5 - v2; // ~ 0.47883550501
const win = w1 - w2; // ~ 0.01058224749
let visibility = 0;
if (aphase < w2) {
visibility = 1;
} else if (aphase < w1) {
visibility = (w1 - aphase) / win;
}
return visibility;
}
module.exports = { getMoonVisibility };
/* console.log(getMoonVisibility(0.010));
console.log(getMoonVisibility(0.012));
console.log(getMoonVisibility(0.014));
console.log(getMoonVisibility(0.016));
console.log(getMoonVisibility(0.018));
console.log(getMoonVisibility(0.020));
console.log(getMoonVisibility(0.022)); */

17
getQiyam.js
View file

@ -1,17 +0,0 @@
function getQiyam(fajrTime, ishaTime) {
// Adjust Fajr time if it is earlier than Isha time
const adjustedFajrTime = fajrTime < ishaTime ? fajrTime + 24 : fajrTime;
// Calculate the length of the night
const nightLength = adjustedFajrTime - ishaTime;
// Calculate the start of the last third of the night
const lastThirdStart = ishaTime + (2 * nightLength / 3);
// If the result is greater than 24, adjust it to get the correct time
return lastThirdStart > 24 ? lastThirdStart - 24 : lastThirdStart;
}
module.exports = {
getQiyam
};

71
getTimes.js
View file

@ -1,71 +0,0 @@
// getTimes.js
const { getSpa } = require('nrel-spa');
const { getAngles } = require('./getAngles');
const { getAsr } = require('./getAsr');
const { getQiyam } = require('./getQiyam');
/**
* Compute all prayer times for a given date and location.
*
* @param {Date} date - Local date for calculation
* @param {number} lat - Latitude in decimal degrees
* @param {number} lng - Longitude in decimal degrees
* @param {number} [tz] - Timezone offset from UTC in hours (default: derived from date)
* @param {number} [elevation] - Observer elevation in meters (default: 50)
* @param {number} [temperature]- Ambient temperature in °C (default: 15)
* @param {number} [pressure] - Atmospheric pressure in mbar (default: 1013.25)
* @param {boolean} [standard] - true=Shāfiʿī (shadow factor 1), false=Ḥanafī (factor 2)
*
* @returns {Object} prayer times (fractional hours for Fajr, Sunrise, Dhuhr, Asr, Maghrib, Isha), plus Qiyam and angles
*/
function getTimes(
date,
lat,
lng,
tz = -date.getTimezoneOffset() / 60,
elevation = 50,
temperature = 15,
pressure = 1013.25,
standard = true
) {
// 1️⃣ Compute Fajr/Isha angles
const { fajrAngle, ishaAngle } = getAngles(date, lat, lng, elevation, temperature, pressure);
// 2️⃣ Get core SPA output with custom angles
const spaParams = { elevation, temperature, pressure };
const spaData = getSpa(date, lat, lng, tz, spaParams, [fajrAngle + 90, ishaAngle + 90]);
// Basic prayer times (fractional hours)
const fajrTime = spaData.angles[0].sunrise;
const sunriseTime = spaData.sunrise;
const noonTime = spaData.solarNoon;
const dhuhrTime = spaData.solarNoon + (2.5 / 60);
const maghribTime = spaData.sunset;
const ishaTime = spaData.angles[1].sunset;
// 3️⃣ Calculate Asr (fractional hours)
// Build a Date for solar noon in local time
const hn = Math.floor(noonTime);
const mn = Math.floor((noonTime - hn) * 60);
const sn = Math.floor(noonTime * 3600 - hn * 3600 - mn * 60);
const solarNoonDate = new Date(date);
solarNoonDate.setHours(hn, mn, sn, 0);
const asrTime = getAsr(solarNoonDate, lat, lng, tz, standard);
// 4️⃣ Calculate Qiyam (last third of the night)
const qiyamTime = getQiyam(fajrTime, ishaTime);
return {
Qiyam: qiyamTime,
Fajr: fajrTime,
Sunrise: sunriseTime,
Noon: noonTime,
Dhuhr: dhuhrTime,
Asr: asrTime,
Maghrib: maghribTime,
Isha: ishaTime,
Angles: [fajrAngle, ishaAngle]
};
}
module.exports = { getTimes };

92
getTimesAll.js
View file

@ -1,92 +0,0 @@
const { getSpa } = require('nrel-spa');
const { getAngles } = require('./getAngles');
const { getAsr } = require('./getAsr');
const { getQiyam } = require('./getQiyam');
const { getFajr, getIsha } = require('./getMSC');
const methods = [
{n:'UOIF', f:12, i:12, r:'France'},
{n:'ISNACA', f:13, i:13, r:'Canada'},
{n:'ISNAUS', f:15, i:15, r:'US, UK'},
{n:'SAMR', f:16, i:15, r:'RU'},
{n:'MWL', f:18, i:17, r:'EU, US, Asia'},
{n:'DIBT', f:18, i:17, r:'TR'},
{n:'Karachi', f:18, i:18, r:'PK, BD, IN, AF, EU'},
{n:'UAQ', f:18.5, i:18, r:'SA'},
{n:'Egypt', f:19.5, i:17.5, r:'Africa, SY, IQ, LB'},
{n:'MUIS', f:20, i:18, r:'SG'},
{n:'MSC', f:null, i:null, r:'Global'},
];
function getTimesAll(date, lat, lng, tz, elevation = 50, temperature = 15, pressure = 1013.25, standard = true) {
// Step 1: Get the custom angles
const { fajrAngle, ishaAngle } = getAngles(date, lat, lng, elevation, temperature, pressure);
const methodAngles = methods.map(m => [m.f + 90, m.i + 90]);
// Step 2: Get SPA data with custom angle for Fajr/Isha and other methods
const spaParams = { elevation, temperature, pressure };
const spaData = getSpa(date, lat, lng, tz, spaParams, [fajrAngle + 90, ishaAngle + 90, ...methodAngles.flat()]);
// Organize prayer times
const fajrTime = spaData.angles[0].sunrise;
const sunriseTime = spaData.sunrise;
const noonTime = spaData.solarNoon;
const dhuhrTime = spaData.solarNoon + ((1 / 60) * 2.5);
const maghribTime = spaData.sunset;
const ishaTime = spaData.angles[1].sunset;
// Step 3: Calculate Asr time
const solarNoonHours = Math.floor(spaData.solarNoon);
const solarNoonMinutes = Math.floor((spaData.solarNoon - solarNoonHours) * 60);
const solarNoonSeconds = Math.floor((spaData.solarNoon * 3600) - (solarNoonHours * 3600) - (solarNoonMinutes * 60));
const solarNoonDate = new Date(date);
solarNoonDate.setHours(solarNoonHours, solarNoonMinutes, solarNoonSeconds);
const asrPrayerTime = getAsr(solarNoonDate, lat, lng, tz, standard);
// Step 4: Calculate Qiyam time
const qiyamTime = getQiyam(fajrTime, ishaTime);
// Final prayer times object
const prayerTimes = {
Qiyam: qiyamTime,
Fajr: fajrTime,
Sunrise: sunriseTime,
Noon: noonTime,
Dhuhr: dhuhrTime,
Asr: asrPrayerTime,
Maghrib: maghribTime,
Isha: ishaTime,
Methods: {},
Angles: [ fajrAngle, ishaAngle ]
};
// Adding other methods
methods.forEach((method, index) => {
const fajrIndex = 2 + (index * 2);
const ishaIndex = 3 + (index * 2);
let fajrMethodTime = spaData.angles[fajrIndex].sunrise;
let ishaMethodTime = spaData.angles[ishaIndex].sunset;
// Adjusting Isha time for Umm Al-Qura method
if (method.n === 'UAQ') {
ishaMethodTime = spaData.sunset + ((1 / 60) * 90);
}
else if (method.n === 'MSC') {
// Calculate Fajr and Isha for MSC method
const fajrMSCMinutes = getFajr(date, lat);
const ishaMSCMinutes = getIsha(date, lat);
fajrMethodTime = spaData.sunrise - ((1 / 60) * fajrMSCMinutes);
ishaMethodTime = spaData.sunset + ((1 / 60) * ishaMSCMinutes);
}
prayerTimes.Methods[method.n] = [fajrMethodTime, ishaMethodTime];
});
return prayerTimes;
}
module.exports = {
getTimesAll
};

80
index.d.ts vendored
View file

@ -1,80 +0,0 @@
// index.d.ts
declare module 'pray-calc' {
export function getMoon(date: Date, latitude?: number, longitude?: number, elevation?: number, temp?: number, pressure?: number, humidity?: number, clouds?: number): MoonDetails;
export function getTimes(date: Date, lat: number, lng: number, tz: number, elevation?: number, temperature?: number, pressure?: number): TimesReturnType;
export function calcTimes(date: Date, lat: number, lng: number, tz: number, elevation?: number, temperature?: number, pressure?: number): CalcTimesReturnType;
export function getTimesAll(date: Date, lat: number, lng: number, tz: number, elevation?: number, temperature?: number, pressure?: number): TimesAllReturnType;
export function calcTimesAll(date: Date, lat: number, lng: number, tz: number, elevation?: number, temperature?: number, pressure?: number): CalcTimesAllReturnType;
interface MoonPosition {
azimuth: number;
altitude: number;
distance: number;
parallacticAngle: number;
}
interface MoonIllumination {
fraction: number;
phase: number;
angle: number;
}
interface MoonDetails {
phase: number;
phaseName: string;
phaseSymbol: string;
position: MoonPosition;
illumination: MoonIllumination;
visibility: number;
}
interface TimesReturnType {
Qiyam: number;
Fajr: number;
Sunrise: number;
Noon: number;
Dhuhr: number;
Asr: number;
Maghrib: number;
Isha: number;
Angles: number[];
}
interface CalcTimesReturnType {
Qiyam: string;
Fajr: string;
Sunrise: string;
Noon: string;
Dhuhr: string;
Asr: string;
Maghrib: string;
Isha: string;
Angles: number[];
}
interface TimesAllReturnType {
Qiyam: number;
Fajr: number;
Sunrise: number;
Noon: number;
Dhuhr: number;
Asr: number;
Maghrib: number;
Isha: number;
Methods: Record<string, string[]>;
Angles: number[];
}
interface CalcTimesAllReturnType {
Qiyam: string;
Fajr: string;
Sunrise: string;
Noon: string;
Dhuhr: string;
Asr: string;
Maghrib: string;
Isha: string;
Methods: Record<string, string[]>;
Angles: number[];
}
}

14
index.js
View file

@ -1,14 +0,0 @@
const { getMoon } = require('./getMoon');
const { getTimes } = require('./getTimes');
const { calcTimes } = require('./calcTimes');
const { getTimesAll } = require('./getTimesAll');
const { calcTimesAll } = require('./calcTimesAll');
module.exports = {
getMoon,
getTimes,
calcTimes,
getTimesAll,
calcTimesAll
};

72
methods.json
View file

@ -1,72 +0,0 @@
[
{
"ID": "UOIF",
"Name": "Union des Organisations Islamiques de France",
"Fajr": "12°",
"Isha": "12°",
"Region": "FR"
},
{
"ID": "ISNACA",
"Name": "Islamic Society of North America - Canada",
"Fajr": "13°",
"Isha": "13°",
"Region": "CA"
},
{
"ID": "ISNAUS",
"Name": "Islamic Society of North America - US",
"Fajr": "15°",
"Isha": "15°",
"Region": "US, UK, AU, NZ"
},
{
"ID": "SAMR",
"Name": "Spiritual Administration of Muslims of Russia",
"Fajr": "16°",
"Isha": "15°",
"Region": "RU"
},
{
"ID": "MWL",
"Name": "Muslim World League",
"Fajr": "18°",
"Isha": "17°",
"Region": "Most common globally (default)"
},
{
"ID": "DIBT",
"Name": "Diyanet İşleri Başkanlığı, Turkey",
"Fajr": "18°",
"Isha": "17°",
"Region": "TR"
},
{
"ID": "Karachi",
"Name": "University of Islamic Sciences, Karachi",
"Fajr": "18°",
"Isha": "18°",
"Region": "PK, BD, IN, AF"
},
{
"ID": "UAQ",
"Name": "Umm Al-Qura University, Makkah",
"Fajr": "18.5°",
"Isha": "90 minutes after sunset",
"Region": "SA (Gulf States)"
},
{
"ID": "Egypt",
"Name": "Egyptian General Authority of Survey",
"Fajr": "19.5°",
"Isha": "17.5°",
"Region": "EG, SY, IQ, LB, surrounding African countries"
},
{
"ID": "MUIS",
"Name": "Majlis Ugama Islam Singapura",
"Fajr": "20°",
"Isha": "18°",
"Region": "SG"
}
]

1844
package-lock.json generated
View file

File diff suppressed because it is too large Load diff

98
package.json
View file

@ -1,43 +1,39 @@
{
"name": "pray-calc",
"version": "1.7.2",
"description": "Accurate prayer times using custom algorithm for dynamic angles and nrel-spa for extreme precision",
"main": "index.js",
"types": "index.d.ts",
"version": "2.0.0",
"description": "Islamic prayer times with a physics-grounded dynamic twilight angle algorithm. Covers Fajr, Sunrise, Dhuhr, Asr, Maghrib, Isha, Qiyam. Includes 14 traditional fixed-angle methods for comparison.",
"author": "Aric Camarata",
"license": "MIT",
"main": "./dist/index.cjs",
"module": "./dist/index.mjs",
"types": "./dist/index.d.ts",
"exports": {
".": {
"import": {
"types": "./dist/index.d.mts",
"default": "./dist/index.mjs"
},
"require": {
"types": "./dist/index.d.ts",
"default": "./dist/index.cjs"
}
}
},
"sideEffects": false,
"files": [
"index.js",
"index.d.ts",
"methods.json",
"dist/",
"src/",
"README.md",
"CHANGELOG.md",
"calcTimes.js",
"calcTimesAll.js",
"getAngles.js",
"getAsr.js",
"getEarthSunDistance.js",
"getMoon.js",
"getMoonIllumination.js",
"getMoonPhase.js",
"getMoonPosition.js",
"getMoonVisibility.js",
"getMSC.js",
"getQiyam.js",
"getTimes.js",
"getTimesAll.js"
"LICENSE"
],
"scripts": {
"test": "mocha test.js",
"lint": "eslint .",
"prepare": "npm test"
"build": "tsup",
"typecheck": "tsc --noEmit",
"pretest": "tsup",
"test": "node test.mjs && node test-cjs.cjs",
"prepublishOnly": "tsup"
},
"repository": {
"type": "git",
"url": "https://github.com/acamarata/pray-calc.git"
},
"bugs": {
"url": "https://github.com/acamarata/pray-calc/issues"
},
"homepage": "https://github.com/acamarata/pray-calc#readme",
"keywords": [
"prayer-times",
"islamic-prayer-times",
@ -48,32 +44,36 @@
"maghrib",
"isha",
"qiyam",
"iqama",
"sunrise",
"sunset",
"solar-position",
"moon-phase",
"moon-illumination",
"hijri-calendar",
"qibla",
"shalat",
"namaz",
"javascript",
"nodejs",
"twilight",
"dynamic-angles",
"nrel-spa",
"suncalc"
"javascript",
"typescript"
],
"author": "Ali Camarata",
"license": "MIT",
"repository": {
"type": "git",
"url": "git+https://github.com/acamarata/pray-calc.git"
},
"homepage": "https://github.com/acamarata/pray-calc#readme",
"bugs": {
"url": "https://github.com/acamarata/pray-calc/issues"
},
"engines": {
"node": ">=12"
"node": ">=20"
},
"publishConfig": {
"access": "public",
"registry": "https://registry.npmjs.org/"
},
"dependencies": {
"nrel-spa": "^1.3.0",
"suncalc": "^1.9.0"
"nrel-spa": "^2.0.1"
},
"devDependencies": {
"eslint": "^8.0.0",
"mocha": "^10.8.2"
"@types/node": "^25.3.0",
"tsup": "^8.5.1",
"typescript": "^5.9.3"
}
}

935
pnpm-lock.yaml Normal file
View file

@ -0,0 +1,935 @@
lockfileVersion: '9.0'
settings:
autoInstallPeers: true
excludeLinksFromLockfile: false
importers:
.:
dependencies:
nrel-spa:
specifier: ^2.0.1
version: 2.0.1
devDependencies:
'@types/node':
specifier: ^25.3.0
version: 25.3.0
tsup:
specifier: ^8.5.1
version: 8.5.1(typescript@5.9.3)
typescript:
specifier: ^5.9.3
version: 5.9.3
packages:
'@esbuild/aix-ppc64@0.27.3':
resolution: {integrity: sha512-9fJMTNFTWZMh5qwrBItuziu834eOCUcEqymSH7pY+zoMVEZg3gcPuBNxH1EvfVYe9h0x/Ptw8KBzv7qxb7l8dg==}
engines: {node: '>=18'}
cpu: [ppc64]
os: [aix]
'@esbuild/android-arm64@0.27.3':
resolution: {integrity: sha512-YdghPYUmj/FX2SYKJ0OZxf+iaKgMsKHVPF1MAq/P8WirnSpCStzKJFjOjzsW0QQ7oIAiccHdcqjbHmJxRb/dmg==}
engines: {node: '>=18'}
cpu: [arm64]
os: [android]
'@esbuild/android-arm@0.27.3':
resolution: {integrity: sha512-i5D1hPY7GIQmXlXhs2w8AWHhenb00+GxjxRncS2ZM7YNVGNfaMxgzSGuO8o8SJzRc/oZwU2bcScvVERk03QhzA==}
engines: {node: '>=18'}
cpu: [arm]
os: [android]
'@esbuild/android-x64@0.27.3':
resolution: {integrity: sha512-IN/0BNTkHtk8lkOM8JWAYFg4ORxBkZQf9zXiEOfERX/CzxW3Vg1ewAhU7QSWQpVIzTW+b8Xy+lGzdYXV6UZObQ==}
engines: {node: '>=18'}
cpu: [x64]
os: [android]
'@esbuild/darwin-arm64@0.27.3':
resolution: {integrity: sha512-Re491k7ByTVRy0t3EKWajdLIr0gz2kKKfzafkth4Q8A5n1xTHrkqZgLLjFEHVD+AXdUGgQMq+Godfq45mGpCKg==}
engines: {node: '>=18'}
cpu: [arm64]
os: [darwin]
'@esbuild/darwin-x64@0.27.3':
resolution: {integrity: sha512-vHk/hA7/1AckjGzRqi6wbo+jaShzRowYip6rt6q7VYEDX4LEy1pZfDpdxCBnGtl+A5zq8iXDcyuxwtv3hNtHFg==}
engines: {node: '>=18'}
cpu: [x64]
os: [darwin]
'@esbuild/freebsd-arm64@0.27.3':
resolution: {integrity: sha512-ipTYM2fjt3kQAYOvo6vcxJx3nBYAzPjgTCk7QEgZG8AUO3ydUhvelmhrbOheMnGOlaSFUoHXB6un+A7q4ygY9w==}
engines: {node: '>=18'}
cpu: [arm64]
os: [freebsd]
'@esbuild/freebsd-x64@0.27.3':
resolution: {integrity: sha512-dDk0X87T7mI6U3K9VjWtHOXqwAMJBNN2r7bejDsc+j03SEjtD9HrOl8gVFByeM0aJksoUuUVU9TBaZa2rgj0oA==}
engines: {node: '>=18'}
cpu: [x64]
os: [freebsd]
'@esbuild/linux-arm64@0.27.3':
resolution: {integrity: sha512-sZOuFz/xWnZ4KH3YfFrKCf1WyPZHakVzTiqji3WDc0BCl2kBwiJLCXpzLzUBLgmp4veFZdvN5ChW4Eq/8Fc2Fg==}
engines: {node: '>=18'}
cpu: [arm64]
os: [linux]
'@esbuild/linux-arm@0.27.3':
resolution: {integrity: sha512-s6nPv2QkSupJwLYyfS+gwdirm0ukyTFNl3KTgZEAiJDd+iHZcbTPPcWCcRYH+WlNbwChgH2QkE9NSlNrMT8Gfw==}
engines: {node: '>=18'}
cpu: [arm]
os: [linux]
'@esbuild/linux-ia32@0.27.3':
resolution: {integrity: sha512-yGlQYjdxtLdh0a3jHjuwOrxQjOZYD/C9PfdbgJJF3TIZWnm/tMd/RcNiLngiu4iwcBAOezdnSLAwQDPqTmtTYg==}
engines: {node: '>=18'}
cpu: [ia32]
os: [linux]
'@esbuild/linux-loong64@0.27.3':
resolution: {integrity: sha512-WO60Sn8ly3gtzhyjATDgieJNet/KqsDlX5nRC5Y3oTFcS1l0KWba+SEa9Ja1GfDqSF1z6hif/SkpQJbL63cgOA==}
engines: {node: '>=18'}
cpu: [loong64]
os: [linux]
'@esbuild/linux-mips64el@0.27.3':
resolution: {integrity: sha512-APsymYA6sGcZ4pD6k+UxbDjOFSvPWyZhjaiPyl/f79xKxwTnrn5QUnXR5prvetuaSMsb4jgeHewIDCIWljrSxw==}
engines: {node: '>=18'}
cpu: [mips64el]
os: [linux]
'@esbuild/linux-ppc64@0.27.3':
resolution: {integrity: sha512-eizBnTeBefojtDb9nSh4vvVQ3V9Qf9Df01PfawPcRzJH4gFSgrObw+LveUyDoKU3kxi5+9RJTCWlj4FjYXVPEA==}
engines: {node: '>=18'}
cpu: [ppc64]
os: [linux]
'@esbuild/linux-riscv64@0.27.3':
resolution: {integrity: sha512-3Emwh0r5wmfm3ssTWRQSyVhbOHvqegUDRd0WhmXKX2mkHJe1SFCMJhagUleMq+Uci34wLSipf8Lagt4LlpRFWQ==}
engines: {node: '>=18'}
cpu: [riscv64]
os: [linux]
'@esbuild/linux-s390x@0.27.3':
resolution: {integrity: sha512-pBHUx9LzXWBc7MFIEEL0yD/ZVtNgLytvx60gES28GcWMqil8ElCYR4kvbV2BDqsHOvVDRrOxGySBM9Fcv744hw==}
engines: {node: '>=18'}
cpu: [s390x]
os: [linux]
'@esbuild/linux-x64@0.27.3':
resolution: {integrity: sha512-Czi8yzXUWIQYAtL/2y6vogER8pvcsOsk5cpwL4Gk5nJqH5UZiVByIY8Eorm5R13gq+DQKYg0+JyQoytLQas4dA==}
engines: {node: '>=18'}
cpu: [x64]
os: [linux]
'@esbuild/netbsd-arm64@0.27.3':
resolution: {integrity: sha512-sDpk0RgmTCR/5HguIZa9n9u+HVKf40fbEUt+iTzSnCaGvY9kFP0YKBWZtJaraonFnqef5SlJ8/TiPAxzyS+UoA==}
engines: {node: '>=18'}
cpu: [arm64]
os: [netbsd]
'@esbuild/netbsd-x64@0.27.3':
resolution: {integrity: sha512-P14lFKJl/DdaE00LItAukUdZO5iqNH7+PjoBm+fLQjtxfcfFE20Xf5CrLsmZdq5LFFZzb5JMZ9grUwvtVYzjiA==}
engines: {node: '>=18'}
cpu: [x64]
os: [netbsd]
'@esbuild/openbsd-arm64@0.27.3':
resolution: {integrity: sha512-AIcMP77AvirGbRl/UZFTq5hjXK+2wC7qFRGoHSDrZ5v5b8DK/GYpXW3CPRL53NkvDqb9D+alBiC/dV0Fb7eJcw==}
engines: {node: '>=18'}
cpu: [arm64]
os: [openbsd]
'@esbuild/openbsd-x64@0.27.3':
resolution: {integrity: sha512-DnW2sRrBzA+YnE70LKqnM3P+z8vehfJWHXECbwBmH/CU51z6FiqTQTHFenPlHmo3a8UgpLyH3PT+87OViOh1AQ==}
engines: {node: '>=18'}
cpu: [x64]
os: [openbsd]
'@esbuild/openharmony-arm64@0.27.3':
resolution: {integrity: sha512-NinAEgr/etERPTsZJ7aEZQvvg/A6IsZG/LgZy+81wON2huV7SrK3e63dU0XhyZP4RKGyTm7aOgmQk0bGp0fy2g==}
engines: {node: '>=18'}
cpu: [arm64]
os: [openharmony]
'@esbuild/sunos-x64@0.27.3':
resolution: {integrity: sha512-PanZ+nEz+eWoBJ8/f8HKxTTD172SKwdXebZ0ndd953gt1HRBbhMsaNqjTyYLGLPdoWHy4zLU7bDVJztF5f3BHA==}
engines: {node: '>=18'}
cpu: [x64]
os: [sunos]
'@esbuild/win32-arm64@0.27.3':
resolution: {integrity: sha512-B2t59lWWYrbRDw/tjiWOuzSsFh1Y/E95ofKz7rIVYSQkUYBjfSgf6oeYPNWHToFRr2zx52JKApIcAS/D5TUBnA==}
engines: {node: '>=18'}
cpu: [arm64]
os: [win32]
'@esbuild/win32-ia32@0.27.3':
resolution: {integrity: sha512-QLKSFeXNS8+tHW7tZpMtjlNb7HKau0QDpwm49u0vUp9y1WOF+PEzkU84y9GqYaAVW8aH8f3GcBck26jh54cX4Q==}
engines: {node: '>=18'}
cpu: [ia32]
os: [win32]
'@esbuild/win32-x64@0.27.3':
resolution: {integrity: sha512-4uJGhsxuptu3OcpVAzli+/gWusVGwZZHTlS63hh++ehExkVT8SgiEf7/uC/PclrPPkLhZqGgCTjd0VWLo6xMqA==}
engines: {node: '>=18'}
cpu: [x64]
os: [win32]
'@jridgewell/gen-mapping@0.3.13':
resolution: {integrity: sha512-2kkt/7niJ6MgEPxF0bYdQ6etZaA+fQvDcLKckhy1yIQOzaoKjBBjSj63/aLVjYE3qhRt5dvM+uUyfCg6UKCBbA==}
'@jridgewell/resolve-uri@3.1.2':
resolution: {integrity: sha512-bRISgCIjP20/tbWSPWMEi54QVPRZExkuD9lJL+UIxUKtwVJA8wW1Trb1jMs1RFXo1CBTNZ/5hpC9QvmKWdopKw==}
engines: {node: '>=6.0.0'}
'@jridgewell/sourcemap-codec@1.5.5':
resolution: {integrity: sha512-cYQ9310grqxueWbl+WuIUIaiUaDcj7WOq5fVhEljNVgRfOUhY9fy2zTvfoqWsnebh8Sl70VScFbICvJnLKB0Og==}
'@jridgewell/trace-mapping@0.3.31':
resolution: {integrity: sha512-zzNR+SdQSDJzc8joaeP8QQoCQr8NuYx2dIIytl1QeBEZHJ9uW6hebsrYgbz8hJwUQao3TWCMtmfV8Nu1twOLAw==}
'@rollup/rollup-android-arm-eabi@4.59.0':
resolution: {integrity: sha512-upnNBkA6ZH2VKGcBj9Fyl9IGNPULcjXRlg0LLeaioQWueH30p6IXtJEbKAgvyv+mJaMxSm1l6xwDXYjpEMiLMg==}
cpu: [arm]
os: [android]
'@rollup/rollup-android-arm64@4.59.0':
resolution: {integrity: sha512-hZ+Zxj3SySm4A/DylsDKZAeVg0mvi++0PYVceVyX7hemkw7OreKdCvW2oQ3T1FMZvCaQXqOTHb8qmBShoqk69Q==}
cpu: [arm64]
os: [android]
'@rollup/rollup-darwin-arm64@4.59.0':
resolution: {integrity: sha512-W2Psnbh1J8ZJw0xKAd8zdNgF9HRLkdWwwdWqubSVk0pUuQkoHnv7rx4GiF9rT4t5DIZGAsConRE3AxCdJ4m8rg==}
cpu: [arm64]
os: [darwin]
'@rollup/rollup-darwin-x64@4.59.0':
resolution: {integrity: sha512-ZW2KkwlS4lwTv7ZVsYDiARfFCnSGhzYPdiOU4IM2fDbL+QGlyAbjgSFuqNRbSthybLbIJ915UtZBtmuLrQAT/w==}
cpu: [x64]
os: [darwin]
'@rollup/rollup-freebsd-arm64@4.59.0':
resolution: {integrity: sha512-EsKaJ5ytAu9jI3lonzn3BgG8iRBjV4LxZexygcQbpiU0wU0ATxhNVEpXKfUa0pS05gTcSDMKpn3Sx+QB9RlTTA==}
cpu: [arm64]
os: [freebsd]
'@rollup/rollup-freebsd-x64@4.59.0':
resolution: {integrity: sha512-d3DuZi2KzTMjImrxoHIAODUZYoUUMsuUiY4SRRcJy6NJoZ6iIqWnJu9IScV9jXysyGMVuW+KNzZvBLOcpdl3Vg==}
cpu: [x64]
os: [freebsd]
'@rollup/rollup-linux-arm-gnueabihf@4.59.0':
resolution: {integrity: sha512-t4ONHboXi/3E0rT6OZl1pKbl2Vgxf9vJfWgmUoCEVQVxhW6Cw/c8I6hbbu7DAvgp82RKiH7TpLwxnJeKv2pbsw==}
cpu: [arm]
os: [linux]
libc: [glibc]
'@rollup/rollup-linux-arm-musleabihf@4.59.0':
resolution: {integrity: sha512-CikFT7aYPA2ufMD086cVORBYGHffBo4K8MQ4uPS/ZnY54GKj36i196u8U+aDVT2LX4eSMbyHtyOh7D7Zvk2VvA==}
cpu: [arm]
os: [linux]
libc: [musl]
'@rollup/rollup-linux-arm64-gnu@4.59.0':
resolution: {integrity: sha512-jYgUGk5aLd1nUb1CtQ8E+t5JhLc9x5WdBKew9ZgAXg7DBk0ZHErLHdXM24rfX+bKrFe+Xp5YuJo54I5HFjGDAA==}
cpu: [arm64]
os: [linux]
libc: [glibc]
'@rollup/rollup-linux-arm64-musl@4.59.0':
resolution: {integrity: sha512-peZRVEdnFWZ5Bh2KeumKG9ty7aCXzzEsHShOZEFiCQlDEepP1dpUl/SrUNXNg13UmZl+gzVDPsiCwnV1uI0RUA==}
cpu: [arm64]
os: [linux]
libc: [musl]
'@rollup/rollup-linux-loong64-gnu@4.59.0':
resolution: {integrity: sha512-gbUSW/97f7+r4gHy3Jlup8zDG190AuodsWnNiXErp9mT90iCy9NKKU0Xwx5k8VlRAIV2uU9CsMnEFg/xXaOfXg==}
cpu: [loong64]
os: [linux]
libc: [glibc]
'@rollup/rollup-linux-loong64-musl@4.59.0':
resolution: {integrity: sha512-yTRONe79E+o0FWFijasoTjtzG9EBedFXJMl888NBEDCDV9I2wGbFFfJQQe63OijbFCUZqxpHz1GzpbtSFikJ4Q==}
cpu: [loong64]
os: [linux]
libc: [musl]
'@rollup/rollup-linux-ppc64-gnu@4.59.0':
resolution: {integrity: sha512-sw1o3tfyk12k3OEpRddF68a1unZ5VCN7zoTNtSn2KndUE+ea3m3ROOKRCZxEpmT9nsGnogpFP9x6mnLTCaoLkA==}
cpu: [ppc64]
os: [linux]
libc: [glibc]
'@rollup/rollup-linux-ppc64-musl@4.59.0':
resolution: {integrity: sha512-+2kLtQ4xT3AiIxkzFVFXfsmlZiG5FXYW7ZyIIvGA7Bdeuh9Z0aN4hVyXS/G1E9bTP/vqszNIN/pUKCk/BTHsKA==}
cpu: [ppc64]
os: [linux]
libc: [musl]
'@rollup/rollup-linux-riscv64-gnu@4.59.0':
resolution: {integrity: sha512-NDYMpsXYJJaj+I7UdwIuHHNxXZ/b/N2hR15NyH3m2qAtb/hHPA4g4SuuvrdxetTdndfj9b1WOmy73kcPRoERUg==}
cpu: [riscv64]
os: [linux]
libc: [glibc]
'@rollup/rollup-linux-riscv64-musl@4.59.0':
resolution: {integrity: sha512-nLckB8WOqHIf1bhymk+oHxvM9D3tyPndZH8i8+35p/1YiVoVswPid2yLzgX7ZJP0KQvnkhM4H6QZ5m0LzbyIAg==}
cpu: [riscv64]
os: [linux]
libc: [musl]
'@rollup/rollup-linux-s390x-gnu@4.59.0':
resolution: {integrity: sha512-oF87Ie3uAIvORFBpwnCvUzdeYUqi2wY6jRFWJAy1qus/udHFYIkplYRW+wo+GRUP4sKzYdmE1Y3+rY5Gc4ZO+w==}
cpu: [s390x]
os: [linux]
libc: [glibc]
'@rollup/rollup-linux-x64-gnu@4.59.0':
resolution: {integrity: sha512-3AHmtQq/ppNuUspKAlvA8HtLybkDflkMuLK4DPo77DfthRb71V84/c4MlWJXixZz4uruIH4uaa07IqoAkG64fg==}
cpu: [x64]
os: [linux]
libc: [glibc]
'@rollup/rollup-linux-x64-musl@4.59.0':
resolution: {integrity: sha512-2UdiwS/9cTAx7qIUZB/fWtToJwvt0Vbo0zmnYt7ED35KPg13Q0ym1g442THLC7VyI6JfYTP4PiSOWyoMdV2/xg==}
cpu: [x64]
os: [linux]
libc: [musl]
'@rollup/rollup-openbsd-x64@4.59.0':
resolution: {integrity: sha512-M3bLRAVk6GOwFlPTIxVBSYKUaqfLrn8l0psKinkCFxl4lQvOSz8ZrKDz2gxcBwHFpci0B6rttydI4IpS4IS/jQ==}
cpu: [x64]
os: [openbsd]
'@rollup/rollup-openharmony-arm64@4.59.0':
resolution: {integrity: sha512-tt9KBJqaqp5i5HUZzoafHZX8b5Q2Fe7UjYERADll83O4fGqJ49O1FsL6LpdzVFQcpwvnyd0i+K/VSwu/o/nWlA==}
cpu: [arm64]
os: [openharmony]
'@rollup/rollup-win32-arm64-msvc@4.59.0':
resolution: {integrity: sha512-V5B6mG7OrGTwnxaNUzZTDTjDS7F75PO1ae6MJYdiMu60sq0CqN5CVeVsbhPxalupvTX8gXVSU9gq+Rx1/hvu6A==}
cpu: [arm64]
os: [win32]
'@rollup/rollup-win32-ia32-msvc@4.59.0':
resolution: {integrity: sha512-UKFMHPuM9R0iBegwzKF4y0C4J9u8C6MEJgFuXTBerMk7EJ92GFVFYBfOZaSGLu6COf7FxpQNqhNS4c4icUPqxA==}
cpu: [ia32]
os: [win32]
'@rollup/rollup-win32-x64-gnu@4.59.0':
resolution: {integrity: sha512-laBkYlSS1n2L8fSo1thDNGrCTQMmxjYY5G0WFWjFFYZkKPjsMBsgJfGf4TLxXrF6RyhI60L8TMOjBMvXiTcxeA==}
cpu: [x64]
os: [win32]
'@rollup/rollup-win32-x64-msvc@4.59.0':
resolution: {integrity: sha512-2HRCml6OztYXyJXAvdDXPKcawukWY2GpR5/nxKp4iBgiO3wcoEGkAaqctIbZcNB6KlUQBIqt8VYkNSj2397EfA==}
cpu: [x64]
os: [win32]
'@types/estree@1.0.8':
resolution: {integrity: sha512-dWHzHa2WqEXI/O1E9OjrocMTKJl2mSrEolh1Iomrv6U+JuNwaHXsXx9bLu5gG7BUWFIN0skIQJQ/L1rIex4X6w==}
'@types/node@25.3.0':
resolution: {integrity: sha512-4K3bqJpXpqfg2XKGK9bpDTc6xO/xoUP/RBWS7AtRMug6zZFaRekiLzjVtAoZMquxoAbzBvy5nxQ7veS5eYzf8A==}
acorn@8.16.0:
resolution: {integrity: sha512-UVJyE9MttOsBQIDKw1skb9nAwQuR5wuGD3+82K6JgJlm/Y+KI92oNsMNGZCYdDsVtRHSak0pcV5Dno5+4jh9sw==}
engines: {node: '>=0.4.0'}
hasBin: true
any-promise@1.3.0:
resolution: {integrity: sha512-7UvmKalWRt1wgjL1RrGxoSJW/0QZFIegpeGvZG9kjp8vrRu55XTHbwnqq2GpXm9uLbcuhxm3IqX9OB4MZR1b2A==}
bundle-require@5.1.0:
resolution: {integrity: sha512-3WrrOuZiyaaZPWiEt4G3+IffISVC9HYlWueJEBWED4ZH4aIAC2PnkdnuRrR94M+w6yGWn4AglWtJtBI8YqvgoA==}
engines: {node: ^12.20.0 || ^14.13.1 || >=16.0.0}
peerDependencies:
esbuild: '>=0.18'
cac@6.7.14:
resolution: {integrity: sha512-b6Ilus+c3RrdDk+JhLKUAQfzzgLEPy6wcXqS7f/xe1EETvsDP6GORG7SFuOs6cID5YkqchW/LXZbX5bc8j7ZcQ==}
engines: {node: '>=8'}
chokidar@4.0.3:
resolution: {integrity: sha512-Qgzu8kfBvo+cA4962jnP1KkS6Dop5NS6g7R5LFYJr4b8Ub94PPQXUksCw9PvXoeXPRRddRNC5C1JQUR2SMGtnA==}
engines: {node: '>= 14.16.0'}
commander@4.1.1:
resolution: {integrity: sha512-NOKm8xhkzAjzFx8B2v5OAHT+u5pRQc2UCa2Vq9jYL/31o2wi9mxBA7LIFs3sV5VSC49z6pEhfbMULvShKj26WA==}
engines: {node: '>= 6'}
confbox@0.1.8:
resolution: {integrity: sha512-RMtmw0iFkeR4YV+fUOSucriAQNb9g8zFR52MWCtl+cCZOFRNL6zeB395vPzFhEjjn4fMxXudmELnl/KF/WrK6w==}
consola@3.4.2:
resolution: {integrity: sha512-5IKcdX0nnYavi6G7TtOhwkYzyjfJlatbjMjuLSfE2kYT5pMDOilZ4OvMhi637CcDICTmz3wARPoyhqyX1Y+XvA==}
engines: {node: ^14.18.0 || >=16.10.0}
debug@4.4.3:
resolution: {integrity: sha512-RGwwWnwQvkVfavKVt22FGLw+xYSdzARwm0ru6DhTVA3umU5hZc28V3kO4stgYryrTlLpuvgI9GiijltAjNbcqA==}
engines: {node: '>=6.0'}
peerDependencies:
supports-color: '*'
peerDependenciesMeta:
supports-color:
optional: true
esbuild@0.27.3:
resolution: {integrity: sha512-8VwMnyGCONIs6cWue2IdpHxHnAjzxnw2Zr7MkVxB2vjmQ2ivqGFb4LEG3SMnv0Gb2F/G/2yA8zUaiL1gywDCCg==}
engines: {node: '>=18'}
hasBin: true
fdir@6.5.0:
resolution: {integrity: sha512-tIbYtZbucOs0BRGqPJkshJUYdL+SDH7dVM8gjy+ERp3WAUjLEFJE+02kanyHtwjWOnwrKYBiwAmM0p4kLJAnXg==}
engines: {node: '>=12.0.0'}
peerDependencies:
picomatch: ^3 || ^4
peerDependenciesMeta:
picomatch:
optional: true
fix-dts-default-cjs-exports@1.0.1:
resolution: {integrity: sha512-pVIECanWFC61Hzl2+oOCtoJ3F17kglZC/6N94eRWycFgBH35hHx0Li604ZIzhseh97mf2p0cv7vVrOZGoqhlEg==}
fsevents@2.3.3:
resolution: {integrity: sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw==}
engines: {node: ^8.16.0 || ^10.6.0 || >=11.0.0}
os: [darwin]
joycon@3.1.1:
resolution: {integrity: sha512-34wB/Y7MW7bzjKRjUKTa46I2Z7eV62Rkhva+KkopW7Qvv/OSWBqvkSY7vusOPrNuZcUG3tApvdVgNB8POj3SPw==}
engines: {node: '>=10'}
lilconfig@3.1.3:
resolution: {integrity: sha512-/vlFKAoH5Cgt3Ie+JLhRbwOsCQePABiU3tJ1egGvyQ+33R/vcwM2Zl2QR/LzjsBeItPt3oSVXapn+m4nQDvpzw==}
engines: {node: '>=14'}
lines-and-columns@1.2.4:
resolution: {integrity: sha512-7ylylesZQ/PV29jhEDl3Ufjo6ZX7gCqJr5F7PKrqc93v7fzSymt1BpwEU8nAUXs8qzzvqhbjhK5QZg6Mt/HkBg==}
load-tsconfig@0.2.5:
resolution: {integrity: sha512-IXO6OCs9yg8tMKzfPZ1YmheJbZCiEsnBdcB03l0OcfK9prKnJb96siuHCr5Fl37/yo9DnKU+TLpxzTUspw9shg==}
engines: {node: ^12.20.0 || ^14.13.1 || >=16.0.0}
magic-string@0.30.21:
resolution: {integrity: sha512-vd2F4YUyEXKGcLHoq+TEyCjxueSeHnFxyyjNp80yg0XV4vUhnDer/lvvlqM/arB5bXQN5K2/3oinyCRyx8T2CQ==}
mlly@1.8.0:
resolution: {integrity: sha512-l8D9ODSRWLe2KHJSifWGwBqpTZXIXTeo8mlKjY+E2HAakaTeNpqAyBZ8GSqLzHgw4XmHmC8whvpjJNMbFZN7/g==}
ms@2.1.3:
resolution: {integrity: sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==}
mz@2.7.0:
resolution: {integrity: sha512-z81GNO7nnYMEhrGh9LeymoE4+Yr0Wn5McHIZMK5cfQCl+NDX08sCZgUc9/6MHni9IWuFLm1Z3HTCXu2z9fN62Q==}
nrel-spa@2.0.1:
resolution: {integrity: sha512-KwsudVfAHMUwz9RwhriI7oNqFYz77+VGi2vUpJeR+xNx57MU28EYcdt1TQ1frEDbpBXkF4EJxM62Hi2iX6QNCA==}
engines: {node: '>=20'}
object-assign@4.1.1:
resolution: {integrity: sha512-rJgTQnkUnH1sFw8yT6VSU3zD3sWmu6sZhIseY8VX+GRu3P6F7Fu+JNDoXfklElbLJSnc3FUQHVe4cU5hj+BcUg==}
engines: {node: '>=0.10.0'}
pathe@2.0.3:
resolution: {integrity: sha512-WUjGcAqP1gQacoQe+OBJsFA7Ld4DyXuUIjZ5cc75cLHvJ7dtNsTugphxIADwspS+AraAUePCKrSVtPLFj/F88w==}
picocolors@1.1.1:
resolution: {integrity: sha512-xceH2snhtb5M9liqDsmEw56le376mTZkEX/jEb/RxNFyegNul7eNslCXP9FDj/Lcu0X8KEyMceP2ntpaHrDEVA==}
picomatch@4.0.3:
resolution: {integrity: sha512-5gTmgEY/sqK6gFXLIsQNH19lWb4ebPDLA4SdLP7dsWkIXHWlG66oPuVvXSGFPppYZz8ZDZq0dYYrbHfBCVUb1Q==}
engines: {node: '>=12'}
pirates@4.0.7:
resolution: {integrity: sha512-TfySrs/5nm8fQJDcBDuUng3VOUKsd7S+zqvbOTiGXHfxX4wK31ard+hoNuvkicM/2YFzlpDgABOevKSsB4G/FA==}
engines: {node: '>= 6'}
pkg-types@1.3.1:
resolution: {integrity: sha512-/Jm5M4RvtBFVkKWRu2BLUTNP8/M2a+UwuAX+ae4770q1qVGtfjG+WTCupoZixokjmHiry8uI+dlY8KXYV5HVVQ==}
postcss-load-config@6.0.1:
resolution: {integrity: sha512-oPtTM4oerL+UXmx+93ytZVN82RrlY/wPUV8IeDxFrzIjXOLF1pN+EmKPLbubvKHT2HC20xXsCAH2Z+CKV6Oz/g==}
engines: {node: '>= 18'}
peerDependencies:
jiti: '>=1.21.0'
postcss: '>=8.0.9'
tsx: ^4.8.1
yaml: ^2.4.2
peerDependenciesMeta:
jiti:
optional: true
postcss:
optional: true
tsx:
optional: true
yaml:
optional: true
readdirp@4.1.2:
resolution: {integrity: sha512-GDhwkLfywWL2s6vEjyhri+eXmfH6j1L7JE27WhqLeYzoh/A3DBaYGEj2H/HFZCn/kMfim73FXxEJTw06WtxQwg==}
engines: {node: '>= 14.18.0'}
resolve-from@5.0.0:
resolution: {integrity: sha512-qYg9KP24dD5qka9J47d0aVky0N+b4fTU89LN9iDnjB5waksiC49rvMB0PrUJQGoTmH50XPiqOvAjDfaijGxYZw==}
engines: {node: '>=8'}
rollup@4.59.0:
resolution: {integrity: sha512-2oMpl67a3zCH9H79LeMcbDhXW/UmWG/y2zuqnF2jQq5uq9TbM9TVyXvA4+t+ne2IIkBdrLpAaRQAvo7YI/Yyeg==}
engines: {node: '>=18.0.0', npm: '>=8.0.0'}
hasBin: true
source-map@0.7.6:
resolution: {integrity: sha512-i5uvt8C3ikiWeNZSVZNWcfZPItFQOsYTUAOkcUPGd8DqDy1uOUikjt5dG+uRlwyvR108Fb9DOd4GvXfT0N2/uQ==}
engines: {node: '>= 12'}
sucrase@3.35.1:
resolution: {integrity: sha512-DhuTmvZWux4H1UOnWMB3sk0sbaCVOoQZjv8u1rDoTV0HTdGem9hkAZtl4JZy8P2z4Bg0nT+YMeOFyVr4zcG5Tw==}
engines: {node: '>=16 || 14 >=14.17'}
hasBin: true
thenify-all@1.6.0:
resolution: {integrity: sha512-RNxQH/qI8/t3thXJDwcstUO4zeqo64+Uy/+sNVRBx4Xn2OX+OZ9oP+iJnNFqplFra2ZUVeKCSa2oVWi3T4uVmA==}
engines: {node: '>=0.8'}
thenify@3.3.1:
resolution: {integrity: sha512-RVZSIV5IG10Hk3enotrhvz0T9em6cyHBLkH/YAZuKqd8hRkKhSfCGIcP2KUY0EPxndzANBmNllzWPwak+bheSw==}
tinyexec@0.3.2:
resolution: {integrity: sha512-KQQR9yN7R5+OSwaK0XQoj22pwHoTlgYqmUscPYoknOoWCWfj/5/ABTMRi69FrKU5ffPVh5QcFikpWJI/P1ocHA==}
tinyglobby@0.2.15:
resolution: {integrity: sha512-j2Zq4NyQYG5XMST4cbs02Ak8iJUdxRM0XI5QyxXuZOzKOINmWurp3smXu3y5wDcJrptwpSjgXHzIQxR0omXljQ==}
engines: {node: '>=12.0.0'}
tree-kill@1.2.2:
resolution: {integrity: sha512-L0Orpi8qGpRG//Nd+H90vFB+3iHnue1zSSGmNOOCh1GLJ7rUKVwV2HvijphGQS2UmhUZewS9VgvxYIdgr+fG1A==}
hasBin: true
ts-interface-checker@0.1.13:
resolution: {integrity: sha512-Y/arvbn+rrz3JCKl9C4kVNfTfSm2/mEp5FSz5EsZSANGPSlQrpRI5M4PKF+mJnE52jOO90PnPSc3Ur3bTQw0gA==}
tsup@8.5.1:
resolution: {integrity: sha512-xtgkqwdhpKWr3tKPmCkvYmS9xnQK3m3XgxZHwSUjvfTjp7YfXe5tT3GgWi0F2N+ZSMsOeWeZFh7ZZFg5iPhing==}
engines: {node: '>=18'}
hasBin: true
peerDependencies:
'@microsoft/api-extractor': ^7.36.0
'@swc/core': ^1
postcss: ^8.4.12
typescript: '>=4.5.0'
peerDependenciesMeta:
'@microsoft/api-extractor':
optional: true
'@swc/core':
optional: true
postcss:
optional: true
typescript:
optional: true
typescript@5.9.3:
resolution: {integrity: sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==}
engines: {node: '>=14.17'}
hasBin: true
ufo@1.6.3:
resolution: {integrity: sha512-yDJTmhydvl5lJzBmy/hyOAA0d+aqCBuwl818haVdYCRrWV84o7YyeVm4QlVHStqNrrJSTb6jKuFAVqAFsr+K3Q==}
undici-types@7.18.2:
resolution: {integrity: sha512-AsuCzffGHJybSaRrmr5eHr81mwJU3kjw6M+uprWvCXiNeN9SOGwQ3Jn8jb8m3Z6izVgknn1R0FTCEAP2QrLY/w==}
snapshots:
'@esbuild/aix-ppc64@0.27.3':
optional: true
'@esbuild/android-arm64@0.27.3':
optional: true
'@esbuild/android-arm@0.27.3':
optional: true
'@esbuild/android-x64@0.27.3':
optional: true
'@esbuild/darwin-arm64@0.27.3':
optional: true
'@esbuild/darwin-x64@0.27.3':
optional: true
'@esbuild/freebsd-arm64@0.27.3':
optional: true
'@esbuild/freebsd-x64@0.27.3':
optional: true
'@esbuild/linux-arm64@0.27.3':
optional: true
'@esbuild/linux-arm@0.27.3':
optional: true
'@esbuild/linux-ia32@0.27.3':
optional: true
'@esbuild/linux-loong64@0.27.3':
optional: true
'@esbuild/linux-mips64el@0.27.3':
optional: true
'@esbuild/linux-ppc64@0.27.3':
optional: true
'@esbuild/linux-riscv64@0.27.3':
optional: true
'@esbuild/linux-s390x@0.27.3':
optional: true
'@esbuild/linux-x64@0.27.3':
optional: true
'@esbuild/netbsd-arm64@0.27.3':
optional: true
'@esbuild/netbsd-x64@0.27.3':
optional: true
'@esbuild/openbsd-arm64@0.27.3':
optional: true
'@esbuild/openbsd-x64@0.27.3':
optional: true
'@esbuild/openharmony-arm64@0.27.3':
optional: true
'@esbuild/sunos-x64@0.27.3':
optional: true
'@esbuild/win32-arm64@0.27.3':
optional: true
'@esbuild/win32-ia32@0.27.3':
optional: true
'@esbuild/win32-x64@0.27.3':
optional: true
'@jridgewell/gen-mapping@0.3.13':
dependencies:
'@jridgewell/sourcemap-codec': 1.5.5
'@jridgewell/trace-mapping': 0.3.31
'@jridgewell/resolve-uri@3.1.2': {}
'@jridgewell/sourcemap-codec@1.5.5': {}
'@jridgewell/trace-mapping@0.3.31':
dependencies:
'@jridgewell/resolve-uri': 3.1.2
'@jridgewell/sourcemap-codec': 1.5.5
'@rollup/rollup-android-arm-eabi@4.59.0':
optional: true
'@rollup/rollup-android-arm64@4.59.0':
optional: true
'@rollup/rollup-darwin-arm64@4.59.0':
optional: true
'@rollup/rollup-darwin-x64@4.59.0':
optional: true
'@rollup/rollup-freebsd-arm64@4.59.0':
optional: true
'@rollup/rollup-freebsd-x64@4.59.0':
optional: true
'@rollup/rollup-linux-arm-gnueabihf@4.59.0':
optional: true
'@rollup/rollup-linux-arm-musleabihf@4.59.0':
optional: true
'@rollup/rollup-linux-arm64-gnu@4.59.0':
optional: true
'@rollup/rollup-linux-arm64-musl@4.59.0':
optional: true
'@rollup/rollup-linux-loong64-gnu@4.59.0':
optional: true
'@rollup/rollup-linux-loong64-musl@4.59.0':
optional: true
'@rollup/rollup-linux-ppc64-gnu@4.59.0':
optional: true
'@rollup/rollup-linux-ppc64-musl@4.59.0':
optional: true
'@rollup/rollup-linux-riscv64-gnu@4.59.0':
optional: true
'@rollup/rollup-linux-riscv64-musl@4.59.0':
optional: true
'@rollup/rollup-linux-s390x-gnu@4.59.0':
optional: true
'@rollup/rollup-linux-x64-gnu@4.59.0':
optional: true
'@rollup/rollup-linux-x64-musl@4.59.0':
optional: true
'@rollup/rollup-openbsd-x64@4.59.0':
optional: true
'@rollup/rollup-openharmony-arm64@4.59.0':
optional: true
'@rollup/rollup-win32-arm64-msvc@4.59.0':
optional: true
'@rollup/rollup-win32-ia32-msvc@4.59.0':
optional: true
'@rollup/rollup-win32-x64-gnu@4.59.0':
optional: true
'@rollup/rollup-win32-x64-msvc@4.59.0':
optional: true
'@types/estree@1.0.8': {}
'@types/node@25.3.0':
dependencies:
undici-types: 7.18.2
acorn@8.16.0: {}
any-promise@1.3.0: {}
bundle-require@5.1.0(esbuild@0.27.3):
dependencies:
esbuild: 0.27.3
load-tsconfig: 0.2.5
cac@6.7.14: {}
chokidar@4.0.3:
dependencies:
readdirp: 4.1.2
commander@4.1.1: {}
confbox@0.1.8: {}
consola@3.4.2: {}
debug@4.4.3:
dependencies:
ms: 2.1.3
esbuild@0.27.3:
optionalDependencies:
'@esbuild/aix-ppc64': 0.27.3
'@esbuild/android-arm': 0.27.3
'@esbuild/android-arm64': 0.27.3
'@esbuild/android-x64': 0.27.3
'@esbuild/darwin-arm64': 0.27.3
'@esbuild/darwin-x64': 0.27.3
'@esbuild/freebsd-arm64': 0.27.3
'@esbuild/freebsd-x64': 0.27.3
'@esbuild/linux-arm': 0.27.3
'@esbuild/linux-arm64': 0.27.3
'@esbuild/linux-ia32': 0.27.3
'@esbuild/linux-loong64': 0.27.3
'@esbuild/linux-mips64el': 0.27.3
'@esbuild/linux-ppc64': 0.27.3
'@esbuild/linux-riscv64': 0.27.3
'@esbuild/linux-s390x': 0.27.3
'@esbuild/linux-x64': 0.27.3
'@esbuild/netbsd-arm64': 0.27.3
'@esbuild/netbsd-x64': 0.27.3
'@esbuild/openbsd-arm64': 0.27.3
'@esbuild/openbsd-x64': 0.27.3
'@esbuild/openharmony-arm64': 0.27.3
'@esbuild/sunos-x64': 0.27.3
'@esbuild/win32-arm64': 0.27.3
'@esbuild/win32-ia32': 0.27.3
'@esbuild/win32-x64': 0.27.3
fdir@6.5.0(picomatch@4.0.3):
optionalDependencies:
picomatch: 4.0.3
fix-dts-default-cjs-exports@1.0.1:
dependencies:
magic-string: 0.30.21
mlly: 1.8.0
rollup: 4.59.0
fsevents@2.3.3:
optional: true
joycon@3.1.1: {}
lilconfig@3.1.3: {}
lines-and-columns@1.2.4: {}
load-tsconfig@0.2.5: {}
magic-string@0.30.21:
dependencies:
'@jridgewell/sourcemap-codec': 1.5.5
mlly@1.8.0:
dependencies:
acorn: 8.16.0
pathe: 2.0.3
pkg-types: 1.3.1
ufo: 1.6.3
ms@2.1.3: {}
mz@2.7.0:
dependencies:
any-promise: 1.3.0
object-assign: 4.1.1
thenify-all: 1.6.0
nrel-spa@2.0.1: {}
object-assign@4.1.1: {}
pathe@2.0.3: {}
picocolors@1.1.1: {}
picomatch@4.0.3: {}
pirates@4.0.7: {}
pkg-types@1.3.1:
dependencies:
confbox: 0.1.8
mlly: 1.8.0
pathe: 2.0.3
postcss-load-config@6.0.1:
dependencies:
lilconfig: 3.1.3
readdirp@4.1.2: {}
resolve-from@5.0.0: {}
rollup@4.59.0:
dependencies:
'@types/estree': 1.0.8
optionalDependencies:
'@rollup/rollup-android-arm-eabi': 4.59.0
'@rollup/rollup-android-arm64': 4.59.0
'@rollup/rollup-darwin-arm64': 4.59.0
'@rollup/rollup-darwin-x64': 4.59.0
'@rollup/rollup-freebsd-arm64': 4.59.0
'@rollup/rollup-freebsd-x64': 4.59.0
'@rollup/rollup-linux-arm-gnueabihf': 4.59.0
'@rollup/rollup-linux-arm-musleabihf': 4.59.0
'@rollup/rollup-linux-arm64-gnu': 4.59.0
'@rollup/rollup-linux-arm64-musl': 4.59.0
'@rollup/rollup-linux-loong64-gnu': 4.59.0
'@rollup/rollup-linux-loong64-musl': 4.59.0
'@rollup/rollup-linux-ppc64-gnu': 4.59.0
'@rollup/rollup-linux-ppc64-musl': 4.59.0
'@rollup/rollup-linux-riscv64-gnu': 4.59.0
'@rollup/rollup-linux-riscv64-musl': 4.59.0
'@rollup/rollup-linux-s390x-gnu': 4.59.0
'@rollup/rollup-linux-x64-gnu': 4.59.0
'@rollup/rollup-linux-x64-musl': 4.59.0
'@rollup/rollup-openbsd-x64': 4.59.0
'@rollup/rollup-openharmony-arm64': 4.59.0
'@rollup/rollup-win32-arm64-msvc': 4.59.0
'@rollup/rollup-win32-ia32-msvc': 4.59.0
'@rollup/rollup-win32-x64-gnu': 4.59.0
'@rollup/rollup-win32-x64-msvc': 4.59.0
fsevents: 2.3.3
source-map@0.7.6: {}
sucrase@3.35.1:
dependencies:
'@jridgewell/gen-mapping': 0.3.13
commander: 4.1.1
lines-and-columns: 1.2.4
mz: 2.7.0
pirates: 4.0.7
tinyglobby: 0.2.15
ts-interface-checker: 0.1.13
thenify-all@1.6.0:
dependencies:
thenify: 3.3.1
thenify@3.3.1:
dependencies:
any-promise: 1.3.0
tinyexec@0.3.2: {}
tinyglobby@0.2.15:
dependencies:
fdir: 6.5.0(picomatch@4.0.3)
picomatch: 4.0.3
tree-kill@1.2.2: {}
ts-interface-checker@0.1.13: {}
tsup@8.5.1(typescript@5.9.3):
dependencies:
bundle-require: 5.1.0(esbuild@0.27.3)
cac: 6.7.14
chokidar: 4.0.3
consola: 3.4.2
debug: 4.4.3
esbuild: 0.27.3
fix-dts-default-cjs-exports: 1.0.1
joycon: 3.1.1
picocolors: 1.1.1
postcss-load-config: 6.0.1
resolve-from: 5.0.0
rollup: 4.59.0
source-map: 0.7.6
sucrase: 3.35.1
tinyexec: 0.3.2
tinyglobby: 0.2.15
tree-kill: 1.2.2
optionalDependencies:
typescript: 5.9.3
transitivePeerDependencies:
- jiti
- supports-color
- tsx
- yaml
typescript@5.9.3: {}
ufo@1.6.3: {}
undici-types@7.18.2: {}

2
pnpm-workspace.yaml Normal file
View file

@ -0,0 +1,2 @@
onlyBuiltDependencies:
- esbuild

43
src/calcTimes.ts Normal file
View file

@ -0,0 +1,43 @@
/**
* Formatted prayer times using the PrayCalc Dynamic Method.
*/
import { formatTime } from 'nrel-spa';
import { getTimes } from './getTimes.js';
import type { FormattedPrayerTimes } from './types.js';
/**
* Compute prayer times formatted as HH:MM:SS strings.
*
* Uses the dynamic twilight angle algorithm. See getTimes() for full parameter
* documentation.
*
* @returns Prayer times as HH:MM:SS strings. Returns "N/A" for any time that
* cannot be computed (polar night, unreachable angle, etc.).
*/
export function calcTimes(
date: Date,
lat: number,
lng: number,
tz: number = -date.getTimezoneOffset() / 60,
elevation = 0,
temperature = 15,
pressure = 1013.25,
hanafi = false,
): FormattedPrayerTimes {
const raw = getTimes(date, lat, lng, tz, elevation, temperature, pressure, hanafi);
// Sort by fractional hour value so output reflects chronological order.
// Angles are preserved as-is (not time values).
return {
Qiyam: formatTime(raw.Qiyam),
Fajr: formatTime(raw.Fajr),
Sunrise: formatTime(raw.Sunrise),
Noon: formatTime(raw.Noon),
Dhuhr: formatTime(raw.Dhuhr),
Asr: formatTime(raw.Asr),
Maghrib: formatTime(raw.Maghrib),
Isha: formatTime(raw.Isha),
angles: raw.angles,
};
}

48
src/calcTimesAll.ts Normal file
View file

@ -0,0 +1,48 @@
/**
* Formatted prayer times — dynamic method plus all traditional method comparisons.
*/
import { formatTime } from 'nrel-spa';
import { getTimesAll } from './getTimesAll.js';
import type { FormattedPrayerTimesAll } from './types.js';
/**
* Compute prayer times formatted as HH:MM:SS strings, plus comparison times
* for every supported traditional method.
*
* Uses the dynamic twilight angle algorithm for the primary times. See
* getTimesAll() for full parameter documentation.
*
* @returns All prayer times as HH:MM:SS strings. "N/A" for unreachable events.
* Methods map contains [fajrString, ishaString] per method.
*/
export function calcTimesAll(
date: Date,
lat: number,
lng: number,
tz: number = -date.getTimezoneOffset() / 60,
elevation = 0,
temperature = 15,
pressure = 1013.25,
hanafi = false,
): FormattedPrayerTimesAll {
const raw = getTimesAll(date, lat, lng, tz, elevation, temperature, pressure, hanafi);
const Methods: Record<string, [string, string]> = {};
for (const [id, [fajr, isha]] of Object.entries(raw.Methods)) {
Methods[id] = [formatTime(fajr), formatTime(isha)];
}
return {
Qiyam: formatTime(raw.Qiyam),
Fajr: formatTime(raw.Fajr),
Sunrise: formatTime(raw.Sunrise),
Noon: formatTime(raw.Noon),
Dhuhr: formatTime(raw.Dhuhr),
Asr: formatTime(raw.Asr),
Maghrib: formatTime(raw.Maghrib),
Isha: formatTime(raw.Isha),
angles: raw.angles,
Methods,
};
}

209
src/getAngles.ts Normal file
View file

@ -0,0 +1,209 @@
/**
* Dynamic twilight angle algorithm — PrayCalc Dynamic Method v2.
*
* Computes adaptive Fajr and Isha solar depression angles that accurately
* track the observable phenomenon (Subh Sadiq / end of Shafaq) across all
* latitudes and seasons, replacing a static angle with a physics-informed
* estimate.
*
* ## Algorithm
*
* The research literature establishes that "true dawn" and "end of twilight"
* are not tied to a single universal solar depression angle. The required
* angle varies with latitude, season, and atmospheric conditions. Field
* studies show approximately:
*
* - Low latitudes (0–30°): ~16–19° (dark-sky conditions approach 18–19°)
* - Mid-latitudes (30–45°): ~14–17°, with seasonal variation
* - High latitudes (45–55°):~11–15°, strongly seasonal (shallow in summer)
*
* This implementation uses a three-layer model:
*
* 1. **MSC base**: The Moonsighting Committee Worldwide (MCW) piecewise
* seasonal function is used as the empirical baseline — the most widely
* validated and observation-calibrated model available. The MCW minutes-
* before-sunrise value is converted to an equivalent depression angle
* via exact spherical trigonometry.
*
* 2. **Ephemeris corrections**: Physics-based adjustments derived from
* accurate solar position features (ecliptic longitude, Earth-Sun
* distance, solar vertical speed). These smooth over the MCW's piecewise
* discontinuities and capture the small irradiance variation (~3.3%)
* due to Earth's orbital eccentricity (perihelion in January, aphelion
* in July).
*
* 3. **Environmental corrections**: Observer elevation (horizon dip) and
* atmospheric refraction scaled to local pressure and temperature.
*
* ## Why this is better than a fixed angle
*
* Fixed angles (e.g., 18°, 15°) do not adapt to latitude-season geometry
* and break outright at higher latitudes in summer when the sun never reaches
* 15° below the horizon. This algorithm produces smooth, continuous values
* validated against the MCW observational corpus and enhanced by physical
* corrections the MCW piecewise model cannot express.
*
* ## References
*
* - Moonsighting Committee Worldwide (Khalid Shaukat): moonsighting.com
* - Deep-research reports PCP1–PCP5 (archived in internal docs)
* - Jean Meeus, Astronomical Algorithms (2nd ed., 1998)
*/
import { toJulianDate, solarEphemeris, atmosphericRefraction } from './getSolarEphemeris.js';
import { getMscFajr, getMscIsha, minutesToDepression } from './getMSC.js';
import type { TwilightAngles } from './types.js';
const DEG = Math.PI / 180;
const FAJR_MIN = 10;
const FAJR_MAX = 22;
const ISHA_MIN = 10;
const ISHA_MAX = 22;
/** Clamp a value to [min, max]. */
function clip(value: number, min: number, max: number): number {
return Math.max(min, Math.min(max, value));
}
/** Round to 3 decimal places. */
function round3(value: number): number {
return Math.round(value * 1000) / 1000;
}
/**
* Compute the Earth-Sun distance correction in degrees.
*
* Earth's orbit is slightly elliptical (eccentricity ~0.017). At perihelion
* (≈Jan 3) r ≈ 0.983 AU; at aphelion (≈Jul 4) r ≈ 1.017 AU. The 3.3%
* irradiance variation affects when twilight brightness crosses the detection
* threshold. At perihelion, higher irradiance means the threshold is crossed
* at a slightly deeper depression (earlier Fajr / later Isha); at aphelion,
* the reverse. Effect magnitude: ≈ ±0.15°.
*
* Physical basis: L_tw ∝ r^{-2}, so threshold α is reached at a value
* proportional to −(1/2) ln(r). The negative sign is because higher
* irradiance means dawn is detectable at a slightly deeper Sun position,
* increasing the angle.
*/
function earthSunDistanceCorrection(r: number): number {
// −0.5 × ln(r): positive correction at aphelion (r > 1), negative at perihelion
// At r = 0.983: correction ≈ −0.5 × (−0.017) = +0.009° (tiny, physically correct)
// At r = 1.017: correction ≈ −0.5 × 0.017 = −0.009° (tiny)
// Scale factor 0.5 chosen to keep the effect physically realistic.
// Full irradiance effect would be larger; 0.5 accounts for the non-linear
// relationship between irradiance and perceived brightness threshold.
return -0.5 * Math.log(r);
}
/**
* Smooth Fourier season correction to remove the MCW's piecewise artifacts
* and add hemisphere-symmetric season curvature.
*
* The correction uses the solar ecliptic longitude θ (season phase) and
* |φ| × seasonal interaction. Coefficients are calibrated to:
* - match MCW behavior at key anchor latitudes (0°, 30°, 50°)
* - reduce step-function artifacts at the MCW segment boundaries (dyy ≈ 91, 137, ...)
* - add a mild correction for the June-solstice / December-solstice asymmetry
* driven by r (perihelion in January vs aphelion in July)
*
* Net effect is small (< 0.3°) and primarily improves day-to-day smoothness.
*/
function fourierSmoothingCorrection(
eclLon: number,
latAbsDeg: number,
): number {
const theta = eclLon; // solar ecliptic longitude, radians [0, 2π)
const phi = latAbsDeg * DEG;
// First harmonic: small annual asymmetry correction
// The perihelion/aphelion asymmetry causes slightly different twilight
// behavior in January vs July even at the same declination.
const a1 = 0.03 * Math.sin(theta); // peaks at ~Jun solstice
const b1 = -0.05 * Math.cos(theta); // peaks at equinoxes
// Second harmonic: semi-annual variation
const a2 = 0.02 * Math.sin(2 * theta);
const b2 = 0.02 * Math.cos(2 * theta);
// Latitude × season interaction: refines the MCW's latitude scaling
const c1 = -0.008 * phi * Math.sin(theta);
const d1 = 0.004 * phi * Math.cos(theta);
return a1 + b1 + a2 + b2 + c1 + d1;
}
/**
* Compute dynamic twilight depression angles for Fajr and Isha.
*
* @param date - Observer's local date (time-of-day is ignored)
* @param lat - Latitude in decimal degrees
* @param lng - Longitude in decimal degrees (currently unused; reserved)
* @param elevation - Observer elevation in meters (default: 0)
* @param temperature - Ambient temperature in °C (default: 15)
* @param pressure - Atmospheric pressure in mbar (default: 1013.25)
* @returns Fajr and Isha depression angles in degrees
*/
export function getAngles(
date: Date,
lat: number,
lng: number,
elevation = 0,
temperature = 15,
pressure = 1013.25,
): TwilightAngles {
// 1. Solar ephemeris features at solar noon of the given date.
// Using UTC noon as a stable reference that avoids timezone artifacts.
const noonDate = new Date(Date.UTC(date.getFullYear(), date.getMonth(), date.getDate(), 12, 0, 0));
const jd = toJulianDate(noonDate);
const { decl, r, eclLon } = solarEphemeris(jd);
// 2. MCW reference times (minutes before/after sunrise/sunset).
const mscFajrMin = getMscFajr(date, lat);
const mscIshaMin = getMscIsha(date, lat);
// 3. Convert MCW minutes to equivalent solar depression angles using
// exact spherical trigonometry with the accurate Meeus declination.
let fajrBase = minutesToDepression(mscFajrMin, lat, decl);
let ishaBase = minutesToDepression(mscIshaMin, lat, decl);
// Handle polar or unreachable geometry: fall back to safe defaults.
if (!isFinite(fajrBase) || isNaN(fajrBase)) fajrBase = 18.0;
if (!isFinite(ishaBase) || isNaN(ishaBase)) ishaBase = 18.0;
// 4. Earth-Sun distance correction (±0.015°, positive at aphelion).
const rCorr = earthSunDistanceCorrection(r);
// 5. Fourier smoothing correction (< 0.3° total).
const fourierCorr = fourierSmoothingCorrection(eclLon, Math.abs(lat));
// 6. Atmospheric refraction at the expected twilight depression.
// Refraction at 15° below horizon is small (~0.06°). We apply it with
// opposite sign for Fajr vs Isha: refraction raises apparent altitude,
// meaning the true geometric sun is slightly deeper than the perceived one.
// For Fajr (morning): refraction effectively means dawn occurs slightly
// earlier (when sun is slightly deeper geometrically) → add to Fajr angle.
// For Isha (evening): same physical effect → add to Isha angle.
// Note: nrel-spa already accounts for refraction near the horizon. Here we
// apply the correction to the twilight angle itself (deeper depression zone).
const refrFajr = atmosphericRefraction(-(fajrBase + 0.5), pressure, temperature);
const refrIsha = atmosphericRefraction(-(ishaBase + 0.5), pressure, temperature);
// 7. Elevation correction: higher observers see further around Earth's curvature,
// effectively dipping the horizon. This makes sunrise slightly earlier and
// sunset slightly later. For Fajr/Isha, the effect is ~0.08°/km elevation.
// Using dip = 1.06 × √(h_km) in degrees, scaled by factor for twilight
// (the dip effect is reduced at large depression angles vs the horizon).
const horizonDipDeg = 1.06 * Math.sqrt(elevation / 1000);
// Apply 30% of horizon dip to twilight angles (remainder already captured
// by nrel-spa's elevation-adjusted sunrise/sunset computation).
const elevCorr = horizonDipDeg * 0.3;
// 8. Assemble final angles with all corrections.
const rawFajr = fajrBase + rCorr + fourierCorr + refrFajr + elevCorr;
const rawIsha = ishaBase + rCorr + fourierCorr + refrIsha + elevCorr;
const fajrAngle = round3(clip(rawFajr, FAJR_MIN, FAJR_MAX));
const ishaAngle = round3(clip(rawIsha, ISHA_MIN, ISHA_MAX));
return { fajrAngle, ishaAngle };
}

49
src/getAsr.ts Normal file
View file

@ -0,0 +1,49 @@
/**
* Asr prayer time calculation.
*
* Asr begins when the shadow of an object equals (Shafi'i/Maliki/Hanbali)
* or twice (Hanafi) the object's length plus its shadow at solar noon.
* This is a pure spherical trigonometry problem once solar declination
* and solar noon are known.
*/
const DEG = Math.PI / 180;
/**
* Compute Asr time as fractional hours.
*
* @param solarNoon - Solar noon in fractional hours (from getSpa)
* @param latitude - Observer latitude in degrees
* @param declination - Solar declination in degrees (from solarEphemeris)
* @param hanafi - true for Hanafi (shadow factor 2), false for Shafi'i (factor 1)
* @returns Fractional hours, or NaN if the sun never reaches the required altitude
*/
export function getAsr(
solarNoon: number,
latitude: number,
declination: number,
hanafi = false,
): number {
const phi = latitude * DEG;
const delta = declination * DEG;
const shadowFactor = hanafi ? 2 : 1;
// Required solar altitude:
// tan(A) = 1 / (shadowFactor + tan(|φ − δ|))
const X = Math.abs(phi - delta);
const tanA = 1 / (shadowFactor + Math.tan(X));
const sinA = tanA / Math.sqrt(1 + tanA * tanA); // sin(atan(tanA))
// Solve the hour-angle equation:
// cos(H0) = (sin(A) − sin(φ)sin(δ)) / (cos(φ)cos(δ))
const cosH0 =
(sinA - Math.sin(phi) * Math.sin(delta)) /
(Math.cos(phi) * Math.cos(delta));
if (cosH0 < -1 || cosH0 > 1) return NaN; // sun never reaches A
// H0 in hours (15°/hr)
const H0h = Math.acos(cosH0) / DEG / 15;
return solarNoon + H0h;
}

188
src/getMSC.ts Normal file
View file

@ -0,0 +1,188 @@
/**
* Moonsighting Committee Worldwide (MCW) seasonal algorithm.
*
* Computes Fajr and Isha as time offsets from sunrise/sunset using the
* empirical piecewise-linear seasonal functions developed by the Moonsighting
* Committee Worldwide (Khalid Shaukat). The functions were derived by
* curve-fitting observations of Subh Sadiq (true dawn) and the end of
* Shafaq (twilight glow) across multiple latitudes.
*
* Reference: moonsighting.com/isha_fajr.html
*
* High-latitude handling (|lat| > 55°): falls back to 1/7-night rule.
*/
export type ShafaqMode = 'general' | 'ahmer' | 'abyad';
function isLeapYear(year: number): boolean {
return (year % 4 === 0 && year % 100 !== 0) || year % 400 === 0;
}
/**
* Compute the MCW seasonal index (dyy): days elapsed since the nearest
* winter solstice (Northern Hemisphere) or summer solstice (Southern).
*/
function computeDyy(date: Date, latitude: number): { dyy: number; daysInYear: number } {
const year = date.getFullYear();
const daysInYear = isLeapYear(year) ? 366 : 365;
// Reference solstice: Dec 21 for Northern, Jun 21 for Southern
const refMonth = latitude >= 0 ? 11 : 5; // Dec = 11, Jun = 5
const refDay = 21;
const zeroDate = new Date(year, refMonth, refDay);
let diffDays = Math.floor(
(Date.UTC(date.getFullYear(), date.getMonth(), date.getDate()) -
Date.UTC(zeroDate.getFullYear(), zeroDate.getMonth(), zeroDate.getDate())) /
86400000,
);
if (diffDays < 0) diffDays += daysInYear;
return { dyy: diffDays, daysInYear };
}
/**
* Piecewise-linear seasonal interpolation over 6 segments.
* a, b, c, d are the reference values at the seasonal anchor points.
*/
function interpolateSegment(
dyy: number,
daysInYear: number,
a: number,
b: number,
c: number,
d: number,
): number {
if (dyy < 91) {
return a + ((b - a) / 91) * dyy;
} else if (dyy < 137) {
return b + ((c - b) / 46) * (dyy - 91);
} else if (dyy < 183) {
return c + ((d - c) / 46) * (dyy - 137);
} else if (dyy < 229) {
return d + ((c - d) / 46) * (dyy - 183);
} else if (dyy < 275) {
return c + ((b - c) / 46) * (dyy - 229);
} else {
const len = daysInYear - 275;
return b + ((a - b) / len) * (dyy - 275);
}
}
/**
* Compute Fajr offset in minutes before sunrise using the MCW algorithm.
*
* Returns minutes before sunrise. At latitudes above 55°, the 1/7-night
* approximation is recommended (handled at the calling site).
*/
export function getMscFajr(date: Date, latitude: number): number {
const latAbs = Math.abs(latitude);
const { dyy, daysInYear } = computeDyy(date, latitude);
const a = 75 + (28.65 / 55) * latAbs;
const b = 75 + (19.44 / 55) * latAbs;
const c = 75 + (32.74 / 55) * latAbs;
const d = 75 + (48.1 / 55) * latAbs;
return Math.round(interpolateSegment(dyy, daysInYear, a, b, c, d));
}
/**
* Compute Isha offset in minutes after sunset using the MCW algorithm.
*
* Three Shafaq modes:
* - 'general': blend that reduces hardship at high latitudes (default)
* - 'ahmer': based on disappearance of redness (shafaq ahmer)
* - 'abyad': based on disappearance of whiteness (shafaq abyad), later
*/
export function getMscIsha(
date: Date,
latitude: number,
shafaq: ShafaqMode = 'general',
): number {
const latAbs = Math.abs(latitude);
const { dyy, daysInYear } = computeDyy(date, latitude);
let a: number, b: number, c: number, d: number;
switch (shafaq) {
case 'ahmer':
a = 62 + (17.4 / 55) * latAbs;
b = 62 - (7.16 / 55) * latAbs;
c = 62 + (5.12 / 55) * latAbs;
d = 62 + (19.44 / 55) * latAbs;
break;
case 'abyad':
a = 75 + (25.6 / 55) * latAbs;
b = 75 + (7.16 / 55) * latAbs;
c = 75 + (36.84 / 55) * latAbs;
d = 75 + (81.84 / 55) * latAbs;
break;
default: // 'general'
a = 75 + (25.6 / 55) * latAbs;
b = 75 + (2.05 / 55) * latAbs;
c = 75 - (9.21 / 55) * latAbs;
d = 75 + (6.14 / 55) * latAbs;
}
return Math.round(interpolateSegment(dyy, daysInYear, a, b, c, d));
}
/**
* Convert MCW minutes-before-sunrise to an equivalent solar depression angle
* in degrees, using exact spherical trigonometry.
*
* This is the inverse of the standard hour-angle sunrise formula and gives
* the depression angle that corresponds to a given pre-sunrise interval at
* the observer's latitude and the given solar declination.
*
* Returns NaN if the geometry is unreachable (polar day/night).
*/
export function minutesToDepression(
minutes: number,
latDeg: number,
declDeg: number,
): number {
const phi = latDeg * (Math.PI / 180);
const delta = declDeg * (Math.PI / 180);
const cosPhi = Math.cos(phi);
const sinPhi = Math.sin(phi);
const cosDelta = Math.cos(delta);
const sinDelta = Math.sin(delta);
// Standard sunrise/sunset: h = -0.833° (includes refraction + semi-diameter)
const h0 = -0.833 * (Math.PI / 180);
const sinH0 = Math.sin(h0);
const denominator = cosPhi * cosDelta;
if (Math.abs(denominator) < 1e-10) return NaN;
// Hour angle at standard sunrise
const cosH_rise = (sinH0 - sinPhi * sinDelta) / denominator;
if (cosH_rise < -1) return NaN; // polar night
if (cosH_rise > 1) return NaN; // polar day
const H_rise = Math.acos(cosH_rise); // radians
// Hour angle at the prayer time (further from solar noon)
const deltaH = (minutes / 60) * 15 * (Math.PI / 180);
const H_prayer = H_rise + deltaH;
// Cap at π (midnight) - sun cannot go further below horizon
if (H_prayer > Math.PI) {
// Return the depression at midnight (minimum possible for this date/lat)
const sinH_midnight = sinPhi * sinDelta + cosPhi * cosDelta * Math.cos(Math.PI);
const h_midnight = Math.asin(Math.max(-1, Math.min(1, sinH_midnight)));
return -h_midnight / (Math.PI / 180);
}
// Solar altitude at H_prayer
const sinH_prayer =
sinPhi * sinDelta + cosPhi * cosDelta * Math.cos(H_prayer);
const h_prayer = Math.asin(Math.max(-1, Math.min(1, sinH_prayer)));
// Depression angle: positive when sun is below horizon
return -h_prayer / (Math.PI / 180);
}

25
src/getQiyam.ts Normal file
View file

@ -0,0 +1,25 @@
/**
* Qiyam al-Layl (night prayer) time calculation.
*
* Returns the start of the last third of the night, which is the recommended
* time for Tahajjud / Qiyam al-Layl. The night is defined as the period
* from Isha to Fajr.
*/
/**
* Compute the start of the last third of the night.
*
* @param fajrTime - Fajr time in fractional hours
* @param ishaTime - Isha time in fractional hours
* @returns Start of the last third of the night (fractional hours)
*/
export function getQiyam(fajrTime: number, ishaTime: number): number {
// If Fajr is numerically earlier (e.g. 5.5) than Isha (e.g. 21.5), Fajr
// is actually the NEXT day — add 24 to get the correct night length.
const adjustedFajr = fajrTime < ishaTime ? fajrTime + 24 : fajrTime;
const nightLength = adjustedFajr - ishaTime;
const lastThirdStart = ishaTime + (2 * nightLength) / 3;
return lastThirdStart >= 24 ? lastThirdStart - 24 : lastThirdStart;
}

123
src/getSolarEphemeris.ts Normal file
View file

@ -0,0 +1,123 @@
/**
* High-accuracy solar ephemeris features without a full SPA call.
*
* Uses Jean Meeus "Astronomical Algorithms" (2nd ed., Ch. 25) low-precision
* formulas, accurate to approximately ±0.01° for solar declination and
* ±0.0001 AU for Earth-Sun distance over the years 1950-2050. This is
* sufficient for computing twilight angles; exact Sun positioning for
* prayer time solving still uses the full SPA via nrel-spa.
*/
const DEG = Math.PI / 180;
/** Julian Date from a JavaScript Date (UTC). */
export function toJulianDate(date: Date): number {
return date.getTime() / 86400000 + 2440587.5;
}
export interface SolarEphemeris {
/** Solar declination in degrees. */
decl: number;
/** Earth-Sun distance in AU. */
r: number;
/** Apparent solar ecliptic longitude in radians (season phase θ, 0–2π). */
eclLon: number;
}
/**
* Compute solar declination, Earth-Sun distance, and ecliptic longitude
* from a Julian Date. Accuracy: ~0.01° for declination, ~0.0001 AU for r.
*/
export function solarEphemeris(jd: number): SolarEphemeris {
const T = (jd - 2451545.0) / 36525.0;
// Geometric mean longitude L0 (degrees)
const L0 = ((280.46646 + 36000.76983 * T + 0.0003032 * T * T) % 360 + 360) % 360;
// Mean anomaly M (degrees)
const M = ((357.52911 + 35999.05029 * T - 0.0001537 * T * T) % 360 + 360) % 360;
const Mrad = M * DEG;
// Orbital eccentricity
const e = 0.016708634 - 0.000042037 * T - 0.0000001267 * T * T;
// Equation of center C (degrees)
const C =
(1.914602 - 0.004817 * T - 0.000014 * T * T) * Math.sin(Mrad) +
(0.019993 - 0.000101 * T) * Math.sin(2 * Mrad) +
0.000289 * Math.sin(3 * Mrad);
// Sun's true longitude (degrees)
const sunLon = L0 + C;
// Sun's true anomaly (degrees)
const nu = M + C;
const nuRad = nu * DEG;
// Earth-Sun distance in AU
const r = (1.000001018 * (1 - e * e)) / (1 + e * Math.cos(nuRad));
// Longitude of ascending node of Moon's orbit (for nutation)
const Omega = ((125.04 - 1934.136 * T) % 360 + 360) % 360;
const OmegaRad = Omega * DEG;
// Apparent solar longitude corrected for nutation and aberration
const lambda = sunLon - 0.00569 - 0.00478 * Math.sin(OmegaRad);
const lambdaRad = lambda * DEG;
// Mean obliquity of the ecliptic (degrees)
const epsilon0 =
23.439291 -
0.013004 * T -
1.638e-7 * T * T +
5.036e-7 * T * T * T;
// True obliquity with nutation correction
const epsilon = (epsilon0 + 0.00256 * Math.cos(OmegaRad)) * DEG;
// Solar declination
const sinDecl = Math.sin(epsilon) * Math.sin(lambdaRad);
const decl = Math.asin(Math.max(-1, Math.min(1, sinDecl))) / DEG;
// Ecliptic longitude as season phase θ ∈ [0, 2π)
const eclLon = ((lambdaRad % (2 * Math.PI)) + 2 * Math.PI) % (2 * Math.PI);
return { decl, r, eclLon };
}
/**
* Solar vertical angular speed near a given hour angle H (radians),
* in degrees per hour. Useful as a confidence weight for angle predictions:
* higher speed means each degree of angle error is fewer minutes of time error.
*
* Formula: dh/dt ≈ 15 × cos(φ) × cos(δ) × sin(H) [°/hr]
*/
export function solarVerticalSpeed(
latRad: number,
declRad: number,
hAngleRad: number,
): number {
return 15 * Math.abs(Math.cos(latRad) * Math.cos(declRad) * Math.sin(hAngleRad));
}
/**
* Compute the atmospheric refraction correction (degrees) for a given
* apparent solar altitude using the Bennett/Saemundsson formula.
* Scaled for pressure and temperature.
*
* Returns a positive correction (the Sun appears higher than its geometric
* position). For altitudes below -1°, returns 0 (not meaningful for Fajr/Isha
* at depression angles like 12–20°, but included for completeness).
*/
export function atmosphericRefraction(
altitudeDeg: number,
pressureMbar = 1013.25,
temperatureC = 15,
): number {
if (altitudeDeg < -1) return 0;
// Bennett's formula in arcminutes
const R0 = 1.02 / Math.tan((altitudeDeg + 10.3 / (altitudeDeg + 5.11)) * DEG);
// Scale for pressure and temperature
const R = R0 * (pressureMbar / 1010) * (283 / (273 + temperatureC));
return Math.max(0, R) / 60; // convert arcminutes to degrees
}

85
src/getTimes.ts Normal file
View file

@ -0,0 +1,85 @@
/**
* Core prayer times computation using the PrayCalc Dynamic Method.
*
* Returns all prayer times as fractional hours using the dynamic twilight
* angle algorithm. Times are in local time as determined by the timezone
* offset (tz parameter).
*/
import { getSpa } from 'nrel-spa';
import { toJulianDate, solarEphemeris } from './getSolarEphemeris.js';
import { getAngles } from './getAngles.js';
import { getAsr } from './getAsr.js';
import { getQiyam } from './getQiyam.js';
import type { PrayerTimes } from './types.js';
/**
* Compute prayer times for a given date and location.
*
* @param date - Observer's local date (time-of-day is ignored)
* @param lat - Latitude in decimal degrees (−90 to 90, south = negative)
* @param lng - Longitude in decimal degrees (−180 to 180, west = negative)
* @param tz - UTC offset in hours (e.g. −5 for EST). Defaults to the
* system timezone derived from the Date object.
* @param elevation - Observer elevation in meters (default: 0)
* @param temperature - Ambient temperature in °C (default: 15)
* @param pressure - Atmospheric pressure in mbar/hPa (default: 1013.25)
* @param hanafi - Asr convention: false = Shafi'i/Maliki/Hanbali (default),
* true = Hanafi
* @returns Prayer times as fractional hours and the dynamic angles used
*/
export function getTimes(
date: Date,
lat: number,
lng: number,
tz: number = -date.getTimezoneOffset() / 60,
elevation = 0,
temperature = 15,
pressure = 1013.25,
hanafi = false,
): PrayerTimes {
// 1. Compute dynamic twilight angles.
const { fajrAngle, ishaAngle } = getAngles(date, lat, lng, elevation, temperature, pressure);
// 2. Convert depression angles to SPA zenith angles.
// SPA uses zenith angle (90° + depression) for custom altitude events.
const fajrZenith = 90 + fajrAngle;
const ishaZenith = 90 + ishaAngle;
// 3. Run SPA for solar position + custom twilight times.
const spaOpts = { elevation, temperature, pressure };
const spaData = getSpa(date, lat, lng, tz, spaOpts, [fajrZenith, ishaZenith]);
const fajrTime = spaData.angles[0].sunrise;
const sunriseTime = spaData.sunrise;
const noonTime = spaData.solarNoon;
const maghribTime = spaData.sunset;
const ishaTime = spaData.angles[1].sunset;
// Dhuhr: 2.5 minutes after solar noon (standard practice to confirm transit).
const dhuhrTime = noonTime + 2.5 / 60;
// 4. Solar declination for Asr (Meeus formula, accurate to ~0.01°).
const jd = toJulianDate(
new Date(Date.UTC(date.getFullYear(), date.getMonth(), date.getDate(), 12, 0, 0)),
);
const { decl } = solarEphemeris(jd);
// 5. Asr time.
const asrTime = getAsr(noonTime, lat, decl, hanafi);
// 6. Qiyam al-Layl (last third of the night).
const qiyamTime = getQiyam(fajrTime, ishaTime);
return {
Qiyam: isFinite(qiyamTime) ? qiyamTime : NaN,
Fajr: isFinite(fajrTime) ? fajrTime : NaN,
Sunrise: isFinite(sunriseTime) ? sunriseTime : NaN,
Noon: isFinite(noonTime) ? noonTime : NaN,
Dhuhr: isFinite(dhuhrTime) ? dhuhrTime : NaN,
Asr: isFinite(asrTime) ? asrTime : NaN,
Maghrib: isFinite(maghribTime) ? maghribTime : NaN,
Isha: isFinite(ishaTime) ? ishaTime : NaN,
angles: { fajrAngle, ishaAngle },
};
}

157
src/getTimesAll.ts Normal file
View file

@ -0,0 +1,157 @@
/**
* Prayer times comparison — all methods.
*
* Returns the PrayCalc Dynamic times plus comparison times for every
* supported traditional method, all as fractional hours.
*
* Supported methods (14 total):
*
* | ID | Name | Fajr | Isha | Region |
* |---------|----------------------------------------------|-------|-----------------|-----------------|
* | UOIF | Union des Org. Islamiques de France | 12° | 12° | France |
* | ISNACA | IQNA / Islamic Council of North America | 13° | 13° | Canada |
* | ISNA | FCNA / Islamic Society of North America | 15° | 15° | US, UK, AU, NZ |
* | SAMR | Spiritual Admin. of Muslims of Russia | 16° | 15° | Russia |
* | IGUT | Inst. of Geophysics, Univ. of Tehran | 17.7° | 14° | Iran, Shia use |
* | MWL | Muslim World League | 18° | 17° | Global default |
* | DIBT | Diyanet İşleri Başkanlığı, Turkey | 18° | 17° | Turkey |
* | Karachi | University of Islamic Sciences, Karachi | 18° | 18° | PK, BD, IN, AF |
* | Kuwait | Kuwait Ministry of Islamic Affairs | 18° | 17.5° | Kuwait |
* | UAQ | Umm Al-Qura University, Makkah | 18.5° | +90 min sunset | Saudi / Gulf |
* | Qatar | Qatar / Gulf (standard minutes interval) | 18° | +90 min sunset | Qatar, Gulf |
* | Egypt | Egyptian General Authority of Survey | 19.5° | 17.5° | EG, SY, IQ, LB |
* | MUIS | Majlis Ugama Islam Singapura | 20° | 18° | Singapore |
* | MSC | Moonsighting Committee Worldwide (seasonal) | — | — | Global |
*/
import { getSpa } from 'nrel-spa';
import { toJulianDate, solarEphemeris } from './getSolarEphemeris.js';
import { getAngles } from './getAngles.js';
import { getAsr } from './getAsr.js';
import { getQiyam } from './getQiyam.js';
import { getMscFajr, getMscIsha } from './getMSC.js';
import type { MethodDefinition, PrayerTimesAll } from './types.js';
/** All supported traditional methods. */
const METHODS: MethodDefinition[] = [
{ id: 'UOIF', name: 'Union des Organisations Islamiques de France', region: 'France', fajrAngle: 12, ishaAngle: 12 },
{ id: 'ISNACA', name: 'IQNA / Islamic Council of North America', region: 'Canada', fajrAngle: 13, ishaAngle: 13 },
{ id: 'ISNA', name: 'FCNA / Islamic Society of North America', region: 'US, UK, AU, NZ', fajrAngle: 15, ishaAngle: 15 },
{ id: 'SAMR', name: 'Spiritual Administration of Muslims of Russia', region: 'Russia', fajrAngle: 16, ishaAngle: 15 },
{ id: 'IGUT', name: 'Institute of Geophysics, University of Tehran', region: 'Iran', fajrAngle: 17.7, ishaAngle: 14 },
{ id: 'MWL', name: 'Muslim World League', region: 'Global', fajrAngle: 18, ishaAngle: 17 },
{ id: 'DIBT', name: 'Diyanet İşleri Başkanlığı, Turkey', region: 'Turkey', fajrAngle: 18, ishaAngle: 17 },
{ id: 'Karachi', name: 'University of Islamic Sciences, Karachi', region: 'PK, BD, IN, AF', fajrAngle: 18, ishaAngle: 18 },
{ id: 'Kuwait', name: 'Kuwait Ministry of Islamic Affairs', region: 'Kuwait', fajrAngle: 18, ishaAngle: 17.5 },
{ id: 'UAQ', name: 'Umm Al-Qura University, Makkah', region: 'Saudi Arabia', fajrAngle: 18.5, ishaAngle: null, ishaMinutes: 90 },
{ id: 'Qatar', name: 'Qatar / Gulf Standard', region: 'Qatar, Gulf', fajrAngle: 18, ishaAngle: null, ishaMinutes: 90 },
{ id: 'Egypt', name: 'Egyptian General Authority of Survey', region: 'EG, SY, IQ, LB', fajrAngle: 19.5, ishaAngle: 17.5 },
{ id: 'MUIS', name: 'Majlis Ugama Islam Singapura', region: 'Singapore', fajrAngle: 20, ishaAngle: 18 },
{ id: 'MSC', name: 'Moonsighting Committee Worldwide', region: 'Global', fajrAngle: null, ishaAngle: null, useMSC: true },
];
/**
* Compute prayer times plus all traditional method comparisons.
*
* @param date - Observer's local date
* @param lat - Latitude in decimal degrees
* @param lng - Longitude in decimal degrees
* @param tz - UTC offset in hours (defaults to system tz)
* @param elevation - Observer elevation in meters (default: 0)
* @param temperature - Ambient temperature in °C (default: 15)
* @param pressure - Atmospheric pressure in mbar (default: 1013.25)
* @param hanafi - Asr convention: false = Shafi'i (default), true = Hanafi
* @returns Prayer times for the dynamic method plus all traditional methods
*/
export function getTimesAll(
date: Date,
lat: number,
lng: number,
tz: number = -date.getTimezoneOffset() / 60,
elevation = 0,
temperature = 15,
pressure = 1013.25,
hanafi = false,
): PrayerTimesAll {
// 1. Dynamic angles.
const { fajrAngle, ishaAngle } = getAngles(date, lat, lng, elevation, temperature, pressure);
// 2. Build batch zenith angles for the SPA call:
// Slot 0: dynamic Fajr, Slot 1: dynamic Isha, then pairs for each method.
// Methods with null angles (UAQ-isha, Qatar-isha, MSC) get a placeholder
// that is overridden below.
const methodZeniths: number[] = [];
for (const m of METHODS) {
const fZ = m.fajrAngle !== null ? 90 + m.fajrAngle : 90 + 18; // placeholder for non-angle Fajr
const iZ = m.ishaAngle !== null ? 90 + m.ishaAngle : 90 + 18; // placeholder for fixed-minute Isha
methodZeniths.push(fZ, iZ);
}
const allZeniths: [number, ...number[]] = [
90 + fajrAngle,
90 + ishaAngle,
...(methodZeniths as number[]),
] as [number, ...number[]];
const spaOpts = { elevation, temperature, pressure };
const spaData = getSpa(date, lat, lng, tz, spaOpts, allZeniths);
// 3. Extract core times (index 0 = dynamic Fajr, index 1 = dynamic Isha).
const fajrTime = spaData.angles[0].sunrise;
const sunriseTime = spaData.sunrise;
const noonTime = spaData.solarNoon;
const maghribTime = spaData.sunset;
const ishaTime = spaData.angles[1].sunset;
const dhuhrTime = noonTime + 2.5 / 60;
// 4. Solar declination for Asr.
const jd = toJulianDate(
new Date(Date.UTC(date.getFullYear(), date.getMonth(), date.getDate(), 12, 0, 0)),
);
const { decl } = solarEphemeris(jd);
const asrTime = getAsr(noonTime, lat, decl, hanafi);
const qiyamTime = getQiyam(fajrTime, ishaTime);
// 5. Build Methods map.
const Methods: Record<string, [number, number]> = {};
for (let i = 0; i < METHODS.length; i++) {
const m = METHODS[i];
const spaBaseIdx = 2 + i * 2; // angles index offset for this method
let methodFajr = spaData.angles[spaBaseIdx].sunrise;
let methodIsha: number;
if (m.useMSC) {
// MSC: seasonal minutes from sunrise/sunset.
const mscFajrMin = getMscFajr(date, lat);
const mscIshaMin = getMscIsha(date, lat);
methodFajr = isFinite(sunriseTime) ? sunriseTime - mscFajrMin / 60 : NaN;
methodIsha = isFinite(maghribTime) ? maghribTime + mscIshaMin / 60 : NaN;
} else if (m.ishaMinutes !== undefined) {
// Fixed-minute Isha (UAQ = 90 min, Qatar = 90 min after sunset).
methodIsha = isFinite(maghribTime) ? maghribTime + m.ishaMinutes / 60 : NaN;
} else {
methodIsha = spaData.angles[spaBaseIdx + 1].sunset;
}
Methods[m.id] = [methodFajr, methodIsha];
}
return {
Qiyam: isFinite(qiyamTime) ? qiyamTime : NaN,
Fajr: isFinite(fajrTime) ? fajrTime : NaN,
Sunrise: isFinite(sunriseTime) ? sunriseTime : NaN,
Noon: isFinite(noonTime) ? noonTime : NaN,
Dhuhr: isFinite(dhuhrTime) ? dhuhrTime : NaN,
Asr: isFinite(asrTime) ? asrTime : NaN,
Maghrib: isFinite(maghribTime) ? maghribTime : NaN,
Isha: isFinite(ishaTime) ? ishaTime : NaN,
Methods,
angles: { fajrAngle, ishaAngle },
};
}
/** Exported method list for documentation and tooling use. */
export { METHODS };

41
src/index.ts Normal file
View file

@ -0,0 +1,41 @@
/**
* pray-calc — Islamic prayer times with a physics-grounded dynamic angle algorithm.
*
* Main exports:
* getTimes - Raw fractional-hour prayer times (dynamic method)
* calcTimes - Formatted HH:MM:SS prayer times (dynamic method)
* getTimesAll - Raw times + all 14 traditional method comparisons
* calcTimesAll - Formatted times + all 14 traditional method comparisons
* getAngles - Dynamic Fajr/Isha twilight depression angles
* getAsr - Asr prayer time from solar noon and declination
* getQiyam - Start of the last third of the night
* getMscFajr - MSC Fajr offset in minutes before sunrise
* getMscIsha - MSC Isha offset in minutes after sunset
* solarEphemeris - Jean Meeus solar ephemeris (declination, Earth-Sun distance, ecliptic lon)
* METHODS - Array of all supported traditional method definitions
*/
export { getTimes } from './getTimes.js';
export { calcTimes } from './calcTimes.js';
export { getTimesAll, METHODS } from './getTimesAll.js';
export { calcTimesAll } from './calcTimesAll.js';
export { getAngles } from './getAngles.js';
export { getAsr } from './getAsr.js';
export { getQiyam } from './getQiyam.js';
export { getMscFajr, getMscIsha } from './getMSC.js';
export { solarEphemeris, toJulianDate } from './getSolarEphemeris.js';
export type {
FractionalHours,
TimeString,
AsrConvention,
ShafaqMode,
TwilightAngles,
PrayerTimes,
FormattedPrayerTimes,
MethodEntry,
PrayerTimesAll,
FormattedPrayerTimesAll,
AtmosphericParams,
MethodDefinition,
} from './types.js';

119
src/types.ts Normal file
View file

@ -0,0 +1,119 @@
/**
* Core types for pray-calc v2.
*/
/** Fractional hours (e.g. 5.5 = 05:30:00). NaN indicates an unreachable event. */
export type FractionalHours = number;
/** HH:MM:SS string produced by formatTime, or "N/A" when unreachable. */
export type TimeString = string;
/** Asr shadow convention: Shafi'i (shadow = 1x object length) or Hanafi (2x). */
export type AsrConvention = 'shafii' | 'hanafi';
/** Shafaq (twilight glow) variant for the MSC Isha model. */
export type ShafaqMode = 'general' | 'ahmer' | 'abyad';
/** Computed twilight depression angles for Fajr and Isha. */
export interface TwilightAngles {
/** Solar depression angle for Fajr (positive degrees below horizon). */
fajrAngle: number;
/** Solar depression angle for Isha (positive degrees below horizon). */
ishaAngle: number;
}
/** Raw prayer times as fractional hours. */
export interface PrayerTimes {
/** Start of the last third of the night (Qiyam al-Layl). */
Qiyam: FractionalHours;
/** True dawn (Subh Sadiq). */
Fajr: FractionalHours;
/** Astronomical sunrise. */
Sunrise: FractionalHours;
/** Solar noon (exact geometric transit). */
Noon: FractionalHours;
/** Dhuhr (2.5 minutes after solar noon). */
Dhuhr: FractionalHours;
/** Asr (Shafi'i or Hanafi shadow convention). */
Asr: FractionalHours;
/** Maghrib (sunset). */
Maghrib: FractionalHours;
/** Isha (nightfall, end of shafaq). */
Isha: FractionalHours;
/** Dynamic twilight angles used for this calculation. */
angles: TwilightAngles;
}
/** Prayer times formatted as HH:MM:SS strings. */
export interface FormattedPrayerTimes {
Qiyam: TimeString;
Fajr: TimeString;
Sunrise: TimeString;
Noon: TimeString;
Dhuhr: TimeString;
Asr: TimeString;
Maghrib: TimeString;
Isha: TimeString;
angles: TwilightAngles;
}
/** Method entry in the Methods map: [fajrTime, ishaTime] as fractional hours. */
export type MethodEntry = [FractionalHours, FractionalHours];
/** Prayer times plus all method comparison times as fractional hours. */
export interface PrayerTimesAll extends PrayerTimes {
/** Comparison results from all supported fixed-angle and seasonal methods. */
Methods: Record<string, MethodEntry>;
}
/** Prayer times plus all method comparison times, fully formatted. */
export interface FormattedPrayerTimesAll {
Qiyam: TimeString;
Fajr: TimeString;
Sunrise: TimeString;
Noon: TimeString;
Dhuhr: TimeString;
Asr: TimeString;
Maghrib: TimeString;
Isha: TimeString;
angles: TwilightAngles;
/** Formatted comparison times for each method: [fajrString, ishaString]. */
Methods: Record<string, [TimeString, TimeString]>;
}
/** Optional atmospheric and elevation parameters. */
export interface AtmosphericParams {
elevation?: number;
temperature?: number;
pressure?: number;
}
/** Internal record for a single traditional method definition. */
export interface MethodDefinition {
/** Short identifier used as the Methods map key. */
id: string;
/** Human-readable name. */
name: string;
/** Geographic region of primary use. */
region: string;
/**
* Fajr depression angle in degrees. Null means the method uses a
* seasonal calculation (MSC) rather than a fixed angle.
*/
fajrAngle: number | null;
/**
* Isha depression angle in degrees. Null means the method uses a
* fixed-minute offset or seasonal calculation instead.
*/
ishaAngle: number | null;
/**
* Fixed minutes after sunset for Isha. Overrides ishaAngle when set.
* UAQ uses 90 year-round; Qatar uses 90 as well.
*/
ishaMinutes?: number;
/**
* When true, the method uses the MSC seasonal algorithm for both
* Fajr and Isha.
*/
useMSC?: boolean;
}

122
test-cjs.cjs Normal file
View file

@ -0,0 +1,122 @@
/**
* pray-calc v2 — CJS smoke test.
*
* Verifies that the CommonJS build loads and the primary API works.
*/
'use strict';
const assert = require('assert');
const {
getTimes,
calcTimes,
getTimesAll,
calcTimesAll,
getAngles,
getAsr,
getQiyam,
getMscFajr,
getMscIsha,
solarEphemeris,
toJulianDate,
METHODS,
} = require('./dist/index.cjs');
let passed = 0;
let failed = 0;
function test(name, fn) {
try {
fn();
console.log(` ${name}... PASS`);
passed++;
} catch (err) {
console.error(` ${name}... FAIL: ${err.message}`);
failed++;
}
}
console.log('\n[CJS] Core exports');
test('METHODS exported and has 14 entries', () => {
assert(Array.isArray(METHODS));
assert.strictEqual(METHODS.length, 14);
});
test('getTimes returns valid structure', () => {
const t = getTimes(new Date('2024-06-21'), 40.7128, -74.0060, -4);
assert(isFinite(t.Fajr), `Fajr=${t.Fajr}`);
assert(isFinite(t.Sunrise), `Sunrise=${t.Sunrise}`);
assert(isFinite(t.Maghrib), `Maghrib=${t.Maghrib}`);
assert(isFinite(t.Isha), `Isha=${t.Isha}`);
assert(typeof t.angles.fajrAngle === 'number');
});
test('calcTimes returns HH:MM:SS strings', () => {
const t = calcTimes(new Date('2024-06-21'), 40.7128, -74.0060, -4);
assert(/^\d{2}:\d{2}:\d{2}$/.test(t.Fajr), `Fajr="${t.Fajr}"`);
assert(/^\d{2}:\d{2}:\d{2}$/.test(t.Sunrise), `Sunrise="${t.Sunrise}"`);
assert(/^\d{2}:\d{2}:\d{2}$/.test(t.Maghrib), `Maghrib="${t.Maghrib}"`);
});
test('getTimesAll returns 14 methods', () => {
const t = getTimesAll(new Date('2024-06-21'), 40.7128, -74.0060, -4);
assert.strictEqual(Object.keys(t.Methods).length, 14);
});
test('calcTimesAll Methods are string pairs', () => {
const t = calcTimesAll(new Date('2024-06-21'), 40.7128, -74.0060, -4);
for (const [fajr, isha] of Object.values(t.Methods)) {
assert(typeof fajr === 'string');
assert(typeof isha === 'string');
}
});
test('getAngles returns bounded angles', () => {
const a = getAngles(new Date('2024-06-21'), 40.7128, -74.0060);
assert(a.fajrAngle >= 10 && a.fajrAngle <= 22);
assert(a.ishaAngle >= 10 && a.ishaAngle <= 22);
});
test('getAsr Hanafi later than Shafii', () => {
const s = getAsr(12.0, 40.7, 20.0, false);
const h = getAsr(12.0, 40.7, 20.0, true);
assert(h > s);
});
test('getQiyam returns a number', () => {
const q = getQiyam(4.0, 22.0);
assert(typeof q === 'number');
});
test('getMscFajr returns positive minutes', () => {
const m = getMscFajr(new Date('2024-06-21'), 40.7);
assert(m > 0);
});
test('getMscIsha returns positive minutes', () => {
const m = getMscIsha(new Date('2024-06-21'), 40.7);
assert(m > 0);
});
test('toJulianDate and solarEphemeris work', () => {
const jd = toJulianDate(new Date(Date.UTC(2024, 5, 21, 12, 0, 0)));
const e = solarEphemeris(jd);
assert(typeof e.decl === 'number');
assert(typeof e.r === 'number');
assert(typeof e.eclLon === 'number');
});
test('Makkah all-methods comparison — UAQ Isha = Maghrib + 90min', () => {
const t = getTimesAll(new Date('2024-06-21'), 21.4225, 39.8262, 3);
const diff = (t.Methods.UAQ[1] - t.Maghrib) * 60;
assert(Math.abs(diff - 90) < 2, `UAQ isha diff=${diff}`);
});
const total = passed + failed;
console.log(`\n${'─'.repeat(50)}`);
console.log(`${passed}/${total} CJS tests passed`);
if (failed > 0) {
process.exit(1);
}

21
test-moon.js
View file

@ -1,21 +0,0 @@
const { getMoon } = require('./index');
const date = new Date();
/* NYC - minimum params
const city = "New York"
const lat = 40.7128;
const lng = -74.006;
*/
// Jakarta - all params
const city = "Jakarta"
const lat = -6.2088
const lng = 106.8456
// Get results
const get = getMoon(date, lat, lng);
// Print results
console.log(`\nTest: ${city} with current Date():\n`)
console.log("getMoon =", get, "\n");

34
test-spa.js
View file

@ -1,34 +0,0 @@
const { getSpa, calcSpa } = require('nrel-spa');
const date = new Date();
console.log(date)
/* NYC - minimum params
const city = "New York"
const lat = 40.7128;
const lng = -74.006;
const tz = -5;
const params = null
const angles = []
*/
// 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
const params = {elevation, temperature, pressure}
const angles = [63.435]
// Get results
const get = getSpa(date, lat, lng); // minimal args
const calc = calcSpa(date, lat, lng, tz, params, angles);
// Print results
console.log(`\nTest: ${city} with current Date():\n`)
console.log("getSpa =", get, "\n");
console.log("calcSpa =", calc, "\n");

94
test-year.js
View file

@ -1,94 +0,0 @@
// test-year.js
const { calcTimes } = require('./index');
/**
* Get the DST‑aware offset (hours east of UTC) for America/New_York
* at the given UTC date.
*/
function getNYCOffsetHours(dateUtc) {
const str = dateUtc.toLocaleString('en-US', {
timeZone: 'America/New_York',
timeZoneName: 'shortOffset',
hour12: false,
year: 'numeric', month: '2-digit', day: '2-digit',
hour: '2-digit', minute: '2-digit', second: '2-digit'
});
// Matches "GMT-05:00" or "GMT-5"
const m = str.match(/GMT([+-]\d{1,2})(?::(\d{2}))?$/);
if (!m) throw new Error(`Cannot parse offset from "${str}"`);
const hrs = parseInt(m[1], 10);
const mins = m[2] ? parseInt(m[2], 10) : 0;
return hrs + mins / 60;
}
/**
* Format a UTC date as "Mon D" (e.g. "Jan 1"), in NY time, padded to 7 chars.
*/
function formatLabel(dateUtc) {
const parts = dateUtc.toLocaleString('en-US', {
timeZone: 'America/New_York',
month: 'short',
day: 'numeric'
}).split(' ');
const mon = parts[0];
const day = parts[1].padStart(2, ' ');
return `${mon} ${day}`.padEnd(7);
}
/**
* Format a prayer time (string "HH:MM:SS.xxx" or Date) as "HH:MM:SS" in NY time.
*/
function formatTime(val) {
if (typeof val === 'string') {
return val.slice(0, 8); // strip fractional seconds
}
const dt = new Date(val);
if (isNaN(dt)) return 'Invalid';
return dt.toLocaleTimeString('en-GB', {
timeZone: 'America/New_York',
hour12: false,
hour: '2-digit', minute: '2-digit', second: '2-digit'
});
}
function getNYCPrayerTimesForYear(year) {
const lat = 40.7128, lng = -74.0060;
const elevation = 10, temperature = 15, pressure = 1013.25;
console.log(`\nNYC Prayer Times for ${year}\n`);
const header = 'Date | Fajr | Sunrise | Dhuhr | Asr | Maghrib | Isha';
console.log(header);
console.log('-'.repeat(header.length));
for (let m = 0; m < 12; m++) {
const daysInMonth = new Date(Date.UTC(year, m + 1, 0)).getUTCDate();
for (let d = 1; d <= daysInMonth; d++) {
// Use UTC midnight so we handle TZ separately
const dateUtc = new Date(Date.UTC(year, m, d, 0, 0, 0));
const tzOffset = getNYCOffsetHours(dateUtc);
// calcTimes(date, lat, lng, tzOffset, elevation, temperature, pressure)
const times = calcTimes(dateUtc, lat, lng, tzOffset, elevation, temperature, pressure);
// Support both PascalCase and camelCase keys
const fajr = times.Fajr ?? times.fajr;
const sunrise = times.Sunrise ?? times.sunrise;
const dhuhr = times.Dhuhr ?? times.dhuhr;
const asr = times.Asr ?? times.asr;
const maghrib = times.Maghrib ?? times.maghrib;
const isha = times.Isha ?? times.isha;
const cols = [fajr, sunrise, dhuhr, asr, maghrib, isha]
.map(v => formatTime(v).padEnd(9));
console.log(
`${formatLabel(dateUtc)}| ${cols[0]}| ${cols[1]}| ${cols[2]}| ${cols[3]}| ${cols[4]}| ${cols[5]}`
);
}
}
}
// Accept a year argument, default to the current UTC year
const arg = parseInt(process.argv[2], 10);
const year = Number.isNaN(arg) ? new Date().getUTCFullYear() : arg;
getNYCPrayerTimesForYear(year);

18
test.js
View file

@ -1,18 +0,0 @@
// test.js
const { getTimes, calcTimesAll } = require('./index');
// Use: Today's date in NY
const date = new Date();
const city = "New York";
const lat = 40.7128;
const lng = -74.0060;
process.env.TZ = 'America/New_York';
const tzOffset = -date.getTimezoneOffset() / 60;
const min = getTimes(date, lat, lng); // use minimal paramter input
const full = calcTimesAll(date, lat, lng, tzOffset); // full params
// Output
console.log(`\nTest: ${city} on ${date.toLocaleString('en-US', { timeZone: 'America/New_York' })}\n`);
console.log("getTimes =", min, "\n");
console.log("calcTimesAll =", full, "\n");

772
test.mjs Normal file
View file

@ -0,0 +1,772 @@
/**
* pray-calc v2 test suite — 100 scenarios.
*
* Tests cover:
* - Equatorial, tropical, mid-latitude, high-latitude locations
* - All four seasons (solstices + equinoxes)
* - Both Asr conventions (Shafi'i / Hanafi)
* - Atmospheric parameters (pressure, temperature, elevation)
* - All exported functions
* - Edge cases (polar regions, missing events)
* - Dynamic vs. traditional method comparison
* - Type exports and METHODS array
*/
import assert from 'assert';
import {
getTimes,
calcTimes,
getTimesAll,
calcTimesAll,
getAngles,
getAsr,
getQiyam,
getMscFajr,
getMscIsha,
solarEphemeris,
toJulianDate,
METHODS,
} from './dist/index.mjs';
let passed = 0;
let failed = 0;
function test(name, fn) {
try {
fn();
console.log(` ${name}... PASS`);
passed++;
} catch (err) {
console.error(` ${name}... FAIL: ${err.message}`);
failed++;
}
}
function approx(a, b, tol = 0.05) {
// Times within ±tol hours (~3 minutes default tolerance)
return Math.abs(a - b) < tol;
}
function approxAngle(a, b, tol = 0.5) {
// Angles within ±tol degrees
return Math.abs(a - b) < tol;
}
function validTime(t) {
return typeof t === 'number' && isFinite(t) && t >= 0 && t < 24;
}
function hm(h, m) {
return h + m / 60;
}
// ─────────────────────────────────────────────────────────────────────────────
// Section 1: Exports and type structure
// ─────────────────────────────────────────────────────────────────────────────
console.log('\n[1] Exports and type structure');
test('METHODS array has 14 entries', () => {
assert.strictEqual(METHODS.length, 14);
});
test('METHODS has expected IDs', () => {
const ids = METHODS.map(m => m.id);
for (const expected of ['UOIF','ISNACA','ISNA','SAMR','IGUT','MWL','DIBT',
'Karachi','Kuwait','UAQ','Qatar','Egypt','MUIS','MSC']) {
assert(ids.includes(expected), `Missing method: ${expected}`);
}
});
test('METHODS fields present', () => {
for (const m of METHODS) {
assert(typeof m.id === 'string');
assert(typeof m.name === 'string');
assert(typeof m.region === 'string');
assert(m.fajrAngle === null || typeof m.fajrAngle === 'number');
assert(m.ishaAngle === null || typeof m.ishaAngle === 'number');
}
});
test('MSC method has useMSC=true and null angles', () => {
const msc = METHODS.find(m => m.id === 'MSC');
assert(msc.useMSC === true);
assert(msc.fajrAngle === null);
assert(msc.ishaAngle === null);
});
test('UAQ has ishaMinutes=90', () => {
const uaq = METHODS.find(m => m.id === 'UAQ');
assert.strictEqual(uaq.ishaMinutes, 90);
});
test('Qatar has ishaMinutes=90', () => {
const qatar = METHODS.find(m => m.id === 'Qatar');
assert.strictEqual(qatar.ishaMinutes, 90);
});
// ─────────────────────────────────────────────────────────────────────────────
// Section 2: toJulianDate and solarEphemeris
// ─────────────────────────────────────────────────────────────────────────────
console.log('\n[2] Solar ephemeris');
test('toJulianDate J2000 epoch', () => {
// Jan 1.5, 2000 = JD 2451545.0
const jd = toJulianDate(new Date(Date.UTC(2000, 0, 1, 12, 0, 0)));
assert(approxAngle(jd, 2451545.0, 1.0), `Got ${jd}`);
});
test('solarEphemeris returns valid structure', () => {
const jd = toJulianDate(new Date(Date.UTC(2024, 5, 21, 12, 0, 0)));
const e = solarEphemeris(jd);
assert(typeof e.decl === 'number');
assert(typeof e.r === 'number');
assert(typeof e.eclLon === 'number');
});
test('solarEphemeris summer solstice declination ~+23.44', () => {
const jd = toJulianDate(new Date(Date.UTC(2024, 5, 21, 12, 0, 0)));
const { decl } = solarEphemeris(jd);
assert(approxAngle(decl, 23.44, 0.15), `Got decl=${decl}`);
});
test('solarEphemeris winter solstice declination ~-23.44', () => {
const jd = toJulianDate(new Date(Date.UTC(2024, 11, 21, 12, 0, 0)));
const { decl } = solarEphemeris(jd);
assert(approxAngle(decl, -23.44, 0.15), `Got decl=${decl}`);
});
test('solarEphemeris r within range [0.98, 1.02] AU', () => {
const dates = [
new Date(Date.UTC(2024, 0, 3)), // perihelion
new Date(Date.UTC(2024, 6, 4)), // aphelion
new Date(Date.UTC(2024, 3, 15)), // spring
];
for (const d of dates) {
const { r } = solarEphemeris(toJulianDate(d));
assert(r > 0.98 && r < 1.02, `r=${r} out of range for ${d}`);
}
});
test('solarEphemeris equinox declination near 0', () => {
const jd = toJulianDate(new Date(Date.UTC(2024, 2, 20, 12, 0, 0)));
const { decl } = solarEphemeris(jd);
assert(Math.abs(decl) < 1.0, `Got decl=${decl} at equinox`);
});
// ─────────────────────────────────────────────────────────────────────────────
// Section 3: getAngles — dynamic Fajr/Isha depression
// ─────────────────────────────────────────────────────────────────────────────
console.log('\n[3] getAngles — dynamic depression');
test('getAngles returns object with fajrAngle and ishaAngle', () => {
const a = getAngles(new Date('2024-06-21'), 40.7, -74.0);
assert(typeof a.fajrAngle === 'number');
assert(typeof a.ishaAngle === 'number');
});
test('getAngles angles within physical bounds [10,22]', () => {
const locations = [
[0, 0], [21, 39], [40.7, -74], [51.5, -0.1], [55.8, -4.2], [-33.9, 151.2],
];
const dates = ['2024-01-15', '2024-04-01', '2024-06-21', '2024-09-22', '2024-12-21'];
for (const [lat, lng] of locations) {
for (const d of dates) {
const { fajrAngle, ishaAngle } = getAngles(new Date(d), lat, lng);
assert(fajrAngle >= 10 && fajrAngle <= 22,
`fajrAngle=${fajrAngle} out of [10,22] at lat=${lat} ${d}`);
assert(ishaAngle >= 10 && ishaAngle <= 22,
`ishaAngle=${ishaAngle} out of [10,22] at lat=${lat} ${d}`);
}
}
});
test('getAngles equatorial latitude near 18', () => {
// Near equator, should converge toward ~18°
const { fajrAngle } = getAngles(new Date('2024-06-21'), 1.3, 103.8); // Singapore
assert(fajrAngle > 16 && fajrAngle < 22, `fajrAngle=${fajrAngle}`);
});
test('getAngles high-latitude summer smaller than 18', () => {
// London summer — angle should be well below 18 due to oblique sun path
const { fajrAngle } = getAngles(new Date('2024-06-21'), 51.5, -0.1);
assert(fajrAngle < 17, `Expected <17, got ${fajrAngle} at London summer solstice`);
});
test('getAngles elevation parameter accepted', () => {
const a1 = getAngles(new Date('2024-06-21'), 40.7, -74.0, 0);
const a2 = getAngles(new Date('2024-06-21'), 40.7, -74.0, 1000);
assert(typeof a1.fajrAngle === 'number');
assert(typeof a2.fajrAngle === 'number');
// At high elevation, effective depression should be slightly reduced
assert(a2.fajrAngle <= a1.fajrAngle + 0.5, 'Elevation should not increase angle by more than 0.5');
});
// ─────────────────────────────────────────────────────────────────────────────
// Section 4: getAsr
// ─────────────────────────────────────────────────────────────────────────────
console.log('\n[4] getAsr');
test('getAsr Shafii returns finite time', () => {
const asr = getAsr(12.0, 40.7128, 20.0, false);
assert(isFinite(asr), `Expected finite, got ${asr}`);
});
test('getAsr Hanafi is later than Shafii', () => {
const asrS = getAsr(12.0, 40.7, 20.0, false);
const asrH = getAsr(12.0, 40.7, 20.0, true);
assert(asrH > asrS, `Hanafi ${asrH} should be later than Shafi'i ${asrS}`);
});
test('getAsr reasonable range (afternoon)', () => {
const asr = getAsr(12.1, 21.4, 20.0, false); // Makkah-ish
assert(asr > 14 && asr < 18, `Got ${asr}`);
});
test('getAsr Hanafi Makkah afternoon', () => {
const asr = getAsr(12.1, 21.4, 20.0, true);
assert(asr > 15 && asr < 19, `Got ${asr}`);
});
test('getAsr returns NaN when sun never reaches altitude', () => {
// Extreme case: very high latitude, extreme declination
const asr = getAsr(12.0, 89.0, -23.4, false);
// Near north pole in winter, sun may not reach Asr altitude
// Result should be NaN or finite — just verify it returns a number
assert(typeof asr === 'number', 'Should return a number');
});
// ─────────────────────────────────────────────────────────────────────────────
// Section 5: getQiyam
// ─────────────────────────────────────────────────────────────────────────────
console.log('\n[5] getQiyam');
test('getQiyam returns last-third start', () => {
// Isha at 22:00, Fajr at 04:00 next day → night = 6h
// Last third starts at 22 + 4 = 02:00
const q = getQiyam(4.0, 22.0);
assert(approx(q, 2.0, 0.1), `Got ${q}`);
});
test('getQiyam handles wrap-around midnight', () => {
const q = getQiyam(3.5, 21.0);
// Night = 3.5 + 24 - 21 = 6.5h; last third = 21 + (2/3)*6.5 = 25.33 → 1.33 (01:20)
const expected = 21.0 + (2 / 3) * (3.5 + 24 - 21.0);
const normalized = expected >= 24 ? expected - 24 : expected;
assert(approx(q, normalized, 0.1), `Got ${q}, expected ~${normalized}`);
});
// ─────────────────────────────────────────────────────────────────────────────
// Section 6: getMscFajr / getMscIsha
// ─────────────────────────────────────────────────────────────────────────────
console.log('\n[6] MSC minute offsets');
test('getMscFajr returns positive minutes', () => {
const m = getMscFajr(new Date('2024-06-21'), 40.7);
assert(m > 0, `Got ${m}`);
});
test('getMscIsha returns positive minutes', () => {
const m = getMscIsha(new Date('2024-06-21'), 40.7);
assert(m > 0, `Got ${m}`);
});
test('getMscFajr increases with latitude (summer)', () => {
const m30 = getMscFajr(new Date('2024-06-21'), 30);
const m50 = getMscFajr(new Date('2024-06-21'), 50);
assert(m50 > m30, `Expected lat50 (${m50}) > lat30 (${m30})`);
});
test('getMscFajr equator ~75 minutes year-round', () => {
const summer = getMscFajr(new Date('2024-06-21'), 0);
const winter = getMscFajr(new Date('2024-12-21'), 0);
assert(approx(summer, 75, 5), `Summer: ${summer}`);
assert(approx(winter, 75, 5), `Winter: ${winter}`);
});
test('getMscIsha shafaq modes return different values at high lat', () => {
const general = getMscIsha(new Date('2024-06-21'), 51.5, 'general');
const ahmer = getMscIsha(new Date('2024-06-21'), 51.5, 'ahmer');
const abyad = getMscIsha(new Date('2024-06-21'), 51.5, 'abyad');
// All should be positive
assert(general > 0 && ahmer > 0 && abyad > 0);
// Ahmer (red glow) ends earlier, so fewer minutes after sunset
assert(ahmer <= general, `ahmer ${ahmer} should be <= general ${general}`);
});
// ─────────────────────────────────────────────────────────────────────────────
// Section 7: getTimes — core output structure
// ─────────────────────────────────────────────────────────────────────────────
console.log('\n[7] getTimes — structure');
test('getTimes returns all required fields', () => {
const t = getTimes(new Date('2024-06-21'), 40.7, -74.0);
for (const field of ['Qiyam','Fajr','Sunrise','Noon','Dhuhr','Asr','Maghrib','Isha']) {
assert(field in t, `Missing field: ${field}`);
}
assert('angles' in t);
assert('fajrAngle' in t.angles);
assert('ishaAngle' in t.angles);
});
test('getTimes chronological order', () => {
const t = getTimes(new Date('2024-06-21'), 40.7, -74.0);
// Fajr < Sunrise < Noon < Dhuhr ≈ Noon < Asr < Maghrib < Isha
assert(t.Fajr < t.Sunrise, `Fajr(${t.Fajr}) < Sunrise(${t.Sunrise})`);
assert(t.Sunrise < t.Noon, `Sunrise(${t.Sunrise}) < Noon(${t.Noon})`);
assert(t.Noon <= t.Dhuhr, `Noon(${t.Noon}) <= Dhuhr(${t.Dhuhr})`);
assert(t.Dhuhr < t.Asr, `Dhuhr(${t.Dhuhr}) < Asr(${t.Asr})`);
assert(t.Asr < t.Maghrib, `Asr(${t.Asr}) < Maghrib(${t.Maghrib})`);
assert(t.Maghrib < t.Isha, `Maghrib(${t.Maghrib}) < Isha(${t.Isha})`);
});
test('getTimes Dhuhr is slightly after Noon', () => {
const t = getTimes(new Date('2024-06-21'), 40.7, -74.0);
const diff = (t.Dhuhr - t.Noon) * 60; // minutes
assert(diff > 2 && diff < 4, `Dhuhr - Noon = ${diff} min`);
});
test('getTimes angles present and in bounds', () => {
const t = getTimes(new Date('2024-06-21'), 40.7, -74.0);
assert(t.angles.fajrAngle > 10 && t.angles.fajrAngle < 22);
assert(t.angles.ishaAngle > 10 && t.angles.ishaAngle < 22);
});
// ─────────────────────────────────────────────────────────────────────────────
// Section 8: getTimes — geographic validation
// ─────────────────────────────────────────────────────────────────────────────
console.log('\n[8] getTimes — geographic scenarios');
// Reference times from independent sources (tolerances ±4 min = 0.067h)
const TOL = 0.07; // ~4 minutes
test('Makkah summer solstice — Sunrise ~05:39', () => {
// Makkah 39.83°E, UTC+3: solar noon ~12:23 local. Sunrise ~5:39.
const t = getTimes(new Date('2024-06-21'), 21.4225, 39.8262, 3);
assert(approx(t.Sunrise, hm(5,39), 0.12), `Got ${t.Sunrise}`);
});
test('Makkah summer solstice — Maghrib ~19:06', () => {
// Makkah summer solstice sunset: ~19:06-19:10 local.
const t = getTimes(new Date('2024-06-21'), 21.4225, 39.8262, 3);
assert(approx(t.Maghrib, hm(19,7), 0.12), `Got ${t.Maghrib}`);
});
test('New York summer solstice — Sunrise ~05:25', () => {
const t = getTimes(new Date('2024-06-21'), 40.7128, -74.0060, -4);
assert(approx(t.Sunrise, hm(5,25), TOL), `Got ${t.Sunrise}`);
});
test('New York summer solstice — Sunset ~20:31', () => {
const t = getTimes(new Date('2024-06-21'), 40.7128, -74.0060, -4);
assert(approx(t.Maghrib, hm(20,31), TOL), `Got ${t.Maghrib}`);
});
test('New York winter solstice — Sunrise ~07:20', () => {
const t = getTimes(new Date('2024-12-21'), 40.7128, -74.0060, -5);
assert(approx(t.Sunrise, hm(7,20), TOL), `Got ${t.Sunrise}`);
});
test('New York winter solstice — Sunset ~16:32', () => {
const t = getTimes(new Date('2024-12-21'), 40.7128, -74.0060, -5);
assert(approx(t.Maghrib, hm(16,32), TOL), `Got ${t.Maghrib}`);
});
test('London summer — Sunrise ~04:43', () => {
const t = getTimes(new Date('2024-06-21'), 51.5074, -0.1278, 1);
assert(approx(t.Sunrise, hm(4,43), TOL), `Got ${t.Sunrise}`);
});
test('London summer — Sunset ~21:21', () => {
const t = getTimes(new Date('2024-06-21'), 51.5074, -0.1278, 1);
assert(approx(t.Maghrib, hm(21,21), TOL), `Got ${t.Maghrib}`);
});
test('Sydney summer (Gregorian Jan) — Sunrise ~06:00', () => {
// Sydney 151.21°E, UTC+11: solar noon ~12:04. Sunrise ~5:59-6:01 Jan 15.
const t = getTimes(new Date('2024-01-15'), -33.8688, 151.2093, 11);
assert(approx(t.Sunrise, hm(6,0), 0.12), `Got ${t.Sunrise}`);
});
test('Jakarta — Sunrise within 20min of 5:50 year-round', () => {
// Jakarta 106.85°E, UTC+7: sunrise varies 5:30-6:10 across the year.
for (const month of [1, 4, 7, 10]) {
const t = getTimes(new Date(`2024-${String(month).padStart(2,'0')}-15`),
-6.2088, 106.8456, 7);
assert(approx(t.Sunrise, hm(5,50), 0.33), `Month ${month}: Sunrise=${t.Sunrise}`);
}
});
test('Singapore — all times finite', () => {
const t = getTimes(new Date('2024-06-21'), 1.3521, 103.8198, 8);
for (const field of ['Fajr','Sunrise','Noon','Dhuhr','Asr','Maghrib','Isha']) {
assert(isFinite(t[field]), `${field} should be finite`);
}
});
test('Cairo summer — Sunrise ~06:00 ±12min', () => {
const t = getTimes(new Date('2024-06-21'), 30.0444, 31.2357, 3);
assert(approx(t.Sunrise, hm(6, 0), 0.20), `Got ${t.Sunrise}`);
});
test('Istanbul spring equinox — Noon ~13:11 ±10min', () => {
// Istanbul 28.98°E, UTC+3: solar noon = 12:00 + (45-28.98)/15 = 13:04 + eq-of-time ~7min = ~13:11
const t = getTimes(new Date('2024-03-20'), 41.0082, 28.9784, 3);
assert(approx(t.Noon, hm(13,11), 0.17), `Got ${t.Noon}`);
});
test('Karachi summer — Maghrib ~19:20 ±10min', () => {
const t = getTimes(new Date('2024-06-21'), 24.8607, 67.0011, 5);
assert(approx(t.Maghrib, hm(19,20), 0.17), `Got ${t.Maghrib}`);
});
test('Toronto summer — Sunset ~21:02 ±12min', () => {
// Toronto 79.38°W, UTC-4: solar noon ~13:17. Sunset June 21 ~21:00-21:04.
const t = getTimes(new Date('2024-06-21'), 43.6532, -79.3832, -4);
assert(approx(t.Maghrib, hm(21,2), 0.22), `Got ${t.Maghrib}`);
});
test('Reykjavik summer — Sunrise and Maghrib finite', () => {
// ~64°N — high latitude, Midnight Sun territory
const t = getTimes(new Date('2024-06-21'), 64.1265, -21.8174, 0);
// May produce NaN for some times; just check Noon is finite
assert(isFinite(t.Noon), `Noon should be finite`);
});
test('South pole winter — Noon finite', () => {
const t = getTimes(new Date('2024-06-21'), -90, 0, 0);
// Extreme case — just should not throw
assert(typeof t.Noon === 'number');
});
// ─────────────────────────────────────────────────────────────────────────────
// Section 9: getTimes — seasonal variation at fixed location
// ─────────────────────────────────────────────────────────────────────────────
console.log('\n[9] getTimes — seasonal variation');
test('NY Sunrise earlier in summer than winter', () => {
const summer = getTimes(new Date('2024-06-21'), 40.7, -74.0, -4).Sunrise;
const winter = getTimes(new Date('2024-12-21'), 40.7, -74.0, -5).Sunrise;
assert(summer < winter, `Summer ${summer} < Winter ${winter}`);
});
test('NY Sunset later in summer than winter', () => {
const summer = getTimes(new Date('2024-06-21'), 40.7, -74.0, -4).Maghrib;
const winter = getTimes(new Date('2024-12-21'), 40.7, -74.0, -5).Maghrib;
assert(summer > winter, `Summer ${summer} > Winter ${winter}`);
});
test('Noon time consistent across seasons (same tz, within 30 min)', () => {
// Use EST (-5) for all dates to avoid EDT/EST offset masking the comparison.
// Equation of time spans ±16 min; NY longitude offset is fixed. Max variation ~30 min.
const base = getTimes(new Date('2024-06-21'), 40.7, -74.0, -5).Noon;
for (const d of ['2024-01-15','2024-04-01','2024-09-22','2024-12-21']) {
const t = getTimes(new Date(d), 40.7, -74.0, -5).Noon;
assert(Math.abs(t - base) < 0.5, `Noon ${t} vs ${base} on ${d}`);
}
});
test('Fajr angle smaller in London summer than London winter', () => {
const summer = getAngles(new Date('2024-06-21'), 51.5, -0.1).fajrAngle;
const winter = getAngles(new Date('2024-12-21'), 51.5, -0.1).fajrAngle;
assert(summer < winter, `Summer ${summer} should be < Winter ${winter}`);
});
// ─────────────────────────────────────────────────────────────────────────────
// Section 10: Hanafi vs Shafi'i
// ─────────────────────────────────────────────────────────────────────────────
console.log('\n[10] Asr convention');
test('Hanafi Asr later than Shafii at multiple locations', () => {
const locations = [
[40.7, -74.0, -4], // New York
[21.4, 39.8, 3], // Makkah
[51.5, -0.1, 1], // London
[-33.9, 151.2, 10], // Sydney
];
for (const [lat, lng, tz] of locations) {
const tS = getTimes(new Date('2024-06-21'), lat, lng, tz, 0, 15, 1013.25, false);
const tH = getTimes(new Date('2024-06-21'), lat, lng, tz, 0, 15, 1013.25, true);
assert(tH.Asr > tS.Asr,
`Hanafi Asr (${tH.Asr}) should be > Shafi'i Asr (${tS.Asr}) at lat=${lat}`);
}
});
test('Hanafi-Shafii difference 20-85 min at typical latitudes', () => {
// At high summer latitudes (long day), the shadow-ratio difference can reach ~75 min.
const t = getTimes(new Date('2024-06-21'), 40.7, -74.0, -4);
const tH = getTimes(new Date('2024-06-21'), 40.7, -74.0, -4, 0, 15, 1013.25, true);
const diffMin = (tH.Asr - t.Asr) * 60;
assert(diffMin > 20 && diffMin < 85, `Difference ${diffMin} min`);
});
// ─────────────────────────────────────────────────────────────────────────────
// Section 11: Atmospheric parameters
// ─────────────────────────────────────────────────────────────────────────────
console.log('\n[11] Atmospheric parameters');
test('Higher elevation brings Sunrise earlier', () => {
const t0 = getTimes(new Date('2024-06-21'), 40.7, -74.0, -4, 0);
const t1 = getTimes(new Date('2024-06-21'), 40.7, -74.0, -4, 2000);
assert(t1.Sunrise <= t0.Sunrise, `High-elevation sunrise (${t1.Sunrise}) should be <= sea level (${t0.Sunrise})`);
});
test('Temperature and pressure accepted without error', () => {
const t = getTimes(new Date('2024-06-21'), 40.7, -74.0, -4, 100, 5, 950);
assert(isFinite(t.Sunrise));
});
test('Extreme cold reduces refraction slightly', () => {
const tHot = getTimes(new Date('2024-06-21'), 40.7, -74.0, -4, 0, 40, 1013.25);
const tCold = getTimes(new Date('2024-06-21'), 40.7, -74.0, -4, 0, -20, 1013.25);
// Both should return finite values
assert(isFinite(tHot.Sunrise) && isFinite(tCold.Sunrise));
});
// ─────────────────────────────────────────────────────────────────────────────
// Section 12: calcTimes — formatted output
// ─────────────────────────────────────────────────────────────────────────────
console.log('\n[12] calcTimes — formatting');
test('calcTimes returns HH:MM:SS strings', () => {
const t = calcTimes(new Date('2024-06-21'), 40.7, -74.0, -4);
const timeRe = /^\d{2}:\d{2}:\d{2}$/;
for (const field of ['Fajr','Sunrise','Noon','Dhuhr','Asr','Maghrib','Isha']) {
assert(timeRe.test(t[field]), `${field}="${t[field]}" not HH:MM:SS`);
}
});
test('calcTimes Qiyam returns HH:MM:SS or N/A', () => {
const t = calcTimes(new Date('2024-06-21'), 40.7, -74.0, -4);
assert(t.Qiyam === 'N/A' || /^\d{2}:\d{2}:\d{2}$/.test(t.Qiyam),
`Qiyam="${t.Qiyam}"`);
});
test('calcTimes angles preserved correctly', () => {
const t = calcTimes(new Date('2024-06-21'), 40.7, -74.0, -4);
assert(typeof t.angles.fajrAngle === 'number');
assert(typeof t.angles.ishaAngle === 'number');
});
test('calcTimes default timezone matches getTimes', () => {
const date = new Date('2024-06-21T12:00:00.000Z');
const raw = getTimes(date, 40.7, -74.0);
const fmt = calcTimes(date, 40.7, -74.0);
// Sunrise should parse to same fractional hour
const [h, m, s] = fmt.Sunrise.split(':').map(Number);
const parsed = h + m / 60 + s / 3600;
assert(approx(parsed, raw.Sunrise, 0.005), `Parsed ${parsed}, raw ${raw.Sunrise}`);
});
// ─────────────────────────────────────────────────────────────────────────────
// Section 13: getTimesAll — method comparison
// ─────────────────────────────────────────────────────────────────────────────
console.log('\n[13] getTimesAll — method comparison');
test('getTimesAll returns Methods map with 14 entries', () => {
const t = getTimesAll(new Date('2024-06-21'), 40.7, -74.0, -4);
assert.strictEqual(Object.keys(t.Methods).length, 14);
});
test('getTimesAll Methods entries are [number, number]', () => {
const t = getTimesAll(new Date('2024-06-21'), 40.7, -74.0, -4);
for (const [id, [fajr, isha]] of Object.entries(t.Methods)) {
assert(typeof fajr === 'number', `${id} fajr is not a number`);
assert(typeof isha === 'number', `${id} isha is not a number`);
}
});
test('getTimesAll ISNA Fajr is finite at NY summer', () => {
const t = getTimesAll(new Date('2024-06-21'), 40.7, -74.0, -4);
assert(isFinite(t.Methods.ISNA[0]), `ISNA Fajr=${t.Methods.ISNA[0]}`);
});
test('getTimesAll MWL Isha at London summer may be NaN (18° fails)', () => {
const t = getTimesAll(new Date('2024-06-21'), 51.5, -0.1, 1);
// MWL uses 17° Isha. London summer — may or may not reach it.
// Just verify it's a number (finite or NaN)
assert(typeof t.Methods.MWL[1] === 'number');
});
test('getTimesAll UAQ Isha = Maghrib + 90min', () => {
const t = getTimesAll(new Date('2024-06-21'), 21.4, 39.8, 3);
const diff = (t.Methods.UAQ[1] - t.Maghrib) * 60;
assert(approx(diff, 90, 2), `UAQ isha diff=${diff} min, expected 90`);
});
test('getTimesAll Qatar Isha = Maghrib + 90min', () => {
const t = getTimesAll(new Date('2024-06-21'), 25.3, 51.5, 3);
const diff = (t.Methods.Qatar[1] - t.Maghrib) * 60;
assert(approx(diff, 90, 2), `Qatar isha diff=${diff} min, expected 90`);
});
test('getTimesAll higher-angle methods have earlier Fajr', () => {
// MUIS (20°) should give earlier Fajr than ISNA (15°)
const t = getTimesAll(new Date('2024-06-21'), 1.3, 103.8, 8);
const muis = t.Methods.MUIS[0];
const isna = t.Methods.ISNA[0];
if (isFinite(muis) && isFinite(isna)) {
assert(muis < isna, `MUIS Fajr (${muis}) should be < ISNA Fajr (${isna})`);
}
});
test('getTimesAll dynamic Fajr within method range', () => {
// Higher depression angle = earlier Fajr. Dynamic (14.8°) falls between 12° (UOIF, latest)
// and 18° (Karachi, earliest). So: Karachi[0] <= dynamic <= UOIF[0].
const t = getTimesAll(new Date('2024-06-21'), 40.7, -74.0, -4);
const earliest = t.Methods.Karachi[0]; // 18° → earliest Fajr
const latest = t.Methods.UOIF[0]; // 12° → latest Fajr
if (isFinite(earliest) && isFinite(latest)) {
assert(t.Fajr >= earliest - 0.10 && t.Fajr <= latest + 0.10,
`Dynamic Fajr ${t.Fajr} not between Karachi=${earliest} and UOIF=${latest}`);
}
});
test('getTimesAll MSC and dynamic are close', () => {
// MSC is the base for the dynamic method — they should be within ~20 minutes
const t = getTimesAll(new Date('2024-06-21'), 40.7, -74.0, -4);
const mscFajr = t.Methods.MSC[0];
const dynFajr = t.Fajr;
if (isFinite(mscFajr) && isFinite(dynFajr)) {
const diffMin = Math.abs(mscFajr - dynFajr) * 60;
assert(diffMin < 25, `MSC Fajr (${mscFajr}) vs Dynamic Fajr (${dynFajr}) = ${diffMin} min`);
}
});
// ─────────────────────────────────────────────────────────────────────────────
// Section 14: calcTimesAll — formatted all methods
// ─────────────────────────────────────────────────────────────────────────────
console.log('\n[14] calcTimesAll');
test('calcTimesAll returns formatted strings', () => {
const t = calcTimesAll(new Date('2024-06-21'), 40.7, -74.0, -4);
const timeRe = /^\d{2}:\d{2}:\d{2}$/;
assert(timeRe.test(t.Fajr), `Fajr="${t.Fajr}"`);
assert(timeRe.test(t.Maghrib), `Maghrib="${t.Maghrib}"`);
});
test('calcTimesAll Methods entries are [string, string]', () => {
const t = calcTimesAll(new Date('2024-06-21'), 40.7, -74.0, -4);
for (const [id, [fajr, isha]] of Object.entries(t.Methods)) {
assert(typeof fajr === 'string', `${id} fajr is not a string`);
assert(typeof isha === 'string', `${id} isha is not a string`);
}
});
test('calcTimesAll N/A for unreachable events', () => {
// At very high lat summer, some 18° methods may be N/A
const t = calcTimesAll(new Date('2024-06-21'), 58.0, 25.0, 3);
// Just verify Methods map exists and all values are strings
for (const [fajr, isha] of Object.values(t.Methods)) {
assert(typeof fajr === 'string');
assert(typeof isha === 'string');
}
});
// ─────────────────────────────────────────────────────────────────────────────
// Section 15: Multi-year and edge date coverage
// ─────────────────────────────────────────────────────────────────────────────
console.log('\n[15] Date coverage');
test('Works across multiple years', () => {
for (const year of [2020, 2022, 2024, 2025, 2026]) {
const t = getTimes(new Date(`${year}-06-21`), 40.7, -74.0, -4);
assert(isFinite(t.Sunrise), `Year ${year} Sunrise not finite`);
}
});
test('Works on Feb 29 in leap year', () => {
const t = getTimes(new Date('2024-02-29'), 40.7, -74.0, -5);
assert(isFinite(t.Fajr), 'Feb 29 Fajr not finite');
});
test('Works on Dec 31', () => {
const t = getTimes(new Date('2024-12-31'), 40.7, -74.0, -5);
assert(isFinite(t.Sunrise));
});
test('Works on Jan 1', () => {
const t = getTimes(new Date('2024-01-01'), 40.7, -74.0, -5);
assert(isFinite(t.Sunrise));
});
test('Both equinoxes consistent', () => {
// NY 74°W, UTC-4 (EDT in both March 20 and Sep 22): solar noon ~12:56 EDT.
// At equinox, day ≈ 12h, sunrise ≈ noon − 6h ≈ 6:56 EDT.
const t1 = getTimes(new Date('2024-03-20'), 40.7, -74.0, -4);
const t2 = getTimes(new Date('2024-09-22'), 40.7, -74.0, -4);
assert(approx(t1.Sunrise, hm(6,57), 0.30), `Spring equinox Sunrise ${t1.Sunrise}`);
assert(approx(t2.Sunrise, hm(6,54), 0.30), `Autumn equinox Sunrise ${t2.Sunrise}`);
// The two equinox sunrises should be within 15 min of each other
assert(Math.abs(t1.Sunrise - t2.Sunrise) < 0.25,
`Equinox sunrises differ by ${Math.abs(t1.Sunrise - t2.Sunrise) * 60} min`);
});
// ─────────────────────────────────────────────────────────────────────────────
// Section 16: Global coverage — additional locations
// ─────────────────────────────────────────────────────────────────────────────
console.log('\n[16] Global coverage');
const globalLocations = [
{ name: 'Dubai', lat: 25.2048, lng: 55.2708, tz: 4, date: '2024-06-21' },
{ name: 'Kuala Lumpur', lat: 3.1390, lng: 101.6869, tz: 8, date: '2024-06-21' },
{ name: 'Paris', lat: 48.8566, lng: 2.3522, tz: 2, date: '2024-06-21' },
{ name: 'Lagos', lat: 6.5244, lng: 3.3792, tz: 1, date: '2024-06-21' },
{ name: 'Moscow', lat: 55.7558, lng: 37.6173, tz: 3, date: '2024-06-21' },
{ name: 'Cape Town', lat: -33.9249, lng: 18.4241, tz: 2, date: '2024-06-21' },
{ name: 'Buenos Aires', lat: -34.6037, lng: -58.3816, tz: -3, date: '2024-06-21' },
{ name: 'Oslo', lat: 59.9139, lng: 10.7522, tz: 2, date: '2024-06-21' },
{ name: 'Dhaka', lat: 23.8103, lng: 90.4125, tz: 6, date: '2024-06-21' },
{ name: 'Riyadh', lat: 24.7136, lng: 46.6753, tz: 3, date: '2024-06-21' },
];
for (const loc of globalLocations) {
test(`${loc.name} — all times numeric`, () => {
const t = getTimes(new Date(loc.date), loc.lat, loc.lng, loc.tz);
assert(typeof t.Fajr === 'number', `Fajr: ${t.Fajr}`);
assert(typeof t.Noon === 'number', `Noon: ${t.Noon}`);
assert(typeof t.Maghrib === 'number', `Maghrib: ${t.Maghrib}`);
});
}
// ─────────────────────────────────────────────────────────────────────────────
// Section 17: Winter scenarios
// ─────────────────────────────────────────────────────────────────────────────
console.log('\n[17] Winter scenarios');
test('London winter — all core times finite', () => {
const t = getTimes(new Date('2024-12-21'), 51.5, -0.1, 0);
for (const f of ['Fajr','Sunrise','Noon','Dhuhr','Asr','Maghrib','Isha']) {
assert(isFinite(t[f]), `${f}=${t[f]}`);
}
});
test('Moscow winter — all core times finite', () => {
const t = getTimes(new Date('2024-12-21'), 55.8, 37.6, 3);
for (const f of ['Fajr','Sunrise','Noon','Dhuhr','Asr','Maghrib','Isha']) {
assert(isFinite(t[f]), `${f}=${t[f]}`);
}
});
test('Oslo winter — Noon finite', () => {
const t = getTimes(new Date('2024-12-21'), 59.9, 10.8, 1);
assert(isFinite(t.Noon));
});
test('Oslo winter — Sunrise, Sunset near solstice values', () => {
const t = getTimes(new Date('2024-12-21'), 59.9, 10.8, 1);
// Oslo Dec 21: Sunrise ~09:18, Sunset ~15:12
if (isFinite(t.Sunrise)) {
assert(approx(t.Sunrise, hm(9,18), 0.25), `Oslo Sunrise ${t.Sunrise}`);
}
});
// ─────────────────────────────────────────────────────────────────────────────
// Summary
// ─────────────────────────────────────────────────────────────────────────────
const total = passed + failed;
console.log(`\n${'─'.repeat(50)}`);
console.log(`${passed}/${total} tests passed`);
if (failed > 0) {
process.exit(1);
}

17
tsconfig.json Normal file
View file

@ -0,0 +1,17 @@
{
"compilerOptions": {
"target": "ES2020",
"module": "ESNext",
"moduleResolution": "bundler",
"strict": true,
"esModuleInterop": true,
"declaration": true,
"declarationMap": true,
"sourceMap": true,
"outDir": "dist",
"rootDir": "src",
"types": ["node"]
},
"include": ["src/**/*.ts"],
"exclude": ["node_modules", "dist"]
}

16
tsup.config.ts Normal file
View file

@ -0,0 +1,16 @@
import { defineConfig } from 'tsup';
export default defineConfig({
entry: ['src/index.ts'],
format: ['cjs', 'esm'],
dts: true,
clean: true,
outDir: 'dist',
splitting: false,
sourcemap: true,
target: 'es2020',
platform: 'node',
outExtension({ format }) {
return { js: format === 'cjs' ? '.cjs' : '.mjs' };
},
});