Number Words Converter

A lightweight, zero-dependency TypeScript library for converting numbers to words in multiple languages. Currently supports English, Romanian, and Spanish.

Features

• ✅ Convert numbers to words in multiple languages
• ✅ Support for both integer and decimal numbers
• ✅ Handles negative numbers and zero
• ✅ TypeScript support out of the box
• ✅ Zero runtime dependencies
• ✅ Accurate handling of very large numbers (up to decillions and beyond) using BigInt.
• ✅ Comprehensive test coverage (~98%)
• ✅ Works in both Node.js and browser environments

Requirements

• Node.js 14 or higher
• npm or yarn

Installation

# Using npm
npm install number-words-converter

# Or using yarn
yarn add number-words-converter

Usage

Basic Usage

import { numberToWords, LANGUAGES } from 'number-words-converter';

// English (default)
const words1 = numberToWords(42); // "forty-two"
const words2 = numberToWords(123.45, LANGUAGES.ENGLISH); // "one hundred twenty-three point forty-five"

// Romanian
const words3 = numberToWords(42, LANGUAGES.ROMANIAN); // "patruzeci și doi"
const words4 = numberToWords('123.45', LANGUAGES.ROMANIAN); // "o sută douăzeci și trei virgulă patruzeci și cinci"

// Spanish
const words5 = numberToWords(42, LANGUAGES.SPANISH); // "cuarenta y dos"
const words6 = numberToWords('123.45', LANGUAGES.SPANISH); // "ciento veintitrés coma cuatro cinco"

Available Languages

• LANGUAGES.ENGLISH - English (default)
• LANGUAGES.ROMANIAN - Romanian (Română)
• LANGUAGES.SPANISH - Spanish (Español)

API Reference

numberToWords(num: string | number, language: Language = 'en'): string

Converts a number to words in the specified language.

Parameters:

• num: The number to convert (can be a string or number)
• language: The target language (defaults to English)

Returns: The number converted to words as a string

Throws:

• Error if the input cannot be converted to a valid number
• Error if the language is not supported

Examples:

// Basic usage
numberToWords(42); // "forty-two"
numberToWords("123.45", LANGUAGES.ENGLISH); // "one hundred twenty-three point forty-five"

// With variables
const amount = 99.99;
const amountInWords = numberToWords(amount); // "ninety-nine point ninety-nine"

// In a template literal
const message = `You owe me ${numberToWords(100)} dollars.`;
// "You owe me one hundred dollars."

Advanced Usage

Handling Different Number Formats

The library handles various number formats:

// Different decimal separators
numberToWords('1,234.56'); // US format
numberToWords('1.234,56', LANGUAGES.ROMANIAN); // EU format

// Negative numbers
numberToWords(-42); // "minus forty-two"

// Large numbers (BigInt support)
numberToWords(1000000); // "one million"
numberToWords(1_000_000_000_000_000_000n, LANGUAGES.ENGLISH); // "one quintillion"
// For Romanian, it also supports very large numbers:
numberToWords('1000000000000000000000000000000000', LANGUAGES.ROMANIAN); // "un decilion"

Development

Prerequisites

• Node.js 14+
• npm or yarn

Setup

1. Clone the repository:

   git clone https://github.com/mike-innerhaus/number-words-converter.git
   cd number-words-converter

2. Install dependencies:

   npm install
   # or
   yarn

Building

npm run build

Testing

# Run tests once
npm test

# Run tests in watch mode
npm run test:watch

# Check test coverage
npm test -- --coverage

Linting

# Check for linting errors
npm run lint

# Automatically fix linting issues
npm run lint -- --fix

Contributing

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

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

Distributed under the MIT License. See LICENSE for more information.

Acknowledgments

• Thanks to all contributors who help improve this project
• Inspired by various number-to-words implementations