@lacspace/nepali-utils

Everyday helpers for Nepal-facing apps — rupees, numerals, amount-in-words, validators, provinces.

The little things every Nepali app re-implements — done once, done right.

New in 1.5.0 — amountInWords, amountInWordsNepali and amountInWordsNepaliRoman accept a decimal string ("99999999999999.01", "Rs. 12,34,567.50", Devanagari digits) or exact parts ({ rupees: 99999999999999, paisa: 1 }), so paisa stays exact beyond ~13 rupee digits; the parser is exported as splitAmount. Number input works as before.

1.4.1 — re-release of 1.4.0 through CI so it carries an npm provenance attestation (npm audit signatures). No code changes.

New in 1.4.0 — नील / Neel (1e13) and पद्म / Padma (1e15) scales; { decimals } option on sqMetersToRopani / sqMetersToBigha (keep fractional daam/dhur with correct carry); plates like "Bagmati Pradesh 01-002 Pa 1234", "Gandaki Province B AB 0123", "Pradesh No 3 …", and province numbers outside 1–7 now rejected; isValidNepaliMobile now always agrees with normalizeMobile. Note: numberToWords(1e13) reads "One Neel".

New in 1.3.0 — fixes from real-world use in a Nepali news app: खरब / Kharab scale (1e11) in every amount-in-words and compact formatter; a "र" / "ra" separator between rupees and paisa; exact land-unit ratios (1 ropani = 256 daam exactly) and carry-correct sqMetersToBigha / sqMetersToRopani (20 dhur → 1 kattha, never "4 daam"); embossed number plates ("BAGMATI B AB 0123", "Ba 1 Pa 1234", "प्रदेश ३ ख ०१२३") in isValidVehiclePlate; Devanagari digits in isValidLandline / isValidPAN; capitalNp on every province; district aliases with the official Nawalparasi East / West (Bardaghat Susta) names (old "Nawalpur" / "Parasi" still resolve); Ncell 970 plus CARRIER_PREFIXES / CARRIER_STATUS (Smart Cell and UTL marked defunct).

⚠️ Output changes to note when upgrading: amountInWordsNepali(1500.5) now reads "… पाँच सय र पचास पैसा मात्र"; numberToWords(1e11) reads "One Kharab" (was "One Hundred Arab"); the two Nawalparasi districts' name fields are now "Nawalparasi East" / "Nawalparasi West" (lookups by the old names still work).

New in 1.2.0 — transliterated (Roman) Nepali amount-in-words (numberToWordsNepaliRoman / amountInWordsNepaliRoman), integer-paisa NPR format/parse (formatNPRFromPaisa / parseNPRToPaisa, no float drift), toNepaliDigits / toEnglishDigits aliases, extra shape validators (isValidVehiclePlate, isValidCitizenshipNumber), and province lookups (findProvince, provinceOfDistrict). All additive & backward compatible.

• 💰 NPR formatting with lakh/crore grouping
• 🔢 Devanagari ↔ Arabic numerals
• 🧾 Amount-in-words for invoices
• ✅ Phone / PAN validators
• 🗺️ The 7 federal provinces
• ⚡ Zero dependencies · 🌍 isomorphic · 📦 ESM + CJS · fully typed

Install

npm install @lacspace/nepali-utils      # or pnpm add / yarn add / bun add

Currency & numbers

import { formatNPR, groupNepali, toDevanagari, fromDevanagari } from "@lacspace/nepali-utils";

formatNPR(1234567.5);                                    // "Rs. 12,34,567.50"
formatNPR(1234567.5, { symbol: "रू ", devanagari: true }); // "रू १२,३४,५६७.५०"
formatNPR(50000, { decimals: 0, symbol: "" });           // "50,000"

groupNepali(1234567);   // "12,34,567"  (South-Asian grouping)
toDevanagari("2081");   // "२०८१"
fromDevanagari("२०८१"); // "2081"

Amount in words (for invoices)

import { numberToWords, amountInWords } from "@lacspace/nepali-utils";

numberToWords(1234567);
// "Twelve Lakh Thirty Four Thousand Five Hundred Sixty Seven"

amountInWords(1234567.75);
// "Rupees Twelve Lakh Thirty Four Thousand Five Hundred Sixty Seven and Seventy Five Paisa Only"

Validators

import { isValidNepaliMobile, isValidPAN } from "@lacspace/nepali-utils";

isValidNepaliMobile("9812345678");     // true
isValidNepaliMobile("+9779812345678"); // true
isValidNepaliMobile("1234567890");     // false
isValidPAN("123456789");               // true (9 digits)

Provinces

import { PROVINCES } from "@lacspace/nepali-utils";

PROVINCES[2];
// { number: 3, name: "Bagmati", nameNp: "बागमती", capital: "Hetauda", capitalNp: "हेटौँडा" }

API

| Function | Description | | --- | --- | | formatNPR(amount, opts?) | NPR string · opts: symbol, decimals, devanagari | | groupNepali(value) | South-Asian digit grouping | | toDevanagari / fromDevanagari | numeral conversion | | numberToWords(n) | words with Lakh / Crore / Arab | | amountInWords(n) | "Rupees … Only" wrapper | | isValidNepaliMobile / isValidPAN | validators | | PROVINCES | the 7 federal provinces | | numberToWordsNepaliRoman(n) | Roman-transliterated Nepali words | | amountInWordsNepaliRoman(n) | "Rupaiyan … Matra" wrapper (Roman) | | parseNPRToPaisa(str) | NPR string → integer paisa (no float drift) | | formatNPRFromPaisa(paisa, opts?) | integer paisa → NPR string | | toNepaliDigits / toEnglishDigits | numeral aliases (Devanagari ↔ Arabic) | | isValidVehiclePlate / isValidCitizenshipNumber | shape validators | | findProvince(numOrName) | province lookup | | provinceOfDistrict(name) | district → province |

The Lacspace family

| Package | For | | --- | --- | | @lacspace/nepali-date | Bikram Sambat dates | | @lacspace/nepali-utils | Nepal helpers (this package) | | @lacspace/sdk | Full Lacspace platform SDK | | @lacspace/react | React hooks |

New in 1.1 — land units, carriers, districts & Nepali words

import {
  landToSqMeters, sqMetersToRopani, convertLand, formatRopani,
  normalizeMobile, getCarrier, ungroupNepali, formatCompactNPR,
  DISTRICTS, districtsByProvince, findDistrict,
  numberToWordsNepali, amountInWordsNepali,
} from "@lacspace/nepali-utils";

// Land area — the thing nobody else packages (hilly ↔ terai ↔ metric)
const m2 = landToSqMeters({ ropani: 2, aana: 3 });   // → 1078.9 m²
sqMetersToRopani(m2);                                  // { ropani: 2, aana: 3, paisa: 0, daam: 0 }
convertLand(1, "bigha", "kattha");                    // 20
formatRopani(m2);                                      // "2-3-0-0"

// Phones
normalizeMobile("984-123 4567");                       // "+9779841234567"
getCarrier("9801234567");                              // "Ncell"  (970 too; see CARRIER_PREFIXES / CARRIER_STATUS)

// Money & geography
ungroupNepali("Rs. 12,34,567.50");                     // 1234567.5
formatCompactNPR(1234567, { nepali: true });           // "Rs. 12.35 लाख"
districtsByProvince(3);                                 // 13 Bagmati districts
findDistrict("काठमाडौं")?.province;                    // 3

// Invoices in Nepali
amountInWordsNepali(1500.5);  // "रुपैयाँ एक हजार पाँच सय र पचास पैसा मात्र"

New in 1.2 — Roman words, integer-paisa NPR, more validators & lookups

import {
  numberToWordsNepaliRoman, amountInWordsNepaliRoman,
  parseNPRToPaisa, formatNPRFromPaisa,
  toNepaliDigits, toEnglishDigits,
  isValidVehiclePlate, isValidCitizenshipNumber,
  findProvince, provinceOfDistrict,
} from "@lacspace/nepali-utils";

// Nepali reading, in Latin letters (for receipts, SMS, ASCII-only contexts)
numberToWordsNepaliRoman(1234567); // "Bahra Lakh Chauntis Hajar Panch Saya Satsatthi"
amountInWordsNepaliRoman(1500.5);  // "Rupaiyan Ek Hajar Panch Saya Pachas Paisa Matra"

// Money as integer paisa — exact, no floating-point drift
parseNPRToPaisa("Rs. 12,34,567.50");     // 123456750
formatNPRFromPaisa(123456750);           // "Rs. 12,34,567.50"
formatNPRFromPaisa(123456750, { devanagari: true }); // "Rs. १२,३४,५६७.५०"

// Digit aliases
toNepaliDigits("2081");   // "२०८१"
toEnglishDigits("२०८१");  // "2081"

// Shape validators (format only, not registry lookups)
isValidVehiclePlate("Ba 2 Kha 1234");      // true
isValidCitizenshipNumber("12-01-73-01234"); // true

// Geography lookups
findProvince("bagmati")?.number;         // 3
provinceOfDistrict("Kathmandu")?.name;   // "Bagmati"

Licensing

This package is free under the Lacspace Free Licence — permissive freedoms. Use it in personal and commercial projects at no cost; just keep the notice.

Not every Lacspace package is free. We also offer Commercial (paid), Client-specific, and Private (proprietary) packages under separate terms. See the full Lacspace Licence Centre.

The Lacspace Developer Platform

@lacspace/nepali-utils is part of 80+ zero-dependency, isomorphic TypeScript packages — one standard library for the modern web. Explore the ecosystem:

• 📦 This package, documented — https://developer.lacspace.com/packages/nepali-utils
• 🗂️ All 80+ packages — https://developer.lacspace.com/packages
• 🧭 Developer handbook — guides & runnable recipes — https://developer.lacspace.com/handbook
• 🧪 Live playground — run any package in your browser — https://developer.lacspace.com/playground
• 🖥️ Finished app templates — https://templates.lacspace.com
• 🚀 Scaffold a full app — npm create lacspace-app@latest

Free under the Lacspace Free Licence — a permissive, free-to-use licence.

1.6.0

• Fix: groupNepali keeps decimals: groupNepali(2587.25) → "2,587.25". It used to return "2,58,725".
• formatCompactNPR(n, { style: "long", decimals: 2 }) gives Rs 4.29 Arba (Thousand/Lakh/Crore/Arba/Kharba). With nepali: true, devanagari: true it gives रु ४.२९ अर्ब (हजार/लाख/करोड/अर्ब/खर्ब). The default output is unchanged.
• Nepal Standard Time (UTC+05:45):
  • toNpt(date) returns wall-clock parts plus the weekday.
  • fromNpt(y, m, d, h, min) returns the instant.
  • formatNpt(date, { time, hour12, devanagari, seconds }).
  • toNptIso(date) returns e.g. 2026-10-04T11:00:00+05:45.
  • NPT_OFFSET_MINUTES is 345.
• For Bikram Sambat ↔ AD dates, use @lacspace/nepali-date (adToBs, bsToAd, formatBs).