API Reference

getCalendar(year: number): SantaliCalendarYear

const yearData = calendar.getCalendar(2026);
// {
//   year: 2026,
//   currentMonthIndex: 0,
//   months: [SantaliCalendarMonth, ...],
//   startDate: Date("2026-01-19"),
//   endDate: Date("2027-01-07")
// }

getMonths(year: number): SantaliMonth[]

const months = calendar.getMonths(2026);
console.log(months[0].name);  // "ᱢᱟᱜᱽ" (Ol Chiki)
console.log(months[0].roman); // "Mag"
console.log(months.length);   // 12 or 13

getCurrentMonth(): SantaliCalendarMonth

const currentMonth = calendar.getCurrentMonth();
console.log(`${currentMonth.name} (${currentMonth.roman})`);

getDate(date?: DateTime): SantaliDate

const santaliDate = calendar.getDate(new Date("2026-04-14"));
console.log(santaliDate.day);           // Day of the lunar month (1..30)
console.log(santaliDate.month.name);    // "ᱢᱟᱜᱽ"
console.log(santaliDate.month.roman);   // "Mag"
console.log(santaliDate.weekDay);       // English weekday
console.log(santaliDate.isPurnima);     // true if Full Moon day
console.log(santaliDate.isAmavasya);    // true if New Moon day

getToday(): SantaliDate

const today = calendar.getToday();
console.log(`${today.day} ${today.month.name}`);

isLeapYear(year: number): boolean

calendar.isLeapYear(2026); // true
calendar.isLeapYear(2027); // false
calendar.isLeapYear(2029); // true

getDaysInMonth(year: number, month: number): number

calendar.getDaysInMonth(2026, 1); // Days in Mag Bonga

getMonthIndex(date: DateTime): number

const idx = calendar.getMonthIndex(new Date()); // 0-12

getCalendarMonthIndex(date: DateTime): number

const idx = calendar.getCalendarMonthIndex(new Date());

getMonthFromDate(date: DateTime): SantaliCalendarMonth

const month = calendar.getMonthFromDate(new Date("2026-06-15"));
console.log(month.name);

getFestivals(year: number): SantaliFestival[]

const festivals = calendar.getFestivals(2026);
festivals.forEach((f) => {
  console.log(`${f.roman}: ${f.date.toLocaleDateString()}`);
  console.log(`  Type: ${f.type}`);
  console.log(`  Month: ${f.monthId}`);
});

// Example output:
// Santali New Year: 1/19/2026
//   Type: observance
//   Month: MAG
// Mag Bonga: 1/23/2026
//   Type: festival
//   Month: MAG

getNewMoon(k: number): number

const nm = getNewMoon(285); // Magh 2023 New Moon\nconsole.log(new Date(nm));

getFullMoon(k: number): number

getFullMoonBetween(startMs: number, endMs: number): number | null

getChandradarshan(newMoonMs: number): number

isSantaliLeapYear(year: number): boolean

isSantaliLeapYear(2032); // true

getSantaliMonths(year: number): SantaliMonth[]

getSantaliMonth(date?: DateTime): SantaliMonth

getNewMoonsForYear(year: number): number[]

getFullMoonsForYear(year: number): number[]

toISTDate(ms: number): Date

unixMsToJulianDay(ms: number): number

getSunriseSunset(
  date: DateTime,
  latitude: number,
  longitude: number,
  utcOffsetHours?: number
): SunTimes | null

const sun = getSunriseSunset(
  new Date(),
  23.3441, // Ranchi latitude
  85.3096, // Ranchi longitude
  5.5      // IST
);
console.log(sun?.sunrise);
console.log(sun?.sunset);
console.log(sun?.dayLengthMs);

getSunrise(
  date: DateTime,
  latitude: number,
  longitude: number,
  utcOffsetHours?: number
): Date | null

getSunset(
  date: DateTime,
  latitude: number,
  longitude: number,
  utcOffsetHours?: number
): Date | null

getBhubaneswarSunriseSunset(date?: DateTime): SunTimes | null

toOlChikiNumeral(n: number): string

toOlChikiNumeral(1);    // "᱑"
toOlChikiNumeral(19);   // "᱑᱙"
toOlChikiNumeral(2026); // "᱒᱐᱒᱖"

// Core types
type DateTime = Date | string | number;

interface SantaliMonth {
  index: number;
  name: string;       // Ol Chiki name
  roman: string;      // English name
  isLeapMonth: boolean;
  startDate: Date;
  endDate: Date;
  displayEndDate: Date;
  totalDays: number;
  newMoon: Date;
  fullMoon: Date;
}

interface SantaliDate {
  day: number;
  date: Date;
  weekDay: string;
  month: SantaliMonth;
  isPurnima: boolean;
  isAmavasya: boolean;
  isLeapMonth: boolean;
}

// Calendar types
interface SantaliCalendarYear {
  year: number;
  currentMonthIndex: number;
  months: SantaliCalendarMonth[];
  startDate: Date;
  endDate: Date;
}

interface SantaliCalendarMonth extends SantaliMonth {
  days: SantaliCalendarDayCell[];
}

interface SantaliCalendarDayCell {
  day: number;
  date: Date;
  olchiki: string;
  weekDay: string;
  santaliWeekDay: string;
  isToday: boolean;
  isNewMoonDay: boolean;
  isFullMoonDay: boolean;
  isCurrentMonth: boolean;
}

// Festival types
type SantaliFestivalType =
  | "festival"
  | "birth-anniversary"
  | "death-anniversary"
  | "cultural"
  | "community"
  | "observance";

type MoonPhase = "new-moon" | "full-moon";

interface SantaliFestival {
  id: string;
  name: string;
  roman: string;
  monthId: string;
  type: SantaliFestivalType;
  description?: string;
  date: Date;
}

// Sun types
interface SunTimes {
  sunrise: Date;
  sunset: Date;
  solarNoon: Date;
  dayLengthMs: number;
}