n2words 1.24.0 → 3.0.0

package/lib/n2words.js

@@ -1,258 +1,122 @@
 /**
- * @module n2words
- */
-
-/** @typedef {'ar'|'az'|'bn'|'cs'|'de'|'da'|'el'|'en'|'es'|'fa'|'fr'|'fr-BE'|'gu'|'he'|'hi'|'hr'|'hu'|'id'|'it'|'ja'|'kn'|'ko'|'lt'|'lv'|'mr'|'ms'|'nl'|'nb'|'pa-Guru'|'pl'|'pt'|'ro'|'ru'|'sr-Latn'|'sv'|'sw'|'ta'|'te'|'th'|'fil'|'tr'|'uk'|'ur'|'vi'|'zh-Hans'} LanguageCode */
-
-/**
- * @typedef {Object} ArabicOptions
- * @property {string} [negativeWord='ناقص'] - Word for negative numbers (minus).
- * @property {boolean} [feminine=false] - Use feminine forms for numbers.
- */
-
-/**
- * @typedef {Object} ChineseOptions
- * @property {boolean} [formal=true] - Use formal/financial numerals (壹贰叁) vs. common numerals (一二三).
- */
-
-/**
- * @typedef {Object} HebrewOptions
- * @property {string} [and='ו'] - Conjunction character (typically 'ו' for and).
- * @property {boolean} [biblical=false] - Use biblical scale words instead of modern ones.
- * @property {boolean} [feminine=false] - Use feminine forms for numbers.
- */
-
-/**
- * @typedef {Object} SpanishOptions
- * @property {('o'|'a'|string)} [genderStem='o'] - Masculine 'o' or feminine 'a' ending.
- */
-
-/**
- * @typedef {Object} DutchOptions
- * @property {boolean} [includeOptionalAnd=false] - Include optional "en" separator.
- * @property {boolean} [noHundredPairs=false] - Disable comma before hundreds.
- * @property {boolean} [accentOne=true] - Use accented "één" for one.
- */
-
-/**
- * @typedef {Object} FrenchOptions
- * @property {boolean} [withHyphenSeparator=false] - Use hyphens (true) instead of spaces (false) in compounds.
- */
-
-/**
- * @typedef {Object} TurkishOptions
- * @property {boolean} [dropSpaces=false] - Remove spaces between words if true.
- */
-
-/**
- * @typedef {Object} RomanianOptions
- * @property {boolean} [feminine=false] - Use feminine forms for numbers.
- */
-
-/**
- * @typedef {Object} DanishOptions
- * @property {boolean} [ordFlag=false] - Enable ordinal number conversion.
- */
-
-/**
- * @typedef {Object} SlavicOptions
- * @property {boolean} [feminine=false] - Use feminine forms for numbers.
- */
-
-/**
- * Configuration object for number-to-words conversion with comprehensive language support.
+ * n2words - Number to words converter
+ *
+ * This module re-exports all language converters as named exports.
+ * Each export is a `toWords(value, options?)` function.
  *
- * @typedef {Object} N2WordsOptions
- * @property {LanguageCode} [lang='en'] - Target language code with full autocomplete support.
- *   Supports many languages with regional variants (e.g., 'fr-BE').
- *   Falls back progressively from most-specific to least-specific (e.g., 'fr-BE' -> 'fr').
- *   Throws an error if no match is found after fallback attempts.
- * @property {string} [negativeWord] - (Arabic only) Word for negative numbers.
- * @property {boolean} [feminine] - (Arabic, Hebrew, Romanian, Slavic languages) Use feminine forms.
- * @property {boolean} [formal] - (Chinese only) Use formal/financial numerals.
- * @property {string} [and] - (Hebrew only) Conjunction character.
- * @property {boolean} [biblical] - (Hebrew only) Use biblical scale words.
- * @property {('o'|'a'|string)} [genderStem] - (Spanish only) Gender ending.
- * @property {boolean} [includeOptionalAnd] - (Dutch only) Include optional "en".
- * @property {boolean} [noHundredPairs] - (Dutch only) Disable comma before hundreds.
- * @property {boolean} [accentOne] - (Dutch only) Use accented "één".
- * @property {boolean} [withHyphenSeparator] - (French, Belgian French) Use hyphens.
- * @property {boolean} [dropSpaces] - (Turkish, Azerbaijani) Remove spaces.
- * @property {boolean} [ordFlag] - (Danish only) Enable ordinal conversion.
+ * Export names use normalized BCP 47 codes (hyphens → camelCase):
+ * - `en`, `fr`, `de` (simple codes unchanged)
+ * - `zhHans` (zh-Hans), `frBE` (fr-BE), `srCyrl` (sr-Cyrl)
  *
- * Language-specific options are automatically validated and forwarded to converters.
- * See individual language implementations for detailed option descriptions.
+ * Imports and exports are alphabetically sorted by normalized name.
+ *
+ * @module n2words
  */
 
-import ar from './languages/ar.js'
-import az from './languages/az.js'
-import cs from './languages/cs.js'
-import de from './languages/de.js'
-import da from './languages/da.js'
-import en from './languages/en.js'
-import es from './languages/es.js'
-import fa from './languages/fa.js'
-import sw from './languages/sw.js'
-import fr from './languages/fr.js'
-import frBE from './languages/fr-BE.js'
-import he from './languages/he.js'
-import hr from './languages/hr.js'
-import hu from './languages/hu.js'
-import id from './languages/id.js'
-import ms from './languages/ms.js'
-import it from './languages/it.js'
-import ja from './languages/ja.js'
-import hi from './languages/hi.js'
-import bn from './languages/bn.js'
-import ko from './languages/ko.js'
-import th from './languages/th.js'
-import ta from './languages/ta.js'
-import te from './languages/te.js'
-import sv from './languages/sv.js'
-import lt from './languages/lt.js'
-import lv from './languages/lv.js'
-import nl from './languages/nl.js'
-import nb from './languages/nb.js'
-import pl from './languages/pl.js'
-import pt from './languages/pt.js'
-import ro from './languages/ro.js'
-import ru from './languages/ru.js'
-import srLatn from './languages/sr-Latn.js'
-import tr from './languages/tr.js'
-import uk from './languages/uk.js'
-import vi from './languages/vi.js'
-import zhHans from './languages/zh-Hans.js'
-import ur from './languages/ur.js'
-import paGuru from './languages/pa-Guru.js'
-import fil from './languages/fil.js'
-import mr from './languages/mr.js'
-import gu from './languages/gu.js'
-import kn from './languages/kn.js'
-import el from './languages/el.js'
-
-/**
- * Language converter registry.
- * Contains converters for all supported languages, statically imported to work
- * in both Node.js and browser environments (enables bundler dead-code elimination).
- * Keys are language codes (e.g., 'en', 'fr', 'fr-BE'); values are converter functions.
- * @type {Object<string, Function>}
- */
-const dict = {
+import { toWords as am } from './languages/am.js'
+import { toWords as amLatn } from './languages/am-Latn.js'
+import { toWords as ar } from './languages/ar.js'
+import { toWords as az } from './languages/az.js'
+import { toWords as bn } from './languages/bn.js'
+import { toWords as cs } from './languages/cs.js'
+import { toWords as da } from './languages/da.js'
+import { toWords as de } from './languages/de.js'
+import { toWords as el } from './languages/el.js'
+import { toWords as en } from './languages/en.js'
+import { toWords as es } from './languages/es.js'
+import { toWords as fa } from './languages/fa.js'
+import { toWords as fi } from './languages/fi.js'
+import { toWords as fil } from './languages/fil.js'
+import { toWords as fr } from './languages/fr.js'
+import { toWords as frBE } from './languages/fr-BE.js'
+import { toWords as gu } from './languages/gu.js'
+import { toWords as ha } from './languages/ha.js'
+import { toWords as hbo } from './languages/hbo.js'
+import { toWords as he } from './languages/he.js'
+import { toWords as hi } from './languages/hi.js'
+import { toWords as hr } from './languages/hr.js'
+import { toWords as hu } from './languages/hu.js'
+import { toWords as id } from './languages/id.js'
+import { toWords as it } from './languages/it.js'
+import { toWords as ja } from './languages/ja.js'
+import { toWords as kn } from './languages/kn.js'
+import { toWords as ko } from './languages/ko.js'
+import { toWords as lt } from './languages/lt.js'
+import { toWords as lv } from './languages/lv.js'
+import { toWords as mr } from './languages/mr.js'
+import { toWords as ms } from './languages/ms.js'
+import { toWords as nb } from './languages/nb.js'
+import { toWords as nl } from './languages/nl.js'
+import { toWords as pa } from './languages/pa.js'
+import { toWords as pl } from './languages/pl.js'
+import { toWords as pt } from './languages/pt.js'
+import { toWords as ro } from './languages/ro.js'
+import { toWords as ru } from './languages/ru.js'
+import { toWords as srCyrl } from './languages/sr-Cyrl.js'
+import { toWords as srLatn } from './languages/sr-Latn.js'
+import { toWords as sv } from './languages/sv.js'
+import { toWords as sw } from './languages/sw.js'
+import { toWords as ta } from './languages/ta.js'
+import { toWords as te } from './languages/te.js'
+import { toWords as th } from './languages/th.js'
+import { toWords as tr } from './languages/tr.js'
+import { toWords as uk } from './languages/uk.js'
+import { toWords as ur } from './languages/ur.js'
+import { toWords as vi } from './languages/vi.js'
+import { toWords as zhHans } from './languages/zh-Hans.js'
+import { toWords as zhHant } from './languages/zh-Hant.js'
+
+export {
+  am,
+  amLatn,
   ar,
   az,
+  bn,
   cs,
-  de,
   da,
+  de,
+  el,
   en,
   es,
   fa,
-  sw,
+  fi,
+  fil,
   fr,
-  'fr-BE': frBE,
+  frBE,
+  gu,
+  ha,
+  hbo,
   he,
+  hi,
   hr,
   hu,
   id,
-  ms,
   it,
   ja,
-  hi,
-  bn,
+  kn,
   ko,
-  th,
-  ta,
-  te,
-  sv,
   lt,
   lv,
-  nl,
+  mr,
+  ms,
   nb,
+  nl,
+  pa,
   pl,
   pt,
   ro,
   ru,
-  'sr-Latn': srLatn,
+  srCyrl,
+  srLatn,
+  sv,
+  sw,
+  ta,
+  te,
+  th,
   tr,
   uk,
-  vi,
-  'zh-Hans': zhHans,
   ur,
-  'pa-Guru': paGuru,
-  fil,
-  mr,
-  gu,
-  kn,
-  el
-}
-
-/**
- * Convert a numeric value to its cardinal (written) form in the requested language.
- *
- * This is the main entry point. The library dispatches synchronously to the appropriate
- * per-language converter based on the `lang` option. For browser builds, language converters
- * are statically imported so bundlers (webpack/rollup) can include them in output; Node.js
- * maintains identical behavior via the same static imports.
- *
- * @param {number|string|bigint} value The number to convert. Accepts:
- *   - `number` (integer or floating-point),
- *   - `string` (numeric string, possibly with decimal point),
- *   - `bigint` for very large integers.
- *   Decimal numbers as strings preserve precision that `number` type cannot.
- * @param {N2WordsOptions} [options={}] Optional configuration object.
- *
- * @returns {string} A human-readable cardinal representation of `value` in the
- *   requested language.
- *
- * @throws {TypeError} If `options` is provided but is not an object.
- * @throws {Error} If the requested language is unsupported (no match after fallback).
- *
- * @example
- * // Basic usage
- * convertToWords(1, { lang: 'en' }) // => 'one'
- * convertToWords('45.67', { lang: 'en' }) // => 'forty-five point six seven'
- * convertToWords(123n, { lang: 'fr' }) // => 'cent vingt-trois'
- *
- * @example
- * // Language-specific options (see individual language implementations)
- * convertToWords(1, { lang: 'zh-Hans', formal: true }) // Chinese formal style
- * convertToWords(1, { lang: 'cs', feminine: true }) // Czech feminine form
- */
-export default function (value, options = {}) {
-  if (options !== null && options !== undefined && typeof options !== 'object') {
-    throw new TypeError('Options must be an object, received: ' + typeof options)
-  }
-
-  if (options === null) {
-    options = {}
-  }
-
-  let languageCode = options.lang
-
-  if (languageCode === undefined) {
-    return dict.en(value, options)
-  }
-
-  if (typeof languageCode !== 'string') {
-    languageCode = String(languageCode)
-  }
-
-  let languageConverter = dict[languageCode]
-  if (languageConverter !== undefined) {
-    return languageConverter(value, options)
-  }
-
-  // Progressive fallback for regional variants: strip suffix on each iteration.
-  // Example: 'fr-BE-XX' -> try 'fr-BE' -> try 'fr' -> throw error
-  // Uses lastIndexOf for efficiency (O(n) vs O(n²) with repeated substring)
-  let lastDashIndex = languageCode.lastIndexOf('-')
-  while (lastDashIndex > 0) {
-    const candidateLanguageCode = languageCode.slice(0, lastDashIndex)
-    languageConverter = dict[candidateLanguageCode]
-    if (languageConverter !== undefined) {
-      return languageConverter(value, options)
-    }
-    lastDashIndex = candidateLanguageCode.lastIndexOf('-')
-  }
-
-  throw new Error('Unsupported language: "' + languageCode + '". Check supported language codes in the documentation.')
+  vi,
+  zhHans,
+  zhHant
 }

package/lib/utils/is-plain-object.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Checks if a value is a plain object (not null, array, or other object types).
+ *
+ * A plain object is one created by:
+ * - Object literal: `{}`
+ * - Object.create(null): null-prototype object
+ *
+ * This excludes arrays, class instances, Map, Set, and other object types.
+ *
+ * @param {*} value Value to check
+ * @returns {boolean} True if value is a plain object
+ */
+export function isPlainObject(value: any): boolean;

package/lib/utils/is-plain-object.js

@@ -0,0 +1,17 @@
+/**
+ * Checks if a value is a plain object (not null, array, or other object types).
+ *
+ * A plain object is one created by:
+ * - Object literal: `{}`
+ * - Object.create(null): null-prototype object
+ *
+ * This excludes arrays, class instances, Map, Set, and other object types.
+ *
+ * @param {*} value Value to check
+ * @returns {boolean} True if value is a plain object
+ */
+export function isPlainObject (value) {
+  if (value === null || typeof value !== 'object') return false
+  const proto = Object.getPrototypeOf(value)
+  return proto === null || proto === Object.prototype
+}

package/lib/utils/parse-numeric.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Numeric value parsing utility.
+ * Transforms user input (number, string, or bigint) into normalized components.
+ * @module parse-numeric
+ */
+/**
+ * Parses a numeric value into its components.
+ * @param {number|string|bigint} value
+ * @returns {{isNegative: boolean, integerPart: bigint, decimalPart?: string}}
+ * @throws {TypeError} If value is not number, string, or bigint
+ * @throws {Error} If value is not a valid number format
+ */
+export function parseNumericValue(value: number | string | bigint): {
+    isNegative: boolean;
+    integerPart: bigint;
+    decimalPart?: string;
+};

package/lib/utils/parse-numeric.js

@@ -0,0 +1,108 @@
+/**
+ * Numeric value parsing utility.
+ * Transforms user input (number, string, or bigint) into normalized components.
+ * @module parse-numeric
+ */
+
+/**
+ * Parses a numeric value into its components.
+ * @param {number|string|bigint} value
+ * @returns {{isNegative: boolean, integerPart: bigint, decimalPart?: string}}
+ * @throws {TypeError} If value is not number, string, or bigint
+ * @throws {Error} If value is not a valid number format
+ */
+export function parseNumericValue (value) {
+  const type = typeof value
+
+  // BigInt: simplest case
+  if (type === 'bigint') {
+    return value < 0n
+      ? { isNegative: true, integerPart: -value }
+      : { isNegative: false, integerPart: value }
+  }
+
+  // Number: fast path for safe integers
+  if (type === 'number') {
+    if (!Number.isFinite(value)) {
+      throw new Error('Number must be finite (NaN and Infinity are not supported)')
+    }
+    if (Number.isSafeInteger(value)) {
+      return value < 0
+        ? { isNegative: true, integerPart: BigInt(-value) }
+        : { isNegative: false, integerPart: BigInt(value) }
+    }
+    return parseNumericString(numberToString(value))
+  }
+
+  // String input
+  if (type === 'string') {
+    return parseNumericString(normalizeString(value))
+  }
+
+  throw new TypeError(
+    `Invalid value type: expected number, string, or bigint, received ${type}`
+  )
+}
+
+/**
+ * Converts a number to decimal string, expanding scientific notation if needed.
+ */
+function numberToString (value) {
+  const str = value.toString()
+  return (str.includes('e') || str.includes('E'))
+    ? expandScientificNotation(str)
+    : str
+}
+
+/**
+ * Validates and normalizes a string numeric input.
+ */
+function normalizeString (value) {
+  const trimmed = value.trim()
+  if (trimmed.length === 0 || Number.isNaN(Number(trimmed))) {
+    throw new Error(`Invalid number format: "${value}"`)
+  }
+  return (trimmed.includes('e') || trimmed.includes('E'))
+    ? expandScientificNotation(trimmed)
+    : trimmed
+}
+
+/**
+ * Parses a normalized numeric string into components.
+ */
+function parseNumericString (str) {
+  const isNegative = str[0] === '-'
+  if (isNegative) str = str.slice(1)
+
+  const dotIndex = str.indexOf('.')
+  if (dotIndex === -1) {
+    return { isNegative, integerPart: BigInt(str) }
+  }
+
+  const integerStr = str.slice(0, dotIndex) || '0'
+  const decimalPart = str.slice(dotIndex + 1)
+  return { isNegative, integerPart: BigInt(integerStr), decimalPart }
+}
+
+/**
+ * Expands scientific notation to decimal form (e.g., "1e21" → "1000...").
+ */
+function expandScientificNotation (str) {
+  const [mantissa, expStr] = str.toLowerCase().split('e')
+  const exp = parseInt(expStr, 10)
+
+  const dotIndex = mantissa.indexOf('.')
+  const digits = dotIndex === -1
+    ? mantissa
+    : mantissa.slice(0, dotIndex) + mantissa.slice(dotIndex + 1)
+  const integerLength = dotIndex === -1 ? mantissa.length : dotIndex
+  const newDotPosition = integerLength + exp
+
+  if (newDotPosition >= digits.length) {
+    return digits + '0'.repeat(newDotPosition - digits.length)
+  }
+  if (newDotPosition <= 0) {
+    return '0.' + '0'.repeat(-newDotPosition) + digits
+  }
+  return digits.slice(0, newDotPosition) + '.' + digits.slice(newDotPosition)
+}

package/lib/utils/validate-options.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Validates and normalizes the options parameter.
+ *
+ * @param {*} options The options value to validate
+ * @returns {Object} A valid options object (empty object if undefined)
+ * @throws {TypeError} If options is not undefined or a plain object
+ */
+export function validateOptions(options: any): Object;

package/lib/utils/validate-options.js

@@ -0,0 +1,16 @@
+import { isPlainObject } from './is-plain-object.js'
+
+/**
+ * Validates and normalizes the options parameter.
+ *
+ * @param {*} options The options value to validate
+ * @returns {Object} A valid options object (empty object if undefined)
+ * @throws {TypeError} If options is not undefined or a plain object
+ */
+export function validateOptions (options) {
+  if (options === undefined) return {}
+  if (isPlainObject(options)) return options
+  throw new TypeError(
+    `Invalid options: expected plain object or undefined, got ${typeof options}`
+  )
+}