@mera-vansh/ms-panchang

@mera-vansh/ms-panchang

Complete Hindu Panchang (almanac) engine — tithi, nakshatra, yoga, karana, vara, Hindu month, sunrise/sunset, and Samvat — for any date and Indian city, in 18 languages.

@mera-vansh/ms-panchang is a zero-database, zero-network panchang engine built for production applications. All calculations run offline using Meeus astronomical algorithms. Query by city name — no lat/lon required. Output arrives in the language you request, formatted as human-readable text and structured data in one call.

Add a full panchang to any calendar, astrology, or temple application in minutes. The narrative field is designed for direct display or LLM prompt injection — no post-processing required.

Key Capabilities

• All five panchang limbs — Tithi (with paksha and second-limb detection), Vara, Nakshatra (with pada), Yoga, and Karana in every response
• Hindu calendar — Vikram Samvat, Shaka Samvat, Kali Yuga, and lunar month (Amanta/Purnimanta) derived automatically from your region
• Sunrise and sunset — computed per city using the USNO algorithm; polar-day/polar-night flags included
• ~220 Indian cities built-in — sacred sites, state capitals, metros, and pilgrimage centres; query by name, alias, or Devanagari spelling (e.g. "Kashi", "Banaras", "काशी")
• 7 regional calendar systems — North, South, East, West, Kerala, Bengal, Tamil Nadu — selected automatically from language or set explicitly
• 18 Indian languages — output names and narrative in English, Hindi, Sanskrit, Tamil, Telugu, Kannada, Malayalam, Bengali, Marathi, Gujarati, Punjabi, Odia, Assamese, Nepali, Konkani, Maithili, Sindhi, or Urdu
• Self-learning delta adjustments — accumulate user feedback to refine ayanamsa, ΔT, and offset corrections over time
• LLM-ready narrative — every response includes a narrative string ready for display or prompt injection
• Export / import state — serialize the learned correction model to JSON and restore it in any environment

Supported Languages

Code	Language	Code	Language
en	English	ml	Malayalam
hi	Hindi	ma	Maithili
sa	Sanskrit	mr	Marathi
ta	Tamil	ne	Nepali
te	Telugu	or	Odia
kn	Kannada	pa	Punjabi
bn	Bengali	kok	Konkani
gu	Gujarati	as	Assamese
ur	Urdu	sd	Sindhi

Installation

npm install @mera-vansh/ms-panchang
# or
pnpm add @mera-vansh/ms-panchang

Requires Node.js ≥ 22.

Quick Start

import { PANCH } from "@mera-vansh/ms-panchang";

const result = PANCH.call({
  date: new Date(),
  cityName: "Varanasi",
  lang: "hi",
});

console.log(result.narrative);
// "शुक्ल पक्ष तृतीया, रोहिणी नक्षत्र, सौभाग्य योग, बव करण, सूर्योदय 05:47"

console.log(result.tithi.name);   // "तृतीया"
console.log(result.vara.name);    // "मंगलवार"
console.log(result.nakshatra.name); // "रोहिणी"
console.log(result.samvat.vikram);  // 2082

API

PANCH.call(request): PanchangResponse

Compute the full panchang for a date and location.

Parameter	Type	Description
date	Date | string | number	Date as a Date object, ISO-8601 string, Unix ms, or natural language ("आज", "today", "kal")
cityName	string?	Named city — resolves lat/lon and timezone from the built-in database. Takes priority over location.
location	GeoLocation?	Raw { lat, lon } coordinates. Used when cityName is absent.
lang	LangCode?	Output language. Auto-detected from the date string; defaults to "hi".
region	RegionCode?	Calendar system override ("north", "south", "east", "west", "kerala", "bengal", "tamil"). Auto-derived from lang if omitted.
tzOffsetMinutes	number?	UTC offset in minutes. Derived from longitude if omitted.
includeAstro	boolean?	Include raw AstroMoment (sidereal/tropical longitudes, ayanamsa, nutation) in the response.

Returns PanchangResponse:

Field	Type	Description
id	string	UUID for feedback via PANCH.feedback()
tithi	TithiInfo	Tithi index, paksha, name, fraction elapsed, second-limb flag
vara	VaraInfo	Weekday index and name
nakshatra	NakshatraInfo	Nakshatra index, pada, name, fraction elapsed
yoga	YogaInfo	Yoga index and name
karana	KaranaInfo	Karana type, sequential index, name
month	HinduMonth	Lunar month number, name, Adhika flag, Amanta/Purnimanta system
samvat	SamvatInfo	Vikram Samvat, Shaka Samvat, Kali Yuga years
solarTimes	SolarTimes	Sunrise/transit/sunset as JD and ISO-8601 strings
narrative	string	Human-readable panchang summary in the requested language
astro	AstroMoment?	Raw astronomical data (only when includeAstro: true)
computeTimeMs	number	Wall-clock computation time in milliseconds

PANCH.suggest(prefix, lang?): PanchangSuggestion[]

Returns autocomplete suggestions for tithi, nakshatra, yoga, karana, vara, and month names matching a given prefix.

const suggestions = PANCH.suggest("र", "hi");
// [{ text: "रोहिणी", category: "nakshatra", index: 4 }, ...]

PANCH.feedback(id, signal): void

Submit a correction signal to improve future calculations. The engine accumulates weighted feedback to auto-tune ayanamsa, ΔT, and offset values.

PANCH.feedback(result.id, {
  type: "negative",
  correction: { field: "nakshatra", expectedValue: 5 },
});

PANCH.optimize(): void

Runs a batch pass over all accumulated feedback to consolidate delta adjustments. Call periodically (e.g. after 50+ feedback signals) for best accuracy.

PANCH.export(): SerialPANCHState

Serializes the current correction model to a plain JSON object. Store in any database or file system.

const state = PANCH.export();
// persist to your database: db.panchangState.save(state)

PANCH.import(state): void

Restores a previously exported correction model.

const state = await db.panchangState.load();
PANCH.import(state);

City Helpers

import { getCityByName, searchCities } from "@mera-vansh/ms-panchang";

// Exact or alias lookup — returns CityEntry or undefined
const city = getCityByName("Kashi");     // matches "Varanasi"
const city2 = getCityByName("काशी");    // Devanagari alias

// Fuzzy prefix search across names, aliases, states, and categories
const results = searchCities("jyotirlinga", { limit: 5 });

Application Examples

Daily Panchang Widget

import { PANCH } from "@mera-vansh/ms-panchang";

function getDailyPanchang(cityName: string, lang = "hi") {
  const res = PANCH.call({ date: new Date(), cityName, lang });
  return {
    summary: res.narrative,
    tithi: `${res.tithi.pakshaName} ${res.tithi.name}`,
    nakshatra: res.nakshatra.name,
    yoga: res.yoga.name,
    sunrise: res.solarTimes.sunriseISO,
    sunset: res.solarTimes.sunsetISO,
    samvat: res.samvat.vikram,
  };
}

console.log(getDailyPanchang("Tirupati", "te"));

LLM Prompt Injection

import { PANCH } from "@mera-vansh/ms-panchang";

function buildAstrologyPrompt(cityName: string, userQuestion: string) {
  const panchang = PANCH.call({ date: new Date(), cityName, lang: "en" });

  return `
Today's Panchang for ${cityName}:
${panchang.narrative}

Vikram Samvat: ${panchang.samvat.vikram}
Sunrise: ${panchang.solarTimes.sunriseISO}
Sunset: ${panchang.solarTimes.sunsetISO}

User question: ${userQuestion}
`.trim();
}

Muhurta Calendar (Auspicious Date Finder)

import { PANCH } from "@mera-vansh/ms-panchang";

function findAuspiciousDays(cityName: string, daysAhead = 30) {
  const auspicious = [];
  const today = new Date();

  for (let i = 0; i < daysAhead; i++) {
    const date = new Date(today);
    date.setDate(today.getDate() + i);

    const p = PANCH.call({ date, cityName, lang: "en" });

    // Avoid Bhadra (Vishti karana) and inauspicious yogas
    const isBhadra = p.karana.typeIndex === 6;
    const isAuspiciousYoga = [1, 3, 5, 7, 10, 14, 17, 20].includes(p.yoga.index);

    if (!isBhadra && isAuspiciousYoga) {
      auspicious.push({ date: p.date, tithi: p.tithi.name, yoga: p.yoga.name });
    }
  }

  return auspicious;
}

Multi-City Temple Dashboard (18 Languages)

import { PANCH } from "@mera-vansh/ms-panchang";

const temples = [
  { city: "Varanasi", lang: "hi" as const },
  { city: "Tirupati", lang: "te" as const },
  { city: "Madurai",  lang: "ta" as const },
  { city: "Puri",     lang: "or" as const },
];

const today = new Date();
const dashboard = temples.map(({ city, lang }) => ({
  city,
  panchang: PANCH.call({ date: today, cityName: city, lang }).narrative,
}));

License

GPL-3.0 © Mera Vansh — dwivna