Calendar Conversion

panchang-ts · v5.1.1 · 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.

The solar regions do not share one day

Mesha Sankranti is a single instant, but the four traditions that anchor to it key their calendar day off that instant differently, so in the same year they can fall on three different dates. Passing the right region matters:

region         rule                                       2027    2028
tamil-nadu     the Sankranti observance day               Apr 14  Apr 14
punjab         the civil day containing the transit       Apr 14  Apr 13
kerala         first sunrise at or after the transit      Apr 15  Apr 14
west-bengal    the day AFTER the transit's civil day      Apr 15  Apr 14

// 2027 transit: Apr 14, 15:33 IST (afternoon)
// 2028 transit: Apr 13, 21:47 IST (after sunset)

The Sankranti observance day itself is DrikPanchang's rule: a transit during daylight keeps its own civil day, a transit between sunset and the next sunrise is observed on the next sunrise's day. The same per-region rules drive the puthandu, vishu, baisakhi and pohela_boishakh festival emissions, so the two surfaces always agree. Validated against DrikPanchang's per-region date pages for 2025–2029.

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.