panchanga 0.1.1

package/dist/eclipses.js

@@ -0,0 +1,132 @@
+/**
+ * src/eclipses.ts — grahaṇa (solar & lunar eclipses).
+ *
+ * Wraps astronomy-engine's eclipse search to enumerate the eclipses of a given
+ * year, with their contact timings, type, local visibility, and sūtak window.
+ *
+ * Conventions:
+ *  • A grahaṇa "counts" for a location only when it is VISIBLE there — a lunar
+ *    eclipse when the Moon is above the horizon during the umbral/penumbral
+ *    phase, a solar eclipse when the Sun is above the horizon and the disc is
+ *    obscured. Sūtak (the abstention period) applies only to a visible eclipse.
+ *  • Sūtak begins before first contact: 9 hours (3 prahara) for a Chandra
+ *    Grahaṇa, 12 hours (4 prahara) for a Sūrya Grahaṇa, and runs to mokṣa (last
+ *    contact). This is the widely-used Smārta convention.
+ *
+ * Timings are UTC instants. Lunar contact times are derived from the eclipse
+ * peak and astronomy-engine's semi-durations (sd_*, in minutes).
+ */
+import { SearchLunarEclipse, NextLunarEclipse, SearchGlobalSolarEclipse, NextGlobalSolarEclipse, SearchLocalSolarEclipse, Equator, Horizon, Observer, Body, MakeTime, } from "astronomy-engine";
+import { validateLocation } from "./time.js";
+const MIN_MS = 60_000;
+const HOUR_MS = 3_600_000;
+const iso = (d) => d.toISOString();
+const isoWin = (start, end) => ({ start: iso(start), end: iso(end) });
+/** Altitude (degrees) of `body` at instant `when` as seen from `loc`. */
+function altitude(body, when, loc) {
+    const t = MakeTime(when);
+    const obs = new Observer(loc.latitude, loc.longitude, loc.elevationMeters ?? 0);
+    const eq = Equator(body, t, obs, true, true);
+    return Horizon(t, obs, eq.ra, eq.dec, "normal").altitude;
+}
+/**
+ * True if the Moon is above the horizon at ANY of `samples` evenly-spaced
+ * instants across `[start, end]` (inclusive) as seen from `loc`. A lunar
+ * grahaṇa is reckoned visible when the Moon is up during the eclipse — sampling
+ * across the whole phase (not just greatest eclipse) catches a moonrise/moonset
+ * eclipse, where the Moon is below the horizon at peak yet the eclipse is in
+ * progress as it rises or sets.
+ */
+function moonUpDuring(start, end, loc, samples = 9) {
+    const a = new Date(start).getTime();
+    const b = new Date(end).getTime();
+    for (let i = 0; i < samples; i++) {
+        const when = new Date(a + ((b - a) * i) / (samples - 1));
+        if (altitude(Body.Moon, when, loc) > 0)
+            return true;
+    }
+    return false;
+}
+/** All lunar eclipses whose peak falls in calendar `year` (UTC). */
+export function lunarEclipses(year, loc) {
+    if (loc)
+        validateLocation(loc);
+    const out = [];
+    const yearStart = Date.UTC(year, 0, 1);
+    const yearEnd = Date.UTC(year + 1, 0, 1);
+    let e = SearchLunarEclipse(new Date(yearStart));
+    // Guard against an eclipse found just before the year boundary.
+    for (let i = 0; i < 30 && e.peak.date.getTime() < yearStart; i++)
+        e = NextLunarEclipse(e.peak);
+    for (let i = 0; i < 30 && e.peak.date.getTime() < yearEnd; i++) {
+        const peak = e.peak.date;
+        const span = (sdMin) => isoWin(new Date(peak.getTime() - sdMin * MIN_MS), new Date(peak.getTime() + sdMin * MIN_MS));
+        const penumbral = span(e.sd_penum);
+        const partial = e.sd_partial > 0 ? span(e.sd_partial) : null;
+        const total = e.sd_total > 0 ? span(e.sd_total) : null;
+        // Reckon visibility across the whole eclipse, not just greatest eclipse:
+        // the umbral (partial) window for an umbral eclipse, else the penumbral
+        // window. This way a moonrise/moonset eclipse — Moon below the horizon at
+        // peak but up during the umbral phase — is correctly counted as visible.
+        const reckonWindow = partial ?? penumbral;
+        const visible = loc ? moonUpDuring(reckonWindow.start, reckonWindow.end, loc) : null;
+        // Sūtak applies only to a grahaṇa with an UMBRAL phase. A purely penumbral
+        // (māndya / upacchāyā) lunar eclipse is not reckoned as a grahaṇa in the
+        // Smārta convention, so it carries no sūtak; and for umbral eclipses the
+        // window is reckoned from the umbral (partial) contacts, not the penumbral.
+        const sutak = visible && partial
+            ? isoWin(new Date(new Date(partial.start).getTime() - 9 * HOUR_MS), new Date(partial.end))
+            : null;
+        out.push({
+            kind: e.kind,
+            peak: iso(peak),
+            penumbral,
+            partial,
+            total,
+            visible,
+            sutak,
+        });
+        e = NextLunarEclipse(e.peak);
+    }
+    return out;
+}
+/** All solar eclipses whose greatest-eclipse instant falls in calendar `year`. */
+export function solarEclipses(year, loc) {
+    if (loc)
+        validateLocation(loc);
+    const out = [];
+    const yearStart = Date.UTC(year, 0, 1);
+    const yearEnd = Date.UTC(year + 1, 0, 1);
+    let e = SearchGlobalSolarEclipse(new Date(yearStart));
+    for (let i = 0; i < 30 && e.peak.date.getTime() < yearStart; i++)
+        e = NextGlobalSolarEclipse(e.peak);
+    for (let i = 0; i < 30 && e.peak.date.getTime() < yearEnd; i++) {
+        const peak = e.peak.date;
+        let local = null;
+        let visible = loc ? false : null;
+        let sutak = null;
+        if (loc) {
+            const obs = new Observer(loc.latitude, loc.longitude, loc.elevationMeters ?? 0);
+            // Search a local eclipse around the global peak; accept it only if it is
+            // the SAME event (its peak is within a day) and the Sun is up & obscured.
+            const lse = SearchLocalSolarEclipse(new Date(peak.getTime() - 24 * HOUR_MS), obs);
+            const within = Math.abs(lse.peak.time.date.getTime() - peak.getTime()) < 24 * HOUR_MS;
+            if (within && lse.partial_begin && lse.peak.altitude > 0 && lse.obscuration > 0) {
+                const partialStart = lse.partial_begin.time.date;
+                const partialEnd = lse.partial_end.time.date;
+                local = {
+                    partialStart: iso(partialStart),
+                    peak: iso(lse.peak.time.date),
+                    partialEnd: iso(partialEnd),
+                    obscuration: lse.obscuration,
+                };
+                visible = true;
+                sutak = isoWin(new Date(partialStart.getTime() - 12 * HOUR_MS), partialEnd);
+            }
+        }
+        out.push({ kind: e.kind, peak: iso(peak), local, visible, sutak });
+        e = NextGlobalSolarEclipse(e.peak);
+    }
+    return out;
+}
+//# sourceMappingURL=eclipses.js.map

package/dist/eclipses.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"eclipses.js","sourceRoot":"","sources":["../src/eclipses.ts"],"names":[],"mappings":"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"}

package/dist/elements.d.ts

@@ -0,0 +1,230 @@
+/**
+ * src/elements.ts — calendar-elements core: tithi, nakshatra, karaṇa/Bhadra,
+ * new moons, solar ingress (saṅkrānti), and amānta/pūrṇimānta lunar months.
+ *
+ * SOURCING (the two fiddly conventions are pinned to authorities, not guessed):
+ *
+ * • KARAṆA SEQUENCE — Wikipedia "Karaṇa (pañcāṅga)"
+ *   https://en.wikipedia.org/wiki/Karana_(pancanga)
+ *   A karaṇa is half a tithi: the span over which Moon−Sun elongation grows 6°.
+ *   A lunar month (0°…360° elongation) has 60 half-tithis, indexed h = 0..59:
+ *     h = 0                          → Kiṁstughna   (fixed)
+ *     h = 1..56                      → the 7 movable karaṇas cycling with
+ *                                      ((h−1) mod 7) over
+ *                                      [Bava, Bālava, Kaulava, Taitila, Gara,
+ *                                       Vaṇij, Viṣṭi]   (8 full cycles = 56)
+ *     h = 57 → Śakuni, 58 → Catuṣpāda, 59 → Nāga   (fixed)
+ *   Viṣṭi ≡ Bhadra. The Mukha/Pucchā subdivision + Vāsa is `bhadraSplit`;
+ *   `bhadraIntervals` returns the whole Viṣṭi span it operates on.
+ *
+ * • LUNAR-MONTH NAMING / ADHIKA / KṢAYA — Wikipedia "Hindu calendar" &
+ *   "Adhika-masa" (https://en.wikipedia.org/wiki/Adhika-masa,
+ *   https://en.wikipedia.org/wiki/Hindu_calendar), consistent with
+ *   drikpanchang's adhika-masa definition.
+ *   An amānta lunation (new moon → next new moon) is named after the rāśi the
+ *   Sun ENTERS (the saṅkrānti) DURING that lunation:
+ *     Mesha saṅkrānti → Chaitra, Vṛṣabha → Vaiśākha, Mithuna → Jyeṣṭha, …
+ *     i.e. month-name-index (0=Chaitra) = entered-rāśi-index (0=Mesha).
+ *   • A lunation with NO saṅkrānti is **adhika** (leap): it takes the name of
+ *     the FOLLOWING lunation's saṅkrānti, prefixed "Adhika"; the following
+ *     lunation is then "Nija/Śuddha".  (Algorithmically: an adhika lunation
+ *     inherits the next lunation's month name.)
+ *   • A lunation with TWO saṅkrāntis is **kṣaya** (lost month, ~1/140 yr).
+ *
+ * • PŪRṆIMĀNTA label — derived from the amānta result. A pūrṇimānta month runs
+ *   full-moon → full-moon, so its kṛṣṇa-pakṣa (waning) half belongs to the
+ *   amānta month one NAME EARLIER. Concretely: in the kṛṣṇa pakṣa the
+ *   pūrṇimānta name = next amānta name; in the śukla pakṣa they coincide.
+ *   Dates do not change — only the label.
+ *
+ * ASTRONOMY PRIMITIVES
+ *   • Elongation = geocentric Moon−Sun ecliptic-longitude difference in [0,360):
+ *     Astronomy.PairLongitude(Body.Moon, Body.Sun, date) (== MoonPhase(date)).
+ *   • Tithi / karaṇa / new-moon boundaries via Astronomy.SearchMoonPhase(target,
+ *     start, limitDays) — robust against intra-day non-monotonicity.
+ *   • Nakshatra & saṅkrānti use the SIDEREAL longitudes from ayanamsha.ts
+ *     (siderealLongitude / siderealSunRashi), kept consistent with Drik Panchang.
+ */
+import { type FlexibleDateTime } from "astronomy-engine";
+/** The 30 tithi names (1-based: index 0 = tithi 1 = Pratipadā). */
+export declare const TITHI_NAMES: readonly ["Pratipada", "Dvitiya", "Tritiya", "Chaturthi", "Panchami", "Shashthi", "Saptami", "Ashtami", "Navami", "Dashami", "Ekadashi", "Dvadashi", "Trayodashi", "Chaturdashi", "Purnima", "Pratipada", "Dvitiya", "Tritiya", "Chaturthi", "Panchami", "Shashthi", "Saptami", "Ashtami", "Navami", "Dashami", "Ekadashi", "Dvadashi", "Trayodashi", "Chaturdashi", "Amavasya"];
+/** The 27 nakshatra names (index 0 = Ashwini; Rohini = 3). */
+export declare const NAKSHATRA_NAMES: readonly ["Ashwini", "Bharani", "Krittika", "Rohini", "Mrigashira", "Ardra", "Punarvasu", "Pushya", "Ashlesha", "Magha", "Purva Phalguni", "Uttara Phalguni", "Hasta", "Chitra", "Swati", "Vishakha", "Anuradha", "Jyeshtha", "Mula", "Purva Ashadha", "Uttara Ashadha", "Shravana", "Dhanishta", "Shatabhisha", "Purva Bhadrapada", "Uttara Bhadrapada", "Revati"];
+/** The 7 movable (cara) karaṇas, in cyclic order. Viṣṭi (index 6) ≡ Bhadra. */
+export declare const MOVABLE_KARANAS: readonly ["Bava", "Balava", "Kaulava", "Taitila", "Gara", "Vanij", "Vishti"];
+/** Karaṇa name for a half-tithi index h ∈ 0..59 (see file header for sourcing). */
+export declare function karanaName(h: number): string;
+/**
+ * The 12 amānta lunar-month names, indexed by the rāśi the Sun enters:
+ * index 0 = Mesha → Chaitra, … index 11 = Mīna → Phalguna.
+ */
+export declare const LUNAR_MONTH_NAMES: readonly ["Chaitra", "Vaishakha", "Jyeshtha", "Ashadha", "Shravana", "Bhadrapada", "Ashwina", "Kartika", "Margashirsha", "Pausha", "Magha", "Phalguna"];
+/**
+ * Geocentric Moon−Sun ecliptic-longitude elongation in [0,360).
+ * 0 = new moon (conjunction), 180 = full moon.
+ */
+export declare function elongation(date: FlexibleDateTime): number;
+/**
+ * Tithi number 1..30 containing `date`.
+ * Tithi n spans elongation [(n−1)·12°, n·12°). 1 = Śukla Pratipadā … 30 = Amāvāsyā.
+ */
+export declare function tithiAt(date: FlexibleDateTime): number;
+export interface TithiBoundaries {
+    /** Tithi number 1..30. */
+    number: number;
+    /** UTC instant the tithi begins (elongation = (n−1)·12°). */
+    start: Date;
+    /** UTC instant the tithi ends (elongation = n·12°). */
+    end: Date;
+}
+/**
+ * Boundaries of the tithi containing `around`.
+ *
+ * Tithi n occupies elongation [(n−1)·12°, n·12°). We locate the start by
+ * searching backward for the (n−1)·12° phase and the end by searching forward
+ * for the n·12° phase (mod 360). The new-moon wrap is handled because phase
+ * 0° ≡ 360°: tithi 30 ends at phase 0 (the next new moon) and tithi 1 starts
+ * at phase 0 (the same new moon), so the SearchMoonPhase target is taken mod
+ * 360 and the wrap is seamless.
+ */
+export declare function tithiBoundaries(around: FlexibleDateTime): TithiBoundaries;
+/**
+ * Nakshatra index 0..26 of the Moon at `date` (0 = Ashwini; Rohini = 3).
+ * Each nakshatra spans 360/27 = 13°20′ of the Moon's sidereal longitude.
+ */
+export declare function nakshatraAt(date: FlexibleDateTime): number;
+export interface NakshatraBoundaries {
+    /** Nakshatra index 0..26 (0 = Ashwini). */
+    index: number;
+    /** UTC instant the Moon enters this nakshatra. */
+    start: Date;
+    /** UTC instant the Moon leaves this nakshatra. */
+    end: Date;
+}
+/**
+ * Boundaries of the nakshatra the Moon occupies at `around`.
+ *
+ * The Moon's sidereal longitude advances ~13.2°/day and is monotonic within a
+ * nakshatra, so each 13°20′ boundary is a clean single crossing. We bracket
+ * the start-edge by stepping back ~1.5 days and the end-edge forward ~1.5 days
+ * (a nakshatra lasts ~24 h) and bisect each crossing.
+ */
+export declare function nakshatraBoundaries(around: FlexibleDateTime): NakshatraBoundaries;
+/** The 27 nitya-yoga names (index 0 = Vishkambha … 26 = Vaidhriti). */
+export declare const YOGA_NAMES: readonly ["Vishkambha", "Priti", "Ayushman", "Saubhagya", "Shobhana", "Atiganda", "Sukarman", "Dhriti", "Shula", "Ganda", "Vriddhi", "Dhruva", "Vyaghata", "Harshana", "Vajra", "Siddhi", "Vyatipata", "Variyan", "Parigha", "Shiva", "Siddha", "Sadhya", "Shubha", "Shukla", "Brahma", "Indra", "Vaidhriti"];
+/**
+ * Yoga index 0..26 at `date` (0 = Vishkambha; 26 = Vaidhriti).
+ * Each nitya-yoga spans 360/27 = 13°20′ of (Sun + Moon) sidereal longitude.
+ */
+export declare function yogaAt(date: FlexibleDateTime): number;
+export interface YogaBoundaries {
+    /** Yoga index 0..26 (0 = Vishkambha). */
+    index: number;
+    /** UTC instant this yoga begins. */
+    start: Date;
+    /** UTC instant this yoga ends. */
+    end: Date;
+}
+/**
+ * Boundaries of the yoga at `around`. The (Sun+Moon) sidereal sum advances
+ * monotonically (~14.2°/day), so a yoga lasts ~22–25 h; ±2 days brackets the
+ * adjacent boundaries safely and we bisect each crossing (the 360°→0° wrap for
+ * Vaidhriti→Vishkambha is handled by `bisectLongitudeCrossing`, exactly as for
+ * the Revati→Ashwini nakshatra wrap).
+ */
+export declare function yogaBoundaries(around: FlexibleDateTime): YogaBoundaries;
+/**
+ * Half-tithi index h ∈ 0..59 at `date` (h = floor(elongation/6°)), i.e. the
+ * karaṇa slot within the current lunation.
+ */
+export declare function karanaIndexAt(date: FlexibleDateTime): number;
+/** Karaṇa name at `date` (see karanaName / file header for the sequence). */
+export declare function karanaAt(date: FlexibleDateTime): string;
+export interface KaranaBoundaries {
+    /** Half-tithi index 0..59 within the lunation. */
+    index: number;
+    /** Karaṇa name (Bava … Naga). */
+    name: string;
+    /** UTC instant this karaṇa begins (elongation = h·6°). */
+    start: Date;
+    /** UTC instant this karaṇa ends (elongation = (h+1)·6°). */
+    end: Date;
+}
+/**
+ * Boundaries of the karaṇa (half-tithi) containing `around`. Mirrors
+ * `tithiBoundaries` on a 6° grid: a karaṇa spans elongation [h·6°, (h+1)·6°),
+ * so we locate the start at h·6° (backward) and the end at (h+1)·6° (forward).
+ * The new-moon wrap (h=59 ends at phase 0°) is seamless because the target is
+ * taken mod 360.
+ */
+export declare function karanaBoundaries(around: FlexibleDateTime): KaranaBoundaries;
+export interface KaranaInterval {
+    start: Date;
+    end: Date;
+}
+/**
+ * Viṣṭi (Bhadra) karaṇa interval(s) near `around`.
+ *
+ * Viṣṭi is the 7th movable karaṇa, so it falls at half-tithi indices h where
+ * ((h−1) mod 7) === 6 and h ∈ 1..56, i.e. h ∈ {7, 14, 21, 28, 35, 42, 49, 56}.
+ * Each such karaṇa is the elongation span [h·6°, (h+1)·6°). Within a lunar
+ * month Bhadra therefore occurs once per pakṣa-ish (8 times across a lunation).
+ *
+ * This scans a window of ±SYNODIC_MONTH_DAYS around `around`, locates every
+ * Viṣṭi slot via SearchMoonPhase on the 6° multiples, and returns each
+ * {start,end} (UTC) that overlaps the window. Adjacent to a date this yields
+ * the Bhadra window(s) on/near that date.
+ *
+ * NOTE: this returns the whole Viṣṭi karaṇa span. The Mukha/Pucchā "face/tail"
+ * subdivision and the Vāsa (loka) used for Holikā Dahan muhūrta are computed by
+ * `bhadraSplit`, which takes one of these intervals.
+ */
+export declare function bhadraIntervals(around: FlexibleDateTime): KaranaInterval[];
+/** Where Bhadra resides — its loka, from the Moon's rāśi during Bhadra. */
+export type BhadraVasa = "svarga" | "prithvi" | "patala";
+export interface BhadraDetails {
+    /** Loka: svarga (heaven), prithvi (earth/bhūmi, the harmful one), patala. */
+    vasa: BhadraVasa;
+    /**
+     * The Moon's sidereal rāśi (0 = Mesha … 11 = Mīna) during Bhadra, sampled at
+     * the interval MIDPOINT. The vāsa is reckoned from the rāśi the Moon occupies
+     * *during* Bhadra; the midpoint is the representative instant (an endpoint can
+     * fall on the wrong side of a rāśi change that occurs within the span).
+     */
+    moonRashi: number;
+    /** Bhadra Mukha — inauspicious leading 1/6 (5 ghaṭī of a 30-ghaṭī karaṇa). */
+    mukha: KaranaInterval;
+    /** Bhadra Pucchā — auspicious trailing 1/10 (3 ghaṭī of a 30-ghaṭī karaṇa). */
+    puccha: KaranaInterval;
+}
+/**
+ * Split a Bhadra (Viṣṭi karaṇa) `interval` into its Mukha (face) and Pucchā
+ * (tail) sub-windows and resolve its Vāsa from the Moon's rāśi at Bhadra's
+ * start. See the sourcing note above. PURE w.r.t. its argument + ephemeris.
+ */
+export declare function bhadraSplit(interval: KaranaInterval): BhadraDetails;
+export declare function newMoons(year: number): Date[];
+export declare function solarIngress(year: number, rashi: number): Date;
+export type MonthSystem = "amanta" | "purnimanta";
+export interface LunarMonth {
+    /** Month name index 0..11 (0 = Chaitra). The label for the chosen system. */
+    month: number;
+    /** Month name (label for `system`). */
+    monthName: string;
+    /** "shukla" (waxing) or "krishna" (waning). */
+    paksha: "shukla" | "krishna";
+    /** True if this lunation is an adhika (leap) month. */
+    adhika: boolean;
+    /** True if this lunation is a kṣaya (lost) month (two saṅkrāntis). */
+    kshaya: boolean;
+    /** Amānta month name index 0..11 (independent of the chosen system). */
+    amantaMonth: number;
+    /** Amānta label (with "Adhika"/"Nija" prefix where applicable). */
+    amantaLabel: string;
+    /** Pūrṇimānta label (with prefix where applicable). */
+    purnimantaLabel: string;
+}
+export declare function lunarMonth(at: FlexibleDateTime, options?: {
+    system?: MonthSystem;
+}): LunarMonth;
+//# sourceMappingURL=elements.d.ts.map

package/dist/elements.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"elements.d.ts","sourceRoot":"","sources":["../src/elements.ts"],"names":[],"mappings":"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"}