3b666c6465
Adds five new kernel-free functions using Meeus Ch. 47/48 approximations,
replacing suncalc as the moon data source in the acamarata stack.
- getMoonPosition(date, lat, lon, elevation?) — topocentric az/alt/distance +
parallactic angle via WGS84 geodetic model and Bennett refraction
- getMoonIllumination(date) — illumination fraction, phase cycle position,
bright limb angle, isWaxing via Meeus Ch. 47/48
- getMoonPhase: adds phaseName ("Waxing Crescent") and phaseSymbol ("🌒")
fields to MoonPhaseResult
- getMoonVisibilityEstimate(date, lat, lon, elevation?) — kernel-free Odeh
V-parameter crescent visibility estimate; returns zone A-D, V, ARCL, ARCV, W
- getMoon(date, lat, lon, elevation?) — convenience wrapper combining all four
kernel-free functions into a single MoonSnapshot result
New types: MoonPosition, MoonIlluminationResult, MoonVisibilityEstimate, MoonSnapshot
98 tests (78 ESM + 20 CJS), typecheck clean, zero build warnings
3 KiB
moon-sighting
High-accuracy lunar crescent visibility and moon sighting calculations using JPL DE442S ephemerides.
What this library does
moon-sighting computes whether the new crescent moon will be visible at a specific location on a specific date. It produces the geometric quantities used by astronomers and Islamic lunar calendar authorities worldwide, including the Yallop q-test and Odeh visibility zones.
It also computes moon phase data, rise/set times, and twilight periods for any location.
Key design decisions
JPL DE442S, not VSOP87 or Meeus. The library uses the same planetary ephemeris as professional observatories. It reads an SPK binary kernel from NASA's NAIF, covering 1849–2150 with sub-arcsecond accuracy. This makes the position calculations verifiable against SPICE and JPL Horizons.
Two authoritative visibility criteria. The Yallop q-test (NAO TN 69, 1997) and Odeh V-parameter (Experimental Astronomy, 2006) are both implemented exactly as published, with all five required geometric variables (ARCL, ARCV, DAZ, W, Lag).
Kernel not bundled. The DE442S kernel is 31 MB. It is downloaded once to a local cache, verified by checksum, and reused. This keeps the npm package small.
Lite mode without kernel. Five functions work immediately with no kernel: getMoonPhase() (phase, illumination, next events), getMoonPosition() (topocentric az/alt/distance), getMoonIllumination() (fraction, phase cycle, bright limb angle), getMoonVisibilityEstimate() (Odeh crescent estimate), and getMoon() (all four in one call). These use Meeus approximations (accurate to ~0.3–1°) and are a direct replacement for the equivalent suncalc moon functions.
Pages
- Getting Started: Installation, kernel setup, first sighting report
- API Reference: Complete function and type documentation
- Architecture: Module structure, data flow, design rationale
- Crescent Visibility: Yallop and Odeh criteria explained in depth
- Ephemeris: DE442S kernel format (DAF/SPK), segment chaining, evaluation
- Time Scales: UTC, TAI, TT, TDB, UT1, delta-T, leap seconds
- Reference Frames: IERS Q·R·W chain, precession, nutation, ERA
- Observer Model: WGS84, topocentric transforms, atmospheric refraction
- Validation: Accuracy goals, test methodology, SPICE/Horizons comparison
Quick example
import { initKernels, getMoonSightingReport } from 'moon-sighting'
await initKernels()
const report = await getMoonSightingReport(new Date('2025-03-29'), {
lat: 51.5074, lon: -0.1278, elevation: 10
})
console.log(report.yallop.category) // 'A'
console.log(report.guidance)
Related packages
- nrel-spa: Solar position algorithm (zero deps)
- pray-calc: Islamic prayer times
- luxon-hijri: Hijri/Gregorian conversion