🇳🇵 Mero Nepali Utils

⚡ Quick Example

import { MeroDate } from "mero-nepali-utils"; 
const d = MeroDate("2024-04-13"); 
d.toBS(); // "2081-01-01" 
d.format("YYYY MMMM DD"); // "2081 बैशाख 01"
Copy

---

⚡ Fast, accurate Nepali date library for BS ↔ AD conversion, formatting, and localization

---

🚀 Why Mero Nepali Utils?

Most Nepali date libraries are:

• ❌ Slow (linear search)
• ❌ Inaccurate (date drift)
• ❌ Hard to use

Mero Nepali Utils is different:

• ⚡ O(log n) conversion (faster than most libraries)
• 🎯 Accurate BS data (2000–2090)
• 🧠 Modern API (like dayjs)
• 🔢 Built-in Nepali number conversion
• 🌐 Localization support (NP / EN)
• 🧠 TypeScript-first (fully typed)
• 🪶 < 5KB gzipped
• 📦 Tree-shakable

Unlike most libraries, this avoids iterative date calculations and uses precomputed offsets + binary search for speed and accuracy.

💡 Why this exists

Handling Nepali dates in JavaScript has always been painful. This library was built to provide:

• accurate conversion
• clean developer experience
• modern API

without hacks or inconsistencies.

---

📦 Installation

npm install mero-nepali-utils
Copy

Core Concepts (Important)

Always store dates in AD

// GOOD 
 createdAt = "2024-04-13"; 
// Convert only in UI 
 MeroDate(createdAt).toBS();
Copy

Don’t store BS in database

• Causes bugs
• Hard to integrate with APIs
• Not standard

Quick Start

import { MeroDate } from "mero-nepali-utils";

const date = MeroDate("2024-04-13");

// Convert
date.toBS(); // "2081-01-01"

// Format
date.format("YYYY MMMM DD", { locale: "np" });
// "2081 बैशाख 01"

// Add / subtract
date.addDays(5).toBS();

// Relative
date.fromNow();
Copy

🔁 Date Conversion

AD => BS

import { meroBs } from "mero-nepali-utils";

meroBs("2024-04-13");
// "2081-01-01"
Copy

BS => AD

import { meroAd } from "mero-nepali-utils";

meroAd("2081-01-01");
// "2024-04-13"
Copy

Formatting

Supports customizable tokens like YYYY, YY, MMMM, MM, M, DD, D for flexible UI formatting.

const d = MeroDate("2024-04-13");

d.format("YYYY-MM-DD") // 2081-01-01
d.format("DD/MM/YYYY") // 01/01/2081
d.format("DD MMMM YYYY") // 01 बैशाख 2081
Copy

Locale

MeroDate.locale("np");
d.format("MMMM"); // बैशाख

MeroDate.locale("en");
d.format("MMMM"); // Baishakh
Copy

Number Conversion

import { toNepaliNumber, toEnglishNumber } from "mero-nepali-utils";
toNepaliNumber(123); // १२३
toEnglishNumber("१२३"); // 123
Copy

📅 MeroDate (Powerful API)

Inspired by modern libraries like dayjs.

const d = MeroDate("2024-01-01");

d.toBS(); // 2080-09-16
d.toAD(); // 2024-01-01

d.addDays(5).toAD(); // 2024-01-06
d.subtractDays(5).toAD(); // 2023-12-27

d.clone(); // new instance
d.valueOf(); // timestamp
Copy

React Usage (VERY IMPORTANT)

//this will crash because React cannot render objects. 
<p>{d.addDays(5)}</p>

// Correct Way
<p>{d.addDays(5).toBS()}</p> 
<p>{d.format("DD MMM YYYY")}</p>
Copy

🔌 Plugins (Auto-enabled)

No setup needed — everything works out of the box.

• diff()

d.diff("2024-01-01", "days"); // 4
d.diff("2024-01-01", "months"); // 0
Copy

• isSame()

d.isSame("2024-01-01"); // true
d.isSame("2024-01-01", "month"); // true
Copy

• isBetween()

d.isBetween("2024-01-01", "2024-01-10"); // true

// inclusive
d.isBetween("2024-01-01", "2024-01-10", "[]");
Copy

-isToday()

MeroDate().isToday(); // true
Copy

• Relative Time

d.fromNow(); // "5 days ago" 
d.toNow(); // "in 5 days" 
d.from("2024-01-01");
Copy

-startOf / endOf

d.startOf("month").toBS(); // start of month
d.endOf("month").toBS(); // end of month

d.startOf("year").toBS(); 
d.endOf("year").toBS();
Copy

🔁 Data Integrity

import { isRoundTripValid } from "mero-nepali-utils";
isRoundTripValid("2081-01-01"); //true
Copy

• No Drift
• No Mutation
• Fully deterministic

How It Works

• Uses precomputed BS calendar data
• Converts using day offsets (no loops)
• Binary search for fast lookup 👉 Result:
• Fast
• Accurate
• Predictable

📁 Supported Range

• BS: 2000 → 2090
• AD: 1943 → 2033

🛠️ Use Cases

• 🇳🇵 Nepali SaaS apps
• 📊 Dashboards
• 🧾 Billing Systems
• 🧾 Invoice systems
• 🏦 Fintech apps
• 📅 Date pickers
• 🌐 Localization

⚖️ Comparison

Feature	Mero Nepali Utils	Others
Speed	⚡ O(log n)	❌ Linear
Accuracy	✅ Verified	⚠️ Drift
API	🧠 Modern	❌ Outdated
Size	🪶 Small	⚠️ Bigger
TypeScript	✅ Full	⚠️ Partial

Advanced: Custom Plugin

const myPlugin = (cls) => { 
  cls.prototype.hello = function () {
     return "Hello"; 
   }; 
 }; 
 MeroDate.extend(myPlugin); 
 MeroDate().hello(); // Hello
Copy

Why not use JavaScript Date?

JavaScript's native Date does not support Bikram Sambat (BS).

This library provides:

• BS ↔ AD conversion
• Nepali month names
• Nepali number formatting

👉 All with accurate calendar data

Used In Production

Running in real-world Nepali applications

• merokarya.com

👨 Author

• sakarkhadka.com.np

📚 API Documentation

• API DOCS LIVE URL

📦 Version

Actively maintained and production-ready.

🔍 Keywords

nepali date, nepali date converter, bikram sambat, bs to ad converter, ad to bs converter, nepali calendar js, nepali date javascript, nepali date npm, nepali date library, bs calendar conversion, nepali localization, devanagari numbers, nepali number converter, nepali date formatter

📄 License

MIT © Sakar Khadka