Solar eclipses visible from a location
Almanac 0.4.0
Release Sky
Almanac 0.4.0 adds solar eclipses for an observer in TypeScript and Swift.
nextSolarEclipse(after:observer:)/nextSolarEclipse(after, observer),previousSolarEclipse(before:observer:)/previousSolarEclipse(before, observer), andsolarEclipses(from:to:observer:)/solarEclipses(from, to, observer)find the solar eclipses a place can see. Each result carries the kind (partial, annular, or total), the obscuration at peak, contacts C1 through C4, and the Sun's altitude at each contact. C2 and C3 are present only for annular and total eclipses.- An eclipse whose Sun is below the horizon at C1, the peak, and C4 is not returned. Next and previous searches walk to the edge of the supported interval, because a place can go years without a visible solar eclipse.
solarObscuration(at:observer:)/solarObscuration(time, observer)gives the fraction of the Sun's disc the Moon covers at any instant, for drawing an eclipse as it happens.- The shared performance harness gains seven solar workloads.
benchmarks/run.mjs --skip <regex>leaves them out when the comparison base predates 0.4.0. - Swift CI runs on Linux with Swift 6.3.3, and the TypeScript package builds with TypeScript 7.
The searches are checked against USNO local circumstances for eight places and against all 337 solar eclipses from 1950 through 2100 in the Espenak Five Millennium Catalog. The worst residuals sit well inside the contract's tolerances:
| Quantity | Worst residual | Tolerance |
|---|---|---|
| USNO contacts C1 through C4 | 7.2 s | 60 s |
| USNO peak | 7.0 s | 300 s |
| Catalog peak, 215 central eclipses | 123 s | 300 s |
| USNO obscuration | 0.001 | 0.01 |
| USNO Sun altitude at a contact | 0.06° | 0.5° |
The hosted CI comparison measured these median query times, in milliseconds:
| Workload | TypeScript | Swift |
|---|---|---|
| Next solar eclipse | 8.1 | 6.0 |
| Previous solar eclipse | 6.9 | 5.1 |
| Solar eclipses / 228 hours, one visible | 0.72 | 0.51 |
| Solar eclipses / 228 hours, new moon not visible | 0.48 | 0.35 |
| Solar eclipses / 228 hours, no new moon | 0.012 | 0.009 |
| Solar eclipses / 1950–2100 | 391 | 295 |
| Obscuration / 228 hours | 2.8 | 2.0 |
Both revisions used the same harness and toolchain within each port, with seven interleaved process pairs and 300 ms warmup. No existing workload moved by more than 2.1% in either port. Validation includes 127 TypeScript tests, 109 Swift release tests, and the shared fixture and parity checks.
npm install @openwaters/almanac@0.4.0
.package(url: "https://github.com/openwatersio/almanac.git", exact: "0.4.0")
Solar eclipses: #24, #27. Development and toolchain: #15, #22, #23, #25, #26. Dependency updates: #16, #17, #18, #19, #20, #21.