numberstring

Number One Way to Makes Words from Numbers

Transform any number into beautiful words. From 42 to "forty-two", from 1000000 to "one million". Supports 22 languages, ordinals, currency, Roman numerals, and more!

Why numberstring?

• Zero dependencies - Lightweight and fast
• 22 languages - English, Spanish, French, German, Danish, Chinese, Hindi, Russian, Portuguese, Japanese, Korean, Arabic, Italian, Dutch, Turkish, Polish, Swedish, Indonesian, Thai, Norwegian, Finnish, Icelandic
• Huge range - Supports 0 to decillions (10^36) with BigInt
• Feature-rich - Ordinals, decimals, currency, fractions, years, phone numbers
• Roman numerals - Convert to and from Roman numerals
• Well tested - 265 tests with 90%+ coverage
• Modern ES modules - Tree-shakeable, TypeScript-friendly

Installation

npm install numberstring

Quick Start

import numberstring from 'numberstring';

numberstring(42);                    // 'forty-two'
numberstring(1000000);               // 'one million'
numberstring(10n ** 18n);            // 'one quintillion' (BigInt!)
numberstring(123, { cap: 'title' }); // 'One Hundred Twenty-Three'

API Reference

Core Functions

numberstring(n, [options])

Convert a number to English words.

numberstring(42);                    // 'forty-two'
numberstring(100, { cap: 'title' }); // 'One Hundred'
numberstring(100, { punc: '!' });    // 'one hundred!'

ordinal(n, [options])

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

import { ordinal } from 'numberstring';

ordinal(1);   // 'first'
ordinal(2);   // 'second'
ordinal(21);  // 'twenty-first'
ordinal(100); // 'one hundredth'

decimal(n, [options])

Convert decimal numbers to words.

import { decimal } from 'numberstring';

decimal(3.14);   // 'three point one four'
decimal(0.5);    // 'zero point five'
decimal(-3.14);  // 'negative three point one four'

currency(amount, [options])

Convert currency amounts to words.

import { currency } from 'numberstring';

currency('$123.45');  // 'one hundred twenty-three dollars and forty-five cents'
currency('€50');      // 'fifty euros'
currency('£1.01');    // 'one pound and one penny'
currency('¥1000');    // 'one thousand yen'
currency('₹100.50');  // 'one hundred rupees and fifty paise'

Supported currencies: $ € £ ¥ ₹ 元 (USD, EUR, GBP, JPY, INR, CNY)

roman(n, [options])

Convert to Roman numerals.

import { roman } from 'numberstring';

roman(42);                   // 'XLII'
roman(1999);                 // 'MCMXCIX'
roman(4, { lower: true });   // 'iv'

parse(str)

Parse English words back to a number.

import { parse } from 'numberstring';

parse('forty-two');        // 42
parse('one thousand');     // 1000
parse('one quintillion');  // 1000000000000000000n (BigInt)

Utility Functions

negative(n, [options])

Handle negative numbers.

import { negative } from 'numberstring';

negative(-42);  // 'negative forty-two'
negative(42);   // 'forty-two'

fraction(numerator, denominator, [options])

Convert fractions to words.

import { fraction } from 'numberstring';

fraction(1, 2);  // 'one half'
fraction(3, 4);  // 'three quarters'
fraction(5, 8);  // 'five eighths'

year(y, [options])

Convert years to spoken form.

import { year } from 'numberstring';

year(1984);  // 'nineteen eighty-four'
year(2000);  // 'two thousand'
year(2024);  // 'twenty twenty-four'

telephone(phone, [options])

Convert phone numbers to words.

import { telephone } from 'numberstring';

telephone('555-1234');  // 'five five five one two three four'
telephone(8675309);     // 'eight six seven five three zero nine'

percent(pct, [options])

Convert percentages to words.

import { percent } from 'numberstring';

percent(50);     // 'fifty percent'
percent('25%');  // 'twenty-five percent'
percent(3.5);    // 'three point five percent'

comma(n)

Format a number with comma separators.

import { comma } from 'numberstring';

comma(1234567);  // '1,234,567'

Multi-Language Support

numberstring supports 22 languages! Each language is in a separate file for easy tree-shaking.

import { toWords } from 'numberstring';

// Using toWords with lang option
toWords(42, { lang: 'es' });  // 'cuarenta y dos'
toWords(42, { lang: 'fr' });  // 'quarante-deux'
toWords(42, { lang: 'de' });  // 'zweiundvierzig'
toWords(42, { lang: 'da' });  // 'toogfyrre'
toWords(42, { lang: 'zh' });  // '四十二'
toWords(42, { lang: 'hi' });  // 'बयालीस'
toWords(42, { lang: 'ru' });  // 'сорок два'
toWords(42, { lang: 'pt' });  // 'quarenta e dois'
toWords(42, { lang: 'ja' });  // '四十二'
toWords(42, { lang: 'ko' });  // '사십이'
toWords(42, { lang: 'ar' });  // 'اثنان وأربعون'
toWords(42, { lang: 'it' });  // 'quarantadue'
toWords(42, { lang: 'nl' });  // 'tweeënveertig'
toWords(42, { lang: 'tr' });  // 'kırk iki'
toWords(42, { lang: 'pl' });  // 'czterdzieści dwa'
toWords(42, { lang: 'sv' });  // 'fyrtiotvå'
toWords(42, { lang: 'id' });  // 'empat puluh dua'
toWords(42, { lang: 'th' });  // 'สี่สิบสอง'
toWords(42, { lang: 'no' });  // 'førtito'
toWords(42, { lang: 'fi' });  // 'neljäkymmentäkaksi'
toWords(42, { lang: 'is' });  // 'fjörutíu og tveir'

Supported Languages

| Code | Language | Example (42) | |------|----------|-------------| | en | English | forty-two | | es | Spanish | cuarenta y dos | | fr | French | quarante-deux | | de | German | zweiundvierzig | | da | Danish | toogfyrre | | zh | Chinese | 四十二 | | hi | Hindi | बयालीस | | ru | Russian | сорок два | | pt | Portuguese | quarenta e dois | | ja | Japanese | 四十二 | | ko | Korean | 사십이 | | ar | Arabic | اثنان وأربعون | | it | Italian | quarantadue | | nl | Dutch | tweeënveertig | | tr | Turkish | kırk iki | | pl | Polish | czterdzieści dwa | | sv | Swedish | fyrtiotvå | | id | Indonesian | empat puluh dua | | th | Thai | สี่สิบสอง | | no | Norwegian | førtito | | fi | Finnish | neljäkymmentäkaksi | | is | Icelandic | fjörutíu og tveir |

Adding a New Language

Languages are modular! To add a new language:

1. Create languages/xx.js following the pattern in languages/en.js
2. Export your conversion function
3. Add to languages/index.js
4. Submit a PR!

Options

| Option | Type | Description | |--------|------|-------------| | cap | string | Capitalization: 'title', 'upper', or 'lower' | | punc | string | Punctuation: '!', '?', or '.' | | lang | string | Language code for toWords() | | point | string | Word for decimal point (default: 'point') | | lower | boolean | Lowercase Roman numerals |

Supported Scales

| Scale | Power | Example | |-------|-------|---------| | Ones | 10^0 | five | | Thousands | 10^3 | five thousand | | Millions | 10^6 | five million | | Billions | 10^9 | five billion | | Trillions | 10^12 | five trillion | | Quadrillions | 10^15 | five quadrillion | | Quintillions | 10^18 | five quintillion (BigInt) | | Sextillions | 10^21 | five sextillion (BigInt) | | Septillions | 10^24 | five septillion (BigInt) | | Octillions | 10^27 | five octillion (BigInt) | | Nonillions | 10^30 | five nonillion (BigInt) | | Decillions | 10^33 | five decillion (BigInt) |

REST API Server

numberstring includes a ready-to-use REST API server!

cd server
npm install
npm start
# Server running at http://localhost:3456

Endpoints

| Endpoint | Description | Example | |----------|-------------|---------| | GET /convert/:n | Number to words | /convert/42 → "forty-two" | | GET /convert/:n?lang=es | Multi-language | /convert/42?lang=es → "cuarenta y dos" | | GET /ordinal/:n | Ordinal words | /ordinal/3 → "third" | | GET /decimal/:n | Decimal words | /decimal/3.14 → "three point one four" | | GET /currency/:amt | Currency words | /currency/$99.99 → "ninety-nine dollars..." | | GET /roman/:n | Roman numerals | /roman/2024 → "MMXXIV" | | GET /parse/:words | Words to number | /parse/forty-two → 42 | | GET /comma/:n | Format with commas | /comma/1000000 → "1,000,000" | | GET /languages | List languages | Returns supported language codes |

Example

curl http://localhost:3456/convert/1000000000000000
# {"input":"1000000000000000","output":"one quadrillion","lang":"en"}

curl "http://localhost:3456/convert/42?lang=fr"
# {"input":"42","output":"quarante-deux","lang":"fr"}

Development

npm install        # Install dependencies
npm test           # Run tests
npm run lint       # Run linter
npm run test:coverage  # Test with coverage

Contributing

Please read CONTRIBUTING.md for details on the process for submitting pull requests.

We especially welcome contributions for new languages! See the Contributing guide for details.

Versioning

This project uses Semantic Versioning 2.0.

Requirements

• Node.js 18+
• ES modules (import/export)

License

MIT

# " "