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

Clone the repository:

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

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.

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
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

パッケージの詳細