panchang-ts 0.7.0 → 1.0.0

package/README.md

@@ -163,7 +163,7 @@ Rahu Kalam, Gulika Kalam, Yamaganda, Panchaka detection.
 Amrit Siddhi, Sarvartha Siddhi, Ravi Pushya, Guru Pushya yoga detection. 24 major pan-Indian festivals, recurring Ekadashi & Pradosha Vrata, Sankranti — Adhika months auto-skipped.
 
 ### Jyotish (Vedic Astrology)
-All 9 graha positions (geocentric, sidereal) with rashi, nakshatra, pada, and retrograde status. Vimshottari Dasha with Antardasha breakdown.
+All 9 graha positions (geocentric, sidereal) with rashi, nakshatra, pada, and retrograde status. Vimshottari Dasha with Antardasha breakdown — from a birth moment alone or from an explicit Moon longitude. Chandra Balam (transit-Moon favorability relative to janma rashi).
 
 ### Astronomy
 Sunrise, Sunset, Moonrise, Moonset, Chandra Rashi (Moon sign), Surya Nakshatra.
@@ -310,7 +310,9 @@ import {
   computeAbhijitMuhurta, computeBrahmaMuhurta,
   computeGowriPanchangam,
   // Jyotish
-  computePlanetaryPositions, computeVimshottariDasha,
+  computePlanetaryPositions,
+  computeVimshottariDasha, computeVimshottariDashaFromBirth,
+  computeChandraBalam,
   GRAHA_ABBR,
 } from 'panchang-ts';
 
@@ -342,17 +344,27 @@ const brahma  = computeBrahmaMuhurta(sunrise, sunset);     // { start, end }
 **Jyotish (Vedic Astrology):**
 
 ```typescript
-// All 9 graha positions (sidereal)
+// All 9 graha positions (sidereal — Rahu/Ketu use mean node)
 const grahas = computePlanetaryPositions(birthDate, 'lahiri');
 console.log(grahas.jupiter.rashi.name);   // "Dhanu"
 console.log(grahas.saturn.isRetrograde);  // true/false
 console.log(GRAHA_ABBR['Jupiter']);       // "Ju"
 
-// Vimshottari Dasha — pass birth date and Moon's sidereal longitude
-const moonLon = getSiderealMoonLongitude(birthDate, 'lahiri');
-const dasha = computeVimshottariDasha(birthDate, moonLon);
+// Vimshottari Dasha — convenience form: birth date only (Moon longitude derived)
+const dasha = computeVimshottariDashaFromBirth(birthDate, 'lahiri');
 console.log(dasha.currentMahaDashaLord);                   // "Rahu"
 console.log(dasha.mahaDashas[0]!.antarDashas[0]!.lord);    // "Rahu"
+
+// Or pass an explicit Moon sidereal longitude (useful when you already have one)
+const moonLon = getSiderealMoonLongitude(birthDate, 'lahiri');
+const dasha2  = computeVimshottariDasha(birthDate, moonLon);
+
+// Chandra Balam — transit Moon's favorability vs. janma rashi
+// janmaRashi and transitMoonRashi are 0-indexed (0 = Mesha ... 11 = Meena)
+const cb = computeChandraBalam(3 /* Karka */, 6 /* Tula */);
+console.log(cb.house);        // 4
+console.log(cb.quality);      // "weak"
+console.log(cb.englishName);  // "Ashubha"
 ```
 
 ---
@@ -559,6 +571,13 @@ interface VimshottariDashaResult {
   currentIndex: number;
   mahaDashas: MahaDasha[];  // 9-entry sequence starting from birth
 }
+
+interface ChandraBalamInfo {
+  house: number;                       // 1 = janma rashi; 12 = rashi before janma
+  quality: 'strong' | 'weak';          // Shubha houses = 1,3,6,7,10,11
+  englishName: string;                 // "Shubha" | "Ashubha"
+  name: string;                        // localized
+}
 ```
 </details>
 
@@ -594,16 +613,42 @@ InteractionManager.runAfterInteractions(() => {
 
 ## Accuracy
 
-Validated against [DrikPanchang.com](https://www.drikpanchang.com) for 19+ date/city combinations across India and New York.
-
-| Element | Accuracy |
-|---------|----------|
-| Sunrise / Sunset | ±2 minutes |
-| Moonrise / Moonset | ±2 minutes |
-| Tithi, Nakshatra, Yoga, Karana names | Exact match |
-| Element end-times | ±5 minutes |
-| Ayanamsa | ±0.005° vs Swiss Ephemeris |
-| Choghadiya / Hora / Gowri slots | Derived from sunrise/sunset — inherits ±2 min |
+4,864 tests passing, including Drik-verified fixtures against
+[DrikPanchang.com](https://www.drikpanchang.com) spanning 2025–2026 across
+Delhi, Chennai, and New York.
+
+| Element | Accuracy | Validation |
+|---------|----------|------------|
+| Sunrise / Sunset | **≤29 s observed vs Drik minute-midpoint** (±45 s tolerance) | 16 assertions |
+| Moonrise / Moonset | ±2 min vs Drik | Strict fixtures |
+| Tithi, Nakshatra, Yoga, Karana names | Exact match vs Drik | Strict fixtures |
+| Tithi / Nakshatra / Yoga / Karana end-times | **±3 min tolerance, max 2.01 min observed** | 20 assertions |
+| Ayanamsa | ±0.005° vs Swiss Ephemeris | Unit tests |
+| Planetary positions (Sun–Saturn) | **±0.02° vs Drik sidereal** | Drik fixtures |
+| Planetary positions (Rahu/Ketu, mean node) | ≤0.5° typical; ±2° tolerance to absorb mean-vs-true drift | Drik fixtures |
+| Rashi / Nakshatra / Retrograde flag | Exact match vs Drik | Drik fixtures |
+| Festival dates | 12 Drik-verified festivals (2025–2026) — see caveats below | Drik fixtures |
+| Choghadiya / Hora / Gowri slots | Derived from sunrise/sunset — inherits ±2 min | — |
+
+### Festival Detection — Documented Tradeoff
+
+Library uses **tithi-at-sunrise** to resolve a festival to a calendar day.
+DrikPanchang applies several other traditional rules depending on the
+festival; where those rules pick a different day, our output can drift
+±1 day vs Drik. This is a rule-choice tradeoff, not a computation bug —
+it is documented and deliberately surfaced rather than hidden.
+
+| Resolution rule Drik uses | Festivals affected |
+|---------------------------|--------------------|
+| Tithi-at-midnight | Krishna Janmashtami, Maha Shivaratri, Diwali / Lakshmi Puja |
+| Madhyahna-vyapini (tithi overlapping noon) | Ganesh Chaturthi on edge years, Akshaya Tritiya 2026 |
+| Kshaya-tithi handling (tithi never at sunrise) | Ugadi 2026-03-19 (Pratipad is Kshaya) |
+
+If exact Drik parity matters for your use case, cross-check the above
+festival set against the Drik site for the target year. Everything else
+— Holi, Ugadi (non-Kshaya years), Rama Navami, Raksha Bandhan, Ganesh
+Chaturthi (normal years), Navaratri, Dussehra, Karva Chauth, Hanuman
+Jayanti — matches Drik's canonical date across 2025 and 2026 fixtures.
 
 ---
 

package/dist/index.cjs

@@ -3262,28 +3262,6 @@ function computeFestivals(tithiIndex, _nakshatraIndex, chandraMasaIndex, isAdhik
   return results;
 }
 
-// src/astronomy/moonrise.ts
-function getMoonrise(searchFromUtc, location, limitDays = 2) {
-  const observer = new Observer(
-    location.latitude,
-    location.longitude,
-    location.elevation ?? 0
-  );
-  const astroTime = MakeTime(searchFromUtc);
-  const result = SearchRiseSet(Body.Moon, observer, 1, astroTime, limitDays);
-  return result ? result.date : null;
-}
-function getMoonset(searchFromUtc, location, limitDays = 2) {
-  const observer = new Observer(
-    location.latitude,
-    location.longitude,
-    location.elevation ?? 0
-  );
-  const astroTime = MakeTime(searchFromUtc);
-  const result = SearchRiseSet(Body.Moon, observer, -1, astroTime, limitDays);
-  return result ? result.date : null;
-}
-
 // src/i18n/en.ts
 var en = {
   tithiNames: [
@@ -3412,6 +3390,7 @@ var en = {
     ravi_pushya: "Ravi Pushya Yoga",
     guru_pushya: "Guru Pushya Yoga"
   },
+  chandraBalamNames: { shubha: "Shubha", ashubha: "Ashubha" },
   festivalNames: {
     ugadi: "Ugadi",
     rama_navami: "Rama Navami",
@@ -3576,6 +3555,7 @@ var sa = {
     ravi_pushya: "\u0930\u0935\u093F \u092A\u0941\u0937\u094D\u092F \u092F\u094B\u0917",
     guru_pushya: "\u0917\u0941\u0930\u0941 \u092A\u0941\u0937\u094D\u092F \u092F\u094B\u0917"
   },
+  chandraBalamNames: { shubha: "\u0936\u0941\u092D", ashubha: "\u0905\u0936\u0941\u092D" },
   festivalNames: {
     ugadi: "\u092F\u0941\u0917\u093E\u0926\u093F",
     rama_navami: "\u0930\u093E\u092E \u0928\u0935\u092E\u0940",
@@ -3740,6 +3720,7 @@ var hi = {
     ravi_pushya: "\u0930\u0935\u093F \u092A\u0941\u0937\u094D\u092F \u092F\u094B\u0917",
     guru_pushya: "\u0917\u0941\u0930\u0941 \u092A\u0941\u0937\u094D\u092F \u092F\u094B\u0917"
   },
+  chandraBalamNames: { shubha: "\u0936\u0941\u092D", ashubha: "\u0905\u0936\u0941\u092D" },
   festivalNames: {
     ugadi: "\u0909\u0917\u093E\u0926\u0940",
     rama_navami: "\u0930\u093E\u092E \u0928\u0935\u092E\u0940",
@@ -3814,6 +3795,45 @@ function resolveChandraMasaName(index, lang, adhika = false) {
   return adhika ? `${t.misc.adhika} ${name}` : name;
 }
 
+// src/jyotish/chandraBalam.ts
+var STRONG_HOUSES = /* @__PURE__ */ new Set([1, 3, 6, 7, 10, 11]);
+function computeChandraBalam(janmaRashiIndex, transitMoonRashiIndex, lang = "en") {
+  if (!Number.isInteger(janmaRashiIndex) || janmaRashiIndex < 0 || janmaRashiIndex > 11) {
+    throw new RangeError(`janmaRashiIndex must be integer in [0, 11], got ${janmaRashiIndex}`);
+  }
+  if (!Number.isInteger(transitMoonRashiIndex) || transitMoonRashiIndex < 0 || transitMoonRashiIndex > 11) {
+    throw new RangeError(`transitMoonRashiIndex must be integer in [0, 11], got ${transitMoonRashiIndex}`);
+  }
+  const house = (transitMoonRashiIndex - janmaRashiIndex + 12) % 12 + 1;
+  const quality = STRONG_HOUSES.has(house) ? "strong" : "weak";
+  const englishName = quality === "strong" ? "Shubha" : "Ashubha";
+  const t = getTranslations(lang);
+  const name = quality === "strong" ? t.chandraBalamNames.shubha : t.chandraBalamNames.ashubha;
+  return { house, quality, englishName, name };
+}
+
+// src/astronomy/moonrise.ts
+function getMoonrise(searchFromUtc, location, limitDays = 2) {
+  const observer = new Observer(
+    location.latitude,
+    location.longitude,
+    location.elevation ?? 0
+  );
+  const astroTime = MakeTime(searchFromUtc);
+  const result = SearchRiseSet(Body.Moon, observer, 1, astroTime, limitDays);
+  return result ? result.date : null;
+}
+function getMoonset(searchFromUtc, location, limitDays = 2) {
+  const observer = new Observer(
+    location.latitude,
+    location.longitude,
+    location.elevation ?? 0
+  );
+  const astroTime = MakeTime(searchFromUtc);
+  const result = SearchRiseSet(Body.Moon, observer, -1, astroTime, limitDays);
+  return result ? result.date : null;
+}
+
 // src/core/panchang.ts
 function getInstantPanchang(date, location, options) {
   validateDate(date);
@@ -3917,6 +3937,7 @@ function getInstantPanchang(date, location, options) {
     (key) => t.festivalNames[key] ?? t.misc[key] ?? key,
     (idx) => resolveMasaName(idx, lang)
   );
+  const chandraBalam = options?.janmaRashi !== void 0 ? computeChandraBalam(options.janmaRashi, chandraRashi.index, lang) : void 0;
   return {
     timestamp: date,
     location,
@@ -3934,7 +3955,8 @@ function getInstantPanchang(date, location, options) {
     suryaNakshatra,
     panchaka: computePanchaka(siderealMoon),
     specialYogas,
-    festivals
+    festivals,
+    ...chandraBalam !== void 0 ? { chandraBalam } : {}
   };
 }
 function getDailyPanchang(date, location, options) {
@@ -4136,6 +4158,7 @@ function getDailyPanchang(date, location, options) {
     k.endTime = toLocalOrNull(k.endTime);
     k.startTime = toLocalOrNull(k.startTime);
   }
+  const chandraBalam = options.janmaRashi !== void 0 ? computeChandraBalam(options.janmaRashi, chandraRashi.index, lang) : void 0;
   return {
     date,
     location,
@@ -4180,7 +4203,8 @@ function getDailyPanchang(date, location, options) {
     gowriPanchangam: {
       day: gowriPanchangam.day.map((s) => ({ ...s, ...convertTimePeriod(s) })),
       night: gowriPanchangam.night.map((s) => ({ ...s, ...convertTimePeriod(s) }))
-    }
+    },
+    ...chandraBalam !== void 0 ? { chandraBalam } : {}
   };
 }
 
@@ -4209,15 +4233,11 @@ function isRetrograde(body, date) {
   if (delta < -180) delta += 360;
   return delta < 0;
 }
-function getTrueRahuLongitudeTropical(date) {
+function getMeanRahuLongitudeTropical(date) {
   const T = (dateToJulianDay(date) - 2451545) / 36525;
-  const omega = 125.04455501 - 1934.13626197 * T + 207765e-8 * T * T;
-  const F = normalize360(
-    93.27191028 + 483202.0175233 * T - 36825e-7 * T * T + 3083e-9 * T * T * T
+  return normalize360(
+    125.0445479 - 1934.1362891 * T + 20754e-7 * T * T + T * T * T / 467441 - T * T * T * T / 60616e3
   );
-  const F_rad = F * Math.PI / 180;
-  const correction = -1.4979 * Math.sin(2 * F_rad) - 0.15 * Math.sin(0 * F_rad + Math.PI * 2 * (357.5 / 360)) - 0.1226 * Math.sin(2 * (omega * Math.PI / 180)) + 0.1176 * Math.sin(2 * F_rad - 2 * (omega * Math.PI / 180));
-  return normalize360(omega + correction / 60);
 }
 function buildGrahaPosition(planet, siderealLon, isRetro, nakshatraNameFn, rashiNameFn) {
   const rashiIndex = Math.floor(siderealLon / 30);
@@ -4243,7 +4263,7 @@ function computePlanetaryPositions(date, ayanamsaType, nakshatraName = identity,
   const jupTrop = getTropicalPlanetLongitude(Body.Jupiter, date);
   const venTrop = getTropicalPlanetLongitude(Body.Venus, date);
   const satTrop = getTropicalPlanetLongitude(Body.Saturn, date);
-  const rahuTrop = getTrueRahuLongitudeTropical(date);
+  const rahuTrop = getMeanRahuLongitudeTropical(date);
   const ketuTrop = normalize360(rahuTrop + 180);
   const marsRetro = isRetrograde(Body.Mars, date);
   const mercRetro = isRetrograde(Body.Mercury, date);
@@ -4349,6 +4369,10 @@ function computeVimshottariDasha(birthDate, moonSiderealLon) {
     mahaDashas
   };
 }
+function computeVimshottariDashaFromBirth(birthDate, ayanamsaType = "lahiri") {
+  const moonSid = getSiderealMoonLongitude(birthDate, ayanamsaType);
+  return computeVimshottariDasha(birthDate, moonSid);
+}
 function buildAntarDashas(mahaLord, mahaStart, mahaDurationMs) {
   const mahaIdx = DASHA_ORDER.indexOf(mahaLord);
   const antarDashas = [];
@@ -4407,11 +4431,13 @@ exports.GRAHA_ABBR = GRAHA_ABBR;
 exports.PanchangError = PanchangError;
 exports.computeAbhijitMuhurta = computeAbhijitMuhurta;
 exports.computeBrahmaMuhurta = computeBrahmaMuhurta;
+exports.computeChandraBalam = computeChandraBalam;
 exports.computeGowriPanchangam = computeGowriPanchangam;
 exports.computeGulikaKalam = computeGulikaKalam;
 exports.computePlanetaryPositions = computePlanetaryPositions;
 exports.computeRahuKalam = computeRahuKalam;
 exports.computeVimshottariDasha = computeVimshottariDasha;
+exports.computeVimshottariDashaFromBirth = computeVimshottariDashaFromBirth;
 exports.computeYamaganda = computeYamaganda;
 exports.getAyanamsa = computeAyanamsa;
 exports.getDailyPanchang = getDailyPanchang;