Calendar Conversion

panchang-ts · v5.0.0 · MIT

Gregorian ↔ Hindu date conversion, Kali Yuga year, region-aware Hindu New Year, and yearly Ekadashi / Sankranti / festival listings.

Gregorian ↔ Hindu

import {
  convertGregorianToHindu, convertHinduToGregorian,
  getKaliYugaYear, getHinduNewYear, computeSamvat,
} from 'panchang-ts';

// Gregorian → Hindu coords at sunrise
const h = convertGregorianToHindu(new Date('2026-04-15'), DELHI, { timezone: 330 });

// Hindu → Gregorian
const dates = convertHinduToGregorian(
  { vikramSamvat: 2083, masaIndex: 0, paksha: 'shukla', pakshaTithi: 9 },
  DELHI, { timezone: 330 },
);   // → Rama Navami in VS 2083

getKaliYugaYear(new Date('2026-04-01'));                       // 5127
getHinduNewYear(2026, 'tamil-nadu', DELHI, { timezone: 330 }); // Puthandu

convertHinduToGregorian returns an array of matching dates — a Hindu date can land on zero (kshaya) or two (adhika/vriddhi) civil days. HinduCalendarCoords and ConvertOptions are exported for typing your own call sites.

Yearly listings

import {
  computeEkadashiDatesForYear, computeSankrantisForYear,
  computeFestivalsForYear, computeFestivalsInRange,
} from 'panchang-ts';

computeEkadashiDatesForYear(2026, DELHI, { timezone: 330 });   // ~24 Date[]
computeSankrantisForYear(2026, DELHI, { timezone: 330 });      // 12 SankrantiEvent[]
computeFestivalsForYear(2026, DELHI, { timezone: 330 });       // FestivalDay[]
computeFestivalsInRange(start, end, DELHI, { timezone: 330 }); // arbitrary span

These run the engine with internal narrowing, so they are far cheaper than a daily loop: computeEkadashiDatesForYear reads only the tithi at sunrise (~18 ms/year), computeSankrantisForYear scans one solar longitude per day and bisects the 12 transits (~3.3 ms/year) — numbers and context in Performance.

Yearly eclipse listings (computeEclipsesForYear, getUpcomingEclipses) are covered in Eclipses & Moon Phases.

Samvat

Field	Meaning
`samvat.vikramSamvat`	Vikram Samvat year (e.g. 2081 during early 2025)
`samvat.shakaSamvat`	Shaka Samvat year (e.g. 1946)
`getKaliYugaYear(date)`	Kali Yuga year (e.g. 5127)

computeSamvat is the standalone helper behind calendar.samvat on the daily result — both use the same Chaitra-anchored year boundaries.