santali_calendar

A Dart package for the traditional Santali lunisolar calendar.

Uses astronomical moon phase calculations (Chandradarshan) to determine accurate month boundaries based on the 19-year Metonic cycle.

Santali days start at 17:00 IST (11:30 UTC). Day numbers use proportional division within the month, matching the reference implementation.

Repository: https://github.com/wesantal/santali-calendar-dart

Installation

dependencies:
  santali_calendar: ^2.1.0

dart pub add santali_calendar

Usage

import 'package:santali_calendar/constants/seasons.dart';
import 'package:santali_calendar/santali_calendar.dart';
import 'package:santali_calendar/utils/olchiki_number.dart';

final calendar = SantaliCalendar();

// Get today's Santali date (exact instant)
final today = calendar.today();
print(today);            // 3 ᱫᱟᱥᱟᱸᱭ 2026 (Dasany, Gregorian: 2026-09-14)
print(today.weekDay);    // 1 (DateTime.weekday: Monday = 1 ... Sunday = 7)
print(today.isPurnima);  // false
print(today.isAmavasya); // false
print(today.season);     // Hemal (ᱦᱮᱢᱟᱞ, Autumn) — a SantaliSeasonDefinition

// Santali date for the calendar grid cell of today
// (evaluates the day starting 17:00 IST on today's Gregorian date)
final gridToday = calendar.getCalendarToday();

// Convert any Gregorian date
final date = calendar.getDate(DateTime.utc(2026, 6, 15));

// Get full calendar year
final year = calendar.getCalendar(2026);
print(year.startDate);         // 2026-01-19 11:30:00.000Z
print(year.currentMonthIndex); // index of today's month

// Get a single month
final magh = calendar.getMonth(2026, 0);
print(magh.name);     // "ᱢᱟᱜᱽ"
print(magh.roman);    // "Mag"
print(magh.totalDays); // 30

// Get month for any date
final month = calendar.getMonthByDate(DateTime.now());

// Get current month
final current = calendar.getCurrentMonth();

// Check leap year (method)
calendar.isLeapYear(2026); // true (Metonic position 1)
calendar.isLeapYear(2027); // false

// Days in a Santali month
calendar.getDaysInMonth(2026, 0); // 30

// Seasons (six per year, two months each)
calendar.getSeason(0);                  // Rabang (ᱨᱟᱵᱟᱝ, Winter) — Mag
calendar.getSeason();                   // season of the current month
calendar.getSeasonFromDate(DateTime.now());
calendar.getSeasons();                  // all six definitions, in year order
calendar.getSeasonMonths(2026, SantaliSeason.sarata); // Dasany, Sohray
calendar.seasonDefinition(SantaliSeason.hemanta);      // Hawed (ᱦᱟᱣᱮᱫ)

// Festivals for a year
final festivals = calendar.getFestivals(2026);
for (final f in festivals) {
  print('${f.roman}: ${f.date} (${f.type.name})');
}

// Convert numbers to Ol Chiki script
toOlChikiNumeral(2026); // "᱒᱐᱒᱖"

Calendar Structure

getCalendar(year) returns a SantaliCalendarYear:

final year = calendar.getCalendar(2026);

print(year.year);              // 2026
print(year.startDate);         // start of Mag
print(year.endDate);           // end of Pus
print(year.currentMonthIndex); // index of today's month
print(year.seasons.length);    // 6

for (final month in year.months) {
  print('${month.name} (${month.roman}): ${month.totalDays} days');
  print('  Season: ${month.season.roman} (${month.season.english})');
  print('  Start: ${month.startDate}');
  print('  End:   ${month.endDate}');
  print('  Full Moon: ${month.fullMoonDate}');
  print('  New Moon:  ${month.newMoonDate}');

  for (final cell in month.days) {
    if (cell != null && cell.isCurrentMonth) {
      print('  ${cell.weekDay} ${cell.day}: ${cell.date}');
    }
  }
}

SantaliMonth

Base month model with astronomical data:

class SantaliMonth {
  final SantaliMonthId id;       // mag, fagun, ..., sarcha
  final int index;               // 0-12
  final String name;             // Ol Chiki name
  final String roman;            // English name
  final DateTime startDate;      // Gregorian start (Chandradarshan, 11:30 UTC)
  final DateTime endDate;        // Gregorian end (next Chandradarshan)
  final DateTime newMoonDate;    // Amavasya date
  final DateTime fullMoonDate;   // Purnima (Kunami) date
  final int totalDays;           // days in month
  final bool isLeapMonth;        // true for Sarcha
  final DateTime displayEndDate; // endDate minus one day
}

SantaliDate

Returned by getDate(), today() and getCalendarToday():

final date = calendar.today();

date.day;          // 3
date.year;         // 2026
date.monthIndex;   // 8 (0-based)
date.month;        // SantaliMonth instance
date.month.roman;  // "Dasany"
date.month.id;     // SantaliMonthId.dasany
date.weekDay;      // 1 (DateTime.weekday: Monday = 1 ... Sunday = 7)
date.date;         // raw UTC timestamp of the queried instant
date.isPurnima;      // false
date.isAmavasya;     // false
date.isFirstMoonDay; // true if day 1 of the month
date.isLeapMonth;    // false
date.olChikiDay;   // "᱓"
date.olChikiYear;  // "᱒᱐᱒᱖"
date.season;       // Hemal (ᱦᱮᱢᱟᱞ, Autumn)

Month boundaries are available via date.month.startDate / date.month.endDate.