@suwi/dateconverter

🗓️ Nepali Bikram Sambat (BS) ↔ Gregorian (AD) date converter for JavaScript & Node.js

A lightweight, dependency-free JavaScript utility for converting dates between the Nepali Bikram Sambat (BS) calendar and the Gregorian (AD) calendar. Powered by an official-style lookup table covering BS 2000–2100 (AD 1943–2044).

✨ Features

• 🔄 Bidirectional conversion — AD → BS and BS → AD
• 📅 Wide range — BS 2000/01/01 through BS 2100/12/30
• 🧮 Lookup-table accuracy — calendar data sourced from the bikram-sambat npm package for BS 2000–2090
• 🛠️ Utility helpers — get days in a month/year, today's BS date, month names
• 🚫 Zero dependencies — pure JavaScript, works in Node.js and the browser
• ✅ Input validation — clear, descriptive errors for out-of-range or invalid dates

📦 Installation

npm install @suwi/dateconverter

🚀 Quick Start

const { adToBS, bsToAD, todayBS } = require('@suwi/dateconverter');

// Convert AD → BS
const bs = adToBS(2025, 5, 24);
console.log(bs.formatted);   // "2082/02/10"
console.log(bs.monthName);   // "Jestha"

// Convert BS → AD
const ad = bsToAD(2082, 2, 10);
console.log(ad.formatted);   // "2025/05/24"
console.log(ad.monthName);   // "May"

// Today's date in BS
const today = todayBS();
console.log(`Today in BS: ${today.formatted}`);

📖 API Reference

adToBS(year, month, day)

Converts a Gregorian (AD) date to a Bikram Sambat (BS) date.

Parameters

| Name | Type | Description | |---------|----------|---------------------------------| | year | number | AD year (e.g. 2025) | | month | number | AD month (1–12) | | day | number | AD day (1–31) |

Returns { year, month, day, monthName, formatted }

adToBS(2025, 5, 24);
// → { year: 2082, month: 2, day: 10, monthName: 'Jestha', formatted: '2082/02/10' }

bsToAD(year, month, day)

Converts a Bikram Sambat (BS) date to a Gregorian (AD) date.

Parameters

| Name | Type | Description | |---------|----------|--------------------------------------| | year | number | BS year (2000–2100) | | month | number | BS month (1–12) | | day | number | BS day (valid for the given month) |

Returns { year, month, day, monthName, formatted }

bsToAD(2082, 2, 10);
// → { year: 2025, month: 5, day: 24, monthName: 'May', formatted: '2025/05/24' }

todayBS()

Returns today's date converted to BS using the system clock.

todayBS();
// → { year: 2082, month: 2, day: 10, monthName: 'Jestha', formatted: '2082/02/10' }

getBSDaysInMonth(bsYear, bsMonth)

Returns the number of days in a given BS month.

getBSDaysInMonth(2082, 1); // → 31  (Baisakh 2082)

getBSDaysInYear(bsYear)

Returns the total number of days in a given BS year.

getBSDaysInYear(2082); // → 365

getBSMonthName(month)

Returns the Nepali month name for a given month number (1–12).

getBSMonthName(1);  // → "Baisakh"
getBSMonthName(9);  // → "Poush"

getADMonthName(month)

Returns the Gregorian month name for a given month number (1–12).

getADMonthName(4);  // → "April"

📅 Nepali Month Reference

| # | Nepali Month | Approx. AD Months | |---|--------------|----------------------| | 1 | Baisakh | April – May | | 2 | Jestha | May – June | | 3 | Ashadh | June – July | | 4 | Shrawan | July – August | | 5 | Bhadra | August – September | | 6 | Ashwin | September – October | | 7 | Kartik | October – November | | 8 | Mangsir | November – December | | 9 | Poush | December – January | |10 | Magh | January – February | |11 | Falgun | February – March | |12 | Chaitra | March – April |

📐 Supported Range

| Calendar | Start | End | |----------|----------------|----------------| | BS | 2000/01/01 | 2100/12/30 | | AD | 1943/04/14 | ~2044/04/13 |

Note: Calendar data for BS 2000–2090 is sourced from the authoritative bikram-sambat npm package. Data for BS 2091–2100 is estimated and may differ slightly from Nepal's official Patro once those years are officially published.

⚠️ Error Handling

All functions throw a RangeError for invalid or out-of-range inputs. It's good practice to wrap calls in a try/catch:

const { adToBS } = require('@suwi/dateconverter');

try {
  const result = adToBS(1900, 1, 1); // Before supported range
} catch (err) {
  console.error(err.message);
  // "AD 1900/1/1 is before the supported start (AD 1943/04/14 = BS 2000/01/01)."
}

Common errors:

• BS/AD year is outside the supported range
• Month is not between 1 and 12
• Day exceeds the maximum for that month (BS months vary between 29–32 days)

🏗️ How It Works

The converter uses a reference anchor point:

BS 2000/01/01  =  AD 1943/04/14

From there, it counts days forward or backward using a complete per-year, per-month lookup table (BS_CALENDAR). Because the Bikram Sambat calendar does not follow a fixed mathematical rule (unlike the Gregorian leap year system), this table-driven approach is the standard method used across Nepali date libraries.

🤝 Contributing

Contributions are welcome! If you notice discrepancies against Nepal's official Patro calendar — especially for years BS 2081 and beyond — please open an issue or pull request with the corrected data.

📄 License

ISC © Subash Gautam