global-currency-words 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shaik Esub
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,191 @@
+# global-currency-words
+
+> Convert numeric currency amounts to human-readable words.  
+> Supports **15-digit numbers**, **decimals/subunits**, **30+ countries**, and **currency codes**.
+
+```js
+currencyWords(1234.56, { country: "India" })
+// => "One Thousand Two Hundred Thirty Four Rupees and Fifty Six Paise"
+
+currencyWords(999999999999999, { country: "USA", includeCode: true })
+// => "Nine Hundred Ninety Nine Trillion ... Nine Hundred Ninety Nine Dollars (USD)"
+```
+
+---
+
+## Installation
+
+```bash
+npm install global-currency-words
+```
+
+---
+
+## Quick Start
+
+```js
+const { currencyWords } = require("global-currency-words");
+
+// Default: United States (USD)
+currencyWords(500);
+// => "Five Hundred Dollars"
+
+currencyWords(1050.75, { country: "India" });
+// => "One Thousand Fifty Rupees and Seventy Five Paise"
+
+currencyWords(99.01, { country: "UK" });
+// => "Ninety Nine Pounds and One Penny"
+```
+
+---
+
+## API
+
+### `currencyWords(amount, options?)`
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `amount` | `number \| string` | The monetary amount. Supports up to **15 digits** before the decimal. Can be negative. |
+| `options` | `CurrencyWordsOptions` | Optional configuration (see below). |
+
+**Returns:** `string`
+
+#### Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `country` | `string` | `"United States"` | Country name **or** ISO 4217 currency code (e.g. `"India"`, `"INR"`, `"USD"`) |
+| `includeDecimals` | `boolean` | `true` | Include subunit (cents/paise/etc.) in the output |
+| `decimalPlaces` | `number` | `2` | How many decimal places to read (`1` or `2`) |
+| `includeSymbol` | `boolean` | `false` | Prepend the currency symbol (e.g. `₹`, `$`) |
+| `includeCode` | `boolean` | `false` | Append the ISO currency code (e.g. `(INR)`) |
+| `andBeforeDecimals` | `boolean` | `true` | Use "and" between main amount and subunit |
+
+---
+
+### `getCurrencyInfo(countryOrCode)`
+
+Returns metadata for a given country or currency code.
+
+```js
+const { getCurrencyInfo } = require("global-currency-words");
+
+getCurrencyInfo("Japan");
+// {
+//   currency: "Yen", currencyPlural: "Yen",
+//   subunit: "Sen",  subunitPlural: "Sen",
+//   symbol: "¥", code: "JPY", subunitFactor: 100
+// }
+```
+
+---
+
+### `listCountries()`
+
+Returns all supported country names as an array of strings.
+
+```js
+const { listCountries } = require("global-currency-words");
+listCountries();
+// => ["India", "Pakistan", "United States", "United Kingdom", ...]
+```
+
+---
+
+## Examples
+
+```js
+const { currencyWords } = require("global-currency-words");
+
+// Basic usage
+currencyWords(0);
+// => "Zero Dollars"
+
+// Large number (15 digits)
+currencyWords("999999999999999");
+// => "Nine Hundred Ninety Nine Trillion ... Nine Hundred Ninety Nine Dollars"
+
+// With symbol and code
+currencyWords(1500, { country: "India", includeSymbol: true, includeCode: true });
+// => "₹ One Thousand Five Hundred Rupees (INR)"
+
+// Without "and"
+currencyWords(10.50, { andBeforeDecimals: false });
+// => "Ten Dollars Fifty Cents"
+
+// Only 1 decimal place
+currencyWords(10.5, { decimalPlaces: 1 });
+// => "Ten Dollars and Five Cents"
+
+// Ignore decimal part
+currencyWords(100.99, { includeDecimals: false });
+// => "One Hundred Dollars"
+
+// Negative amount
+currencyWords(-250.50, { country: "UK" });
+// => "Negative Two Hundred Fifty Pounds and Fifty Pence"
+
+// Lookup by currency code
+currencyWords(100, { country: "EUR" });
+// => "One Hundred Euros"
+```
+
+---
+
+## Supported Countries
+
+| Country | Code | Currency | Subunit |
+|---------|------|----------|---------|
+| India | INR | Rupee | Paisa |
+| United States / USA | USD | Dollar | Cent |
+| United Kingdom / UK | GBP | Pound | Penny/Pence |
+| Euro Zone / Germany / France… | EUR | Euro | Cent |
+| Japan | JPY | Yen | Sen |
+| China | CNY | Yuan | Fen |
+| Australia | AUD | Dollar | Cent |
+| Canada | CAD | Dollar | Cent |
+| UAE | AED | Dirham | Fils |
+| Saudi Arabia | SAR | Riyal | Halala |
+| Singapore | SGD | Dollar | Cent |
+| South Africa | ZAR | Rand | Cent |
+| Brazil | BRL | Real | Centavo |
+| Russia | RUB | Ruble | Kopek |
+| Pakistan | PKR | Rupee | Paisa |
+| Bangladesh | BDT | Taka | Paisa |
+| Indonesia | IDR | Rupiah | Sen |
+| Malaysia | MYR | Ringgit | Sen |
+| Thailand | THB | Baht | Satang |
+| Switzerland | CHF | Franc | Centime |
+| … and more | | | |
+
+> Use `listCountries()` for the full list, or pass an ISO 4217 code directly.
+
+---
+
+## Limits & Validation
+
+- Maximum **15 digits** in the integer part (up to 999,999,999,999,999)
+- Throws `RangeError` if the integer part exceeds 15 digits
+- Throws `TypeError` for invalid or missing amounts
+- Throws `Error` for unsupported country names
+
+---
+
+## TypeScript
+
+Full TypeScript definitions are included:
+
+```ts
+import { currencyWords, getCurrencyInfo, listCountries, CurrencyWordsOptions } from "global-currency-words";
+
+const result: string = currencyWords(1234.56, {
+  country: "India",
+  includeCode: true,
+});
+```
+
+---
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "global-currency-words",
+  "version": "1.0.0",
+  "description": "Convert numeric currency amounts to words. Supports 15-digit numbers, decimal points, and 30+ countries/currencies.",
+  "main": "src/index.js",
+  "types": "src/index.d.ts",
+  "scripts": {
+    "test": "node test/index.test.js"
+  },
+  "keywords": [
+    "currency",
+    "words",
+    "number-to-words",
+    "currency-converter",
+    "amount-in-words",
+    "inr",
+    "usd",
+    "eur",
+    "rupees",
+    "dollars"
+  ],
+  "author": "codify",
+  "license": "MIT",
+  "engines": {
+    "node": ">=12.0.0"
+  }
+}

package/src/converter.js

@@ -0,0 +1,93 @@
+"use strict";
+
+const ONES = [
+  "",
+  "One",
+  "Two",
+  "Three",
+  "Four",
+  "Five",
+  "Six",
+  "Seven",
+  "Eight",
+  "Nine",
+  "Ten",
+  "Eleven",
+  "Twelve",
+  "Thirteen",
+  "Fourteen",
+  "Fifteen",
+  "Sixteen",
+  "Seventeen",
+  "Eighteen",
+  "Nineteen",
+];
+
+const TENS = [
+  "",
+  "",
+  "Twenty",
+  "Thirty",
+  "Forty",
+  "Fifty",
+  "Sixty",
+  "Seventy",
+  "Eighty",
+  "Ninety",
+];
+
+/**
+ * Convert a number 0–999 to words.
+ */
+function convertHundreds(n) {
+  if (n === 0) return "";
+  if (n < 20) return ONES[n];
+  if (n < 100) {
+    const rem = n % 10;
+    return TENS[Math.floor(n / 10)] + (rem ? " " + ONES[rem] : "");
+  }
+  const rem = n % 100;
+  return (
+    ONES[Math.floor(n / 100)] +
+    " Hundred" +
+    (rem ? " " + convertHundreds(rem) : "")
+  );
+}
+
+/**
+ * Convert an integer (BigInt-safe via string) up to 15 digits to words.
+ * Returns "" for 0.
+ */
+function integerToWords(numStr) {
+  // Remove leading zeros
+  numStr = String(numStr).replace(/^0+/, "") || "0";
+
+  if (numStr === "0") return "Zero";
+  if (numStr.length > 15) {
+    throw new Error("Number exceeds 15-digit limit (max: 999,999,999,999,999)");
+  }
+
+  // Pad to 15 digits for slicing
+  const padded = numStr.padStart(15, "0");
+
+  // Groups (Indian system awareness + international)
+  // We split into: [trillions(3), billions(3), millions(3), thousands(3), hundreds(3)]
+  const groups = [
+    { value: parseInt(padded.slice(0, 3), 10), label: "Trillion" },
+    { value: parseInt(padded.slice(3, 6), 10), label: "Billion" },
+    { value: parseInt(padded.slice(6, 9), 10), label: "Million" },
+    { value: parseInt(padded.slice(9, 12), 10), label: "Thousand" },
+    { value: parseInt(padded.slice(12, 15), 10), label: "" },
+  ];
+
+  const parts = [];
+  for (const { value, label } of groups) {
+    if (value === 0) continue;
+    const words = convertHundreds(value);
+    parts.push(label ? words + " " + label : words);
+  }
+
+  return parts.join(" ");
+}
+
+module.exports = { integerToWords, convertHundreds };

package/src/currencies.js

@@ -0,0 +1,358 @@
+"use strict";
+
+/**
+ * Currency definitions by country name (case-insensitive lookup)
+ * Each entry: { currency, subunit, symbol, code, subunitFactor }
+ */
+const CURRENCIES = {
+  // Asia
+  india: {
+    currency: "Rupee",
+    currencyPlural: "Rupees",
+    subunit: "Paisa",
+    subunitPlural: "Paise",
+    symbol: "₹",
+    code: "INR",
+    subunitFactor: 100,
+  },
+  pakistan: {
+    currency: "Rupee",
+    currencyPlural: "Rupees",
+    subunit: "Paisa",
+    subunitPlural: "Paise",
+    symbol: "₨",
+    code: "PKR",
+    subunitFactor: 100,
+  },
+  "sri lanka": {
+    currency: "Rupee",
+    currencyPlural: "Rupees",
+    subunit: "Cent",
+    subunitPlural: "Cents",
+    symbol: "Rs",
+    code: "LKR",
+    subunitFactor: 100,
+  },
+  nepal: {
+    currency: "Rupee",
+    currencyPlural: "Rupees",
+    subunit: "Paisa",
+    subunitPlural: "Paise",
+    symbol: "Rs",
+    code: "NPR",
+    subunitFactor: 100,
+  },
+  bangladesh: {
+    currency: "Taka",
+    currencyPlural: "Taka",
+    subunit: "Paisa",
+    subunitPlural: "Paise",
+    symbol: "৳",
+    code: "BDT",
+    subunitFactor: 100,
+  },
+  china: {
+    currency: "Yuan",
+    currencyPlural: "Yuan",
+    subunit: "Fen",
+    subunitPlural: "Fen",
+    symbol: "¥",
+    code: "CNY",
+    subunitFactor: 100,
+  },
+  japan: {
+    currency: "Yen",
+    currencyPlural: "Yen",
+    subunit: "Sen",
+    subunitPlural: "Sen",
+    symbol: "¥",
+    code: "JPY",
+    subunitFactor: 100,
+  },
+  "south korea": {
+    currency: "Won",
+    currencyPlural: "Won",
+    subunit: "Jeon",
+    subunitPlural: "Jeon",
+    symbol: "₩",
+    code: "KRW",
+    subunitFactor: 100,
+  },
+  indonesia: {
+    currency: "Rupiah",
+    currencyPlural: "Rupiah",
+    subunit: "Sen",
+    subunitPlural: "Sen",
+    symbol: "Rp",
+    code: "IDR",
+    subunitFactor: 100,
+  },
+  malaysia: {
+    currency: "Ringgit",
+    currencyPlural: "Ringgit",
+    subunit: "Sen",
+    subunitPlural: "Sen",
+    symbol: "RM",
+    code: "MYR",
+    subunitFactor: 100,
+  },
+  singapore: {
+    currency: "Dollar",
+    currencyPlural: "Dollars",
+    subunit: "Cent",
+    subunitPlural: "Cents",
+    symbol: "S$",
+    code: "SGD",
+    subunitFactor: 100,
+  },
+  thailand: {
+    currency: "Baht",
+    currencyPlural: "Baht",
+    subunit: "Satang",
+    subunitPlural: "Satang",
+    symbol: "฿",
+    code: "THB",
+    subunitFactor: 100,
+  },
+  "united arab emirates": {
+    currency: "Dirham",
+    currencyPlural: "Dirhams",
+    subunit: "Fils",
+    subunitPlural: "Fils",
+    symbol: "د.إ",
+    code: "AED",
+    subunitFactor: 100,
+  },
+  uae: {
+    currency: "Dirham",
+    currencyPlural: "Dirhams",
+    subunit: "Fils",
+    subunitPlural: "Fils",
+    symbol: "د.إ",
+    code: "AED",
+    subunitFactor: 100,
+  },
+  "saudi arabia": {
+    currency: "Riyal",
+    currencyPlural: "Riyals",
+    subunit: "Halala",
+    subunitPlural: "Halalas",
+    symbol: "﷼",
+    code: "SAR",
+    subunitFactor: 100,
+  },
+
+  // Americas
+  "united states": {
+    currency: "Dollar",
+    currencyPlural: "Dollars",
+    subunit: "Cent",
+    subunitPlural: "Cents",
+    symbol: "$",
+    code: "USD",
+    subunitFactor: 100,
+  },
+  usa: {
+    currency: "Dollar",
+    currencyPlural: "Dollars",
+    subunit: "Cent",
+    subunitPlural: "Cents",
+    symbol: "$",
+    code: "USD",
+    subunitFactor: 100,
+  },
+  canada: {
+    currency: "Dollar",
+    currencyPlural: "Dollars",
+    subunit: "Cent",
+    subunitPlural: "Cents",
+    symbol: "CA$",
+    code: "CAD",
+    subunitFactor: 100,
+  },
+  mexico: {
+    currency: "Peso",
+    currencyPlural: "Pesos",
+    subunit: "Centavo",
+    subunitPlural: "Centavos",
+    symbol: "MX$",
+    code: "MXN",
+    subunitFactor: 100,
+  },
+  brazil: {
+    currency: "Real",
+    currencyPlural: "Reais",
+    subunit: "Centavo",
+    subunitPlural: "Centavos",
+    symbol: "R$",
+    code: "BRL",
+    subunitFactor: 100,
+  },
+  argentina: {
+    currency: "Peso",
+    currencyPlural: "Pesos",
+    subunit: "Centavo",
+    subunitPlural: "Centavos",
+    symbol: "AR$",
+    code: "ARS",
+    subunitFactor: 100,
+  },
+
+  // Europe
+  "euro zone": {
+    currency: "Euro",
+    currencyPlural: "Euros",
+    subunit: "Cent",
+    subunitPlural: "Cents",
+    symbol: "€",
+    code: "EUR",
+    subunitFactor: 100,
+  },
+  germany: {
+    currency: "Euro",
+    currencyPlural: "Euros",
+    subunit: "Cent",
+    subunitPlural: "Cents",
+    symbol: "€",
+    code: "EUR",
+    subunitFactor: 100,
+  },
+  france: {
+    currency: "Euro",
+    currencyPlural: "Euros",
+    subunit: "Cent",
+    subunitPlural: "Cents",
+    symbol: "€",
+    code: "EUR",
+    subunitFactor: 100,
+  },
+  italy: {
+    currency: "Euro",
+    currencyPlural: "Euros",
+    subunit: "Cent",
+    subunitPlural: "Cents",
+    symbol: "€",
+    code: "EUR",
+    subunitFactor: 100,
+  },
+  spain: {
+    currency: "Euro",
+    currencyPlural: "Euros",
+    subunit: "Cent",
+    subunitPlural: "Cents",
+    symbol: "€",
+    code: "EUR",
+    subunitFactor: 100,
+  },
+  "united kingdom": {
+    currency: "Pound",
+    currencyPlural: "Pounds",
+    subunit: "Penny",
+    subunitPlural: "Pence",
+    symbol: "£",
+    code: "GBP",
+    subunitFactor: 100,
+  },
+  uk: {
+    currency: "Pound",
+    currencyPlural: "Pounds",
+    subunit: "Penny",
+    subunitPlural: "Pence",
+    symbol: "£",
+    code: "GBP",
+    subunitFactor: 100,
+  },
+  switzerland: {
+    currency: "Franc",
+    currencyPlural: "Francs",
+    subunit: "Centime",
+    subunitPlural: "Centimes",
+    symbol: "CHF",
+    code: "CHF",
+    subunitFactor: 100,
+  },
+  sweden: {
+    currency: "Krona",
+    currencyPlural: "Kronor",
+    subunit: "Öre",
+    subunitPlural: "Öre",
+    symbol: "kr",
+    code: "SEK",
+    subunitFactor: 100,
+  },
+  norway: {
+    currency: "Krone",
+    currencyPlural: "Kroner",
+    subunit: "Øre",
+    subunitPlural: "Øre",
+    symbol: "kr",
+    code: "NOK",
+    subunitFactor: 100,
+  },
+  russia: {
+    currency: "Ruble",
+    currencyPlural: "Rubles",
+    subunit: "Kopek",
+    subunitPlural: "Kopeks",
+    symbol: "₽",
+    code: "RUB",
+    subunitFactor: 100,
+  },
+
+  // Africa & Oceania
+  "south africa": {
+    currency: "Rand",
+    currencyPlural: "Rand",
+    subunit: "Cent",
+    subunitPlural: "Cents",
+    symbol: "R",
+    code: "ZAR",
+    subunitFactor: 100,
+  },
+  australia: {
+    currency: "Dollar",
+    currencyPlural: "Dollars",
+    subunit: "Cent",
+    subunitPlural: "Cents",
+    symbol: "A$",
+    code: "AUD",
+    subunitFactor: 100,
+  },
+  "new zealand": {
+    currency: "Dollar",
+    currencyPlural: "Dollars",
+    subunit: "Cent",
+    subunitPlural: "Cents",
+    symbol: "NZ$",
+    code: "NZD",
+    subunitFactor: 100,
+  },
+};
+
+/**
+ * Lookup by country name (case-insensitive) or currency code (e.g. "USD")
+ */
+function getCurrency(countryOrCode) {
+  if (!countryOrCode) return CURRENCIES["united states"];
+  const key = countryOrCode.trim().toLowerCase();
+  if (CURRENCIES[key]) return CURRENCIES[key];
+
+  // Try matching by currency code
+  const byCode = Object.values(CURRENCIES).find(
+    (c) => c.code.toLowerCase() === key
+  );
+  if (byCode) return byCode;
+
+  throw new Error(
+    `Unsupported country or currency code: "${countryOrCode}". ` +
+      `Supported: ${getSupportedCountries().join(", ")}`
+  );
+}
+
+function getSupportedCountries() {
+  return Object.keys(CURRENCIES).map((k) =>
+    k.replace(/\b\w/g, (c) => c.toUpperCase())
+  );
+}
+
+module.exports = { getCurrency, getSupportedCountries, CURRENCIES };

package/src/index.d.ts

@@ -0,0 +1,79 @@
+export interface CurrencyInfo {
+  currency: string;
+  currencyPlural: string;
+  subunit: string;
+  subunitPlural: string;
+  symbol: string;
+  code: string;
+  subunitFactor: number;
+}
+
+export interface CurrencyWordsOptions {
+  /**
+   * Country name (e.g. "India", "United States") or ISO 4217 currency code (e.g. "INR", "USD").
+   * @default "United States"
+   */
+  country?: string;
+
+  /**
+   * Whether to include the decimal/subunit part in the output.
+   * @default true
+   */
+  includeDecimals?: boolean;
+
+  /**
+   * Number of decimal places to read (1 or 2).
+   * @default 2
+   */
+  decimalPlaces?: number;
+
+  /**
+   * Prepend the currency symbol to the result (e.g. "₹ One Hundred Rupees").
+   * @default false
+   */
+  includeSymbol?: boolean;
+
+  /**
+   * Append the ISO currency code to the result (e.g. "One Hundred Dollars (USD)").
+   * @default false
+   */
+  includeCode?: boolean;
+
+  /**
+   * Use "and" between the main amount and the subunit amount.
+   * @default true
+   */
+  andBeforeDecimals?: boolean;
+}
+
+/**
+ * Convert a numeric currency amount to words.
+ *
+ * Supports up to 15 digits in the integer part.
+ *
+ * @param amount  - Numeric amount as a number or string
+ * @param options - Conversion options
+ * @returns Human-readable currency string
+ *
+ * @example
+ * currencyWords(1050.75, { country: "India" })
+ * // => "One Thousand Fifty Rupees and Seventy Five Paise"
+ *
+ * @example
+ * currencyWords("999999999999999", { country: "USA", includeCode: true })
+ * // => "Nine Hundred Ninety Nine Trillion Nine Hundred Ninety Nine Billion ... Dollars (USD)"
+ */
+export function currencyWords(
+  amount: number | string,
+  options?: CurrencyWordsOptions
+): string;
+
+/**
+ * Get currency metadata for a given country or currency code.
+ */
+export function getCurrencyInfo(countryOrCode: string): CurrencyInfo;
+
+/**
+ * List all supported country names.
+ */
+export function listCountries(): string[];

package/src/index.js

@@ -0,0 +1,129 @@
+"use strict";
+
+const { getCurrency, getSupportedCountries } = require("./currencies");
+const { integerToWords } = require("./converter");
+
+/**
+ * @typedef {Object} CurrencyWordsOptions
+ * @property {string}  [country="United States"]  Country name or currency code (e.g. "India", "USD")
+ * @property {boolean} [includeDecimals=true]      Whether to include decimal/subunit words
+ * @property {number}  [decimalPlaces=2]           Decimal places to consider (1 or 2)
+ * @property {boolean} [includeSymbol=false]       Prepend the currency symbol
+ * @property {boolean} [includeCode=false]         Append the currency ISO code
+ * @property {boolean} [andBeforeDecimals=true]    Add "and" before subunit part
+ */
+
+/**
+ * Convert a numeric amount to currency words.
+ *
+ * @param {number|string} amount   - The amount (up to 15 digits before decimal)
+ * @param {CurrencyWordsOptions} options
+ * @returns {string}
+ *
+ * @example
+ * currencyWords(1234.56, { country: "India" })
+ * // => "One Thousand Two Hundred Thirty Four Rupees and Fifty Six Paise"
+ *
+ * @example
+ * currencyWords(500, { country: "USA" })
+ * // => "Five Hundred Dollars"
+ */
+function currencyWords(amount, options = {}) {
+  const {
+    country = "United States",
+    includeDecimals = true,
+    decimalPlaces = 2,
+    includeSymbol = false,
+    includeCode = false,
+    andBeforeDecimals = true,
+  } = options;
+
+  // ── Validate & parse amount ──────────────────────────────────────────────
+  if (amount === null || amount === undefined || amount === "") {
+    throw new TypeError("amount is required");
+  }
+
+  const amountStr = String(amount).trim();
+  if (!/^-?\d+(\.\d+)?$/.test(amountStr)) {
+    throw new TypeError(`Invalid amount: "${amount}". Must be a numeric value.`);
+  }
+
+  const isNegative = amountStr.startsWith("-");
+  const absStr = isNegative ? amountStr.slice(1) : amountStr;
+
+  const dotIndex = absStr.indexOf(".");
+  const intPart = dotIndex === -1 ? absStr : absStr.slice(0, dotIndex);
+  const rawDecimalStr = dotIndex === -1 ? "" : absStr.slice(dotIndex + 1);
+
+  // Enforce 15-digit integer limit
+  const cleanInt = intPart.replace(/^0+/, "") || "0";
+  if (cleanInt.length > 15) {
+    throw new RangeError(
+      `Integer part exceeds 15 digits. Got ${cleanInt.length} digits.`
+    );
+  }
+
+  // ── Resolve currency ─────────────────────────────────────────────────────
+  const currency = getCurrency(country);
+
+  // ── Integer words ────────────────────────────────────────────────────────
+  const intWords = integerToWords(cleanInt);
+  const intValue = parseInt(cleanInt, 10);
+  const currencyLabel =
+    intValue === 1 ? currency.currency : currency.currencyPlural;
+
+  let result = intWords + " " + currencyLabel;
+
+  // ── Decimal / subunit words ──────────────────────────────────────────────
+  if (includeDecimals && rawDecimalStr) {
+    const places = Math.min(Math.max(parseInt(decimalPlaces, 10) || 2, 1), 2);
+
+    // Pad or trim decimal string to `places` digits
+    let decStr = rawDecimalStr.padEnd(places, "0").slice(0, places);
+    const decValue = parseInt(decStr, 10);
+
+    if (decValue > 0) {
+      const decWords = integerToWords(String(decValue));
+      const subLabel =
+        decValue === 1 ? currency.subunit : currency.subunitPlural;
+
+      result +=
+        (andBeforeDecimals ? " and " : " ") + decWords + " " + subLabel;
+    }
+  }
+
+  // ── Negative ─────────────────────────────────────────────────────────────
+  if (isNegative) {
+    result = "Negative " + result;
+  }
+
+  // ── Symbol / code affixes ─────────────────────────────────────────────────
+  if (includeSymbol) {
+    result = currency.symbol + " " + result;
+  }
+  if (includeCode) {
+    result = result + " (" + currency.code + ")";
+  }
+
+  return result;
+}
+
+/**
+ * Get currency info for a country.
+ *
+ * @param {string} country
+ * @returns {{ currency, currencyPlural, subunit, subunitPlural, symbol, code, subunitFactor }}
+ */
+function getCurrencyInfo(country) {
+  return getCurrency(country);
+}
+
+/**
+ * List all supported countries.
+ * @returns {string[]}
+ */
+function listCountries() {
+  return getSupportedCountries();
+}
+
+module.exports = { currencyWords, getCurrencyInfo, listCountries };