panchang-ts 4.2.0 → 4.3.0

package/README.md

@@ -5,7 +5,7 @@
 Pure TypeScript Hindu Panchang (almanac), Jyotish, and Birth Chart calculations.
 Zero native dependencies. Works offline in React Native (Hermes), Node.js, and browsers.
 
-**Fast** (~0.1 ms names-only, ~0.5 ms full) · **Typed** (full TypeScript) · **Offline** (pure JS math) · **8,103 tests across 96 files**
+**Fast** (~0.1 ms names-only, ~0.5 ms full) · **Typed** (full TypeScript) · **Offline** (pure JS math) · **8,164 tests across 100 files**
 
 ---
 
@@ -290,8 +290,9 @@ FESTIVALS_META.languages;                       // ["en", "hi"]
 This entry point is engine-free — it ships only the JSON + accessors, so
 importing it won't pull the calculation engine into your bundle. Both `en`
 and `hi` are bundled (names *and* descriptions); pass the locale as the
-second argument. Eclipses are excluded (visibility is location-dependent —
-use `getUpcomingEclipses`).
+second argument. Eclipses are excluded here (visibility is location-dependent)
+— they ship as their own bundled table at `panchang-ts/eclipses` (see
+[Eclipses](#eclipses)).
 
 ### Festivals outside India — build a location table and cache it
 
@@ -353,6 +354,117 @@ import { getUpcomingSolarEclipse, getUpcomingLunarEclipse } from 'panchang-ts';
 const next = getUpcomingSolarEclipse(new Date(), loc, 365 /* days */);
 ```
 
+### Pre-computed table (bundled, India / IST)
+
+Like the festivals table, eclipse data ships as a static, engine-free entry
+at `panchang-ts/eclipses` — a rolling **2-years-past / 5-years-future** window
+pre-computed against Varanasi (IST). It lists every eclipse **visible from
+there during any phase** (so an eclipse already in progress at moon/sunrise or
+moon/sunset is included); the `visibleAtPeak` flag tells you whether greatest
+eclipse itself is observable. Within India visibility is essentially uniform.
+
+```typescript
+import {
+  getEclipsesForYear,
+  getEclipsesForDate,
+  ECLIPSES_META,
+  ECLIPSES_YEAR_RANGE,
+} from 'panchang-ts/eclipses';
+
+const e = getEclipsesForYear(2025)![0].eclipses[0];
+e.kind;                 // 'lunar'
+e.subtype;              // 'total'
+e.start; e.peak; e.end; // ISO UTC strings
+e.magnitude;            // 0..1 obscuration at peak
+e.visibleFromLocation;  // visible during any phase? (always true in bundled table)
+e.visibleAtPeak;        // is greatest eclipse itself above the horizon?
+e.sutak;                // { start, end } — see note below
+getEclipsesForDate('2025-09-07', 'hi');  // [पूर्ण चंद्र ग्रहण]
+ECLIPSES_META.referenceLocation;         // "Varanasi"
+```
+
+Each entry carries `en` + `hi` text. Solar eclipses report the subtype seen
+**locally** (a globally-total eclipse may read `partial` from Varanasi). The
+`sutak` window is present only where it applies — all visible solar eclipses
+and visible **umbral** (partial/total) lunar eclipses; **penumbral** lunar
+eclipses carry no `sutak` and are not religiously observed (drik / pandit
+consensus). For full astronomical detail (e.g. eclipses *not* visible in
+India), use `getUpcomingEclipses` / `getEclipsesInRange` from the main entry.
+
+**Outside India:** which eclipses are visible — and thus carry `sutak` —
+differs by location. Build and cache a location-specific table with
+`buildEclipsesTable` (main entry, uses the engine), then read it back via the
+same accessors' `source` argument — the same compute-once-then-cache pattern
+as festivals:
+
+```typescript
+import { buildEclipsesTable } from 'panchang-ts';
+import { getEclipsesForYear } from 'panchang-ts/eclipses';
+
+const table = buildEclipsesTable({
+  location: { latitude: 51.5074, longitude: -0.1278 },
+  timezoneOffsetMinutes: 0,        // UK / GMT
+  startYear: 2024,
+  endYear: 2031,
+  // visibleOnly: false → also include eclipses below the horizon (no sutak)
+});
+getEclipsesForYear(2025, 'en', table);
+```
+
+To regenerate the bundled India table, run `npm run eclipses:gen` (rolling
+window, no constants to edit).
+
+## Moon Phases
+
+The four principal lunar phases — **new** (Amavasya), **first quarter**,
+**full** (Purnima), **last quarter** — as precise instants. (These are the
+astronomical quarter moments, distinct from the same-named *tithis*, which are
+~24h windows.)
+
+```typescript
+import { getMoonPhasesInRange } from 'panchang-ts';
+const phases = getMoonPhasesInRange(new Date('2026-01-01'), new Date('2026-12-31'));
+phases.forEach(p => console.log(p.phase, p.time.toISOString()));  // ~49 / year
+```
+
+### Pre-computed table (bundled, India / IST)
+
+Same engine-free pattern as festivals and eclipses, at `panchang-ts/moon-phases`
+— a rolling **2-years-past / 5-years-future** window. Phases are global
+instants; the bundled table maps each onto its **IST** calendar date (so a new
+moon at 19:52 UTC on Jan 18 is listed under Jan 19 in India).
+
+```typescript
+import {
+  getMoonPhasesForYear,
+  getMoonPhasesForDate,
+  MOON_PHASES_META,
+  MOON_PHASES_YEAR_RANGE,
+} from 'panchang-ts/moon-phases';
+
+getMoonPhasesForYear(2026)!.length;            // ~49 phase days
+getMoonPhasesForDate('2026-01-03');            // [{ phase: 'full', name: 'Full Moon', ... }]
+getMoonPhasesForDate('2026-01-03', 'hi');      // [{ phase: 'full', name: 'पूर्णिमा', ... }]
+```
+
+Each entry carries `phase`, the phase `time` (ISO UTC), and `en` + `hi` text.
+For another timezone, build and cache a table with `buildMoonPhasesTable` (main
+entry) and pass it as the accessors' `source` argument — it takes only a
+`timezoneOffsetMinutes` (no coordinates, since phases are location-independent):
+
+```typescript
+import { buildMoonPhasesTable } from 'panchang-ts';
+import { getMoonPhasesForYear } from 'panchang-ts/moon-phases';
+
+const table = buildMoonPhasesTable({
+  timezoneOffsetMinutes: -300,   // US Eastern
+  startYear: 2024, endYear: 2031,
+});
+getMoonPhasesForYear(2026, 'en', table);
+```
+
+Regenerate the bundled India table with `npm run moon-phases:gen`.
+
 ## Planetary Positions
 
 ```typescript
@@ -730,7 +842,7 @@ import {
   convertGregorianToHindu, convertHinduToGregorian,
   getKaliYugaYear, getHinduNewYear,
   getEkadashiDatesForYear, getSankrantisForYear,
-  getFestivalsInRange, getUpcomingEclipses,
+  getFestivalsInRange, getUpcomingEclipses, getEclipsesInRange,
 } from 'panchang-ts';
 
 // Gregorian → Hindu coords at sunrise
@@ -927,6 +1039,10 @@ computeMadhyahna, computePratahSandhya, computeSayahnaSandhya
 
 // Eclipses
 getUpcomingSolarEclipse, getUpcomingLunarEclipse, getEclipseDuringDay
+isEclipseVisibleAnyPhase
+
+// Moon phases (new / quarters / full as precise instants)
+getMoonPhasesInRange
 
 // Jyotish — planets, dashas, transits
 computePlanetaryPositions, GRAHA_ABBR
@@ -961,7 +1077,12 @@ aksharabhyasamRule, seemanthamRule, shopOpeningRule, travelStartRule
 // Calendar conversion + yearly listings
 convertGregorianToHindu, convertHinduToGregorian
 getKaliYugaYear, getHinduNewYear, computeSamvat
-getEkadashiDatesForYear, getSankrantisForYear, getFestivalsInRange, getUpcomingEclipses
+getEkadashiDatesForYear, getSankrantisForYear, getFestivalsInRange
+getUpcomingEclipses, getEclipsesInRange
+
+// Static data tables (engine-using runtime builders; bundled JSON at
+// panchang-ts/festivals, panchang-ts/eclipses, panchang-ts/moon-phases)
+buildFestivalsTable, buildEclipsesTable, buildMoonPhasesTable
 
 // Errors
 PanchangError
@@ -999,7 +1120,7 @@ InteractionManager.runAfterInteractions(() => {
 
 ## Accuracy
 
-8,103 tests across 96 files, including fixtures cross-verified against reference
+8,164 tests across 100 files, including fixtures cross-verified against reference
 panchang calculations spanning 2025–2026 across 10 Indian cities plus New York,
 London, Sydney, Dubai, Singapore (diaspora fixtures cover DST on
 `America/New_York`).

package/dist/calendar/eclipsesTable.cjs

@@ -0,0 +1,404 @@
+'use strict';
+
+// src/data/eclipses.json
+var eclipses_default = {
+  _meta: {
+    referenceLocation: "Varanasi",
+    latitude: 25.3176,
+    longitude: 82.9739,
+    timezoneOffsetMinutes: 330,
+    visibleOnly: true,
+    languages: [
+      "en",
+      "hi"
+    ],
+    startYear: 2024,
+    endYear: 2031,
+    generatedAt: "2026-05-30T14:11:40.371Z",
+    note: "Eclipses pre-computed for Varanasi (IST), visible from there during any phase (eclipsed body above the horizon between first and last contact \u2014 so an eclipse in progress at moon/sunrise or moon/sunset is included). visibleAtPeak flags whether greatest eclipse itself is observable. Within India visibility is essentially uniform; elsewhere it differs, so build a location-specific table at runtime with buildEclipsesTable and cache it. Solar eclipses carry the subtype seen from Varanasi (a globally-total eclipse may show as partial). Times are ISO UTC. Sutak: 4 prahara (12h) before first contact for solar, 3 prahara (9h) for umbral (partial/total) lunar, ending at moksha; penumbral lunar eclipses carry no sutak and are not religiously observed (drik / pandit consensus). Each entry carries both en and hi text."
+  },
+  years: {
+    "2024": [],
+    "2025": [
+      {
+        date: "2025-09-07",
+        eclipses: [
+          {
+            name: {
+              en: "Total Lunar Eclipse",
+              hi: "\u092A\u0942\u0930\u094D\u0923 \u091A\u0902\u0926\u094D\u0930 \u0917\u094D\u0930\u0939\u0923"
+            },
+            kind: "lunar",
+            subtype: "total",
+            start: "2025-09-07T15:28:02.515Z",
+            peak: "2025-09-07T18:11:41.501Z",
+            end: "2025-09-07T20:55:20.486Z",
+            magnitude: 1,
+            visibleFromLocation: true,
+            visibleAtPeak: true,
+            description: {
+              en: "Total Lunar Eclipse \u2014 100% obscuration.",
+              hi: "\u092A\u0942\u0930\u094D\u0923 \u091A\u0902\u0926\u094D\u0930 \u0917\u094D\u0930\u0939\u0923 \u2014 100% \u0917\u094D\u0930\u093E\u0938\u0964"
+            },
+            sutak: {
+              start: "2025-09-07T06:28:02.515Z",
+              end: "2025-09-07T20:55:20.486Z"
+            }
+          }
+        ]
+      }
+    ],
+    "2026": [
+      {
+        date: "2026-03-03",
+        eclipses: [
+          {
+            name: {
+              en: "Total Lunar Eclipse",
+              hi: "\u092A\u0942\u0930\u094D\u0923 \u091A\u0902\u0926\u094D\u0930 \u0917\u094D\u0930\u0939\u0923"
+            },
+            kind: "lunar",
+            subtype: "total",
+            start: "2026-03-03T08:44:01.948Z",
+            peak: "2026-03-03T11:33:40.289Z",
+            end: "2026-03-03T14:23:18.629Z",
+            magnitude: 1,
+            visibleFromLocation: true,
+            visibleAtPeak: false,
+            description: {
+              en: "Total Lunar Eclipse \u2014 100% obscuration.",
+              hi: "\u092A\u0942\u0930\u094D\u0923 \u091A\u0902\u0926\u094D\u0930 \u0917\u094D\u0930\u0939\u0923 \u2014 100% \u0917\u094D\u0930\u093E\u0938\u0964"
+            },
+            sutak: {
+              start: "2026-03-02T23:44:01.948Z",
+              end: "2026-03-03T14:23:18.629Z"
+            }
+          }
+        ]
+      }
+    ],
+    "2027": [
+      {
+        date: "2027-02-21",
+        eclipses: [
+          {
+            name: {
+              en: "Penumbral Lunar Eclipse",
+              hi: "\u0909\u092A\u091A\u094D\u091B\u093E\u092F\u093E \u091A\u0902\u0926\u094D\u0930 \u0917\u094D\u0930\u0939\u0923"
+            },
+            kind: "lunar",
+            subtype: "penumbral",
+            start: "2027-02-20T21:11:52.109Z",
+            peak: "2027-02-20T23:12:44.142Z",
+            end: "2027-02-21T01:13:36.174Z",
+            magnitude: 0,
+            visibleFromLocation: true,
+            visibleAtPeak: true,
+            description: {
+              en: "Penumbral Lunar Eclipse \u2014 penumbral shadow only; no sutak.",
+              hi: "\u0909\u092A\u091A\u094D\u091B\u093E\u092F\u093E \u091A\u0902\u0926\u094D\u0930 \u0917\u094D\u0930\u0939\u0923 \u2014 \u0915\u0947\u0935\u0932 \u0909\u092A\u091A\u094D\u091B\u093E\u092F\u093E \u091B\u093E\u092F\u093E; \u0938\u0942\u0924\u0915 \u0928\u0939\u0940\u0902\u0964"
+            }
+          }
+        ]
+      },
+      {
+        date: "2027-07-18",
+        eclipses: [
+          {
+            name: {
+              en: "Penumbral Lunar Eclipse",
+              hi: "\u0909\u092A\u091A\u094D\u091B\u093E\u092F\u093E \u091A\u0902\u0926\u094D\u0930 \u0917\u094D\u0930\u0939\u0923"
+            },
+            kind: "lunar",
+            subtype: "penumbral",
+            start: "2027-07-18T15:50:13.585Z",
+            peak: "2027-07-18T16:02:54.880Z",
+            end: "2027-07-18T16:15:36.174Z",
+            magnitude: 0,
+            visibleFromLocation: true,
+            visibleAtPeak: true,
+            description: {
+              en: "Penumbral Lunar Eclipse \u2014 penumbral shadow only; no sutak.",
+              hi: "\u0909\u092A\u091A\u094D\u091B\u093E\u092F\u093E \u091A\u0902\u0926\u094D\u0930 \u0917\u094D\u0930\u0939\u0923 \u2014 \u0915\u0947\u0935\u0932 \u0909\u092A\u091A\u094D\u091B\u093E\u092F\u093E \u091B\u093E\u092F\u093E; \u0938\u0942\u0924\u0915 \u0928\u0939\u0940\u0902\u0964"
+            }
+          }
+        ]
+      },
+      {
+        date: "2027-08-02",
+        eclipses: [
+          {
+            name: {
+              en: "Partial Solar Eclipse",
+              hi: "\u0906\u0902\u0936\u093F\u0915 \u0938\u0942\u0930\u094D\u092F \u0917\u094D\u0930\u0939\u0923"
+            },
+            kind: "solar",
+            subtype: "partial",
+            start: "2027-08-02T10:35:33.763Z",
+            peak: "2027-08-02T11:07:37.251Z",
+            end: "2027-08-02T11:38:16.999Z",
+            magnitude: 0.06923317826751327,
+            visibleFromLocation: true,
+            visibleAtPeak: true,
+            description: {
+              en: "Partial Solar Eclipse \u2014 7% obscuration.",
+              hi: "\u0906\u0902\u0936\u093F\u0915 \u0938\u0942\u0930\u094D\u092F \u0917\u094D\u0930\u0939\u0923 \u2014 7% \u0917\u094D\u0930\u093E\u0938\u0964"
+            },
+            sutak: {
+              start: "2027-08-01T22:35:33.763Z",
+              end: "2027-08-02T11:38:16.999Z"
+            }
+          }
+        ]
+      }
+    ],
+    "2028": [
+      {
+        date: "2028-07-06",
+        eclipses: [
+          {
+            name: {
+              en: "Partial Lunar Eclipse",
+              hi: "\u0906\u0902\u0936\u093F\u0915 \u091A\u0902\u0926\u094D\u0930 \u0917\u094D\u0930\u0939\u0923"
+            },
+            kind: "lunar",
+            subtype: "partial",
+            start: "2028-07-06T15:43:55.421Z",
+            peak: "2028-07-06T18:19:38.379Z",
+            end: "2028-07-06T20:55:21.336Z",
+            magnitude: 0.3322998217792101,
+            visibleFromLocation: true,
+            visibleAtPeak: true,
+            description: {
+              en: "Partial Lunar Eclipse \u2014 33% obscuration.",
+              hi: "\u0906\u0902\u0936\u093F\u0915 \u091A\u0902\u0926\u094D\u0930 \u0917\u094D\u0930\u0939\u0923 \u2014 33% \u0917\u094D\u0930\u093E\u0938\u0964"
+            },
+            sutak: {
+              start: "2028-07-06T06:43:55.421Z",
+              end: "2028-07-06T20:55:21.336Z"
+            }
+          }
+        ]
+      },
+      {
+        date: "2028-12-31",
+        eclipses: [
+          {
+            name: {
+              en: "Total Lunar Eclipse",
+              hi: "\u092A\u0942\u0930\u094D\u0923 \u091A\u0902\u0926\u094D\u0930 \u0917\u094D\u0930\u0939\u0923"
+            },
+            kind: "lunar",
+            subtype: "total",
+            start: "2028-12-31T14:03:27.574Z",
+            peak: "2028-12-31T16:51:54.549Z",
+            end: "2028-12-31T19:40:21.523Z",
+            magnitude: 1,
+            visibleFromLocation: true,
+            visibleAtPeak: true,
+            description: {
+              en: "Total Lunar Eclipse \u2014 100% obscuration.",
+              hi: "\u092A\u0942\u0930\u094D\u0923 \u091A\u0902\u0926\u094D\u0930 \u0917\u094D\u0930\u0939\u0923 \u2014 100% \u0917\u094D\u0930\u093E\u0938\u0964"
+            },
+            sutak: {
+              start: "2028-12-31T05:03:27.574Z",
+              end: "2028-12-31T19:40:21.523Z"
+            }
+          }
+        ]
+      }
+    ],
+    "2029": [
+      {
+        date: "2029-12-21",
+        eclipses: [
+          {
+            name: {
+              en: "Total Lunar Eclipse",
+              hi: "\u092A\u0942\u0930\u094D\u0923 \u091A\u0902\u0926\u094D\u0930 \u0917\u094D\u0930\u0939\u0923"
+            },
+            kind: "lunar",
+            subtype: "total",
+            start: "2029-12-20T19:42:34.436Z",
+            peak: "2029-12-20T22:41:54.610Z",
+            end: "2029-12-21T01:41:14.783Z",
+            magnitude: 1,
+            visibleFromLocation: true,
+            visibleAtPeak: true,
+            description: {
+              en: "Total Lunar Eclipse \u2014 100% obscuration.",
+              hi: "\u092A\u0942\u0930\u094D\u0923 \u091A\u0902\u0926\u094D\u0930 \u0917\u094D\u0930\u0939\u0923 \u2014 100% \u0917\u094D\u0930\u093E\u0938\u0964"
+            },
+            sutak: {
+              start: "2029-12-20T10:42:34.436Z",
+              end: "2029-12-21T01:41:14.783Z"
+            }
+          }
+        ]
+      }
+    ],
+    "2030": [
+      {
+        date: "2030-06-01",
+        eclipses: [
+          {
+            name: {
+              en: "Partial Solar Eclipse",
+              hi: "\u0906\u0902\u0936\u093F\u0915 \u0938\u0942\u0930\u094D\u092F \u0917\u094D\u0930\u0939\u0923"
+            },
+            kind: "solar",
+            subtype: "partial",
+            start: "2030-06-01T05:29:15.459Z",
+            peak: "2030-06-01T06:26:07.220Z",
+            end: "2030-06-01T07:23:32.918Z",
+            magnitude: 0.03201876826173855,
+            visibleFromLocation: true,
+            visibleAtPeak: true,
+            description: {
+              en: "Partial Solar Eclipse \u2014 3% obscuration.",
+              hi: "\u0906\u0902\u0936\u093F\u0915 \u0938\u0942\u0930\u094D\u092F \u0917\u094D\u0930\u0939\u0923 \u2014 3% \u0917\u094D\u0930\u093E\u0938\u0964"
+            },
+            sutak: {
+              start: "2030-05-31T17:29:15.459Z",
+              end: "2030-06-01T07:23:32.918Z"
+            }
+          }
+        ]
+      },
+      {
+        date: "2030-06-16",
+        eclipses: [
+          {
+            name: {
+              en: "Partial Lunar Eclipse",
+              hi: "\u0906\u0902\u0936\u093F\u0915 \u091A\u0902\u0926\u094D\u0930 \u0917\u094D\u0930\u0939\u0923"
+            },
+            kind: "lunar",
+            subtype: "partial",
+            start: "2030-06-15T16:13:48.134Z",
+            peak: "2030-06-15T18:33:14.732Z",
+            end: "2030-06-15T20:52:41.329Z",
+            magnitude: 0.4708077570686115,
+            visibleFromLocation: true,
+            visibleAtPeak: true,
+            description: {
+              en: "Partial Lunar Eclipse \u2014 47% obscuration.",
+              hi: "\u0906\u0902\u0936\u093F\u0915 \u091A\u0902\u0926\u094D\u0930 \u0917\u094D\u0930\u0939\u0923 \u2014 47% \u0917\u094D\u0930\u093E\u0938\u0964"
+            },
+            sutak: {
+              start: "2030-06-15T07:13:48.134Z",
+              end: "2030-06-15T20:52:41.329Z"
+            }
+          }
+        ]
+      },
+      {
+        date: "2030-12-10",
+        eclipses: [
+          {
+            name: {
+              en: "Penumbral Lunar Eclipse",
+              hi: "\u0909\u092A\u091A\u094D\u091B\u093E\u092F\u093E \u091A\u0902\u0926\u094D\u0930 \u0917\u094D\u0930\u0939\u0923"
+            },
+            kind: "lunar",
+            subtype: "penumbral",
+            start: "2030-12-09T20:07:30.214Z",
+            peak: "2030-12-09T22:27:32.805Z",
+            end: "2030-12-10T00:47:35.395Z",
+            magnitude: 0,
+            visibleFromLocation: true,
+            visibleAtPeak: true,
+            description: {
+              en: "Penumbral Lunar Eclipse \u2014 penumbral shadow only; no sutak.",
+              hi: "\u0909\u092A\u091A\u094D\u091B\u093E\u092F\u093E \u091A\u0902\u0926\u094D\u0930 \u0917\u094D\u0930\u0939\u0923 \u2014 \u0915\u0947\u0935\u0932 \u0909\u092A\u091A\u094D\u091B\u093E\u092F\u093E \u091B\u093E\u092F\u093E; \u0938\u0942\u0924\u0915 \u0928\u0939\u0940\u0902\u0964"
+            }
+          }
+        ]
+      }
+    ],
+    "2031": [
+      {
+        date: "2031-05-21",
+        eclipses: [
+          {
+            name: {
+              en: "Partial Solar Eclipse",
+              hi: "\u0906\u0902\u0936\u093F\u0915 \u0938\u0942\u0930\u094D\u092F \u0917\u094D\u0930\u0939\u0923"
+            },
+            kind: "solar",
+            subtype: "partial",
+            start: "2031-05-21T06:16:35.159Z",
+            peak: "2031-05-21T07:56:20.750Z",
+            end: "2031-05-21T09:26:36.965Z",
+            magnitude: 0.3939059024675881,
+            visibleFromLocation: true,
+            visibleAtPeak: true,
+            description: {
+              en: "Partial Solar Eclipse \u2014 39% obscuration.",
+              hi: "\u0906\u0902\u0936\u093F\u0915 \u0938\u0942\u0930\u094D\u092F \u0917\u094D\u0930\u0939\u0923 \u2014 39% \u0917\u094D\u0930\u093E\u0938\u0964"
+            },
+            sutak: {
+              start: "2031-05-20T18:16:35.159Z",
+              end: "2031-05-21T09:26:36.965Z"
+            }
+          }
+        ]
+      }
+    ]
+  }
+};
+
+// src/calendar/eclipsesTable.ts
+var bundled = eclipses_default;
+var ECLIPSES_META = bundled._meta;
+var ECLIPSES_YEAR_RANGE = {
+  start: bundled._meta.startYear,
+  end: bundled._meta.endYear
+};
+function flatten(raw, lang) {
+  const name = raw.name[lang] ?? Object.values(raw.name)[0] ?? "";
+  const out = {
+    name,
+    kind: raw.kind,
+    subtype: raw.subtype,
+    start: raw.start,
+    peak: raw.peak,
+    end: raw.end,
+    magnitude: raw.magnitude,
+    visibleFromLocation: raw.visibleFromLocation,
+    visibleAtPeak: raw.visibleAtPeak
+  };
+  if (raw.sutak) out.sutak = raw.sutak;
+  if (raw.description) {
+    out.description = raw.description[lang] ?? Object.values(raw.description)[0] ?? "";
+  }
+  return out;
+}
+function getEclipsesForYear(year, lang = "en", source = bundled) {
+  const days = source.years[String(year)];
+  if (!days) return null;
+  return days.map((d) => ({
+    date: d.date,
+    eclipses: d.eclipses.map((e) => flatten(e, lang))
+  }));
+}
+function getEclipsesForDate(date, lang = "en", source = bundled) {
+  const key = typeof date === "string" ? date : toDateKey(date, source._meta.timezoneOffsetMinutes);
+  const yearKey = key.slice(0, 4);
+  const days = source.years[yearKey];
+  if (!days) return [];
+  const day = days.find((d) => d.date === key);
+  return day ? day.eclipses.map((e) => flatten(e, lang)) : [];
+}
+function toDateKey(d, offsetMinutes) {
+  const shifted = new Date(d.getTime() + offsetMinutes * 6e4);
+  const y = shifted.getUTCFullYear();
+  const m = String(shifted.getUTCMonth() + 1).padStart(2, "0");
+  const day = String(shifted.getUTCDate()).padStart(2, "0");
+  return `${y}-${m}-${day}`;
+}
+
+exports.ECLIPSES_META = ECLIPSES_META;
+exports.ECLIPSES_YEAR_RANGE = ECLIPSES_YEAR_RANGE;
+exports.getEclipsesForDate = getEclipsesForDate;
+exports.getEclipsesForYear = getEclipsesForYear;

package/dist/calendar/eclipsesTable.d.cts

@@ -0,0 +1,40 @@
+import { g as EclipseTableMeta, E as EclipsesTableLanguage, a as EclipsesFile, d as EclipseTableEntry, c as EclipseTableDay } from '../eclipsesTableTypes-D-tSQMQd.cjs';
+export { b as EclipseSutak, e as EclipseTableEntryRaw, f as EclipseTableKind, h as EclipseTableSubtype, R as RawEclipseTableDay } from '../eclipsesTableTypes-D-tSQMQd.cjs';
+
+/** Metadata describing what the bundled table was generated from. */
+declare const ECLIPSES_META: EclipseTableMeta;
+/** Inclusive year range covered by the bundled table. */
+declare const ECLIPSES_YEAR_RANGE: {
+    readonly start: number;
+    readonly end: number;
+};
+/**
+ * Eclipse days for a Gregorian year, flattened to the requested locale.
+ *
+ * Returns `null` if `year` is outside the table's range, or an empty array if
+ * the year is in range but had no (visible) eclipses.
+ *
+ * @param year Gregorian year.
+ * @param lang `'en'` (default) or `'hi'`.
+ * @param source Table to read from. Defaults to the bundled Varanasi table;
+ *               pass a {@link buildEclipsesTable} result to read a
+ *               location-specific table you built and cached.
+ */
+declare function getEclipsesForYear(year: number, lang?: EclipsesTableLanguage, source?: EclipsesFile): EclipseTableDay[] | null;
+/**
+ * Eclipses on a specific date, flattened to the requested locale.
+ *
+ * Returns an empty array if the date has no eclipse or is outside the table's
+ * range. The date is matched against the eclipse peak's local date.
+ *
+ * @param date Either an ISO `YYYY-MM-DD` string (interpreted in the table's
+ *             reference timezone) or a `Date` (its local calendar date in the
+ *             table's reference timezone is used).
+ * @param lang `'en'` (default) or `'hi'`.
+ * @param source Table to read from. Defaults to the bundled Varanasi table;
+ *               pass a {@link buildEclipsesTable} result for a
+ *               location-specific table.
+ */
+declare function getEclipsesForDate(date: string | Date, lang?: EclipsesTableLanguage, source?: EclipsesFile): EclipseTableEntry[];
+
+export { ECLIPSES_META, ECLIPSES_YEAR_RANGE, EclipseTableDay, EclipseTableEntry, EclipseTableMeta, EclipsesFile, EclipsesTableLanguage, getEclipsesForDate, getEclipsesForYear };

package/dist/calendar/eclipsesTable.d.ts

@@ -0,0 +1,40 @@
+import { g as EclipseTableMeta, E as EclipsesTableLanguage, a as EclipsesFile, d as EclipseTableEntry, c as EclipseTableDay } from '../eclipsesTableTypes-D-tSQMQd.js';
+export { b as EclipseSutak, e as EclipseTableEntryRaw, f as EclipseTableKind, h as EclipseTableSubtype, R as RawEclipseTableDay } from '../eclipsesTableTypes-D-tSQMQd.js';
+
+/** Metadata describing what the bundled table was generated from. */
+declare const ECLIPSES_META: EclipseTableMeta;
+/** Inclusive year range covered by the bundled table. */
+declare const ECLIPSES_YEAR_RANGE: {
+    readonly start: number;
+    readonly end: number;
+};
+/**
+ * Eclipse days for a Gregorian year, flattened to the requested locale.
+ *
+ * Returns `null` if `year` is outside the table's range, or an empty array if
+ * the year is in range but had no (visible) eclipses.
+ *
+ * @param year Gregorian year.
+ * @param lang `'en'` (default) or `'hi'`.
+ * @param source Table to read from. Defaults to the bundled Varanasi table;
+ *               pass a {@link buildEclipsesTable} result to read a
+ *               location-specific table you built and cached.
+ */
+declare function getEclipsesForYear(year: number, lang?: EclipsesTableLanguage, source?: EclipsesFile): EclipseTableDay[] | null;
+/**
+ * Eclipses on a specific date, flattened to the requested locale.
+ *
+ * Returns an empty array if the date has no eclipse or is outside the table's
+ * range. The date is matched against the eclipse peak's local date.
+ *
+ * @param date Either an ISO `YYYY-MM-DD` string (interpreted in the table's
+ *             reference timezone) or a `Date` (its local calendar date in the
+ *             table's reference timezone is used).
+ * @param lang `'en'` (default) or `'hi'`.
+ * @param source Table to read from. Defaults to the bundled Varanasi table;
+ *               pass a {@link buildEclipsesTable} result for a
+ *               location-specific table.
+ */
+declare function getEclipsesForDate(date: string | Date, lang?: EclipsesTableLanguage, source?: EclipsesFile): EclipseTableEntry[];
+
+export { ECLIPSES_META, ECLIPSES_YEAR_RANGE, EclipseTableDay, EclipseTableEntry, EclipseTableMeta, EclipsesFile, EclipsesTableLanguage, getEclipsesForDate, getEclipsesForYear };