digit-to-words-nepali

A TypeScript library to convert numbers into their word representations in English and Nepali languages. Supports numbers up to Adanta Singhar (10^39) with extensive currency and decimal formatting options.

Features

• Convert numbers to words in English and Nepali languages
• Support for numbers up to 999...9 (39 nines), effectively 10^39 - 1. Throws error for larger numbers or inputs with more than 39 digits (ignoring leading zeros).
• Native BigInt support for large numbers
• High-performance optimizations:
  • LRU caching for frequently converted values
  • Efficient singleton converter instances via factory pattern
  • Binary search algorithm for scale lookup (O(log n) complexity)
• Currency formatting with custom currency names
• Decimal number handling with configurable formats and refined rounding/zero logic
• Individual decimal digit pronunciation: Choose between individual digits ("तीन तीन") or combined numbers ("तेत्तिस") for decimal places
• Language-specific defaults
• Zero external dependencies
• Strict input validation
• Fully tested with comprehensive test cases

Installation

npm install digit-to-words-nepali

Usage Examples

Basic Usage

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

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

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

// Zero
digitToNepaliWords(0);
// Output: "शून्य"

Currency Formatting

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

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

Large Numbers

// Large number (1 Arab)
digitToNepaliWords(BigInt("1000000000"));
// Output: "एक अरब"

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

// Very large number (1 Padma)
digitToNepaliWords(BigInt("1" + "0".repeat(15)));
// Output: "एक पद्म"

// Maximum supported number (39 nines)
const maxSupported = BigInt("9".repeat(39));
digitToNepaliWords(maxSupported);
// Output: "उनान्सय महासिंघर उनान्सय सिंघर ... नौ सय उनान्सय"

// Numbers larger than 10^39 - 1 will throw an error
try {
  digitToNepaliWords(BigInt("1" + "0".repeat(39))); // 1 followed by 39 zeros
} catch (e) {
  console.error(e.message); // Output: Input exceeds maximum supported value (10^39 - 1)
}

// Complex large number with English output
digitToNepaliWords(BigInt("987654321987654321"), { lang: "en" });
// Output: "nine shankha eighty seven padma sixty five neel forty three
//          kharab twenty one arab ninety eight crore seventy six lakh
//          fifty four thousand three hundred twenty one"

// Complex large number with Nepali output
digitToNepaliWords(BigInt("987654321987654321"));
// Output: "नौ शंख सतासी पद्म पैंसट्ठी नील त्रिचालीस खरब एक्काइस अरब अन्ठान्नब्बे करोड
//          छयहत्तर लाख चवन्न हजार तीन सय एक्काइस"

Working with Negative Numbers

The library focuses on positive number conversion. For negative numbers, use this pattern:

// Handle negative numbers in your application logic:
const num = -123;
const prefix = num < 0 ? "ऋणात्मक" : "";
const words = digitToNepaliWords(Math.abs(num));
console.log(`${prefix} ${words}`);
// Output: "ऋणात्मक एक सय तेइस"

Decimal Handling

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

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

// Force combined decimal digits for non-currency
digitToNepaliWords(1255556.33, { 
  individualDecimalDigits: false,
  includeDecimal: true 
});
// Output: "बाह्र लाख पचपन्न हजार पाँच सय छपन्न दशमलव तेत्तिस"

// Custom decimal suffix with individual digits
digitToNepaliWords(1.23, {
  lang: "en",
  includeDecimal: true,
  decimalSuffix: "point"
});
// Output: "one point two three"

// Custom decimal suffix with combined digits
digitToNepaliWords(1.23, {
  lang: "en",
  includeDecimal: true,
  individualDecimalDigits: false,
  decimalSuffix: "point"
});
// Output: "one point twenty three"

Decimal Handling Rules

The library follows these rules for decimal places:

1. Rounding: If there are more than 2 decimal places, the number is rounded to 2 decimal places using standard rounding rules (>= .005 rounds up).

   digitToNepaliWords(1.567, { includeDecimal: true })
   // => "एक दशमलव सन्ताउन्न"  (rounds to 1.57)
   
   digitToNepaliWords(1.999, { includeDecimal: true })
   // => "दुई"  (rounds to 2.00)
   
   digitToNepaliWords(0.009, { includeDecimal: true })
   // => "शून्य दशमलव एक" (rounds to 0.01)
   
   digitToNepaliWords(0.001, { includeDecimal: true })
   // => "शून्य" (rounds to 0.00)

2. Padding: Single decimal digits are padded with a zero after rounding.

   digitToNepaliWords(1.5, { includeDecimal: true })
   // => "एक दशमलव पचास"  (pads to 1.50)

3. Zero Decimals: If the decimal part becomes 00 after rounding, it is omitted from the output unless the integer part is also zero.

   digitToNepaliWords(1.001, { includeDecimal: true })
   // => "एक" (rounds to 1.00, decimal omitted)
   
   digitToNepaliWords(0.001, { includeDecimal: true })
   // => "शून्य" (rounds to 0.00, decimal omitted)

4. Currency Format: These rules apply to both regular and currency formats.

   digitToNepaliWords(1.567, {
     isCurrency: true,
     includeDecimal: true
   })
   // => "रुपैयाँ एक पैसा सन्ताउन्न"  (rounds to 1.57)
   
   digitToNepaliWords(1.5, {
     isCurrency: true,
     includeDecimal: true
   })
   // => "रुपैयाँ एक पैसा पचास"  (pads to 1.50)
   
   digitToNepaliWords(0.009, { isCurrency: true, includeDecimal: true })
   // => "रुपैयाँ शून्य पैसा एक" (rounds to 0.01)

Individual vs Combined Decimal Digits

The library now supports two modes for pronouncing decimal digits:

1. Individual Digits (Default for non-currency): Each decimal digit is pronounced separately

   digitToNepaliWords(1255556.33)
   // => "बाह्र लाख पचपन्न हजार पाँच सय छपन्न दशमलव तीन तीन"
      
   digitToNepaliWords(1.05)
   // => "एक दशमलव शून्य पाँच"

2. Combined Digits (Default for currency): Decimal digits are treated as a single number

   digitToNepaliWords(1255556.33, { isCurrency: true })
   // => "रुपैयाँ बाह्र लाख पचपन्न हजार पाँच सय छपन्न पैसा तेत्तिस"
      
   digitToNepaliWords(1.05, { individualDecimalDigits: false })
   // => "एक दशमलव पाँच"

3. Override Behavior: You can control this behavior using the individualDecimalDigits option

   // Force combined digits for non-currency
   digitToNepaliWords(1.33, { individualDecimalDigits: false })
   // => "एक दशमलव तेत्तिस"
      
   // Force individual digits for currency (unusual but possible)
   digitToNepaliWords(1.33, { isCurrency: true, individualDecimalDigits: true })
   // => "रुपैयाँ एक पैसा तीन तीन"

Configuration Options

Basic Configuration

interface ConverterConfig {
  lang?: "en" | "ne";           // Output language (default: "ne")
  isCurrency?: boolean;         // Format as currency (default: false)
  includeDecimal?: boolean;     // Include decimal part (default: true)
  individualDecimalDigits?: boolean; // Spell decimal digits individually (default: true for non-currency, false for currency)
  currency?: string;            // Custom currency text (empty string omits prefix)
  decimalSuffix?: string;       // Custom decimal suffix (empty string omits suffix)
  currencyDecimalSuffix?: string; // Custom currency decimal suffix (empty string omits suffix)
  units?: Record<number, CustomMapping>;    // Custom number words
  scales?: Record<number, CustomMapping>;   // Custom scale words
}

// CustomMapping type for language-specific text
type CustomMapping = {
  en: string;  // English text
  ne: string;  // Nepali text
};

Custom Mappings Example

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

Default Values

Nepali (lang: "ne")

{
  currency: "रुपैयाँ",
  decimalSuffix: "दशमलव",
  currencyDecimalSuffix: "पैसा"
}

English (lang: "en")

{
  currency: "Rupees",
  decimalSuffix: "point",
  currencyDecimalSuffix: "paisa"
}

Best Practices

1. Migration from v0.1.1 and earlier: The default decimal behavior changed in v0.1.2. If you need the old combined decimal behavior for non-currency numbers, set individualDecimalDigits: false:

   // Old behavior (v0.1.1 and earlier)
   digitToNepaliWords(1.33) // => "एक दशमलव तेत्तिस"
       
   // New behavior (v0.1.2+)
   digitToNepaliWords(1.33) // => "एक दशमलव तीन तीन"
       
   // To get old behavior in v0.1.2+
   digitToNepaliWords(1.33, { individualDecimalDigits: false })
   // => "एक दशमलव तेत्तिस"

2. For large numbers (> Number.MAX_SAFE_INTEGER or near the 39-digit limit), use BigInt strings or BigInt literals:

3. For large numbers (> Number.MAX_SAFE_INTEGER or near the 39-digit limit), use BigInt strings or BigInt literals:

   digitToNepaliWords(BigInt("12345678901234567890")); // Use BigInt
   digitToNepaliWords("9".repeat(39)); // Use string for max value

4. Handle potential errors, especially for invalid inputs or numbers exceeding the maximum supported value:

   try {
     // These will throw errors
     digitToNepaliWords(-123);        // Negative numbers
     digitToNepaliWords("abc");       // Non-numeric input
     digitToNepaliWords("1.2a");      // Invalid decimal
     digitToNepaliWords(NaN);         // NaN
     digitToNepaliWords(Infinity);    // Infinity
     digitToNepaliWords("1".repeat(40)); // Exceeds max length/value
   } catch (error) {
     console.error(error.message);
   }

5. For currency values, typically set both flags:

   digitToNepaliWords(amount, {
     isCurrency: true,
     includeDecimal: true, // Usually desired for currency
   });

6. The library relies on standard parseFloat and BigInt behavior for parsing strings. Ensure your string inputs are valid representations.

Number Scale Support

The library supports numbers up to 10^39 - 1. Here's the complete scale used:

| Power | English | Nepali | Example | | ----- | -------------- | ----------- | ----------------------------------------------------------- | | 10^2 | hundred | सय | 100 | | 10^3 | thousand | हजार | 1,000 | | 10^5 | lakh | लाख | 1,00,000 | | 10^7 | crore | करोड | 1,00,00,000 | | 10^9 | arab | अरब | 1,00,00,00,000 | | 10^11 | kharab | खरब | 1,00,00,00,00,000 | | 10^13 | neel | नील | 1,00,00,00,00,00,000 | | 10^15 | padma | पद्म | 1,00,00,00,00,00,00,000 | | 10^17 | shankha | शंख | 1,00,00,00,00,00,00,00,000 | | 10^19 | udpadh | उपाध | 1,00,00,00,00,00,00,00,00,000 | | 10^21 | ank | अंक | 1,00,00,00,00,00,00,00,00,00,000 | | 10^23 | jald | जल्द | 1,00,00,00,00,00,00,00,00,00,00,000 | | 10^25 | madh | मध | 1,00,00,00,00,00,00,00,00,00,00,00,000 | | 10^27 | paraardha | परार्ध | 1,00,00,00,00,00,00,00,00,00,00,00,00,000 | | 10^29 | ant | अन्त | 1,00,00,00,00,00,00,00,00,00,00,00,00,00,000 | | 10^31 | maha ant | महाअन्त | 1,00,00,00,00,00,00,00,00,00,00,00,00,00,00,000 | | 10^33 | shishant | शिशान्त | 1,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,000 | | 10^35 | singhar | सिंघर | 1,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,000 | | 10^37 | maha singhar | महासिंघर | 1,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,000 | | 10^39 | adanta singhar | अदन्त सिंघर | 1,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,000 |

License

BSD 3-Clause License - see LICENSE file for details.

Contributing

Contributions welcome! Please check our contributing guidelines.

Support

For issues and questions, please open an issue.