Upgrading 5.3 → 5.4

This page covers the npm package and the Go module. They move together: the Go module carries every change below with the same instants, days, festivals and labels.

Nothing breaks at compile time. 5.4.0 removes, renames and retypes no exports, and no signature changes. One export and two festival keys are added, and the Go module adds a few more calls (listed under Go, below). What changes is output. Festival days follow the reference almanac's day rules, holi moves to the day after the new holika_dahan, the Yoni koota scores on a corrected table, Brahma Muhurta gets a new window, day-valued dates west of UTC stop reading a day early, and a long list of edge cases in the daily panchang and the Jyotish layer now return the right value.

So there is no type diff to walk, and the compiler will flag none of this. Most of what follows is a stored-value problem: re-run anything you cached, and re-pin anything you snapshotted. The exception is input that 5.3 accepted and 5.4 now rejects with an error: a two-digit year (see Listings and the calendar), an Invalid Date, a fractional UTC offset and the other cases under Input validation.

Festival days follow the reference almanac

Every festival rule below was checked against published dates: the reference almanac first, then other almanacs, with the classical rule (Nirnaya Sindhu, Dharma Sindhu) as the tie-breaker. The dates relied on are pinned in the library's test data. Before, most once-a-year festivals were listed on two consecutive days in some years. Now, over five cities and 1900 to 2100, no once-a-year festival is listed twice in a year, and each monthly one fires at most once per paksha or month. The one exception is phagli, whose rule is deferred (below). A few years still list a festival on no day, as 5.3 did. At Delhi these are Krishna Janmashtami in 1963 and 2088, and Maha Shivaratri and Vasant Panchami in 1983.

The kala windows are the reference's. Madhyahna is the third fifth of the daytime and aparahna the fourth. Pradosha runs from sunset to sunset plus a fifth of the night. Nishita is the 8th of the 15 night muhurtas. The day whose window the tithi covers most decides Ganesh and Vinayaka Chaturthi (madhyahna), Dhanteras, Diwali and Parashurama Jayanti (pradosha) and Govardhan Puja (the whole daytime), the earlier day winning a tie or when both days' windows are full. Masik and Maha Shivaratri follow the reference's nishita ladder, and Dussehra its aparahna ladder with the Shravana rule. Rama Navami (madhyahna), Bhai Dooj and Vat Savitri Amavasya (aparahna) take the last day whose window the tithi touches. Narak Chaturdashi takes the first day whose arunodaya it touches, and Vasant Panchami the first day on which Panchami has begun by two fifths of the daytime.

Three of the four festivals that 5.2 left keyed on sunrise now have anchors of their own: holi (below), narak_chaturdashi at arunodaya, and chhath_usha_arghya one day after the Shashthi day. Only phagli still takes every day whose sunrise holds Purnima: two days in 2033 at Delhi, and none in 2018. That rule is deferred for lack of a reference capture, together with a Pradosh fallback (a paksha whose Trayodashi touches no pradosha window has no Pradosh) and the Guru Purnima short-udaya refinement.

The net effect on one listing: computeFestivalsForYear(2026, delhi, { timezone: 330 }) returns 253 entries, against 260 on 5.3.0.

Two new festival keys

Both are type 'major'. FestivalInfo.key is typed string, so these are new values, not new type members. No key is removed or renamed. Tables you build with buildFestivalsTable pick up holika_dahan, and karthigai_deepam when built for all or tamil-nadu.

karthigai_deepam takes over a Masik Karthigai day. On that day, regions all and tamil-nadu list karthigai_deepam in place of masik_karthigai, and every other region still lists masik_karthigai. At Chennai on 4 December 2025, region 'tamil-nadu' gives karthigai_deepam and region 'kerala' gives masik_karthigai. So a table built for 'all' and filtered by region afterwards loses that month's Masik Karthigai outside Tamil Nadu. Build one table per region if you filter.

Holi is now the day after Holika Dahan

holi keeps its key and its name, but it now means Rangwali Holi, the day of colours. It is always the civil day after holika_dahan, which is how the reference publishes it. In 5.3 holi was the Purnima sunrise day: both days when Purnima held two sunrises, and none when it held no sunrise.

computeFestivalsForYear(2026, delhi, { timezone: 330 })
- 2026-03-03  holi
+ 2026-03-03  holika_dahan
+ 2026-03-04  holi

In a year when Purnima holds the Rangwali sunrise, holi keeps its date: in 2025 holika_dahan is 13 March and holi is 14 March, as before. In 2018, a kshaya Purnima year, 5.3 had no holi at all. 5.4 gives holika_dahan on 1 March and holi on 2 March.

If you read the Purnima evening, the bonfire, from holi, read it from holika_dahan now. No other key's date is tied to holi, and phagli is unchanged.

Yoni koota and Pathu Porutham Yoni

computeAshtakoot now scores the Yoni koota on the published five-level table. The old table had four levels (4, 2, 1 and 0), never awarded 3, and matched no published chakra. The new one is the Yoni chakra of Mahidhar Sharma's tika on Muhurta Chintamani, as carried by Frawley and by PyJHora, the Python port of Jagannatha Hora. Muhurta Chintamani itself fixes only the seven enemy pairs.

computeAshtakoot({ rashi: 0, nakshatra: 0 }, { rashi: 1, nakshatra: 3 })   // Ashwini boy, Rohini girl
- Yoni 1 'horse ↔ snake', totalScore 21.5
+ Yoni 3 'horse ↔ snake', totalScore 23.5

  computeAshtakoot({ rashi: 0, nakshatra: 0 }, { rashi: 6, nakshatra: 15 })  // Ashwini boy, Vishakha girl
- Yoni 2 'horse ↔ tiger', totalScore 23.5
+ Yoni 1 'horse ↔ tiger', totalScore 22.5

The nakshatra-to-animal map, the Yoni maximum of 4, the total of 36 and the other seven koots are unchanged, and ganaCancellation moves by the same amount. Over all 1,296 valid pairs of natal Moons, 550 change their total: 372 lose a point, 166 gain one and 12 gain two. 27 of them cross the 18-point line.

Pathu Porutham Yoni is the enemy-pair test

The Yoni porutham in computePathuPorutham is now the Tamil pass/fail test. It fails, with veto: true, only on the seven enemy pairs above, and it no longer reads the Ashtakoot score. In 5.3 it passed on an Ashtakoot Yoni score of 2 or more, so every 1-point pair failed.

computePathuPorutham(ashwiniBoy, rohiniGirl)   // the Yoni entry of poruthams
- { name: 'Yoni', passes: false, description: 'horse ↔ snake (Ashtakoot Yoni score 1/4)' }
+ { name: 'Yoni', passes: true,  description: 'horse ↔ snake, not enemies' }

  computePathuPorutham(anuradhaBoy, mulaGirl)
- { name: 'Yoni', passes: false, description: 'deer ↔ dog (Ashtakoot Yoni score 0/4)', veto: true }
+ { name: 'Yoni', passes: false, description: 'deer ↔ dog, enemies', veto: true }

The description is now <boy> ↔ <girl>, not enemies or <boy> ↔ <girl>, enemies, so every Pathu Yoni description string changes and a snapshot of it will break. Over the 1,296 pairs the Yoni verdict flips on 52, all from fail to pass, no veto flips, and recommended turns true on 5. Snake ↔ rat is deliberately not an enemy pair: some Tamil lists add it, and the narrower classical list was kept.

Brahma Muhurta is the 14th night muhurta

muhurtas.brahma is now the 14th of the 15 muhurtas of the night, the night being the span from sunset to the next sunrise. It runs from two night muhurtas before sunrise to one night muhurta before sunrise. In 5.3 it was a daylight/30 window, about 24 minutes wide, ending another daylight/30 before sunrise.

That is 95 to 47.5 minutes before sunrise. The daily panchang measures the night from the day's sunset to the next sunrise, the same night Pratah Sandhya uses, so the window's midpoint is exactly muhurtas.pratahSandhya.start (05:27:29 here). The reference-almanac captures in the library's test data confirm that Pratah Sandhya start. They hold no Brahma Muhurta value of their own.

The standalone computeBrahmaMuhurta(sunrise, sunset) keeps its signature and applies the same rule. With only those two instants it takes the night as 24 hours less the daylight, so its window can differ from muhurtas.brahma by a few seconds: 6.6 s and 3.3 s earlier at Pune on the same day.

Day-valued dates read in the location's zone

Some results name a day rather than a moment. Every one of them now reads as the right day when you format it in the location's zone. They come in two forms.

What changed is that SankrantiEvent.date and the solar branch of getHinduNewYear (Tamil Nadu, Kerala, Punjab, West Bengal and Assam) moved onto the second form. In 5.3 they were the date's own UTC midnight, which west of UTC reads one day early in the zone: Mesha Sankranti and Puthandu 2025 in New York read as 12 April. At UTC and east of it, IST included, every value is byte-identical. SankrantiEvent.moment, the exact transit, did not change.

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

// A day value, formatted as YYYY-MM-DD in the location's zone.
const day = (d: Date, timeZone: string) =>
  new Intl.DateTimeFormat('en-CA', { timeZone }).format(d);

// (a) A festival listing: the local midnight itself.
const delhi = { latitude: 28.6139, longitude: 77.2090 };
const at = computeFestivalsForYear(2020, delhi, { timezone: 330 })
  .find((f) => f.festival.key === 'akshaya_tritiya')!;
day(at.date, 'Asia/Kolkata');          // '2020-04-26'

// (b) A Sankranti or a new year: the UTC midnight inside the local day.
const ny = { latitude: 40.7128, longitude: -74.0060 };
const mesha = computeSankrantisForYear(2025, ny, { timezone: 'America/New_York' })
  .find((e) => e.rashi === 0)!;
day(mesha.date, 'America/New_York');   // '2025-04-13'   (5.3.0: '2025-04-12')

const puthandu = getHinduNewYear(2025, 'tamil-nadu', ny, { timezone: 'America/New_York' })!;
day(puthandu, 'America/New_York');     // '2025-04-13'   (5.3.0: '2025-04-12')

package main

import (
	"fmt"
	"time"

	"github.com/ishankgupta95/panchang/source/go/v5/panchang"
	"github.com/ishankgupta95/panchang/source/go/v5/types"
)

// day formats a day value as YYYY-MM-DD in the location's zone.
func day(d types.JSDate, zone string) string {
	loc, err := time.LoadLocation(zone)
	if err != nil {
		panic(err)
	}
	return d.Time().In(loc).Format("2006-01-02")
}

func main() {
	s := panchang.New()

	// (a) A festival listing: the local midnight itself.
	delhi := types.GeoLocation{Latitude: 28.6139, Longitude: 77.2090}
	fest, err := s.ComputeFestivalsForYear(2020, delhi,
		types.YearlyListingOptions{Timezone: panchang.OffsetMinutes(330)})
	if err != nil {
		panic(err)
	}
	for _, f := range fest {
		if f.Festival.Key == "akshaya_tritiya" {
			fmt.Println(day(f.Date, "Asia/Kolkata")) // 2020-04-26
		}
	}

	// (b) A Sankranti or a new year: the UTC midnight inside the local day.
	ny := types.GeoLocation{Latitude: 40.7128, Longitude: -74.0060}
	nyZone := panchang.Zone("America/New_York")
	sank, err := s.ComputeSankrantisForYear(2025, ny, types.YearlyListingOptions{Timezone: nyZone})
	if err != nil {
		panic(err)
	}
	for _, e := range sank {
		if e.Rashi == 0 { // Mesha
			fmt.Println(day(e.Date, "America/New_York")) // 2025-04-13 (5.3.0: 2025-04-12)
		}
	}

	puthandu, ok, err := s.GetHinduNewYear(2025, types.RegionTamilNadu, ny,
		types.ConvertOptions{Timezone: nyZone})
	if err != nil {
		panic(err)
	}
	if ok {
		fmt.Println(day(puthandu, "America/New_York")) // 2025-04-13 (5.3.0: 2025-04-12)
	}
}

The Odisha new year is Pana Sankranti

getHinduNewYear(year, 'odisha', location, options) now returns Pana Sankranti, the Mesha Sankranti day, instead of Chaitra Shukla Pratipada. The day is the transit's civil date, or, when the transit falls later than 0.315 of the way through the night after sunset, the date of the sunrise that ends that night. That cutoff is fitted to the reference almanac's Bhubaneswar dates. No textbook Odia rule reproduces them.

The cutoff is a fraction of the local night, so the date depends on the location: the same 21:48 transit is past the cutoff at Bhubaneswar and before it at Delhi. The new year can also fall a day before SankrantiEvent.date, which moves every transit after sunset to the date of the next sunrise. At Bhubaneswar in 2024 the new year is 13 April and the Mesha SankrantiEvent.date is 14 April. There is no pana_sankranti festival key: for region 'odisha' the daily list shows the Mesha sankranti entry on 14 April and nothing on 13 April.

Other values that move

Listings and the calendar

The daily panchang

Dashas and the Jyotish layer

The Shadbala change moves kala and total in computeShadbala, and bhavadhipati and total in computeBhavaBala. Totals in the library's pinned charts move by up to about 34 virupas, and more for a birth just after sunrise in a long night: at Oslo one minute after sunrise on 21 December 2025 the Sun's total goes from 357.29 to 402.29. The Varshaphala year lord, which reads Shadbala, can change with them.

New: computeVimshottariPratyantarIn

computeVimshottariPratyantarIn(mahaDasha, antardasha) returns the pratyantardashas of an antardasha split over its full length and then clipped, which is what the birth antardasha needs. The antardasha running at birth is clipped to start at birth, so its list begins with the pratyantar running at birth and can hold fewer than nine. Only mahaDasha.lord is read.

import {
  computeVimshottariDashaFromBirth, computeVimshottariPratyantar, computeVimshottariPratyantarIn,
} from 'panchang-ts';

const birth = new Date('1995-08-15T05:30:00Z');
const vim = computeVimshottariDashaFromBirth(birth, 'lahiri');
const maha = vim.mahaDashas[0]!;      // Mercury, from birth
const antar = maha.antarDashas[0]!;   // Rahu, clipped to start at birth

// The birth antardasha, split over its full length, then clipped.
const pra = computeVimshottariPratyantarIn(maha, antar);
console.log(pra.length, pra[0]!.lord, pra[0]!.startDate.toISOString());
// 6 Mercury 1995-08-15T05:30:00.000Z

// The older call treats the clipped span as a whole antardasha.
const squeezed = computeVimshottariPratyantar(antar);
console.log(squeezed.length, squeezed[0]!.lord);   // 9 Rahu

package main

import (
	"fmt"
	"time"

	"github.com/ishankgupta95/panchang/source/go/v5/panchang"
)

func main() {
	s := panchang.New()
	birth := time.Date(1995, 8, 15, 5, 30, 0, 0, time.UTC)

	vim, err := s.ComputeVimshottariDashaFromBirth(birth, panchang.Lahiri, time.Time{})
	if err != nil {
		panic(err)
	}
	maha := vim.MahaDashas[0]    // Mercury, from birth
	antar := maha.AntarDashas[0] // Rahu, clipped to start at birth

	// The birth antardasha, split over its full length, then clipped.
	pra, err := panchang.ComputeVimshottariPratyantarIn(maha, antar)
	if err != nil {
		panic(err)
	}
	fmt.Println(len(pra), pra[0].Lord, pra[0].StartDate.ISOString())
	// 6 Mercury 1995-08-15T05:30:00.000Z

	// The older call treats the clipped span as a whole antardasha.
	squeezed, err := panchang.ComputeVimshottariPratyantar(antar)
	if err != nil {
		panic(err)
	}
	fmt.Println(len(squeezed), squeezed[0].Lord) // 9 Rahu
}

The six run Mercury, Ketu, Venus, Sun, Moon and Mars, and the last ends exactly at the antardasha's end, 1996-10-17T02:07:37Z. computeVimshottariPratyantar is unchanged: it treats whatever span it is given as a whole antardasha, so on the clipped birth antardasha it fits all nine into the remaining span, starting with Rahu. For an antardasha that is not clipped the two calls return the same list. Neither takes an asOfDate. An unknown lord throws PanchangError with code INVALID_INPUT. See Dashas & Transits.

Input validation

Only inputs that used to hang, crash with a raw TypeError, or return garbage are affected. Valid input gives the same result as before.

One relaxation: from untyped JavaScript, janmaRashi: null or janmaNakshatra: null in getDailyPanchang now means the same as leaving the key out, so chandraBalam and tarabala come back null. 5.3 threw a RangeError. The TypeScript type still takes only a number.

Documented, not changed: an omitted timezone falls back to the host's zone in untyped JavaScript. The Go port reports INVALID_TIMEZONE instead, and accepts the zone names "" (UTC) and "Local" (the host), which TypeScript rejects. See Errors & Compatibility.

Faster, with no output changes

The speed work in this release changed no output: every table file and every pinned test value is byte-identical before and after it. Each figure below is a ratio, the time before divided by the time after, measured on one machine with the two builds alternating, as medians. They are not absolute times.

Most of the causes were repeated work. New-moon searches and planet positions were recomputed across days and charts, and are now kept in bounded caches keyed by every input, so no result depends on which calls ran before it. House cusps computed nine planet positions they never read. The converters and table builders built whole days to read four labels. Sade Sati sampled Saturn at steps where it cannot change sign, and a timezone formatter was rebuilt on every call. One cause was not repeated work: in TypeScript, the sine and cosine behind every series evaluation now keep their reduced argument in locals instead of module-level variables. That alone gives the chart primitives their whole speedup and most of the gain on a distinct day and in the Ekadashi and Sankranti listings. The caches give nearly all of the gain on a repeated day. See Performance.

Go: additive

github.com/ishankgupta95/panchang/source/go/v5 carries every change above with the same instants, days, festivals and labels, and adds API without removing or changing any. Every exported function, method, field, constant and type of v5.3.0 is unchanged.

• New calls: ComputeVimshottariPratyantarIn, ComputeJaimini8Karakas, (*Session).ComputeSripatiLagnaWithCusps and (*Session).GetUpcomingEclipsesContext.
• Table readers, the Go form of the panchang-ts/festivals, /eclipses, /moon-phases and /muhurta subpaths: ReadFestivalsForYear, ReadFestivalsForDate, ReadFestivalsForDateKey, ReadFestivalsYearRange and the same four for eclipses and moon phases, plus ReadMuhurtaForYear, ReadMuhurtaForDate, ReadMuhurtaForDateKey, ReadMuhurtaYearRange, ReadMuhurtaOccasion and ReadBestMuhurtaDays, with their result types in types.
• Enum helpers and constants: AllKaraka8Names, AllMoonPhaseNames, AllMoonPhaseTableNames, AllNarayanDirections, AllNodeAspects, AllReferences and AllYogaPolarities, the eight YoginiName constants, and JSDate.Time().
• Behaviour: a zero-value Session now behaves like New(). An empty ayanamsa means Lahiri in ComputeAyanamsa and GetSidereal*Longitude, as an omitted one does in TypeScript. ComputeAshtottariDasha and ComputeYoginiDasha wrap an out-of-range Moon longitude instead of returning ErrInvalidInput.

What to rebuild and re-pin

• Rebuild every festival table and diff it. Festival days move, holika_dahan appears (and karthigai_deepam in tables for 'all' and 'tamil-nadu'), and a table built west of UTC no longer starts on the previous 31 December. The format is unchanged, so nothing will warn you.
• Re-read cached listings and muhurta scores. Year and range listings in a zone with daylight saving, the eclipse listings and computeEkadashiDatesForYear near a year boundary can all change. An eclipse around sunrise now shows on one day, not two, so the other day's muhurta score can move: New York on 28 March 2025 scores 45 for vivahRule, not 0, and still fails.
• Rebuild eclipse tables if you read subtype. A solar eclipse whose peak is below the horizon now carries the subtype of its deepest visible phase, and its name and description follow. That is rare: at New York over 1950 to 2080 it is one eclipse, 1 July 2057, annular before and partial now, and the Delhi, London, Sydney and Reykjavik tables do not change.
• Move any Holika Dahan logic from holi to holika_dahan, and check anything that hard-coded the meaning of bathukamma_saddula, masik_karthigai, the Chhath keys or the default Shravan Somvar list.
• Recompute stored Ashtakoot totals and Pathu Porutham verdicts, and re-pin snapshots of the Pathu Yoni description.
• Re-pin Brahma Muhurta wherever you stored or displayed it.
• Re-read Sankranti and solar new-year dates cached west of UTC, and format every day value in the location's zone.
• Re-pin new-year dates and conversions: the Odisha new year at every offset, a lunar new year whose Pratipada holds no sunrise (Delhi 2026 moves from 20 to 19 March), and convertHinduToGregorian in an Adhika Chaitra year.
• Handle the new nulls and re-pin daily values. getDailyPanchang and getInstantPanchang return null when there is no sunrise to start the Hindu day, moon.set on a day with no moonrise is that day's own moonset or null, never the next day's, and computeVarjyam returns null for an index that is not the sunrise nakshatra. The eclipse of the day, specialYogas with computeEndTimes: false and some Bhadra ends move.
• Recompute Shadbala, Bhava Bala and the Varshaphala year lord.
• Re-pin yoga lists and Placidus-KP charts: the Sun no longer breaks Kemadruma, and 'placidus-kp' returns cusps between about 66.3° and 66.56° of latitude instead of PLACIDUS_DIVERGED.
• Re-pin Ashtottari and Yogini birth antardashas, Narayan variable durations, sub-period ends and Sade Sati nextArcStart, and switch the birth antardasha's pratyantars to computeVimshottariPratyantarIn.
• Match festivals on key, never on name, and match errors on code, never on message text.