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
• Currency formatting with custom currency names
• Decimal number handling with configurable formats and refined rounding/zero logic
• 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

// Regular decimal
digitToNepaliWords(1.23, { 
  includeDecimal: true 
});
// Output: "एक दशमलव तेइस"

// Custom decimal suffix
digitToNepaliWords(1.23, {
  lang: "en",
  includeDecimal: true,
  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)

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)
  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. 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

2. 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);
   }

3. For currency values, typically set both flags:

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

4. 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:

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.