Documentation
Everything you need to use the Bikram Sambat (BS) calendar in a JavaScript or TypeScript application. You do not need to know the Nepali calendar in advance: BS months have 29 to 32 days that change every year, so all conversion comes from a verified month-length table, never from a formula.
Installation
npm install sajilo-patroसजिलो पात्रो (sajilo patro) means “easy calendar”. Prefer the full name?npm install @nepali-calendar/nepali-calendarSame code, same version.
- Node.js 20 or newer. Also works in modern browsers and bundlers.
- ESM and CommonJS builds with TypeScript declarations.
- Zero runtime dependencies. The dataset is bundled, so conversion works offline.
// ES modules: Node.js, Vite, webpack, Next.js, esbuild, Denoimport { NepaliCalendar } from "sajilo-patro"; // CommonJSconst { NepaliCalendar } = require("sajilo-patro");Node.js, bundlers and TypeScript (nodenext, node16 or bundler resolution) pick the right build automatically. Use one format per application: mixing import and require loads two copies, and instanceof checks between them fail.
Quick start
import { NepaliCalendar } from "sajilo-patro"; const calendar = new NepaliCalendar(); const today = await calendar.getToday();console.log(today.bs.iso); // e.g. "2083-07-20"console.log(today.ad.iso); // e.g. "2026-11-06"console.log(today.monthName.ne, today.weekdayName.ne); // "कात्तिक" "शुक्रबार"console.log(today.verification.status); // "official" | "provisional" | "unverified"CommonJS:
const { NepaliCalendar } = require("sajilo-patro");Date conversion
Conversion is synchronous and offline. Both methods return a DateInfo with bs, ad, weekday (0 = Sunday), names and verification.
const result = calendar.convertToBS("2026-11-06");result.bs; // { year: 2083, month: 7, day: 20, iso: "2083-07-20" } calendar.convertToAD({ year: 2083, month: 7, day: 21 }).ad.iso; // "2026-11-07"calendar.convertToAD("२०८३-०७-२१").ad.iso; // "2026-11-07" // A Date is read as the calendar date in Nepal (UTC+05:45)calendar.convertToBS(new Date("2026-11-05T18:15:00Z")).bs.iso; // "2083-07-20"Calendar retrieval
const month = await calendar.getMonth(2083, 7);month.totalDays; // 30month.startWeekday; // 0 (Sunday) — for laying out a gridmonth.adStart.iso; // "2026-10-18"month.verification.status; // "official"month.holidayDataAvailable; // true const day = await calendar.getDate(2083, 7, 22);day.events.map((event) => event.id); // ["tihar"]day.isPublicHoliday; // trueday.tithi?.name.en; // calculated tithi at Kathmandu sunriseHolidays and events
Holidays come from the Ministry of Home Affairs notice. Each event lists who it applies to in holidays[].scope: national, regional (districts), community, women, education or disability. An empty holidays array means the day is observed but offices stay open. Festivals are not assumed to be holidays.
const holidays = await calendar.getHolidays(2083);const national = await calendar.getHolidays(2083, { scopes: ["national"] }); // 24 eventsconst festivals = await calendar.getFestivals(2083);const kartik = await calendar.getEvents({ year: 2083, month: 7 }); const pending = holidays.filter((event) => event.status === "pending-date");// e.g. Eid ul-Fitr: a holiday whose date the notice fixes later (start === null) await calendar.hasHolidayData(2084); // false until the 2084 notice is publishedWorking days and payroll
These utilities classify days; they do not calculate pay, tax or leave entitlements. Ranges are inclusive. Check holidayData.complete and holidayData.pendingHolidays before relying on public-holiday counts.
const summary = await calendar.getWorkingDays({ year: 2083, month: 7 });summary.workingDays; // 14summary.weeklyHolidayDays; // 4 Saturdayssummary.publicHolidaysOnWorkingDays; // 12 (Dashain, Tihar, Chhath) const payroll = await calendar.getPayrollCalendar({ year: 2083, month: 7 });payroll.days[0]?.type; // "working" | "weekly-holiday" | "public-holiday" | "custom-holiday" const leave = await calendar.getDateRangeSummary({ startDate: "2083-01-01", endDate: "2083-01-15", includeDays: true,});leave.workingDays; // 12Configuration
All options are optional and are checked when the calendar is created. A misspelt option name or a value of the wrong type throws ConfigurationError instead of being ignored, so a typo cannot silently change payroll results. The calendar keeps a frozen copy of your settings, so changing your objects afterwards has no effect.
import { NepaliCalendar, WEEKDAY } from "sajilo-patro"; const calendar = new NepaliCalendar({ // Default: [6] (Saturday). Add Sunday for a two-day weekend: weeklyHolidays: [WEEKDAY.SATURDAY, WEEKDAY.SUNDAY], // Default: national holidays only. holidayPolicy: { district: "kathmandu", // applies district holidays (ID, name or alias) includeScopes: ["women"], // community | women | education | disability includeEvents: ["civil-service-day"], excludeEvents: ["chhath"], }, customHolidays: [ { name: "Founders' Day", start: "2083-07-10" }, { id: "retreat", name: { en: "Retreat", ne: "रिट्रिट" }, start: "2083-01-07", end: "2083-01-09" }, ], tithi: true, // default; set false to skip tithi calculation now: () => new Date(), // clock used by getToday(); inject a fixed one in tests});The rule options can also be overridden for a single call to the working-day methods:
await calendar.getWorkingDays({ year: 2083, month: 7, weeklyHolidays: [WEEKDAY.SATURDAY], holidayPolicy: { district: "kaski" }, includePublicHolidays: true, // default includeCustomHolidays: true, // default});Localization
calendar.toNepaliDigits("2083-07-11"); // "२०८३-०७-११"calendar.toEnglishDigits("२०८३-०७-११"); // "2083-07-11" const date = { year: 2083, month: 7, day: 11 };calendar.formatDate(date); // "2083-07-11"calendar.formatDate(date, { format: "short" }); // "11 Kartik 2083"calendar.formatDate(date, { locale: "ne", format: "short" }); // "कात्तिक ११, २०८३"calendar.formatDate(date, { locale: "ne", format: "long" }); // "२०८३ कात्तिक ११ गते, बुधबार"Name lists are exported as BS_MONTH_NAMES, AD_MONTH_NAMES, WEEKDAY_NAMES, TITHI_NAMES and PAKSHA_NAMES.
Remote dataset
The bundled dataset is the default and needs no network. To receive new holiday notices without upgrading the package, load the published dataset. The bundled dataset is used if loading fails or if the remote dataset is older than the bundled one. Every option below is checked, and an out-of-range value throws ConfigurationError.
import { NepaliCalendar, RemoteDatasetProvider } from "sajilo-patro"; const calendar = new NepaliCalendar({ provider: new RemoteDatasetProvider({ url: "https://nepali-calendar.sarthaksharma.com.np/dataset.json", timeoutMs: 10_000, // whole request including the body (1 ms to 2 minutes) retries: 1, // after network errors, 5xx and 429 (at most 3) retryDelayMs: 500, // doubled for each further retry cacheTtlMs: 6 * 60 * 60 * 1000, // reuse a loaded dataset for 6 hours failureCacheMs: 5 * 60 * 1000, // wait before retrying after a failure maxResponseBytes: 5_000_000, // larger responses are refused while streaming fallbackToBundled: true, // use the bundled dataset if anything goes wrong onWarning: (message) => console.warn(message), // fetch: customFetch, // for proxies, authentication headers or tests }),}); await calendar.load(); // synchronous conversions use the bundled dataset until this resolvesError handling
Every error extends NepaliCalendarError and has a stable code.
| Class | code | When |
|---|---|---|
| InvalidDateError | INVALID_DATE | Malformed input or a date that does not exist (e.g. Mangsir 30, 2083). |
| DateOutOfRangeError | DATE_OUT_OF_RANGE | A valid date outside the dataset (before BS 1970 or after BS 2090). |
| ConfigurationError | INVALID_CONFIGURATION | Invalid weekly holidays, unknown district, bad custom holiday. |
| DatasetValidationError | DATASET_INVALID | A dataset from a provider failed validation; issues lists every problem. |
| RemoteDatasetError | REMOTE_DATASET_FAILED | Remote dataset unavailable and fallbackToBundled is false. |
import { DateOutOfRangeError, InvalidDateError } from "sajilo-patro"; try { calendar.convertToAD({ year: 2083, month: 8, day: 30 });} catch (error) { if (error instanceof InvalidDateError) console.error(error.code, error.message); else if (error instanceof DateOutOfRangeError) console.error("Outside BS 1970–2090"); else throw error;}Security
- No runtime dependencies, no Node.js built-ins and no
evalin the published builds. - Date strings longer than 32 characters are rejected before parsing. Error messages quote at most 40 characters of your input.
- The bundled dataset and every object returned for it are deep-frozen. One part of an application cannot change the data another part sees.
- Data from any provider is copied, fully validated and frozen before use, so the data that was checked is exactly the data that is used.
- Remote datasets load over HTTPS only, including after redirects (plain
httponly forlocalhost). Cookies and credentials are never sent, and URLs with a user name or password are rejected. - Response size is capped while streaming, invalid UTF-8 is rejected, and JSON is parsed with
JSON.parseonly.
To report a vulnerability privately, email ssarthakxd@gmail.com.
API overview
- convertToBS(date)
- AD → BS. Accepts "YYYY-MM-DD", { year, month, day } or a Date (read in Asia/Kathmandu). Synchronous.
- convertToAD(date)
- BS → AD. Accepts { year, month, day } or "YYYY-MM-DD" (English or Nepali digits). Synchronous.
- isValidBSDate(date)
- true if the BS date exists in the dataset.
- getMonthLength(year, month)
- Days in a BS month (29–32).
- getSupportedYears()
- { min, max } BS years in the loaded dataset.
- getToday()
- Today in Nepal as a CalendarDay.
- getDate(year, month, day)
- One BS day with events, holiday flags and tithi.
- getMonth(year, month)
- Every day of a BS month with AD mapping, events and verification.
- hasHolidayData(year)
- true if a government holiday list exists for the BS year.
- getHolidays(year, { scopes?, observedOnly? })
- Government holidays, including those whose date is still pending.
- getFestivals(year)
- Festivals and jatras, whether or not they are holidays.
- getEvents({ year, month? })
- All holidays and observed days for a year or month.
- getWorkingDays({ year, month, ...rules })
- Working-day summary for a BS month.
- getPayrollCalendar({ year, month, ...rules })
- Summary plus a classification of every day.
- getDateRangeSummary({ startDate, endDate, includeDays?, ...rules })
- Totals for an inclusive range, e.g. a leave request.
- formatDate(date, { locale?, format? })
- Format a BS date: iso, short or long, in English or Nepali.
- toNepaliDigits(value) / toEnglishDigits(value)
- Convert digits between scripts.
- getDatasetInfo() / load()
- Dataset version, coverage, statuses, holiday years and sources.
Data source and accuracy
- Government holidays: Ministry of Home Affairs notices published in the Nepal Rajpatra, transcribed by hand with a page and section reference for every entry, pending a second review.
- Month lengths: two open-source tables that agree on every month, checked against the official Saturday lists for BS 2080–2083 (official) and marked provisional (Chaitra 2083, 2084–2090) or unverified (1970–2079, may not be 100% correct).
- Tithi: calculated astronomically for Kathmandu sunrise; always labelled calculated.
- Not an official government calendar and not endorsed by the Government of Nepal.
Licence and contact
The package is free to use, including commercially, and you may ship it inside your own applications. You may not resell it, republish it (or a modified copy) as a package, or redistribute its dataset on its own. Read the full Nepali Calendar Free Use License.
- Found a wrong date or holiday? Email a data error report with a source, such as the government notice.
- Questions or licensing: ssarthakxd@gmail.com or the contact page.