n2words 4.0.0 → 5.1.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "n2words",
-  "version": "4.0.0",
-  "description": "Convert numbers to words in 71 languages with zero dependencies. Supports BigInt, decimals, and browser/Node.js environments.",
+  "version": "5.1.0",
+  "description": "Convert numbers to words in 70+ languages with zero dependencies. Supports BigInt, decimals, and browser/Node.js environments.",
   "keywords": [
     "number-to-words",
     "num2words",
@@ -46,6 +46,14 @@
     "./utils/*": null,
     "./package.json": "./package.json"
   },
+  "typesVersions": {
+    "*": {
+      "utils/*": [],
+      "*": [
+        "./src/*.d.ts"
+      ]
+    }
+  },
   "files": [
     "src/**/*.js",
     "src/**/*.d.ts",
@@ -58,24 +66,27 @@
     "bench": "node --expose-gc bench/index.js",
     "browserslist": "browserslist",
     "browserslist:coverage": "browserslist --coverage",
-    "build": "npm run clean && npm run build:types && npm run build:dist",
-    "build:dist": "npm run clean:dist && rollup -c",
-    "build:types": "npm run clean:types && tsc --project tsconfig.build.json",
-    "clean": "npm run clean:dist && npm run clean:types",
-    "clean:all": "npm run clean && npm run clean:artifacts",
+    "build": "node --run clean && node --run build:types && node --run build:dist",
+    "build:dist": "node --run clean:dist && rollup -c",
+    "build:types": "node --run clean:types && tsc --project tsconfig.build.json",
+    "clean": "node --run clean:dist && node --run clean:types",
+    "clean:all": "node --run clean && node --run clean:artifacts",
     "clean:artifacts": "rimraf coverage .nyc_output",
     "clean:dist": "rimraf dist",
     "clean:types": "rimraf \"src/**/*.d.ts\" --glob",
-    "coverage": "c8 npm run test:unit",
+    "coverage": "c8 node --run test:unit",
+    "coverage:check": "c8 check-coverage",
     "docs:languages": "node scripts/generate-languages-md.js",
     "lang:add": "node scripts/add-language.js",
-    "lint": "npm run lint:js && npm run lint:md",
-    "lint:fix": "npm run lint:js -- --fix && npm run lint:md -- --fix",
-    "lint:js": "standard",
+    "lint": "node --run lint:js && node --run lint:md",
+    "lint:fix": "eslint --fix && markdownlint-cli2 --fix",
+    "lint:js": "eslint",
     "lint:md": "markdownlint-cli2",
+    "prepack": "node --run build",
     "prepare:husky": "husky",
-    "test": "npm run test:unit && npm run build:types",
-    "test:unit": "ava \"test/*.test.js\" \"test/utils/*.test.js\""
+    "test": "node --run test:unit && node --run build:types",
+    "test:unit": "ava \"test/*.test.js\" \"test/utils/*.test.js\"",
+    "typecheck": "tsc --project tsconfig.build.json --noEmit"
   },
   "ava": {
     "extensions": [
@@ -89,11 +100,6 @@
     "concurrency": 8,
     "workerThreads": false
   },
-  "standard": {
-    "ignore": [
-      "!.vscode/"
-    ]
-  },
   "c8": {
     "all": true,
     "include": [
@@ -106,41 +112,52 @@
       "lcov",
       "text",
       "json-summary"
-    ]
+    ],
+    "lines": 90,
+    "statements": 90,
+    "functions": 90,
+    "branches": 85
   },
   "lint-staged": {
     "*.{js,cjs,mjs}": [
-      "standard --fix"
+      "eslint --fix"
     ],
     "*.md": [
       "markdownlint-cli2 --fix"
     ]
   },
   "devDependencies": {
-    "@babel/core": "^7.29.0",
-    "@babel/preset-env": "^7.29.0",
-    "@commitlint/cli": "^20.4.3",
-    "@commitlint/config-conventional": "^20.4.3",
-    "@commitlint/format": "^20.4.3",
-    "@rollup/plugin-babel": "^7.0.0",
-    "@rollup/plugin-node-resolve": "^16.0.3",
+    "@commitlint/cli": "^21.0.2",
+    "@commitlint/config-conventional": "^21.0.2",
+    "@eslint-community/eslint-plugin-eslint-comments": "^4.7.2",
+    "@eslint/js": "^10.0.1",
     "@rollup/plugin-terser": "^1.0.0",
     "@rollup/plugin-virtual": "^3.0.2",
-    "ava": "^7.0.0",
-    "benchmark": "^2.1.4",
-    "browserslist": "^4.28.1",
+    "@stylistic/eslint-plugin": "^5.10.0",
+    "@types/node": "^24.13.2",
+    "ava": "^8.0.1",
+    "browserslist": "^4.28.2",
     "c8": "^11.0.0",
     "chalk": "^5.6.2",
+    "eslint": "^10.5.0",
+    "eslint-plugin-ava": "^17.0.1",
+    "eslint-plugin-compat": "^7.0.2",
+    "eslint-plugin-es-x": "^9.6.0",
+    "eslint-plugin-import-x": "^4.16.2",
+    "eslint-plugin-jsdoc": "^63.0.4",
+    "eslint-plugin-n": "^18.1.0",
+    "fast-check": "^4.8.0",
+    "globals": "^17.6.0",
     "husky": "^9.1.7",
-    "lint-staged": "^16.3.2",
-    "markdownlint-cli2": "^0.21.0",
+    "lint-staged": "^17.0.7",
+    "markdownlint-cli2": "^0.22.1",
     "rimraf": "^6.1.3",
-    "rollup": "^4.59.0",
-    "standard": "^17.1.2",
-    "typescript": "^5.9.3"
+    "rollup": "^4.62.0",
+    "tinybench": "^6.0.2",
+    "typescript": "^6.0.3"
   },
   "engines": {
-    "node": ">=20"
+    "node": ">=22"
   },
   "publishConfig": {
     "access": "public",

package/src/am-ET.d.ts

@@ -1,6 +1,8 @@
+export const cardinalMax: bigint;
+export const ordinalMax: bigint;
+export const currencyMax: bigint;
 /**
  * Converts a numeric value to Amharic words.
- *
  * @param {number | string | bigint} value - The numeric value to convert
  * @returns {string} The number in Amharic words
  */
@@ -10,12 +12,10 @@ export function toCardinal(value: number | string | bigint): string;
  *
  * Amharic ordinals: add -ኛ suffix to cardinal.
  * Special case: 1 → አንደኛ
- *
  * @param {number | string | bigint} value - The numeric value to convert (positive integer)
  * @returns {string} The number as ordinal words
  * @throws {TypeError} If value is not a valid numeric type
  * @throws {RangeError} If value is negative, zero, or has a decimal part
- *
  * @example
  * toOrdinal(1)    // 'አንደኛ'
  * toOrdinal(2)    // 'ሁለትኛ'
@@ -25,12 +25,10 @@ export function toCardinal(value: number | string | bigint): string;
 export function toOrdinal(value: number | string | bigint): string;
 /**
  * Converts a numeric value to Amharic currency words (Ethiopian Birr).
- *
  * @param {number | string | bigint} value - The currency amount to convert
  * @returns {string} The amount in Amharic currency words
  * @throws {TypeError} If value is not a valid numeric type
  * @throws {Error} If value is not a valid number format
- *
  * @example
  * toCurrency(42.50)  // 'አርባ ሁለት ብር ሃምሳ ሳንቲም'
  * toCurrency(1)      // 'አንድ ብር'

package/src/am-ET.js

@@ -14,6 +14,8 @@
 import { parseCardinalValue } from './utils/parse-cardinal.js'
 import { parseCurrencyValue } from './utils/parse-currency.js'
 import { parseOrdinalValue } from './utils/parse-ordinal.js'
+import { checkMax } from './utils/check-max.js'
+import { western } from './utils/scale.js'
 
 // ============================================================================
 // Vocabulary
@@ -53,11 +55,23 @@ const SANTIM = 'ሳንቲም'
 // Short scale
 const SCALE_WORDS = ['', THOUSAND, 'ሚሊዮን', 'ቢሊዮን']
 
+// Supported magnitude ceiling (checked at the public entry points). SCALE_WORDS
+// reaches index SCALE_WORDS.length-1 (ቢሊዮን, 10^9), so values must stay below
+// 10^(SCALE_WORDS.length * 3) = 10^12. Ordinal and currency build on the
+// cardinal, so they share it. Decimals are read digit-by-digit (no ceiling).
+export const cardinalMax = western(SCALE_WORDS.length - 1)
+export const ordinalMax = western(SCALE_WORDS.length - 1)
+export const currencyMax = western(SCALE_WORDS.length - 1)
+
 // ============================================================================
 // Precomputed Lookup Table
 // ============================================================================
 
-function buildSegment (n) {
+/**
+ * @param {number} n The three-digit segment value (0-999) to convert.
+ * @returns {string} The segment in Amharic words.
+ */
+function buildSegment(n) {
   if (n === 0) return ''
 
   const ones = n % 10
@@ -73,7 +87,8 @@ function buildSegment (n) {
 
   if (tensDigit === 1) {
     parts.push(TEENS[ones])
-  } else {
+  }
+  else {
     if (tensDigit > 1) {
       parts.push(TENS[tensDigit])
     }
@@ -89,7 +104,11 @@ function buildSegment (n) {
 // Conversion Functions
 // ============================================================================
 
-function integerToWords (n) {
+/**
+ * @param {bigint} n The non-negative integer to convert.
+ * @returns {string} The integer in Amharic words.
+ */
+function integerToWords(n) {
   if (n === 0n) return ZERO
 
   if (n < 1000n) {
@@ -99,7 +118,11 @@ function integerToWords (n) {
   return buildLargeNumberWords(n)
 }
 
-function buildLargeNumberWords (n) {
+/**
+ * @param {bigint} n The integer (>= 1000) to convert using scale words.
+ * @returns {string} The integer in Amharic words.
+ */
+function buildLargeNumberWords(n) {
   const numStr = n.toString()
   const len = numStr.length
 
@@ -128,7 +151,8 @@ function buildLargeNumberWords (n) {
 
       if (scaleIndex === 0) {
         parts.push(buildSegment(segment))
-      } else {
+      }
+      else {
         parts.push(buildSegment(segment) + ' ' + scaleWord)
       }
     }
@@ -139,7 +163,11 @@ function buildLargeNumberWords (n) {
   return parts.join(' ')
 }
 
-function decimalPartToWords (decimalPart) {
+/**
+ * @param {string} decimalPart The digit string after the decimal point.
+ * @returns {string} The decimal digits read individually in Amharic words.
+ */
+function decimalPartToWords(decimalPart) {
   // Per-digit decimal reading
   const digits = []
   for (const char of decimalPart) {
@@ -151,12 +179,12 @@ function decimalPartToWords (decimalPart) {
 
 /**
  * Converts a numeric value to Amharic words.
- *
  * @param {number | string | bigint} value - The numeric value to convert
  * @returns {string} The number in Amharic words
  */
-function toCardinal (value) {
+function toCardinal(value) {
   const { isNegative, integerPart, decimalPart } = parseCardinalValue(value)
+  checkMax(integerPart, cardinalMax)
 
   let result = ''
 
@@ -182,11 +210,10 @@ function toCardinal (value) {
  *
  * In Amharic, ordinals are formed by adding -ኛ suffix to the cardinal.
  * Special case: 1 = አንደኛ (not አንድኛ)
- *
  * @param {bigint} n - Positive integer to convert
  * @returns {string} Amharic ordinal words
  */
-function integerToOrdinal (n) {
+function integerToOrdinal(n) {
   // Special case: 1 → አንደኛ
   if (n === 1n) {
     return FIRST
@@ -202,20 +229,19 @@ function integerToOrdinal (n) {
  *
  * Amharic ordinals: add -ኛ suffix to cardinal.
  * Special case: 1 → አንደኛ
- *
  * @param {number | string | bigint} value - The numeric value to convert (positive integer)
  * @returns {string} The number as ordinal words
  * @throws {TypeError} If value is not a valid numeric type
  * @throws {RangeError} If value is negative, zero, or has a decimal part
- *
  * @example
  * toOrdinal(1)    // 'አንደኛ'
  * toOrdinal(2)    // 'ሁለትኛ'
  * toOrdinal(10)   // 'አስርኛ'
  * toOrdinal(100)  // 'አንድ መቶኛ'
  */
-function toOrdinal (value) {
+function toOrdinal(value) {
   const integerPart = parseOrdinalValue(value)
+  checkMax(integerPart, ordinalMax)
   return integerToOrdinal(integerPart)
 }
 
@@ -225,20 +251,19 @@ function toOrdinal (value) {
 
 /**
  * Converts a numeric value to Amharic currency words (Ethiopian Birr).
- *
  * @param {number | string | bigint} value - The currency amount to convert
  * @returns {string} The amount in Amharic currency words
  * @throws {TypeError} If value is not a valid numeric type
  * @throws {Error} If value is not a valid number format
- *
  * @example
  * toCurrency(42.50)  // 'አርባ ሁለት ብር ሃምሳ ሳንቲም'
  * toCurrency(1)      // 'አንድ ብር'
  * toCurrency(0.99)   // 'ዘጠና ዘጠኝ ሳንቲም'
  * toCurrency(0.01)   // 'አንድ ሳንቲም'
  */
-function toCurrency (value) {
+function toCurrency(value) {
   const { isNegative, dollars: birr, cents: santim } = parseCurrencyValue(value)
+  checkMax(birr, currencyMax)
 
   // Build result
   let result = ''

package/src/am-Latn-ET.d.ts

@@ -1,18 +1,18 @@
+export const cardinalMax: bigint;
+export const ordinalMax: bigint;
+export const currencyMax: bigint;
 /**
  * Converts a numeric value to Amharic (Latin script) words.
- *
  * @param {number | string | bigint} value - The numeric value to convert
  * @returns {string} The number in Amharic Latin words
  */
 export function toCardinal(value: number | string | bigint): string;
 /**
  * Converts a numeric value to Amharic (Latin script) ordinal words.
- *
  * @param {number | string | bigint} value - The numeric value to convert (positive integer)
  * @returns {string} The number as ordinal words
  * @throws {TypeError} If value is not a valid numeric type
  * @throws {RangeError} If value is negative, zero, or has a decimal part
- *
  * @example
  * toOrdinal(1)    // 'andenya'
  * toOrdinal(2)    // 'huletnya'
@@ -21,12 +21,10 @@ export function toCardinal(value: number | string | bigint): string;
 export function toOrdinal(value: number | string | bigint): string;
 /**
  * Converts a numeric value to Amharic (Latin script) currency words (Ethiopian Birr).
- *
  * @param {number | string | bigint} value - The currency amount to convert
  * @returns {string} The amount in Amharic (Latin) currency words
  * @throws {TypeError} If value is not a valid numeric type
  * @throws {Error} If value is not a valid number format
- *
  * @example
  * toCurrency(42.50)  // 'arba hulet birr hamsa santim'
  * toCurrency(1)      // 'and birr'

package/src/am-Latn-ET.js

@@ -14,6 +14,8 @@
 import { parseCardinalValue } from './utils/parse-cardinal.js'
 import { parseCurrencyValue } from './utils/parse-currency.js'
 import { parseOrdinalValue } from './utils/parse-ordinal.js'
+import { checkMax } from './utils/check-max.js'
+import { western } from './utils/scale.js'
 
 // ============================================================================
 // Vocabulary
@@ -53,11 +55,24 @@ const SANTIM = 'santim'
 // Short scale
 const SCALE_WORDS = ['', THOUSAND, 'miliyon', 'billiyon']
 
+// Supported magnitude ceiling (checked at the public entry points). SCALE_WORDS
+// reaches index SCALE_WORDS.length-1 (billiyon, 10^9), so values must stay below
+// 10^(SCALE_WORDS.length * 3) = 10^12. Ordinal and currency build on the
+// cardinal, so they share it. Decimals are read digit-by-digit (no ceiling).
+export const cardinalMax = western(SCALE_WORDS.length - 1)
+export const ordinalMax = western(SCALE_WORDS.length - 1)
+export const currencyMax = western(SCALE_WORDS.length - 1)
+
 // ============================================================================
 // Precomputed Lookup Table
 // ============================================================================
 
-function buildSegment (n) {
+/**
+ * Builds the words for a 3-digit segment (0-999).
+ * @param {number} n - Segment value (0-999)
+ * @returns {string} The segment in Amharic (Latin) words
+ */
+function buildSegment(n) {
   if (n === 0) return ''
 
   const ones = n % 10
@@ -73,7 +88,8 @@ function buildSegment (n) {
 
   if (tensDigit === 1) {
     parts.push(TEENS[ones])
-  } else {
+  }
+  else {
     if (tensDigit > 1) {
       parts.push(TENS[tensDigit])
     }
@@ -89,7 +105,12 @@ function buildSegment (n) {
 // Conversion Functions
 // ============================================================================
 
-function integerToWords (n) {
+/**
+ * Converts a non-negative integer to Amharic (Latin script) words.
+ * @param {bigint} n - Non-negative integer to convert
+ * @returns {string} The integer in Amharic (Latin) words
+ */
+function integerToWords(n) {
   if (n === 0n) return ZERO
 
   if (n < 1000n) {
@@ -99,7 +120,12 @@ function integerToWords (n) {
   return buildLargeNumberWords(n)
 }
 
-function buildLargeNumberWords (n) {
+/**
+ * Builds the words for a number of 1000 or greater using short-scale grouping.
+ * @param {bigint} n - Integer of 1000 or greater
+ * @returns {string} The number in Amharic (Latin) words
+ */
+function buildLargeNumberWords(n) {
   const numStr = n.toString()
   const len = numStr.length
 
@@ -128,7 +154,8 @@ function buildLargeNumberWords (n) {
 
       if (scaleIndex === 0) {
         parts.push(buildSegment(segment))
-      } else {
+      }
+      else {
         parts.push(buildSegment(segment) + ' ' + scaleWord)
       }
     }
@@ -139,7 +166,12 @@ function buildLargeNumberWords (n) {
   return parts.join(' ')
 }
 
-function decimalPartToWords (decimalPart) {
+/**
+ * Reads the decimal part digit by digit.
+ * @param {string} decimalPart - The fractional digits as a string
+ * @returns {string} The decimal digits in Amharic (Latin) words
+ */
+function decimalPartToWords(decimalPart) {
   // Per-digit decimal reading
   const digits = []
   for (const char of decimalPart) {
@@ -151,12 +183,12 @@ function decimalPartToWords (decimalPart) {
 
 /**
  * Converts a numeric value to Amharic (Latin script) words.
- *
  * @param {number | string | bigint} value - The numeric value to convert
  * @returns {string} The number in Amharic Latin words
  */
-function toCardinal (value) {
+function toCardinal(value) {
   const { isNegative, integerPart, decimalPart } = parseCardinalValue(value)
+  checkMax(integerPart, cardinalMax)
 
   let result = ''
 
@@ -182,11 +214,10 @@ function toCardinal (value) {
  *
  * In Amharic, ordinals are formed by adding -nya suffix to the cardinal.
  * Special case: 1 = andenya
- *
  * @param {bigint} n - Positive integer to convert
  * @returns {string} Amharic (Latin) ordinal words
  */
-function integerToOrdinal (n) {
+function integerToOrdinal(n) {
   // Special case: 1 → andenya
   if (n === 1n) {
     return FIRST
@@ -199,19 +230,18 @@ function integerToOrdinal (n) {
 
 /**
  * Converts a numeric value to Amharic (Latin script) ordinal words.
- *
  * @param {number | string | bigint} value - The numeric value to convert (positive integer)
  * @returns {string} The number as ordinal words
  * @throws {TypeError} If value is not a valid numeric type
  * @throws {RangeError} If value is negative, zero, or has a decimal part
- *
  * @example
  * toOrdinal(1)    // 'andenya'
  * toOrdinal(2)    // 'huletnya'
  * toOrdinal(10)   // 'asirnya'
  */
-function toOrdinal (value) {
+function toOrdinal(value) {
   const integerPart = parseOrdinalValue(value)
+  checkMax(integerPart, ordinalMax)
   return integerToOrdinal(integerPart)
 }
 
@@ -221,19 +251,18 @@ function toOrdinal (value) {
 
 /**
  * Converts a numeric value to Amharic (Latin script) currency words (Ethiopian Birr).
- *
  * @param {number | string | bigint} value - The currency amount to convert
  * @returns {string} The amount in Amharic (Latin) currency words
  * @throws {TypeError} If value is not a valid numeric type
  * @throws {Error} If value is not a valid number format
- *
  * @example
  * toCurrency(42.50)  // 'arba hulet birr hamsa santim'
  * toCurrency(1)      // 'and birr'
  * toCurrency(0.01)   // 'and santim'
  */
-function toCurrency (value) {
+function toCurrency(value) {
   const { isNegative, dollars: birr, cents: santim } = parseCurrencyValue(value)
+  checkMax(birr, currencyMax)
 
   // Build result
   let result = ''

package/src/ar-SA.d.ts

@@ -1,46 +1,72 @@
+export const cardinalMax: bigint;
+export const ordinalMax: bigint;
+export const currencyMax: bigint;
+/**
+ * @typedef {object} CardinalOptions
+ * @property {('masculine'|'feminine')} [gender] - Grammatical gender
+ * @property {string} [negativeWord] - Custom word for negative numbers
+ */
+/** @type {Required<CardinalOptions>} */
+export const cardinalDefaults: Required<CardinalOptions>;
+/** @type {{ gender: ReadonlyArray<Required<CardinalOptions>['gender']> }} */
+export const cardinalValues: {
+    gender: ReadonlyArray<Required<CardinalOptions>["gender"]>;
+};
+/**
+ * @typedef {object} OrdinalOptions
+ * @property {('masculine'|'feminine')} [gender] - Grammatical gender
+ */
+/** @type {Required<OrdinalOptions>} */
+export const ordinalDefaults: Required<OrdinalOptions>;
+/** @type {{ gender: ReadonlyArray<Required<OrdinalOptions>['gender']> }} */
+export const ordinalValues: {
+    gender: ReadonlyArray<Required<OrdinalOptions>["gender"]>;
+};
+export type CardinalOptions = {
+    /**
+     * - Grammatical gender
+     */
+    gender?: "feminine" | "masculine" | undefined;
+    /**
+     * - Custom word for negative numbers
+     */
+    negativeWord?: string | undefined;
+};
+export type OrdinalOptions = {
+    /**
+     * - Grammatical gender
+     */
+    gender?: "feminine" | "masculine" | undefined;
+};
 /**
  * Converts a numeric value to Arabic words.
- *
  * @param {number | string | bigint} value - The numeric value to convert
- * @param {Object} [options] - Optional configuration
- * @param {('masculine'|'feminine')} [options.gender='masculine'] - Grammatical gender
- * @param {string} [options.negativeWord] - Custom word for negative numbers
+ * @param {CardinalOptions} [options] - Optional configuration
  * @returns {string} The number in Arabic words
- *
  * @example
  * toCardinal(1)                        // 'واحد'
  * toCardinal(1, {gender: 'feminine'})  // 'واحدة'
  */
-export function toCardinal(value: number | string | bigint, options?: {
-    gender?: "masculine" | "feminine" | undefined;
-    negativeWord?: string | undefined;
-}): string;
+export function toCardinal(value: number | string | bigint, options?: CardinalOptions): string;
 /**
  * Converts a numeric value to Arabic ordinal words.
- *
  * @param {number | string | bigint} value - The numeric value to convert (positive integer)
- * @param {Object} [options] - Optional configuration
- * @param {('masculine'|'feminine')} [options.gender='masculine'] - Grammatical gender
+ * @param {OrdinalOptions} [options] - Optional configuration
  * @returns {string} The number as ordinal words
  * @throws {TypeError} If value is not a valid numeric type
  * @throws {RangeError} If value is negative, zero, or has a decimal part
- *
  * @example
  * toOrdinal(1)                        // 'الأول'
  * toOrdinal(1, {gender: 'feminine'})  // 'الأولى'
  * toOrdinal(3)                        // 'الثالث'
  */
-export function toOrdinal(value: number | string | bigint, options?: {
-    gender?: "masculine" | "feminine" | undefined;
-}): string;
+export function toOrdinal(value: number | string | bigint, options?: OrdinalOptions): string;
 /**
  * Converts a numeric value to Arabic currency words (Saudi Riyal).
- *
  * @param {number | string | bigint} value - The currency amount to convert
  * @returns {string} The amount in Arabic currency words
  * @throws {TypeError} If value is not a valid numeric type
  * @throws {Error} If value is not a valid number format
- *
  * @example
  * toCurrency(42.50)  // 'اثنان وأربعون ريالاً وخمسون هللة'
  * toCurrency(1)      // 'ريال واحد'