Skip to content

brianfunk/numberstring

Repository files navigation

numberstring npm version npm downloads CI Open Source Love Semver License LinkedIn

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 8 languages, ordinals, currency, Roman numerals, and more!

Why numberstring?

  • Zero dependencies - Lightweight and fast
  • 9 languages - English, Spanish, French, German, Danish, Chinese, Hindi, Russian, Portuguese
  • 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 - 174 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 9 languages! Each language is in a separate file for easy tree-shaking.

import { toWords, spanish, french, german, danish, chinese, hindi, russian, portuguese } 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'

// Or use language functions directly
spanish(1000);    // 'mil'
french(80);       // 'quatre-vingts'
german(21);       // 'einundzwanzig'
chinese(10000);   // '一万'
russian(2000);    // 'две тысячи'
portuguese(100);  // 'cem'

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-two42
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

# " "

About

numberstring - # " "

Topics

Resources

License

Contributing

Stars

Watchers

Forks

Packages

No packages published

Contributors 2

  •  
  •