nemo-nwc

A comprehensive JavaScript library for number-to-words conversion with multilingual support, currency formatting, date/time conversion, and advanced text processing.

✨ Features

Core Features

• 🔢 Number to Words: Converts integers and decimals to English words
• 💰 Currency Support: 13+ currencies with proper units/subunits
• 🔢 Ordinal Numbers: Convert to ordinal words (first, second, third, etc.)
• 🏛️ Roman Numerals: Bi-directional conversion (numbers ↔ Roman numerals)
• ➗ Fraction Support: Convert fractions to words with mixed number support
• 📦 Batch Processing: Convert multiple numbers at once
• 🎨 Case Formatting: Support for lowercase, UPPERCASE, Title Case
• 🌍 Indian & Western Systems: Automatic system selection based on currency

New Advanced Features (v2.0.0)

• 🌐 Multilingual Support: Convert numbers to words in 5 languages (English, Spanish, French, German, Hindi)
• 📅 Date to Words: Convert dates to natural language (March fifteenth, twenty twenty four)
• ⏰ Time to Words: Convert time to spoken format (two thirty PM, half past ten)
• 🔬 Scientific Notation: Handle very large/small numbers
• 📊 Percentage Conversion: Convert decimals to percentage words
• 📝 Text Processing: Replace numbers in text with words
• 💵 Check Writing Format: Standard banking check format
• 📱 Compact Numbers: Modern abbreviated formats (1.5K, 2.5M, 3B)
• ↩️ Reverse Conversion: Words to number and Roman to number
• 🧮 Decimal to Fraction: Convert decimals to fraction notation
• 📞 Phone Number Formatting: Convert phone numbers to words
• 🌍 Localization Options: Regional formatting preferences
• ⚡ Performance Caching: Built-in memoization for repeated conversions
• 🎯 Zero Dependencies: Lightweight and fast
• 📦 Multiple Formats: CommonJS, ESM, and Browser builds

Install

npm install nemo-nwc

🚀 Quick Start

Basic Number Conversion

const { nemoNumberToWords } = require('nemo-nwc');

nemoNumberToWords(123); // "One hundred twenty three"
nemoNumberToWords(12345678); // "One crore twenty three lakh forty five thousand six hundred seventy eight"
nemoNumberToWords(45.67); // "Forty five point six seven"
nemoNumberToWords(-45); // "Negative forty five"

Currency Formatting

nemoNumberToWords(100.22, 'INR'); // "One hundred rupees and twenty two paise"
nemoNumberToWords(99.99, 'USD'); // "Ninety nine dollars and ninety nine cents"
nemoNumberToWords(500.75, 'AED'); // "Five hundred dirhams and seventy five fils"
nemoNumberToWords(1234567, 'GBP'); // "One million two hundred thirty four thousand five hundred sixty seven pounds"

Multilingual Support (NEW!)

const { nemoNumberToWordsMultilingual } = require('nemo-nwc');

nemoNumberToWordsMultilingual(123, 'es'); // "Ciento veintitrés" (Spanish)
nemoNumberToWordsMultilingual(123, 'fr'); // "Cent vingt trois" (French)
nemoNumberToWordsMultilingual(123, 'de'); // "Eins hundert dreiundzwanzig" (German)
nemoNumberToWordsMultilingual(123, 'hi'); // "एक सौ तेईस" (Hindi)

Date & Time Conversion (NEW!)

const { nemoDateToWords, nemoTimeToWords, nemoDateTimeToWords } = require('nemo-nwc');

nemoDateToWords('2024-03-15'); // "March fifteenth, two thousand twenty four"
nemoTimeToWords('14:30'); // "Half past two PM"
nemoTimeToWords('14:30', { format: '24h' }); // "Fourteen thirty"
nemoDateTimeToWords('2024-03-15 14:30'); // "March fifteenth, two thousand twenty four at half past two pm"

Text Processing (NEW!)

const { nemoSpelloutInText } = require('nemo-nwc');

nemoSpelloutInText('I have 5 apples and 3 oranges'); 
// "I have Five apples and Three oranges"

nemoSpelloutInText('Total: $1,234.56', { currency: 'USD' }); 
// "Total: One thousand two hundred thirty four dollars and fifty six cents"

Check Writing Format (NEW!)

const { nemoCheckFormat } = require('nemo-nwc');

nemoCheckFormat(1234.56, 'USD'); 
// "One thousand two hundred thirty four and 56/100 Dollars"

nemoCheckFormat(5000.00, 'EUR'); 
// "Five thousand and 00/100 Euros"

Compact Numbers (NEW!)

const { nemoCompactNumber, nemoCompactToWords } = require('nemo-nwc');

nemoCompactNumber(1500); // "1.5K"
nemoCompactNumber(2500000); // "2.5M"
nemoCompactNumber(3000000000); // "3.0B"

nemoCompactToWords(1500000); // "One point five million"

Reverse Conversion (NEW!)

const { nemoWordsToNumber, nemoRomanToNumber } = require('nemo-nwc');

nemoWordsToNumber('one hundred twenty three'); // 123
nemoWordsToNumber('five million'); // 5000000
nemoWordsToNumber('negative fifty'); // -50

nemoRomanToNumber('MCMXCIV'); // 1994
nemoRomanToNumber('XLII'); // 42

Fraction Support (Enhanced!)

const { 
  nemoFractionToWords, 
  nemoDecimalToFraction, 
  nemoMixedNumberToWords 
} = require('nemo-nwc');

nemoFractionToWords('1/2'); // "Half"
nemoFractionToWords('3/4'); // "Three quarters"

nemoDecimalToFraction(0.5); // "1/2"
nemoDecimalToFraction(2.75); // "2 3/4"

nemoMixedNumberToWords('2 1/2'); // "Two and half"

Percentage & Precision (NEW!)

const { nemoPercentageToWords, nemoNumberWithPrecision } = require('nemo-nwc');

nemoPercentageToWords(0.75); // "Seventy five percent"
nemoPercentageToWords(0.856, { decimalPlaces: 1 }); // "Eighty five point six percent"

nemoNumberWithPrecision(3.14159, 2); // "Three point one four"

Performance Caching (NEW!)

const { nemoNumberToWordsCached, nemoClearCache } = require('nemo-nwc');

// Cached for better performance on repeated calls
nemoNumberToWordsCached(123); // First call - computed
nemoNumberToWordsCached(123); // Second call - from cache

nemoClearCache(); // Clear cache when needed

📦 Installation & Usage

Node.js (CommonJS)

const { 
  // Core functions
  nemoNumberToWords, 
  nemoNumberToOrdinal, 
  nemoNumberToRoman,
  nemoFractionToWords,
  nemoBatchNumberToWords,
  nemoGetSupportedCurrencies,
  
  // Multilingual
  nemoNumberToWordsMultilingual,
  
  // Date & Time
  nemoDateToWords,
  nemoTimeToWords,
  nemoDateTimeToWords,
  
  // Advanced conversions
  nemoScientificToWords,
  nemoPercentageToWords,
  nemoNumberWithPrecision,
  
  // Text processing
  nemoSpelloutInText,
  nemoCheckFormat,
  
  // Compact numbers
  nemoCompactNumber,
  nemoCompactToWords,
  
  // Reverse conversions
  nemoWordsToNumber,
  nemoRomanToNumber,
  
  // Fractions
  nemoDecimalToFraction,
  nemoMixedNumberToWords,
  
  // Utilities
  nemoPhoneToWords,
  nemoNumberToWordsLocalized,
  nemoNumberToWordsCached,
  nemoClearCache
} = require('nemo-nwc');

ESM/TypeScript

import { 
  nemoNumberToWords, 
  nemoNumberToOrdinal, 
  nemoNumberToRoman,
  nemoNumberToWordsMultilingual,
  nemoDateToWords,
  nemoTimeToWords,
  nemoSpelloutInText,
  nemoWordsToNumber
} from 'nemo-nwc';

console.log(nemoNumberToWords(1234567, 'USD'));
console.log(nemoNumberToWordsMultilingual(123, 'es'));
console.log(nemoDateToWords('2024-12-25'));

Browser

<script src="dist/nemo-nwc.browser.js"></script>
<script>
  // All functions available under nemoNWC global
  const result = nemoNWC.nemoNumberToWords(1234567, 'INR');
  const ordinal = nemoNWC.nemoNumberToOrdinal(42);
  const roman = nemoNWC.nemoNumberToRoman(2024);
  const spanish = nemoNWC.nemoNumberToWordsMultilingual(100, 'es');
  const date = nemoNWC.nemoDateToWords('2024-03-15');
  const compact = nemoNWC.nemoCompactNumber(1500000);
  
  console.log(result, ordinal, roman, spanish, date, compact);
</script>

💰 Supported Currencies

| Code | Currency | Major Unit | Minor Unit | System | |------|----------|------------|------------|---------| | INR | Indian Rupee | rupee/rupees | paise | Indian (lakh, crore) | | USD | US Dollar | dollar/dollars | cent/cents | Western | | EUR | Euro | euro/euros | cent/cents | Western | | GBP | British Pound | pound/pounds | pence | Western | | JPY | Japanese Yen | yen | sen | Western (no decimals) | | AED | UAE Dirham | dirham/dirhams | fils | Western | | AUD | Australian Dollar | dollar/dollars | cent/cents | Western | | CNY | Chinese Yuan | yuan | jiao | Western | | CAD | Canadian Dollar | dollar/dollars | cent/cents | Western | | CHF | Swiss Franc | franc/francs | centime/centimes | Western | | SEK | Swedish Krona | krona/kronor | öre | Western | | NOK | Norwegian Krone | krone/kroner | øre | Western | | DKK | Danish Krone | krone/kroner | øre | Western |

// Get all supported currencies programmatically
const currencies = nemoGetSupportedCurrencies();
console.log(currencies);

📚 API Reference

Core Functions

nemoNumberToWords(number, currencyCode?, options?)

Convert numbers to English words with optional currency formatting.

Parameters:

• number (Number): The number to convert (-999,999,999,999 to 999,999,999,999)
• currencyCode (String, optional): Currency code (e.g., 'INR', 'USD', 'EUR')
• options (Object, optional): Formatting options
  • case (String): 'lower', 'upper', 'title', or default

Returns: String

Example:

nemoNumberToWords(123); // "One hundred twenty three"
nemoNumberToWords(100.50, 'USD'); // "One hundred dollars and fifty cents"

nemoNumberToOrdinal(number, options?)

Convert numbers to ordinal words (first, second, third, etc.).

Parameters:

• number (Number): The number to convert (0 to 999,999,999,999)
• options (Object, optional): Formatting options

Returns: String

nemoNumberToRoman(number)

Convert numbers to Roman numerals.

Parameters:

• number (Number): The number to convert (1 to 3999)

Returns: String

nemoFractionToWords(fraction, options?)

Convert fraction strings to English words.

Parameters:

• fraction (String): Fraction in format "numerator/denominator" (e.g., "1/2", "3/4")
• options (Object, optional): Formatting options

Returns: String

nemoBatchNumberToWords(numbers, currencyCode?, options?)

Convert multiple numbers to words in batch.

Parameters:

• numbers (Array): Array of numbers to convert
• currencyCode (String, optional): Currency code for all numbers
• options (Object, optional): Formatting options

Returns: Array of objects with { input, output, success } or { input, error, success }

nemoGetSupportedCurrencies()

Get list of all supported currencies.

Returns: Array of currency objects with code, major, minor units

Multilingual Functions

nemoNumberToWordsMultilingual(number, lang, options?)

Convert numbers to words in specified language.

Parameters:

• number (Number): The number to convert
• lang (String): Language code: 'en', 'es', 'fr', 'de', 'hi'
• options (Object, optional): Formatting options

Returns: String

Example:

nemoNumberToWordsMultilingual(123, 'es'); // "Ciento veintitrés"
nemoNumberToWordsMultilingual(123, 'fr'); // "Cent vingt trois"
nemoNumberToWordsMultilingual(123, 'de'); // "Eins hundert dreiundzwanzig"
nemoNumberToWordsMultilingual(123, 'hi'); // "एक सौ तेईस"

Language-Specific Features:

• Spanish: Special forms for 21-29 (veintiuno, veintidós...), uses "y" connector for 30+
• French: Base-20 system for 70-99 (soixante-dix, quatre-vingts), special "et" for x1 numbers
• German: Reversed order (ones before tens: einundzwanzig = one-and-twenty)
• Hindi: Unique words for each number 20-99 (तेईस, चौबीस...)

Date & Time Functions

nemoDateToWords(date, options?)

Convert date to natural language.

Parameters:

• date (String | Date): Date in 'YYYY-MM-DD' format or Date object
• options (Object, optional): Formatting options

Returns: String

Example:

nemoDateToWords('2024-03-15'); // "March fifteenth, two thousand twenty four"
nemoDateToWords(new Date('2024-12-25')); // "December twenty fifth, two thousand twenty four"

nemoTimeToWords(time, options?)

Convert time to spoken words.

Parameters:

• time (String): Time in 'HH:MM' or 'HH:MM:SS' format
• options (Object, optional):
  • format (String): '12h' (default) or '24h'

Returns: String

Example:

nemoTimeToWords('14:30'); // "Half past two PM"
nemoTimeToWords('10:00'); // "Ten o'clock AM"
nemoTimeToWords('14:30', { format: '24h' }); // "Fourteen thirty"

nemoDateTimeToWords(dateTime, options?)

Convert date and time to words.

Parameters:

• dateTime (String | Date): DateTime string or Date object
• options (Object, optional): Formatting options

Returns: String

Advanced Conversion Functions

nemoScientificToWords(number, options?)

Convert scientific notation numbers to words.

Parameters:

• number (Number): Number in scientific notation
• options (Object, optional): Formatting options

Returns: String

Example:

nemoScientificToWords(1.5e6); // "One point five times ten to the power of six"

nemoPercentageToWords(number, options?)

Convert decimal to percentage words.

Parameters:

• number (Number): Decimal number (0.75 = 75%)
• options (Object, optional):
  • decimalPlaces (Number): Decimal precision (default: 2)

Returns: String

Example:

nemoPercentageToWords(0.75); // "Seventy five percent"
nemoPercentageToWords(0.856, { decimalPlaces: 1 }); // "Eighty five point six percent"

nemoNumberWithPrecision(number, decimalPlaces, options?)

Convert number with specific decimal precision.

Parameters:

• number (Number): The number to convert
• decimalPlaces (Number): Number of decimal places (default: 2)
• options (Object, optional): Formatting options

Returns: String

Text Processing Functions

nemoSpelloutInText(text, options?)

Replace all numbers in text with their word equivalents.

Parameters:

• text (String): Text containing numbers
• options (Object, optional):
  • currency (String): Currency code for dollar amounts

Returns: String

Example:

nemoSpelloutInText('I have 5 apples'); // "I have Five apples"
nemoSpelloutInText('Total: $123.45', { currency: 'USD' }); 
// "Total: One hundred twenty three dollars and forty five cents"

nemoCheckFormat(amount, currencyCode, options?)

Format amount for check/cheque writing.

Parameters:

• amount (Number): Amount to format
• currencyCode (String): Currency code (default: 'USD')
• options (Object, optional): Formatting options

Returns: String

Example:

nemoCheckFormat(1234.56, 'USD'); 
// "One thousand two hundred thirty four and 56/100 Dollars"

Compact Number Functions

nemoCompactNumber(number, options?)

Convert number to compact format (K, M, B, T).

Parameters:

• number (Number): The number to convert
• options (Object, optional): Formatting options

Returns: String

Example:

nemoCompactNumber(1500); // "1.5K"
nemoCompactNumber(2500000); // "2.5M"
nemoCompactNumber(3000000000); // "3.0B"

nemoCompactToWords(number, options?)

Convert compact number to words.

Parameters:

• number (Number): The number to convert
• options (Object, optional): Formatting options

Returns: String

Example:

nemoCompactToWords(1500); // "One point five thousand"
nemoCompactToWords(2500000); // "Two point five million"

Reverse Conversion Functions

nemoWordsToNumber(words)

Convert words back to number.

Parameters:

• words (String): Number in words

Returns: Number

Example:

nemoWordsToNumber('one hundred twenty three'); // 123
nemoWordsToNumber('five million'); // 5000000
nemoWordsToNumber('negative fifty'); // -50

nemoRomanToNumber(roman)

Convert Roman numerals to number.

Parameters:

• roman (String): Roman numeral string

Returns: Number

Example:

nemoRomanToNumber('MCMXCIV'); // 1994
nemoRomanToNumber('XLII'); // 42

Fraction Functions

nemoDecimalToFraction(decimal, options?)

Convert decimal to fraction notation.

Parameters:

• decimal (Number): Decimal number
• options (Object, optional):
  • maxDenominator (Number): Maximum denominator (default: 100)

Returns: String

Example:

nemoDecimalToFraction(0.5); // "1/2"
nemoDecimalToFraction(0.75); // "3/4"
nemoDecimalToFraction(2.5); // "2 1/2"

nemoMixedNumberToWords(mixedNumber, options?)

Convert mixed number to words.

Parameters:

• mixedNumber (String): Mixed number like "2 1/2"
• options (Object, optional): Formatting options

Returns: String

Example:

nemoMixedNumberToWords('2 1/2'); // "Two and half"
nemoMixedNumberToWords('3 3/4'); // "Three and three quarters"

Utility Functions

nemoPhoneToWords(phone, options?)

Convert phone number to words.

Parameters:

• phone (String): Phone number
• options (Object, optional): Formatting options

Returns: String

Example:

nemoPhoneToWords('+1-555-1234'); // "Plus one five five five one two three four"

nemoNumberToWordsLocalized(number, options?)

Convert number with localization options.

Parameters:

• number (Number): The number to convert
• options (Object, optional):
  • locale (String): Locale code (default: 'en-US')
  • useAnd (Boolean): Include "and" in output (default: true)
  • currency (String): Currency code

Returns: String

nemoNumberToWordsCached(number, currencyCode?, options?)

Convert number with caching for better performance.

Parameters:

• number (Number): The number to convert
• currencyCode (String, optional): Currency code
• options (Object, optional): Formatting options

Returns: String

nemoClearCache()

Clear the conversion cache.

Returns: void

🎮 Interactive Demo

Open demo.html in your browser for an interactive demo with all features.

License

MIT

🔧 Advanced Examples

Error Handling

try {
  const result = nemoNumberToWords(1000000000000); // Out of range
} catch (error) {
  console.error(error.message); // "Number 1000000000000 is out of range"
}

// Batch processing with error handling
const results = nemoBatchNumberToWords([1, 'invalid', 3]);
results.forEach(result => {
  if (result.success) {
    console.log(`${result.input} → ${result.output}`);
  } else {
    console.error(`Error with ${result.input}: ${result.error}`);
  }
});

Custom Formatting

// Different case formats
nemoNumberToWords(1234, 'USD', { case: 'title' }); 
// "One Thousand Two Hundred Thirty Four Dollars"

nemoNumberToOrdinal(21, { case: 'upper' }); 
// "TWENTY FIRST"

nemoFractionToWords('3/8', { case: 'lower' }); 
// "three eighths"

Working with Large Numbers

// Indian system (default for INR or no currency)
nemoNumberToWords(12345678); 
// "One crore twenty three lakh forty five thousand six hundred seventy eight"

// Western system (for other currencies)
nemoNumberToWords(12345678, 'USD'); 
// "Twelve million three hundred forty five thousand six hundred seventy eight dollars"

🚨 Limitations & Ranges

| Feature | Range | Notes | |---------|-------|-------| | Number to Words | -999,999,999,999 to 999,999,999,999 | Supports decimals | | Ordinal Numbers | 0 to 999,999,999,999 | No negative ordinals | | Roman Numerals | 1 to 3999 | Standard Roman numeral range | | Fractions | Any valid fraction | Handles common fractions specially |

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. Make sure to:

1. Add tests for new features
2. Update documentation
3. Follow the existing code style
4. Ensure all tests pass

📄 Changelog

v2.0.0 (Current) - Major Feature Release 🎉

Breaking Changes: None - Fully backward compatible

New Features:

• 🌐 Multilingual Support: Convert numbers to words in 5 languages (English, Spanish, French, German, Hindi)
• 📅 Date to Words: Natural language date conversion (nemoDateToWords)
• ⏰ Time to Words: Spoken time format with 12h/24h support (nemoTimeToWords, nemoDateTimeToWords)
• 🔬 Scientific Notation: Handle very large/small numbers (nemoScientificToWords)
• 📊 Percentage Conversion: Convert decimals to percentage words (nemoPercentageToWords)
• 📝 Text Processing: Replace numbers in text with words (nemoSpelloutInText)
• 💵 Check Writing Format: Standard banking check format (nemoCheckFormat)
• 📱 Compact Numbers: Modern abbreviated formats - 1.5K, 2.5M, 3B (nemoCompactNumber, nemoCompactToWords)
• ↩️ Reverse Conversion: Words to number (nemoWordsToNumber) and Roman to number (nemoRomanToNumber)
• 🧮 Decimal to Fraction: Convert decimals to fraction notation (nemoDecimalToFraction)
• 🔢 Mixed Number Support: Convert mixed numbers to words (nemoMixedNumberToWords)
• 📞 Phone Number Formatting: Convert phone numbers to words (nemoPhoneToWords)
• 🌍 Localization Options: Regional formatting preferences (nemoNumberToWordsLocalized)
• ⚡ Performance Caching: Built-in memoization (nemoNumberToWordsCached, nemoClearCache)
• 🎯 Precision Control: Decimal precision for numbers and percentages (nemoNumberWithPrecision)

Improvements:

• ✅ 131 comprehensive tests (all passing)
• 📚 Complete API documentation with examples
• 🚀 Production-ready with extensive error handling
• 📦 Optimized bundle size (16KB minified)
• 🎨 Enhanced demo page with all new features

Languages Supported:

• English (en)
• Spanish (es)
• French (fr)
• German (de)
• Hindi (hi)

v1.1.0

• ✨ Added ordinal number conversion (nemoNumberToOrdinal)
• ✨ Added Roman numeral conversion (nemoNumberToRoman)
• ✨ Added fraction to words conversion (nemoFractionToWords)
• ✨ Added batch processing (nemoBatchNumberToWords)
• ✨ Added case formatting options (upper, lower, title)
• ✨ Added 5 new currencies (CAD, CHF, SEK, NOK, DKK)
• ✨ Enhanced demo with new features
• 🐛 Improved error handling and validation
• 📚 Comprehensive documentation updates

v1.0.2

• 🎉 Initial stable release
• ✨ Basic number to words conversion
• 💰 Currency support for 8 major currencies
• 🌍 Indian and Western numbering systems
• 📦 Multiple build formats (CommonJS, ESM, Browser)