nepali-date-lite

Bikram Sambat (Nepali calendar) date conversion and formatting. Zero dependencies, ESM, TypeScript types included.

npm install nepali-date-lite

Published as nepali-date-lite on npm. The name bikram-sambat was already taken by an actively maintained package — this one differs by having zero dependencies and TypeScript types, which that one does not.

Why

Every application built for Nepal eventually needs BS dates — invoices, VAT filings, hospital records, government forms. The conversion is not arithmetic: month lengths vary between 29 and 32 days with no formula, so it requires a lookup table per year. This packages that table with a small, tested API.

Built while shipping a hospital ERP that files VAT returns in Nepal, where getting this wrong meant a document nobody could legally submit.

Usage

import { toBS, toAD, format, today } from 'nepali-date-lite';

toBS('2024-04-13');
// { year: 2081, month: 1, day: 1, weekday: 6 }

toAD(2081, 1, 1);
// 2024-04-13T00:00:00.000Z

format(today(), 'D MMMM YYYY');
// '1 Baishakh 2081'

format(today(), 'D MMMM YYYY', { nepali: true });
// '१ बैशाख २०८१'

API

| Function | Returns | | --- | --- | | toBS(date) | { year, month, day, weekday } from a Date or 'YYYY-MM-DD' string | | toAD(year, month, day) | A Date at UTC midnight | | today() | Today as a BS date | | format(bs, pattern?, { nepali }) | Formatted string | | addDays(bs, n) | A new BS date | | diffDays(a, b) | Whole days between two BS dates | | daysInMonth(year, month) | 29–32 | | daysInYear(year) | 365 or 366 | | isValid(year, month, day) | boolean — never throws | | toNepaliDigits(value) | '2081' → '२०८१' |

Format tokens

YYYY YY MM M DD D MMMM MMM dddd

With { nepali: true }, month and weekday names render in Devanagari and digits convert automatically.

Also exported

MONTHS_EN MONTHS_NP WEEKDAYS_EN WEEKDAYS_NP MIN_BS_YEAR MAX_BS_YEAR SUPPORTED_RANGE

Supported range

BS 2000-01-01 → 2090-12-30, which is AD 1943-04-14 → 2034-04-13.

Anything outside that throws a RangeError rather than returning a wrong answer, because a silently incorrect date is worse than a failed one.

Correctness

The calendar table is validated three ways, and the test suite runs all of it:

• Every one of the 91 years sums to exactly 365 or 366 days.
• Conversions match published anchors across eight decades — BS 2000, 2050, 2070, 2079, 2080, 2081 and 2082 new year.
• 3,276 round-trips — the first, middle and last day of every month in every supported year converts to AD and back to exactly the same BS date.

npm test

If you find a date this gets wrong, please open an issue with the date and a source — it will be fixed quickly.

Licence

MIT © Sujay Aryal