Uranus and Neptune, plus guides for moving from SunCalc and Solar
Almanac 0.8.0
Release Sky
Almanac 0.8.0 adds Uranus and Neptune, the Sun and Moon events apps need to move off SunCalc, and migration guides for SunCalc and Solar, in TypeScript and Swift.
sunAltitudeEvents(startUtc, endUtc, observer, altitudeDeg)finds the Sun crossing any altitude, rising and falling: golden hour at +6°, blue hour, or SunCalc'saddTimeangles, which mean the same thing here. At −6° it returns the same instants as civil twilight.sunTransitsandmoonTransitsfind upper and lower transits, so solar midnight and the Moon's highest and lowest points are available alongside rise and set.moonOrientation(time, observer)gives the position angle of the Moon's bright limb and its parallactic angle; subtracting one from the other gives the bright limb's angle from the zenith, which is what drawing the Moon as it looks needs.- Uranus and Neptune support every planetary API: Sun-centered vectors, apparent positions, altitude and azimuth, illumination, approximate magnitude, solar elongation, and rise and set.
- Migrating from SunCalc and Migrating from Solar map every export of those libraries to an Almanac call and give drop-in adapters; both test suites run the guides' code verbatim against output recorded from SunCalc 2.1.1 and Solar 4.0.1. How Almanac compares sets it beside SunCalc, Astronomy Engine, astronomia, Solar, SwiftAA, and EDSunriseSet, including where they are the better choice.
Existing functions return the same results, and no existing enum gains a case.
| New quantity | Evidence | Worst | Limit |
|---|---|---|---|
| Sun altitude crossings at +6°, −0.3°, −4°, −8° | 124 crossings on Horizons one-minute grids, 20°N to 70.5°N | 5.6 s | 60 s |
| Upper and lower transits, Sun and Moon | Horizons hour-angle grids | 1.1 s | 60 s |
| Moon upper transit, Sun and Moon lower transit | 54 USNO rows | 27.5 s | 60 s |
| Parallactic angle | Horizons azimuth, elevation, and declination | 0.18′ | 1′ |
| Bright limb, elongation 20°–160° | Meeus 48.5 on Horizons apparent positions | 0.42′ | 1′ |
| Uranus, Neptune Sun-centered position | Horizons, 1950–2100 | 0.00035 AU | 0.001 AU |
Against SunCalc 2.1.1 the migration adapters agree within 7 seconds on Sun times and 4 seconds on moonrise and moonset. Against Solar 4.0.1 they agree within 59 seconds from 34°S to 49°N; at 78°N, where the Sun grazes the twilight altitudes, the worst is 449 seconds.
Validation includes 216 TypeScript tests, 178 Swift release tests, offline fixture regeneration, cross-port parity, and Apple Watch compilation. Every existing benchmark workload stays inside the 20% regression limit. A year of Sun altitude events takes about 21 ms in TypeScript and 12 ms in Swift, and a year of Sun or Moon transits about 7 ms and 4 ms; timings vary by machine.
Fixture metadata records each Horizons request's own retrieval date, checked against the raw response headers.
npm install @openwaters/almanac@0.8.0
.package(url: "https://github.com/openwatersio/almanac.git", exact: "0.8.0")
Uranus and Neptune: #59. SunCalc parity and migration guide: #62. Solar migration guide: #65. Library comparison: #64. CI lockfile checks: #60, #66. Release preparation: #67.