c02f197ece
Complete rewrite from plain JavaScript to TypeScript with dual CJS/ESM output via tsup. Removes all legacy .js source files and the old CommonJS-only index. Key changes: - Full TypeScript source in src/ with strict mode and declaration maps - tsup build: dist/index.cjs + dist/index.mjs + dual .d.ts / .d.mts types - 14 traditional fixed-angle methods (UOIF through MUIS) + MSC seasonal method - PCD dynamic algorithm: MSC seasonal base + Earth-Sun distance correction + ecliptic geometry + atmospheric refraction + observer elevation - getTimesAll() batches all 14x2 zenith angles into a single SPA call - getMscFajr() / getMscIsha() expose MSC seasonal reference directly - getAngles() returns the PCD-computed fajrAngle and ishaAngle - High-latitude bounds: angles clipped to [10, 20] above 55N - 106 tests across ESM and CJS (test.mjs + test-cjs.cjs) - CI matrix: Node 20/22/24, typecheck, pack-check - Wiki: 12 reference pages + 6-page research section with global accuracy study, home-territory comparison, observational evidence, and field observation matrix - Moon functions removed (migrated to moon-sighting package) - pnpm-only, Node >=20, sideEffects: false
3.5 KiB
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 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:
pnpm add moon-sighting # or npm install moon-sighting
Update your imports:
// 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
- GitHub: https://github.com/acamarata/moon-sighting
- Wiki: https://github.com/acamarata/moon-sighting/wiki