@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