Convert numbers to English words with currency formatting, ordinals, Roman numerals, fractions, multilingual support, date/time conversion, and advanced text processing features
npm install nemo-nwcsh
npm install nemo-nwc
`
🚀 Quick Start
$3
`js
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"
`
$3
`js
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"
`
$3
`js
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)
`
$3
`js
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"
`
$3
`js
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"
`
$3
`js
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"
`
$3
`js
const { nemoCompactNumber, nemoCompactToWords } = require('nemo-nwc');
nemoCompactNumber(1500); // "1.5K"
nemoCompactNumber(2500000); // "2.5M"
nemoCompactNumber(3000000000); // "3.0B"
nemoCompactToWords(1500000); // "One point five million"
`
$3
`js
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
`
$3
`js
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"
`
$3
`js
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"
`
$3
`js
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
$3
`js
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');
`
$3
`js
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'));
`
$3
`html
`
💰 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 |
`js
// Get all supported currencies programmatically
const currencies = nemoGetSupportedCurrencies();
console.log(currencies);
`
📚 API Reference
$3
#### 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:
`js
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
---
$3
#### 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:
`js
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 (तेईस, चौबीस...)
---
$3
#### 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:
`js
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:
`js
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
---
$3
#### nemoScientificToWords(number, options?)
Convert scientific notation numbers to words.
Parameters:
- number (Number): Number in scientific notation
- options (Object, optional): Formatting options
Returns: String
Example:
`js
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:
`js
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
---
$3
#### 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:
`js
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:
`js
nemoCheckFormat(1234.56, 'USD');
// "One thousand two hundred thirty four and 56/100 Dollars"
`
---
$3
#### 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:
`js
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:
`js
nemoCompactToWords(1500); // "One point five thousand"
nemoCompactToWords(2500000); // "Two point five million"
`
---
$3
#### nemoWordsToNumber(words)
Convert words back to number.
Parameters:
- words (String): Number in words
Returns: Number
Example:
`js
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:
`js
nemoRomanToNumber('MCMXCIV'); // 1994
nemoRomanToNumber('XLII'); // 42
`
---
$3
#### 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:
`js
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:
`js
nemoMixedNumberToWords('2 1/2'); // "Two and half"
nemoMixedNumberToWords('3 3/4'); // "Three and three quarters"
`
---
$3
#### nemoPhoneToWords(phone, options?)
Convert phone number to words.
Parameters:
- phone (String): Phone number
- options (Object, optional): Formatting options
Returns: String
Example:
`js
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
$3
`js
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});
}
});
`
$3
`js
// 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"
`
$3
`js
// 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
$3
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)
---
$3
- ✨ Added ordinal number conversion (nemoNumberToOrdinal)
- ✨ Added Roman numeral conversion (nemoNumberToRoman)
- ✨ Added fraction to words conversion (nemoFractionToWords)
- ✨ Added batch processing (nemoBatchNumberToWords`)