Number to Words

​

Function

numberToWords(
  numberValue: number | string,
  options?: NumberToWordsOptions,
): string | PersianToolsTypeError

interface NumberToWordsOptions {
  ordinal?: boolean;   // append Persian ordinal suffix
}

import { numberToWords } from "@persian-tools/persian-tools";

numberToWords(0); // "صفر"
numberToWords(7); // "هفت"
numberToWords(123); // "صد و بیست و سه"
numberToWords(1234); // "یک هزار و دویست و سی و چهار"
numberToWords(1_000_000); // "یک میلیون"
numberToWords("12,345"); // "دوازده هزار و سیصد و چهل و پنج"
numberToWords(-100); // "منفی صد"

numberToWords(3, { ordinal: true }); // "سوم"

​

Input rules

• Accepts number | string. Strings are first run through removeCommas.
• The numeric value must be a safe integer (Number.isSafeInteger).
• Non-safe-integer input (floats, values above Number.MAX_SAFE_INTEGER) returns a PersianToolsTypeError instance (the function returns the error; it does not throw).
• Negative integers work — output is prefixed with منفی.

​

Return type — union with the error

import { numberToWords, PersianToolsTypeError } from "@persian-tools/persian-tools";

const result = numberToWords(userInput);
if (result instanceof PersianToolsTypeError) {
	console.error(result.message);
} else {
	console.log(result);
}

​

Range

• Min: -Number.MAX_SAFE_INTEGER
• Max: Number.MAX_SAFE_INTEGER (≈ 9.007e15)
• Floats: rejected.

​

Ordinal mode

• Ends with ی → append اُم (with leading space).
• Ends with سه → strip last 2 chars, append سوم.
• Otherwise → append م.

​

Pitfalls

• No currency or scale options. Older docs reference them — they do not exist.
• No locale switching. Output is always Persian words separated by و.
• Return is string | PersianToolsTypeError — guard accordingly.
• Persian-digit string input is not auto-normalized — removeCommas only handles commas. Run autoConvertDigitsToEN upstream if needed.

​

Composition

import { numberToWords, addCommas } from "@persian-tools/persian-tools";

const formatInvoice = (n: number) => `${addCommas(n)} ریال (${numberToWords(n)})`;

​

Source