# digit-to-words-nepali: Converting Numbers to Nepali Words, Properly

If you've ever built a billing system, an invoice generator, or a cheque-printing tool for a Nepali audience, you already know the pain: turning `1234` into "एक हजार दुई सय चौँतिस" is not a simple lookup table. Nepali numbering follows the Indian numbering system (hundred, thousand, lakh, crore, arab, kharab...) rather than the Western one (hundred, thousand, million, billion), and the words themselves change based on context — currency, decimals, and scale all have their own quirks.

That's the problem [**digit-to-words-nepali**](https://www.npmjs.com/package/digit-to-words-nepali) sets out to solve — a zero-dependency TypeScript library that converts numbers into their word form in both Nepali and English.

## Why Another Number-to-Words Library?

A quick search on npm turns up a handful of Nepali number-to-words packages, but most stop at basic conversion and don't hold up once you need currency formatting, decimals, or genuinely large numbers. `digit-to-words-nepali` was built to go further:

*   **Massive scale support** — it converts non-negative numbers all the way up to `10^41 - 1` (99 अदन्त सिंघर / adanta singhar), using the full traditional Nepali scale: हजार, लाख, करोड, अरब, खरब, नील, पद्म, शंख, and beyond.
    
*   **BigInt-native** — once you're past `Number.MAX_SAFE_INTEGER`, regular JavaScript numbers lose precision. The library accepts `number`, numeric `string`, and `bigint` inputs, so you can safely pass astronomically large values.
    
*   **Currency and decimal formatting** — built-in support for रुपैयाँ/पैसा style output, with configurable currency names and decimal suffixes.
    
*   **Two decimal reading modes** — decimals can be read digit-by-digit ("तीन तीन") or as a combined number ("तेत्तिस"), which matters a lot depending on whether you're reading a decimal quantity or a currency amount.
    
*   **Performance-minded internals** — LRU caching for repeated conversions, singleton converter instances via a factory pattern, and a binary-search scale lookup for O(log n) performance instead of a linear scan.
    
*   **Digit transliteration helpers** — utilities to convert between English and Unicode Nepali digits, independent of the word conversion itself.
    
*   **Zero dependencies**, full TypeScript types, and a solid test suite.
    

## Installation

```shell
npm install digit-to-words-nepali
```

## Basic Usage

```typescript
import { digitToNepaliWords } from "digit-to-words-nepali";

digitToNepaliWords(1234);
// "एक हजार दुई सय चौँतिस"

digitToNepaliWords(1234, { lang: "en" });
// "one thousand two hundred thirty four"

digitToNepaliWords(0);
// "शून्य"
```

One function, one config object — that's the whole surface area for the common case.

## Currency Formatting

Invoices and receipts are probably the single biggest use case for a library like this, so currency formatting is a first-class option rather than something you bolt on yourself:

```typescript
digitToNepaliWords(1234.5, {
  isCurrency: true,
  includeDecimal: true,
});
// "रुपैयाँ एक हजार दुई सय चौँतिस पैसा पचास"

digitToNepaliWords(1234.05, {
  lang: "en",
  isCurrency: true,
  includeDecimal: true,
  currency: "dollars",
  currencyDecimalSuffix: "cents",
});
// "dollars one thousand two hundred thirty four cents five"
```

Because `currency` and `currencyDecimalSuffix` are configurable strings, the same engine works for Nepali rupees, US dollars, or any currency you define — you're not locked into रुपैयाँ.

## Handling Genuinely Large Numbers

This is where the library distinguishes itself. The traditional Nepali numbering system keeps going well past what most libraries bother to support:

```typescript
// 1 Arab
digitToNepaliWords(BigInt("1000000000"));
// "एक अरब"

// 12 Kharab 34 Arab 56 Crore 78 Lakh 90 Thousand
digitToNepaliWords(BigInt("1234567890000"));
// "बाह्र खरब चौँतिस अरब छपन्न करोड अठहत्तर लाख नब्बे हजार"

// 1 Padma (10^15)
digitToNepaliWords(BigInt("1" + "0".repeat(15)));
// "एक पद्म"

// Top of the scale table (10^39)
digitToNepaliWords(BigInt("1" + "0".repeat(39)));
// "एक अदन्त सिंघर"
```

Feed it something past the supported range and it fails loudly instead of silently producing garbage:

```typescript
try {
  digitToNepaliWords(BigInt("1" + "0".repeat(41)));
} catch (e) {
  console.error(e.message);
  // "Input exceeds maximum supported value (10^41 - 1)"
}
```

The full scale table, from सय (hundred) up to अदन्त सिंघर (10^39), is documented in the README — useful as a reference even outside the context of this library.

## Decimal Handling Done Carefully

Decimals in Nepali can be read two different ways depending on context, and the library treats this as a real design decision rather than an afterthought:

```typescript
// Individual digits (default for non-currency)
digitToNepaliWords(1255556.33);
// "बाह्र लाख पचपन्न हजार पाँच सय छपन्न दशमलव तीन तीन"

// Combined digits (default for currency)
digitToNepaliWords(1255556.33, { isCurrency: true });
// "रुपैयाँ बाह्र लाख पचपन्न हजार पाँच सय छपन्न पैसा तेत्तिस"
```

Rounding, zero-decimal omission, and padding all follow explicit, documented rules — for example, `1.999` correctly rounds up to `"दुई"`, and `0.001` rounds down to `"शून्य"` with the decimal part omitted entirely rather than reading out a stray "दशमलव शून्य शून्य".

## Custom Mappings

If you need different vocabulary — a regional dialect, a stylistic variant, or a completely custom scale — you can override the defaults per call:

```typescript
digitToNepaliWords(1234, {
  units: {
    1: { ne: "एक्का", en: "ekka" },
    2: { ne: "दुक्का", en: "dukka" },
  },
  scales: {
    1000: { ne: "हज्जार", en: "hazzar" },
  },
});
```

## Digit Transliteration

Separate from word conversion, the library also ships small helpers for converting between ASCII and Nepali (Devanagari) digits:

```typescript
import {
  englishToUnicodeNumber,
  unicodeToEnglishNumber,
} from "digit-to-words-nepali";

englishToUnicodeNumber(2081);   // "२०८१"
unicodeToEnglishNumber("२०८१"); // 2081
```

## When Would You Reach for This?

*   Invoice, receipt, and cheque generation for Nepali businesses
    
*   Government or fintech systems that need to spell out amounts in words (a common legal/formatting requirement)
    
*   Localized UI components that display quantities or prices in Nepali
    
*   Any Nepal-focused SaaS product that needs number-to-word conversion without pulling in a heavy dependency
    

## Wrapping Up

`digit-to-words-nepali` is a good example of taking a seemingly small utility — "turn a number into words" — and actually handling the edge cases that make Nepali number formatting hard: the traditional scale beyond lakh and crore, currency-specific decimal reading, rounding rules, and safe handling of numbers too large for a JavaScript `number`. Zero dependencies and full TypeScript types make it easy to drop into any Node or browser project.

```shell
npm install digit-to-words-nepali
```

Check it out on [npm](https://www.npmjs.com/package/digit-to-words-nepali) or browse the source on [GitHub](https://github.com/codernirdesh/digit-to-words-nepali).