DEV Community: Svarbhanu Neel

A library named "eclipse" should compute eclipses: grahan 1.0

Svarbhanu Neel — Mon, 06 Jul 2026 12:29:32 +0000

ix months ago I started an experiment: could one TypeScript library compute
everything a Nepali calendar app needs (sunrise, moon phases, the Hindu
panchang, birth charts, Bikram Sambat dates, even eclipses) with zero
runtime dependencies, MIT licensed, and accuracy you can actually measure?

Today grahan hit 1.0. The name is
ग्रहण, the Nepali/Sanskrit word for eclipse, so it wasn't allowed to ship
1.0 without living up to it:

import { nextSolarEclipseAt, julianDayFromDate, dateFromJulianDay } from '@grahan/core';

// When does Kathmandu next see the Sun bitten? Works for any lat/lon.
const jd = julianDayFromDate(new Date('2026-07-06T00:00:00Z'));
const e = nextSolarEclipseAt(jd, { latitude: 27.7172, longitude: 85.324 });

e.type;                        // 'partial': 2027-08-02, the Egypt totality grazing Nepal
dateFromJulianDay(e.maximum);  // 2027-08-02T11:05:02Z (16:50 local)
e.magnitude;                   // 0.0751, a small bite off the solar diameter

That covers every solar and lunar eclipse from 1900 to 2100: detection,
type, magnitudes, contact times, local visibility. All computed from raw
geometry in plain TypeScript. No WASM, no data files, no dependencies.

The feature calendar sites actually show

panchang() tells you the sky now. But printed panchangs and sites like
drikpanchang label a day by its sunrise elements, with the time each one
ends. That's panchangAtSunrise():

import { panchangAtSunrise } from '@grahan/vedic';

const day = panchangAtSunrise({
  year: 2026, month: 7, day: 2,
  latitude: 27.7172, longitude: 85.324, timezone: 'Asia/Kathmandu',
});

day.vaar.name;        // 'Thursday'
day.tithi[0].name;    // 'Dwitiya', the day's label...
day.tithi[0].endsAt;  // ...upto 09:53 local, then:
day.tithi[1].name;    // 'Tritiya'
day.karana.map(k => k.name); // ['Gara', 'Vanija', 'Vishti']
day.rahuKaal;         // 13:51 to 15:35 that Thursday

Notice tithi is an array. That's deliberate honesty: lunar days drift
against solar days, so some civil dates hold three tithis (a kshaya day,
where one tithi begins and ends entirely between two sunrises) and some
tithis span two sunrises (vriddhi). Most libraries squash this into a
single value and silently disagree with every printed calendar a few days
per month. grahan returns the ordered list of spans touching the day, each
with its real start and end instant.

I cross-checked the end times against drikpanchang's rendered pages: every
element name matched exactly, every time within about 80 seconds (they
print whole minutes).

Accuracy: measured, not hoped

Swiss Ephemeris is the industry standard, but it's AGPL, so linking it was
off the table for an MIT library. Instead, everything is implemented from
public-domain sources (Meeus's Astronomical Algorithms, VSOP87, ELP-2000)
and verified against Swiss Ephemeris outputs, which are facts, not
code. An offline Python script generates JSON reference fixtures; tests
assert tolerances and print an accuracy report on every CI run:

Quantity	Measured vs Swiss Ephemeris (1900–2100)
Sun longitude	max 4.6″, mean 0.9″
Moon longitude	max 65″, mean 10.5″
Planets	max 7.8″ (Mercury) to 1.1″ (Saturn)
Sunrise/sunset	max 4.6 s over 272 events, 5 sites incl. 71°N
Panchang end times	max 37.5 s over 122 boundaries
Eclipse instants	mean ~20 s; detection and type exact on all 909 events

Three bugs this method caught that eyeballing never would:

The Arctic is a unit test. At Utqiagvik (71°N) the sun can set before it rises within one civil day, and near the polar-night boundary the "nearest" sunrise belongs to a neighbouring solar cycle. Two real algorithm bugs, both caught by fixtures I only generated because 71°N felt like a good edge case.
Two eclipses where the references disagree. For 1927-01-03 and 1948-05-09, Swiss Ephemeris says hybrid while NASA's Espenak catalog says annular, with 3 seconds and 0 seconds of annularity respectively. My independent shadow geometry sided with NASA both times. Knife-edge cases are where you learn whose model does what.
A 17.2″ systematic error in the lunar node turned out to be a frame mismatch (mean vs true equinox). It was diagnosed purely because the error's scale matched the nutation amplitude. When your tests print arcseconds, error signatures become fingerprints.

What else is in the box

kundali(): sidereal birth charts with nine grahas, lagna, whole-sign houses, navamsa, plus SVG renderers in North and South Indian styles, Vimshottari dashas, transits, muhurta windows, gun-milan matching. Rahu can follow the mean node or the true osculating node (node: 'true'), computed the way Swiss Ephemeris does it: from the Moon's instantaneous orbit plane.
@grahan/calendars: Bikram Sambat to AD conversion for BS 1975–2200, with verified tables through 2083 and beyond that a Surya Siddhanta projection, clearly flagged projected: true, because pretending certainty about 2199 would be a lie.
The secular core stands alone: Julian days, ΔT, sidereal time, and sunrise/sunset with explicit 'always-up' / 'always-down' polar states. No fabricated 00:00 sunrises.

What 1.0 means here

Not "it compiles". For 1.0 I froze and tested the API surface (the exact
export list of each package is pinned by tests), made every public function
throw a RangeError naming the offending value on bad input (latitude 95,
new Date(NaN), month 13; nothing silently returns NaN), and published an
API reference generated from the
JSDoc.

Two production details I'm particularly happy with:

The panchang core tree-shakes to 9.7 KB gzipped. CI proves it: a scratch consumer bundles the shipped tarballs with esbuild in browser mode (so any Node builtin is a hard build error), runs the bundle, and asserts the planet tables and eclipse code actually shake off.
Releases are tokenless. Publishing happens from GitHub Actions via npm trusted publishing (OIDC), so no npm token exists anywhere, and every package carries a SLSA provenance attestation. npm audit signatures verifies the whole chain. The release workflow also refuses to publish a partial release: every package must pass an OIDC preflight before any of them ships.

Try it

npm install @grahan/vedic   # panchang + charts (pulls in @grahan/core)

GitHub: https://github.com/svarbhanu/grahan
API reference: https://svarbhanu.github.io/grahan/
npm: @grahan/core · @grahan/vedic · @grahan/calendars

Next up: lunar months (masa/adhika-masa), moonrise/moonset, festival rules,
and more calendars on the same core. Which would you use first: Hijri,
Hebrew, or Chinese lunisolar? The architecture is one secular core with
cultural layers on top, so your answer genuinely steers the roadmap.

I built a zero-dependency sky engine in TypeScript, verified to 4.6 arcseconds

Svarbhanu Neel — Sat, 04 Jul 2026 13:21:55 +0000

Today I shipped v0.1.0 of grahan, an MIT-licensed TypeScript library that computes Sun/Moon positions, sunrise/sunset, moon phases, and the Vedic panchang (tithi, nakshatra, yoga, karana, Rahu Kaal). Zero runtime dependencies. Runs in Node 18+, browsers, and edge runtimes.

npm install @grahan/vedic

import { panchang } from '@grahan/vedic';

const p = panchang({
  date: new Date('2026-07-02T06:00:00Z'),
  latitude: 27.7172,
  longitude: 85.324,
  timezone: 'Asia/Kathmandu',
});
// p.tithi      → { index: 17, paksha: 'krishna', name: 'Tritiya' }
// p.nakshatra  → { index: 21, name: 'Shravana', pada: 1 }
// p.rahuKaal   → 13:51 to 15:35 local, that Thursday

This post is about the three engineering decisions that mattered, and the bugs the process caught that I would never have found by eyeballing outputs.

Why zero dependencies

The industry-standard ephemeris is Swiss Ephemeris. It is superb, but AGPL (or paid), so linking it was off the table for an MIT library. The alternatives were: wrap a WASM build (license problem remains), depend on a chain of npm astronomy packages of varying maintenance, or implement from the public-domain sources: Meeus's Astronomical Algorithms, the VSOP87 planetary theory, and the ELP-2000 lunar series.

I implemented from sources. It also bought me something I didn't expect to value so much: the whole library is auditable. Every formula has a citation to a chapter of Meeus or an official data file.

Rule one: generate the answer sheet before writing the formula

Swiss Ephemeris is AGPL code, but its outputs are facts. So before writing any calculation, I ran an offline Python script (pyswisseph) that generated JSON reference fixtures and committed them to the repo: 120 Sun/Moon longitudes spanning 1900 to 2100, 150 sunrise/sunset events across 5 sites from Singapore to Utqiagvik at 71°N, 41 ayanamsa epochs. Tests read the JSON and assert tolerances, and CI prints an accuracy report on every run:

[accuracy] sun apparent longitude: n=120 max=4.60″ mean=0.85″
[accuracy] moon apparent longitude: n=120 max=65.37″ mean=10.46″
[accuracy] sunrise/sunset: n=272 max=4.6s mean=0.9s polar-states=28

Promised tolerances are ±36″ (Sun), ±180″ (Moon), ±60 s (rise/set). Measured is 8 to 13 times inside the promise. The README publishes both columns, promise and measurement, because accuracy claims without numbers are marketing.

Rule two: don't type coefficient tables by hand

The Sun's position needs a truncated VSOP87 series: hundreds of coefficients. Typing them from a book is how you get a library that's subtly wrong forever. Instead, a script downloads the official VSOP87D data file from the CDS astronomical data center, truncates it by amplitude, and emits the TypeScript table with provenance in the header. The Moon's 120-term table I did have to type from Meeus, but the fixtures had my back: the mean error came out at 10.5″, exactly the intrinsic accuracy Meeus states for that truncation. A single typo would have inflated it.

The bugs the fixtures caught

The nutation fingerprint. My lunar-node function disagreed with the reference by a systematic 11 to 18 arcseconds. The scale was the clue: nutation oscillates ±17.2″. Swiss Ephemeris reports the node on the true equinox of date; my polynomial gave the mean equinox. One line fixed it, and max error fell to 0.35″. Good reference data doesn't just say wrong. The error's shape tells you why.

Sunset before sunrise. At 71°N, near the midnight-sun transition, a local calendar day can contain a sunset at 01:30 and a sunrise at 02:40, in that order. My test asserted sunrise < sunset as a universal property. The fixture data taught me otherwise.

The neighbouring solar cycle. Also at 71°N: a local day whose sunset belongs to the previous day's solar arc, 15 minutes after local midnight. My first algorithm only searched around that day's own solar noon and reported "always up." The fix: consider events from adjacent transits and keep whatever lands inside the local day.

The refraction calibration. First full run: every site showed sunrise late and sunset early by the same amount. The day was symmetrically too short, and that signature means exactly one thing: the horizon-altitude constant is wrong. The textbook says 34′ of refraction; Swiss Ephemeris effectively bends about 36.7′ at the event's true altitude. At tangent polar crossings that 0.6′ costs two minutes. One calibrated constant, documented with its provenance, took max error from 115 s to 4.6 s.

The empty tarball. My npm build hook was prepublishOnly, which does not run on pack. CI packed tarballs with no compiled code in them. I only caught it because the CI installs the packed tarballs with plain npm into a scratch project on Node 18/20/22 and runs a smoke test, exactly as a consumer would. If your CI only ever tests your source tree, you are not testing the thing you ship.

Architecture: secular core, cultural layers

@grahan/core is pure astronomy. A weather or photography app can use it without touching a single Vedic concept. @grahan/vedic layers the cultural interpretation on top: the Lahiri ayanamsa (fitted to reference values to 0.002″), then tithi, nakshatra, yoga, and karana as pure functions over longitudes. Planned layers on the same core: world calendars (Bikram Sambat, Hijri, Hebrew), prayer times, tropical charts.

A detail I enjoyed: the ayanamsa cancels in the Moon minus Sun difference, so tithi works on tropical longitudes directly. But it doesn't cancel in the Moon plus Sun sum, so yoga genuinely needs the sidereal frame. The kind of thing you only internalize by implementing it.

What's next

Phase 2 is kundali(), full birth charts: the remaining planets, lagna, whole-sign houses, D9, and SVG chart renderers. Same method: fixtures first, formulas second.

Repo: https://github.com/svarbhanu/grahan · Packages: @grahan/core, @grahan/vedic. Issues and PRs welcome, especially from people who know panchang traditions better than I do.