currency-amount-to-words

Convert numeric currency amounts into human-readable English words with country-specific formatting.

25.30  →  "Twenty-Five Ghana Cedis and Thirty Pesewas"

📦 npm: https://www.npmjs.com/package/currency-amount-to-words
🐙 GitHub: https://github.com/jahidulsaeid/currency-amount-to-words

Features

• 🌍 Multi-currency – GHS, BDT, USD out-of-the-box; add more at runtime.
• 🔢 Decimal-aware – Splits amounts into major & minor units automatically.
• 📝 Singular / plural – "One Dollar" vs "Two Dollars".
• ➖ Negative values – Prefixed with "Minus".
• 🔒 Input validation – Throws descriptive errors for NaN, null, strings, etc.
• 📦 ESM + CJS – Dual build with full TypeScript declarations.
• 🌳 Tree-shakable – sideEffects: false.

Installation

npm install currency-amount-to-words

Quick Start

import { amountToWords } from 'currency-amount-to-words';

amountToWords(25.3, 'GHS');
// "Twenty-Five Ghana Cedis and Thirty Pesewas"

amountToWords(1, 'USD');
// "One Dollar"

amountToWords(99.99, 'BDT');
// "Ninety-Nine Taka and Ninety-Nine Paisa"

CommonJS

const { amountToWords } = require('currency-amount-to-words');

amountToWords(10.5, 'USD');
// "Ten Dollars and Fifty Cents"

API Reference

amountToWords(amount: number, currency: CurrencyCode): string

Convert a numeric amount into words for the given currency.

| Parameter | Type | Description | | ---------- | -------------- | ------------------------------------- | | amount | number | The numeric value (may be negative). | | currency | CurrencyCode | A registered currency code. |

Returns – A capitalised English string.

Throws

| Error | Condition | | ------------ | ----------------------------------------- | | TypeError | amount is not a finite number. | | TypeError | currency is not a non-empty string. | | Error | currency code is not registered. |

registerCurrency(config: CurrencyConfig): void

Register (or override) a currency at runtime.

import { registerCurrency, amountToWords } from 'currency-amount-to-words';

registerCurrency({
  code: 'EUR',
  major: 'Euro',
  majorPlural: 'Euros',
  minor: 'Cent',
  minorPlural: 'Cents',
});

amountToWords(15.5, 'EUR');
// "Fifteen Euros and Fifty Cents"

getRegisteredCurrencies(): string[]

Returns the list of all currently registered currency codes.

import { getRegisteredCurrencies } from 'currency-amount-to-words';

getRegisteredCurrencies();
// ['GHS', 'BDT', 'USD', ...]

Types

interface CurrencyConfig {
  code: string;
  major: string;        // singular, e.g. "Dollar"
  majorPlural: string;  // plural,   e.g. "Dollars"
  minor: string;        // singular, e.g. "Cent"
  minorPlural: string;  // plural,   e.g. "Cents"
}

type DefaultCurrencyCode = 'GHS' | 'BDT' | 'USD';
type CurrencyCode = DefaultCurrencyCode | (string & {});

Default Currencies

| Code | Major Unit | Minor Unit | | ---- | ------------ | ---------- | | GHS | Ghana Cedi(s)| Pesewa(s) | | BDT | Taka | Paisa | | USD | Dollar(s) | Cent(s) |

Example Outputs

GHS (Ghana Cedi)

| Input | Output | | -------------- | --------------------------------------------------- | | 0 | Zero Ghana Cedis | | 1 | One Ghana Cedi | | 25.30 | Twenty-Five Ghana Cedis and Thirty Pesewas | | 0.50 | Fifty Pesewas | | 0.01 | One Pesewa | | -5 | Minus Five Ghana Cedis |

BDT (Bangladeshi Taka)

| Input | Output | | -------------- | --------------------------------------------------- | | 0 | Zero Taka | | 1 | One Taka | | 100 | One Hundred Taka | | 99.99 | Ninety-Nine Taka and Ninety-Nine Paisa |

USD (US Dollar)

| Input | Output | | -------------- | --------------------------------------------------- | | 0 | Zero Dollars | | 1 | One Dollar | | 42.50 | Forty-Two Dollars and Fifty Cents | | 1000000 | One Million Dollars | | -10 | Minus Ten Dollars |

Edge Cases

| Scenario | Behaviour | | --------------------- | -------------------------------------------- | | Large numbers | Supports up to trillions. | | Negative values | Prefixed with "Minus". | | Rounding | Rounds to 2 decimal places (toFixed(2)). | | NaN / Infinity | Throws TypeError. | | null / undefined | Throws TypeError. | | String amounts | Throws TypeError. | | Unknown currency code | Throws Error with helpful message. |

Development

# Install dependencies
npm install

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Build
npm run build

# Lint
npm run lint

# Format
npm run format

Publishing to npm

1. Ensure you are logged in:

   npm login

2. Bump the version (follows semver):

   npm version patch   # or minor / major

3. Publish:

   npm publish

   The prepublishOnly script will automatically run the build before publishing.

4. Scoped package (optional):

   If you want to publish under a scope (e.g. @yourname/currency-amount-to-words), update the name field in package.json and publish with:

   npm publish --access public

Contributing

Contributions are welcome! Whether it's a bug fix, new currency support, or documentation improvement — all help is appreciated.

How to Contribute

1. Fork the repository

   Click the Fork button at the top-right of the GitHub repo to create your own copy.

2. Clone your fork

   git clone https://github.com/<your-username>/currency-amount-to-words.git
   cd currency-amount-to-words

3. Install dependencies

   npm install

4. Create a feature branch

   git checkout -b feat/my-new-feature

5. Make your changes

   • Add or update code in the src/ directory.

   • Add tests for any new functionality in src/__tests__/.

   • Run the test suite to make sure nothing is broken:

     npm test

6. Lint & format

   npm run lint
   npm run format

7. Commit your changes

   Write clear, descriptive commit messages:

   git commit -m "feat: add support for EUR currency"

8. Push to your fork

   git push origin feat/my-new-feature

9. Open a Pull Request

   Go to the original repository and click New Pull Request. Select your fork and branch, describe your changes, and submit.

Contribution Ideas

• 🌍 Add a new currency – Register additional currencies in src/currencyConfig.ts.
• 🐛 Fix a bug – Check the issues page for open bugs.
• 📖 Improve documentation – Typos, examples, or better explanations are always welcome.
• ✅ Write tests – Increase test coverage for edge cases.

Guidelines

• Follow the existing code style and conventions.
• Ensure all tests pass before submitting a PR.
• Keep PRs focused — one feature or fix per PR.
• Be respectful and constructive in discussions.

License

MIT

Links

• 📦 npm: https://www.npmjs.com/package/currency-amount-to-words
• 🐙 GitHub: https://github.com/jahidulsaeid/currency-amount-to-words
• 🐛 Issues: https://github.com/jahidulsaeid/currency-amount-to-words/issues