n2words 3.0.0 → 4.0.0

package/src/ur-PK.js

@@ -0,0 +1,268 @@
+/**
+ * Urdu (Pakistan) language converter
+ *
+ * CLDR: ur-PK | Urdu as used in Pakistan
+ *
+ * Key features:
+ * - Indian numbering system (ہزار, لاکھ, کروڑ)
+ * - Urdu script (right-to-left)
+ * - 3-2-2 grouping pattern (last 3 digits, then groups of 2)
+ * - Complete word forms for 0-99
+ */
+
+import { parseCardinalValue } from './utils/parse-cardinal.js'
+import { parseCurrencyValue } from './utils/parse-currency.js'
+import { parseOrdinalValue } from './utils/parse-ordinal.js'
+
+// ============================================================================
+// Vocabulary
+// ============================================================================
+
+const ZERO = 'صفر'
+const NEGATIVE = 'منفی'
+const DECIMAL_SEP = 'اعشاریہ'
+const HUNDRED = 'سو'
+
+// ============================================================================
+// Ordinal Vocabulary
+// ============================================================================
+
+// Ordinal suffix (adds to cardinal)
+const ORDINAL_SUFFIX = 'واں'
+
+// Special ordinals for first few numbers
+const ORDINAL_SPECIAL = ['', 'پہلا', 'دوسرا', 'تیسرا', 'چوتھا', 'پانچواں', 'چھٹا']
+
+// ============================================================================
+// Currency Vocabulary (Pakistani Rupee)
+// ============================================================================
+
+// Rupee: singular/plural (same form used)
+const RUPEE = 'روپیہ'
+const RUPEES = 'روپے'
+
+// Paisa: singular/plural
+const PAISA = 'پیسہ'
+const PAISE = 'پیسے'
+
+const BELOW_HUNDRED = [
+  'صفر', 'ایک', 'دو', 'تین', 'چار', 'پانچ', 'چھ', 'سات', 'آٹھ', 'نو',
+  'دس', 'گیارہ', 'بارہ', 'تیرہ', 'چودہ', 'پندرہ', 'سولہ', 'سترہ', 'اٹھارہ', 'انیس',
+  'بیس', 'اکیس', 'بائیس', 'تیئیس', 'چوبیس', 'پچیس', 'چھبیس', 'ستائیس', 'اٹھائیس', 'انتیس',
+  'تیس', 'اکتیس', 'بتیس', 'تینتیس', 'چونتیس', 'پینتیس', 'چھتیس', 'سینتیس', 'اڑتیس', 'انتالیس',
+  'چالیس', 'اکتالیس', 'بیالیس', 'تینتالیس', 'چوالیس', 'پینتالیس', 'چھالیس', 'سینتالیس', 'اڑتالیس', 'انچاس',
+  'پچاس', 'اکاون', 'باون', 'ترپن', 'چون', 'پچپن', 'چھپن', 'ستاون', 'اٹھاون', 'انسٹھ',
+  'ساٹھ', 'اکسٹھ', 'باسٹھ', 'ترسٹھ', 'چونسٹھ', 'پینسٹھ', 'چھیاسٹھ', 'سڑسٹھ', 'اڑسٹھ', 'انہتر',
+  'ستر', 'اکہتر', 'بہتر', 'تہتر', 'چوہتر', 'پچھتر', 'چھہتر', 'ستتر', 'اٹھہتر', 'اناسی',
+  'اسی', 'اکیاسی', 'بیاسی', 'تریاسی', 'چوراسی', 'پچاسی', 'چھیاسی', 'ستاسی', 'اٹھاسی', 'نواسی',
+  'نوے', 'اکانوے', 'بانوے', 'ترانوے', 'چورانوے', 'پچانوے', 'چھیانوے', 'ستانوے', 'اٹھانوے', 'ننانوے'
+]
+
+// Scale words: index 0 = units (empty), 1 = thousand, 2 = lakh, 3 = crore, etc.
+const SCALE_WORDS = ['', 'ہزار', 'لاکھ', 'کروڑ', 'ارب', 'کھرب', 'نیل', 'پدم', 'شنکھ']
+
+// ============================================================================
+// Segment Building
+// ============================================================================
+
+/**
+ * Builds words for a 0-999 segment.
+ */
+function buildSegment (n) {
+  if (n === 0) return ''
+  if (n < 100) return BELOW_HUNDRED[n]
+
+  const hundreds = Math.trunc(n / 100)
+  const remainder = n % 100
+
+  if (remainder === 0) {
+    return BELOW_HUNDRED[hundreds] + ' ' + HUNDRED
+  }
+  return BELOW_HUNDRED[hundreds] + ' ' + HUNDRED + ' ' + BELOW_HUNDRED[remainder]
+}
+
+// ============================================================================
+// Conversion Functions
+// ============================================================================
+
+/**
+ * Converts a non-negative integer to Urdu words.
+ *
+ * Uses BigInt modulo for segment extraction (faster than string slicing).
+ * South Asian 3-2-2 grouping: first 3 digits, then groups of 2.
+ *
+ * @param {bigint} n - Non-negative integer to convert
+ * @returns {string} Urdu words
+ */
+function integerToWords (n) {
+  if (n === 0n) return ZERO
+
+  // Fast path: numbers < 1000 (direct lookup)
+  if (n < 1000n) {
+    return buildSegment(Number(n))
+  }
+
+  // Extract segments using BigInt modulo
+  const segments = []
+  segments.push(Number(n % 1000n))
+  let temp = n / 1000n
+
+  while (temp > 0n) {
+    segments.push(Number(temp % 100n))
+    temp = temp / 100n
+  }
+
+  // Build result string (process from most-significant to least)
+  const words = []
+  for (let i = segments.length - 1; i >= 0; i--) {
+    const segment = segments[i]
+    if (segment === 0) continue
+
+    if (i === 0) {
+      words.push(buildSegment(segment))
+    } else {
+      words.push(BELOW_HUNDRED[segment])
+    }
+
+    if (i > 0 && SCALE_WORDS[i]) {
+      words.push(SCALE_WORDS[i])
+    }
+  }
+
+  return words.join(' ')
+}
+
+function decimalPartToWords (decimalPart) {
+  let result = ''
+  let i = 0
+
+  while (i < decimalPart.length && decimalPart[i] === '0') {
+    if (result) result += ' '
+    result += ZERO
+    i++
+  }
+
+  const remainder = decimalPart.slice(i)
+  if (remainder) {
+    if (result) result += ' '
+    result += integerToWords(BigInt(remainder))
+  }
+
+  return result
+}
+
+/**
+ * Converts a numeric value to Urdu words.
+ *
+ * @param {number | string | bigint} value - The numeric value to convert
+ * @returns {string} The number in Urdu words
+ */
+function toCardinal (value) {
+  const { isNegative, integerPart, decimalPart } = parseCardinalValue(value)
+
+  let result = ''
+
+  if (isNegative) {
+    result = NEGATIVE + ' '
+  }
+
+  result += integerToWords(integerPart)
+
+  if (decimalPart) {
+    result += ' ' + DECIMAL_SEP + ' ' + decimalPartToWords(decimalPart)
+  }
+
+  return result
+}
+
+// ============================================================================
+// ORDINAL: toOrdinal(value)
+// ============================================================================
+
+/**
+ * Converts a positive integer to Urdu ordinal words.
+ *
+ * Urdu ordinals: First 6 are irregular, then add -واں suffix.
+ *
+ * @param {bigint} n - Positive integer to convert
+ * @returns {string} Urdu ordinal words
+ */
+function integerToOrdinal (n) {
+  // Special ordinals for 1-6
+  if (n >= 1n && n <= 6n) {
+    return ORDINAL_SPECIAL[Number(n)]
+  }
+
+  // For 7 and above, add suffix to cardinal
+  const cardinal = integerToWords(n)
+  return cardinal + ORDINAL_SUFFIX
+}
+
+/**
+ * Converts a numeric value to Urdu 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)    // 'پہلا'
+ * toOrdinal(2)    // 'دوسرا'
+ * toOrdinal(3)    // 'تیسرا'
+ * toOrdinal(10)   // 'دسواں'
+ */
+function toOrdinal (value) {
+  const integerPart = parseOrdinalValue(value)
+  return integerToOrdinal(integerPart)
+}
+
+// ============================================================================
+// CURRENCY: toCurrency(value, options?)
+// ============================================================================
+
+/**
+ * Converts a numeric value to Urdu currency words (Pakistani Rupee).
+ *
+ * @param {number | string | bigint} value - The currency amount to convert
+ * @returns {string} The amount in Urdu 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.01)   // 'ایک پیسہ'
+ */
+function toCurrency (value) {
+  const { isNegative, dollars: rupees, cents: paise } = parseCurrencyValue(value)
+
+  // Build result
+  let result = ''
+  if (isNegative) result = NEGATIVE + ' '
+
+  // Rupees part - show if non-zero, or if no paise
+  if (rupees > 0n || paise === 0n) {
+    result += integerToWords(rupees)
+    // Singular for 1 rupee, plural otherwise
+    result += ' ' + (rupees === 1n ? RUPEE : RUPEES)
+  }
+
+  // Paise part
+  if (paise > 0n) {
+    if (rupees > 0n) {
+      result += ' '
+    }
+    result += integerToWords(paise)
+    // Singular for 1 paisa, plural otherwise
+    result += ' ' + (paise === 1n ? PAISA : PAISE)
+  }
+
+  return result
+}
+
+// ============================================================================
+// Exports
+// ============================================================================
+
+export { toCardinal, toOrdinal, toCurrency }

package/src/utils/expand-scientific.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Scientific notation expansion utility.
+ * Converts scientific notation strings to full decimal form.
+ * @module expand-scientific
+ */
+/**
+ * Expands scientific notation to full decimal form.
+ * Handles arbitrarily large exponents without precision loss.
+ *
+ * @param {string} str - String in scientific notation (e.g., "1e21", "1.5e-3")
+ * @returns {string} Full decimal representation (e.g., "1000000000000000000000", "0.0015")
+ *
+ * @example
+ * expandScientificNotation("1e21")    // "1000000000000000000000"
+ * expandScientificNotation("1.5e3")   // "1500"
+ * expandScientificNotation("1e-3")    // "0.001"
+ */
+export function expandScientificNotation(str: string): string;
+/**
+ * Converts a number to decimal string, expanding scientific notation if needed.
+ *
+ * @param {number} value - The number to convert
+ * @returns {string} Decimal string representation
+ */
+export function numberToString(value: number): string;
+/**
+ * Checks if a string contains scientific notation.
+ *
+ * @param {string} str - String to check
+ * @returns {boolean} True if string contains 'e' or 'E'
+ */
+export function hasScientificNotation(str: string): boolean;

package/src/utils/expand-scientific.js

@@ -0,0 +1,65 @@
+/**
+ * Scientific notation expansion utility.
+ * Converts scientific notation strings to full decimal form.
+ * @module expand-scientific
+ */
+
+/**
+ * Expands scientific notation to full decimal form.
+ * Handles arbitrarily large exponents without precision loss.
+ *
+ * @param {string} str - String in scientific notation (e.g., "1e21", "1.5e-3")
+ * @returns {string} Full decimal representation (e.g., "1000000000000000000000", "0.0015")
+ *
+ * @example
+ * expandScientificNotation("1e21")    // "1000000000000000000000"
+ * expandScientificNotation("1.5e3")   // "1500"
+ * expandScientificNotation("1e-3")    // "0.001"
+ */
+export function expandScientificNotation (str) {
+  let [mantissa, expStr] = str.toLowerCase().split('e')
+  const exp = parseInt(expStr, 10)
+
+  // Strip sign before processing digits
+  let sign = ''
+  if (mantissa[0] === '-') {
+    sign = '-'
+    mantissa = mantissa.slice(1)
+  }
+
+  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 sign + digits + '0'.repeat(newDotPosition - digits.length)
+  } else if (newDotPosition <= 0) {
+    return sign + '0.' + '0'.repeat(-newDotPosition) + digits
+  } else {
+    return sign + digits.slice(0, newDotPosition) + '.' + digits.slice(newDotPosition)
+  }
+}
+
+/**
+ * Converts a number to decimal string, expanding scientific notation if needed.
+ *
+ * @param {number} value - The number to convert
+ * @returns {string} Decimal string representation
+ */
+export function numberToString (value) {
+  const str = value.toString()
+  return hasScientificNotation(str) ? expandScientificNotation(str) : str
+}
+
+/**
+ * Checks if a string contains scientific notation.
+ *
+ * @param {string} str - String to check
+ * @returns {boolean} True if string contains 'e' or 'E'
+ */
+export function hasScientificNotation (str) {
+  return str.includes('e') || str.includes('E')
+}

package/src/utils/parse-cardinal.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Parses a value for cardinal conversion.
+ * Cardinals accept any numeric value: integers, decimals, negatives.
+ *
+ * @param {number|string|bigint} value - The value to parse
+ * @returns {{isNegative: boolean, integerPart: bigint, decimalPart?: string}}
+ * @throws {TypeError} If value is not number, string, or bigint
+ * @throws {RangeError} If value is not finite
+ */
+export function parseCardinalValue(value: number | string | bigint): {
+    isNegative: boolean;
+    integerPart: bigint;
+    decimalPart?: string;
+};

package/{lib/utils/parse-numeric.js → src/utils/parse-cardinal.js}

@@ -1,17 +1,22 @@
 /**
- * Numeric value parsing utility.
+ * Cardinal value parsing utility.
  * Transforms user input (number, string, or bigint) into normalized components.
- * @module parse-numeric
+ * Handles negatives, decimals, and scientific notation.
+ * @module parse-cardinal
  */
 
+import { expandScientificNotation, hasScientificNotation, numberToString } from './expand-scientific.js'
+
 /**
- * Parses a numeric value into its components.
- * @param {number|string|bigint} value
+ * Parses a value for cardinal conversion.
+ * Cardinals accept any numeric value: integers, decimals, negatives.
+ *
+ * @param {number|string|bigint} value - The value to parse
  * @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
+ * @throws {RangeError} If value is not finite
  */
-export function parseNumericValue (value) {
+export function parseCardinalValue (value) {
   const type = typeof value
 
   // BigInt: simplest case
@@ -24,7 +29,7 @@ export function parseNumericValue (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)')
+      throw new RangeError('Number must be finite (NaN and Infinity are not supported)')
     }
     if (Number.isSafeInteger(value)) {
       return value < 0
@@ -44,27 +49,15 @@ export function parseNumericValue (value) {
   )
 }
 
-/**
- * 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}"`)
+    throw new RangeError(`Invalid number format: "${value}"`)
   }
-  return (trimmed.includes('e') || trimmed.includes('E'))
-    ? expandScientificNotation(trimmed)
-    : trimmed
+  return hasScientificNotation(trimmed) ? expandScientificNotation(trimmed) : trimmed
 }
 
 /**
@@ -83,26 +76,3 @@ function parseNumericString (str) {
   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/src/utils/parse-currency.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Parses a value for currency conversion.
+ * Returns dollars and cents as separate bigints, plus negative flag.
+ *
+ * @param {number|string|bigint} value - The value to parse
+ * @returns {{isNegative: boolean, dollars: bigint, cents: bigint}}
+ * @throws {TypeError} If value is not number, string, or bigint
+ * @throws {RangeError} If value is not finite
+ */
+export function parseCurrencyValue(value: number | string | bigint): {
+    isNegative: boolean;
+    dollars: bigint;
+    cents: bigint;
+};

package/src/utils/parse-currency.js

@@ -0,0 +1,91 @@
+/**
+ * Currency value parsing utility.
+ * Optimized parser for currency conversion - extracts dollars and cents.
+ * @module parse-currency
+ */
+
+import { expandScientificNotation, hasScientificNotation, numberToString } from './expand-scientific.js'
+
+/**
+ * Parses a value for currency conversion.
+ * Returns dollars and cents as separate bigints, plus negative flag.
+ *
+ * @param {number|string|bigint} value - The value to parse
+ * @returns {{isNegative: boolean, dollars: bigint, cents: bigint}}
+ * @throws {TypeError} If value is not number, string, or bigint
+ * @throws {RangeError} If value is not finite
+ */
+export function parseCurrencyValue (value) {
+  const type = typeof value
+
+  // BigInt: whole dollars only
+  if (type === 'bigint') {
+    return value < 0n
+      ? { isNegative: true, dollars: -value, cents: 0n }
+      : { isNegative: false, dollars: value, cents: 0n }
+  }
+
+  // Number: fast path for safe integers
+  if (type === 'number') {
+    if (!Number.isFinite(value)) {
+      throw new RangeError('Currency must be a finite number')
+    }
+    if (Number.isSafeInteger(value)) {
+      return value < 0
+        ? { isNegative: true, dollars: BigInt(-value), cents: 0n }
+        : { isNegative: false, dollars: BigInt(value), cents: 0n }
+    }
+    // Non-integer or unsafe: convert to string
+    return parseCurrencyString(numberToString(value))
+  }
+
+  // String input
+  if (type === 'string') {
+    return parseCurrencyString(value)
+  }
+
+  throw new TypeError(
+    `Invalid value type: expected number, string, or bigint, received ${type}`
+  )
+}
+
+/**
+ * Parses a string for currency conversion.
+ *
+ * @param {string} value - The string to parse
+ * @returns {{isNegative: boolean, dollars: bigint, cents: bigint}}
+ */
+function parseCurrencyString (value) {
+  let str = value.trim()
+
+  if (str.length === 0 || Number.isNaN(Number(str))) {
+    throw new RangeError(`Invalid currency format: "${value}"`)
+  }
+
+  // Expand scientific notation
+  if (hasScientificNotation(str)) {
+    str = expandScientificNotation(str)
+  }
+
+  // Handle negative
+  const isNegative = str[0] === '-'
+  if (isNegative) str = str.slice(1)
+
+  // Split on decimal
+  const dotIndex = str.indexOf('.')
+  if (dotIndex === -1) {
+    return { isNegative, dollars: BigInt(str), cents: 0n }
+  }
+
+  const dollarStr = str.slice(0, dotIndex) || '0'
+  const decimalPart = str.slice(dotIndex + 1)
+
+  // Truncate to 2 decimal places and pad if needed
+  const centStr = (decimalPart + '00').slice(0, 2)
+
+  return {
+    isNegative,
+    dollars: BigInt(dollarStr),
+    cents: BigInt(centStr)
+  }
+}

package/src/utils/parse-ordinal.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Parses a value for ordinal conversion.
+ * Ordinals require positive integers only (no zero, negatives, or decimals).
+ *
+ * @param {number|string|bigint} value - The value to parse
+ * @returns {bigint} The positive integer value
+ * @throws {TypeError} If value is not number, string, or bigint
+ * @throws {RangeError} If value is zero, negative, or has a decimal part
+ */
+export function parseOrdinalValue(value: number | string | bigint): bigint;