Skip to content
Esc

Use the up and down arrow keys to choose a result and Enter to open it.

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 sunrise

Holidays 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 published

Working 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; // 12

Configuration

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 resolves

Error handling

Every error extends NepaliCalendarError and has a stable code.

ClasscodeWhen
InvalidDateErrorINVALID_DATEMalformed input or a date that does not exist (e.g. Mangsir 30, 2083).
DateOutOfRangeErrorDATE_OUT_OF_RANGEA valid date outside the dataset (before BS 1970 or after BS 2090).
ConfigurationErrorINVALID_CONFIGURATIONInvalid weekly holidays, unknown district, bad custom holiday.
DatasetValidationErrorDATASET_INVALIDA dataset from a provider failed validation; issues lists every problem.
RemoteDatasetErrorREMOTE_DATASET_FAILEDRemote 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 eval in 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 http only for localhost). 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.parse only.

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.

See the data reliability summary

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.