n2words 1.23.0 → 1.24.0

package/typings/languages/fr-BE.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Converts a number to Belgian French cardinal (written) form.
+ *
+ * @param {number|string|bigint} value The number to convert.
+ * @param {Object} [options={}] Configuration options.
+ * @param {boolean} [options.withHyphenSeparator=false] Use hyphens (true) instead of spaces (false) in compounds.
+ * @returns {string} The number expressed in Belgian French words.
+ * @throws {TypeError} If value is NaN or invalid type.
+ * @throws {Error} If value is an invalid number string.
+ */
+export default function convertToWords(value: number | string | bigint, options?: {
+    withHyphenSeparator?: boolean;
+}): string;
+/**
+ * @typedef {Object} BelgianFrenchOptions
+ * @property {boolean} [withHyphenSeparator=false] Use hyphens (true) instead of spaces (false) in compounds.
+ */
+/**
+ * Belgian French language converter.
+ *
+ * Extends the French converter with Belgian French regional variant:
+ * - Uses "septante" (70) instead of "soixante-dix"
+ * - Uses "nonante" (90) instead of "quatre-vingt-dix"
+ * - Maintains standard French "quatre-vingts" for 80
+ * - More regular and logical number system than standard French
+ *
+ * Features:
+ * - Regional number word variations (septante, nonante)
+ * - Simplified tens naming (no complex arithmetic)
+ * - Inherits all other French grammar rules from FR class
+ * - Same pluralization and hyphenation patterns as standard French
+ */
+export class BelgianFrench extends French {
+}
+export type BelgianFrenchOptions = {
+    /**
+     * Use hyphens (true) instead of spaces (false) in compounds.
+     */
+    withHyphenSeparator?: boolean;
+};
+import { French } from './fr.js';

package/typings/languages/fr.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Converts a number to French cardinal (written) form.
+ *
+ * @param {number|string|bigint} value The number to convert.
+ * @param {Object} [options] Conversion options (see FR class).
+ * @returns {string} The number expressed in French words.
+ * @throws {TypeError} If value is NaN or invalid type.
+ * @throws {Error} If value is an invalid number string.
+ *
+ * @example
+ * convertToWords(42, { lang: 'fr' }); // 'quarante-deux'
+ * convertToWords(81, { lang: 'fr' }); // 'quatre-vingt-un'
+ */
+export default function convertToWords(value: number | string | bigint, options?: any): string;
+/**
+ * @typedef {Object} FrenchOptions
+ * @property {boolean} [withHyphenSeparator=false] Use hyphens (true) instead of spaces (false) in compounds.
+ */
+/**
+ * French language converter.
+ *
+ * Special handling:
+ * - Pluralization of "cent" (hundred) and other words
+ * - "et" (and) before odd numbers in tens place
+ * - Hyphenation for compound numbers
+ * - Regional number word variations
+ */
+export class French extends GreedyScaleLanguage {
+    /**
+     * Initializes the French converter with language-specific options.
+     *
+     * @param {FrenchOptions} [options={}] Configuration options.
+     */
+    constructor({ withHyphenSeparator }?: FrenchOptions);
+    withHyphenSeparator: boolean;
+}
+export type FrenchOptions = {
+    /**
+     * Use hyphens (true) instead of spaces (false) in compounds.
+     */
+    withHyphenSeparator?: boolean;
+};
+import GreedyScaleLanguage from '../classes/greedy-scale-language.js';

package/typings/languages/gu.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Convert a number to Gujarati words
+ *
+ * @param {number|string|bigint} value - The number to convert
+ * @param {Object} [options={}] - Conversion options
+ * @returns {string} The Gujarati word representation
+ * @example
+ * convertToWords(42) // 'બેતાળીસ'
+ * convertToWords(1000) // 'એક હજાર'
+ * convertToWords(100000) // 'એક લાખ'
+ */
+export default function convertToWords(value: number | string | bigint, options?: any): string;

package/typings/languages/he.d.ts

@@ -0,0 +1,197 @@
+/**
+ * Converts a number to Hebrew cardinal (written) form.
+ *
+ * @param {number|string|bigint} value The number to convert.
+ * @param {HebrewOptions} [options={}] Configuration options.
+ * @returns {string} The number expressed in Hebrew words.
+ * @throws {TypeError} If value is NaN or invalid type.
+ * @throws {Error} If value is an invalid number string.
+ */
+export default function convertToWords(value: number | string | bigint, options?: HebrewOptions): string;
+/**
+ * @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.
+ */
+/**
+ * Hebrew language converter.
+ *
+ * Implements Hebrew number words using the Slavic language pattern:
+ * - Hebrew alphabet and right-to-left text
+ * - Hebrew number words (אחת, שתים, שלוש, ארבע...)
+ * - Feminine number forms (default in Hebrew)
+ * - Optional "ve" (ו, "and") conjunction between number groups
+ *
+ * Key Features:
+ * - Three-form pluralization system shared across Slavic languages
+ *   * Form 1 (singular): 1 (e.g., "אלף")
+ *   * Form 2 (few): 2-4, 22-24, 32-34... excluding teens (e.g., "אלפים")
+ *   * Form 3 (many): all other numbers (e.g., "אלף")
+ * - Chunk-based decomposition (splits into groups of 3 digits: ones, thousands, millions, etc.)
+ * - Large number handling via thousands[] array with indexed [singular, few, many] forms
+ *
+ * Features:
+ * - Right-to-left text orientation
+ * - Feminine grammatical gender for numbers
+ * - Three-form pluralization (similar to Slavic pattern)
+ * - Conjunction control via "and" option
+ *
+ * Inherits from SlavicLanguage for complex pluralization algorithms.
+ */
+export class Hebrew extends SlavicLanguage {
+    /**
+     * Initializes the Hebrew converter with language-specific options.
+     *
+     * @param {HebrewOptions} [options={}] Configuration options.
+     */
+    constructor({ and, biblical, feminine }?: HebrewOptions);
+    ones: {
+        1: string;
+        2: string;
+        3: string;
+        4: string;
+        5: string;
+        6: string;
+        7: string;
+        8: string;
+        9: string;
+    };
+    tens: {
+        0: string;
+        1: string;
+        2: string;
+        3: string;
+        4: string;
+        5: string;
+        6: string;
+        7: string;
+        8: string;
+        9: string;
+    };
+    twenties: {
+        2: string;
+        3: string;
+        4: string;
+        5: string;
+        6: string;
+        7: string;
+        8: string;
+        9: string;
+    };
+    hundreds: {
+        1: string;
+        2: string;
+        3: string;
+    };
+    thousands: {
+        1: string;
+        2: string;
+        3: string;
+        4: string;
+        5: string;
+        6: string;
+        7: string;
+        8: string;
+        9: string;
+    };
+    scale: {
+        1: string;
+        2: string;
+        3: string;
+        4: string;
+        5: string;
+        6: string;
+    };
+    scalePlural: {
+        1: string;
+        2: string;
+        3: string;
+        4: string;
+        5: string;
+        6: string;
+    };
+    biblicalOnes: {
+        1: string;
+        2: string;
+        3: string;
+        4: string;
+        5: string;
+        6: string;
+        7: string;
+        8: string;
+        9: string;
+    };
+    biblicalTens: {
+        0: string;
+        1: string;
+        2: string;
+        3: string;
+        4: string;
+        5: string;
+        6: string;
+        7: string;
+        8: string;
+        9: string;
+    };
+    biblicalTwenties: {
+        2: string;
+        3: string;
+        4: string;
+        5: string;
+        6: string;
+        7: string;
+        8: string;
+        9: string;
+    };
+    biblicalHundreds: {
+        1: string;
+        2: string;
+        3: string;
+    };
+    biblicalThousands: {
+        1: string;
+        2: string;
+        3: string;
+        4: string;
+        5: string;
+        6: string;
+        7: string;
+        8: string;
+        9: string;
+    };
+    biblicalScale: {
+        1: string;
+        2: string;
+        3: string;
+        4: string;
+        5: string;
+        6: string;
+    };
+    biblicalScalePlural: {
+        1: string;
+        2: string;
+        3: string;
+        4: string;
+        5: string;
+        6: string;
+    };
+    and: string;
+    biblical: boolean;
+    convertWholePart(number: any): string;
+}
+export type HebrewOptions = {
+    /**
+     * Conjunction character (typically 'ו' for and).
+     */
+    and?: string;
+    /**
+     * Use biblical scale words instead of modern ones.
+     */
+    biblical?: boolean;
+    /**
+     * Use feminine forms for numbers.
+     */
+    feminine?: boolean;
+};
+import SlavicLanguage from '../classes/slavic-language.js';

package/typings/languages/hi.d.ts

@@ -0,0 +1 @@
+export default function convertToWords(value: any, options?: {}): string;

package/typings/languages/hr.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Converts a number to Croatian cardinal (written) form.
+ *
+ * @param {number|string|bigint} value The number to convert.
+ * @param {Object} [options={}] Configuration options.
+ * @param {boolean} [options.feminine=false] Use feminine forms for numbers.
+ * @returns {string} The number expressed in Croatian words.
+ * @throws {TypeError} If value is NaN or invalid type.
+ * @throws {Error} If value is an invalid number string.
+ */
+export default function convertToWords(value: number | string | bigint, options?: {
+    feminine?: boolean;
+}): string;
+/**
+ * @typedef {Object} SlavicOptions
+ * @property {boolean} [feminine=false] Use feminine forms for numbers.
+ */
+/**
+ * Croatian language converter.
+ *
+ * Implements Croatian number words using the Slavic language pattern:
+ * - Croatian number words (jedan/jedna, dva/dvije, tri, četiri...)
+ * - Gender-aware forms (masculine/feminine)
+ * - Slavic three-form pluralization (tisuća/tisuće/tisuća)
+ * - Croatian-specific declension endings
+ *
+ * Key Features:
+ * - Three-form pluralization system shared across Slavic languages
+ *   * Form 1 (singular): 1 (e.g., "tisuća")
+ *   * Form 2 (few): 2-4, 22-24, 32-34... excluding teens (e.g., "tisuće")
+ *   * Form 3 (many): all other numbers (e.g., "tisuća")
+ * - Chunk-based decomposition (splits into groups of 3 digits: ones, thousands, millions, etc.)
+ * - Large number handling via thousands[] array with indexed [singular, few, many] forms
+ * - Gender-specific number forms for 1 and 2 (masculine/feminine dual forms)
+ *
+ * Features:
+ * - Dual gender forms for 1 and 2 (jedan/jedna, dva/dvije)
+ * - Latin script orthography
+ * - Similar structure to Serbian
+ *
+ * Inherits from SlavicLanguage for complex pluralization algorithms.
+ */
+export class Croatian extends SlavicLanguage {
+    ones: {
+        1: string[];
+        2: string[];
+        3: string[];
+        4: string[];
+        5: string[];
+        6: string[];
+        7: string[];
+        8: string[];
+        9: string[];
+    };
+    tens: {
+        0: string;
+        1: string;
+        2: string;
+        3: string;
+        4: string;
+        5: string;
+        6: string;
+        7: string;
+        8: string;
+        9: string;
+    };
+    twenties: {
+        2: string;
+        3: string;
+        4: string;
+        5: string;
+        6: string;
+        7: string;
+        8: string;
+        9: string;
+    };
+    hundreds: {
+        1: string;
+        2: string;
+        3: string;
+        4: string;
+        5: string;
+        6: string;
+        7: string;
+        8: string;
+        9: string;
+    };
+    SCALE: {
+        0: (string | boolean)[];
+        1: (string | boolean)[];
+        2: (string | boolean)[];
+        3: (string | boolean)[];
+        4: (string | boolean)[];
+        5: (string | boolean)[];
+        6: (string | boolean)[];
+        7: (string | boolean)[];
+        8: (string | boolean)[];
+        9: (string | boolean)[];
+        10: (string | boolean)[];
+    };
+    pluralize(n: any, forms: any): any;
+    convertWholePart(number: any): string;
+}
+export type SlavicOptions = {
+    /**
+     * Use feminine forms for numbers.
+     */
+    feminine?: boolean;
+};
+import SlavicLanguage from '../classes/slavic-language.js';

package/typings/languages/hu.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Converts a number to Hungarian cardinal (written) form.
+ *
+ * @param {number|string|bigint} value The number to convert.
+ * @param {Object} [options] Conversion options (see Hungarian class options).
+ * @returns {string} The number expressed in Hungarian words.
+ * @throws {TypeError} If value is NaN or invalid type.
+ * @throws {Error} If value is an invalid number string.
+ *
+ * @example
+ * convertToWords(42); // 'negyvenkettő'
+ * convertToWords(21); // 'huszonegy'
+ */
+export default function convertToWords(value: number | string | bigint, options?: any): string;
+/**
+ * Hungarian language converter.
+ *
+ * Converts numbers to Hungarian words following Hungarian conventions:
+ * - Agglutinative structure for compound numbers
+ * - No spaces between tens and units (e.g., "huszonegy" = twenty-one)
+ * - Special handling for "egy" (one) - often omitted as multiplier
+ * - Vowel harmony in compound words
+ *
+ * Features:
+ * - Compact number representations (húsz, harminc, negyven)
+ * - Pre-composed twenties (huszonegy through huszonkilenc)
+ * - "egész" as decimal separator (meaning "whole")
+ * - Support for very large numbers (up to quadrilliards)
+ */
+export class Hungarian extends GreedyScaleLanguage {
+    tensToCardinal(number: any): string;
+    hundredsToCardinal(number: any): string;
+    thousandsToCardinal(number: any): string;
+    bigNumberToCardinal(number: any): string;
+    convertWholePart(number: any, zeroWord?: string): string;
+}
+import GreedyScaleLanguage from '../classes/greedy-scale-language.js';

package/typings/languages/id.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Converts a number to Indonesian cardinal (written) form.
+ *
+ * @param {number|string|bigint} value The number to convert.
+ * @param {Object} [options={}] Configuration options.
+ * @returns {string} The number expressed in Indonesian words.
+ * @throws {TypeError} If value is NaN or invalid type.
+ * @throws {Error} If value is an invalid number string.
+ */
+export default function convertToWords(value: number | string | bigint, options?: any): string;
+/**
+ * Indonesian language converter.
+ *
+ * Converts numbers to Indonesian words following Indonesian conventions:
+ * - Simple base-10 structure
+ * - "Se-" prefix for one (e.g., "seratus" = one hundred, "seribu" = one thousand)
+ * - Space-separated number components
+ * - Straightforward grouping by thousands
+ *
+ * Key Features:
+ * - Base number mapping (base) for single digits 0-9
+ * - Magnitude scale (thousands) mapping powers of 10 to Indonesian words
+ * - Group-based algorithm:
+ *   1. Split number into groups of 3 digits
+ *   2. For each group, convert ones/tens/hundreds using base and naming rules
+ *   3. Apply "se-" prefix for 1 (seratus, seribu, sejuta)
+ *   4. Combine with magnitude words
+ *   5. Join all parts with spaces
+ * - Regular patterns (puluh for tens, ratus for hundreds, ribu for thousands)
+ * - Clear grouping: ribu (10³), juta (10⁶), miliar (10⁹), triliun (10¹²)
+ *
+ * Features:
+ * - "Se-" prefix usage for singular units
+ * - Support for very large numbers (up to decillions)
+ */
+export class Indonesian extends AbstractLanguage {
+    base: {
+        0: any[];
+        1: string[];
+        2: string[];
+        3: string[];
+        4: string[];
+        5: string[];
+        6: string[];
+        7: string[];
+        8: string[];
+        9: string[];
+    };
+    thousands: {
+        3: string;
+        6: string;
+        9: string;
+        12: string;
+        15: string;
+        18: string;
+        21: string;
+        24: string;
+        27: string;
+        30: string;
+        33: string;
+    };
+    splitBy3(number: any): any[][];
+    spell(blocks: any): any[];
+    getHundreds(number: any): any[];
+    getTens(number: any): any;
+    join(wordBlocks: any): string;
+    convertWholePart(number: any): string;
+}
+import AbstractLanguage from '../classes/abstract-language.js';

package/typings/languages/it.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Converts a number to Italian cardinal (written) form.
+ *
+ * @param {number|string|bigint} value The number to convert.
+ * @param {Object} [options={}] Configuration options.
+ * @returns {string} The number expressed in Italian words.
+ * @throws {TypeError} If value is NaN or invalid type.
+ * @throws {Error} If value is an invalid number string.
+ */
+export default function convertToWords(value: number | string | bigint, options?: any): string;
+/**
+ * Italian language converter.
+ *
+ * Converts numbers to Italian words following Italian conventions:
+ * - Phonetic contractions (removes duplicate vowels: "ventotto" not "ventiotto")
+ * - Accentuation rules for "tre" in compounds ("ventitré" not "ventitre")
+ * - Special handling for "uno" and vowel agreement
+ * - Complex composition patterns for large numbers
+ *
+ * Architecture Note:
+ * Unlike other GreedyScaleLanguage subclasses, Italian uses a custom algorithm
+ * rather than the standard highest-matching-scale approach. This is necessary
+ * because Italian's word formation rules are irregular and context-dependent.
+ * See tensToCardinal(), hundredsToCardinal(), and bigNumberToCardinal().
+ *
+ * Features:
+ * - Vowel elision (e.g., "ventotto" not "ventiotto")
+ * - Accentuation of final "tre" (ventitré, trentacinque - note: accent on compound tres)
+ * - Exponent-based large number naming (milione, miliardo, trilione)
+ * - Custom word construction for hundreds and thousands
+ */
+export class Italian extends GreedyScaleLanguage {
+    cardinalWords: string[];
+    strTens: {
+        2: string;
+        3: string;
+        4: string;
+        6: string;
+    };
+    exponentPrefixes: string[];
+    accentuate(string: any): any;
+    omitIfZero(numberToString: any): any;
+    phoneticContraction(string: any): any;
+    tensToCardinal(number: any): any;
+    hundredsToCardinal(number: any): any;
+    thousandsToCardinal(number: any): string;
+    exponentLengthToString(exponentLength: any): string;
+    bigNumberToCardinal(number: any): string;
+    convertWholePart(number: any): any;
+}
+import GreedyScaleLanguage from '../classes/greedy-scale-language.js';

package/typings/languages/ja.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Converts a value to cardinal (written) form in Japanese.
+ *
+ * @param {number|string|bigint} value - Number to convert.
+ * @param {Object} [options] - Options for the converter.
+ * @returns {string} Value in Japanese kanji numerals.
+ * @throws {Error} If value is invalid.
+ *
+ * @example
+ * convertToWords(42, { lang: 'ja' }); // '四十二'
+ * convertToWords(1000, { lang: 'ja' }); // '千'
+ * convertToWords(10000, { lang: 'ja' }); // '一万'
+ */
+export default function convertToWords(value: number | string | bigint, options?: any): string;
+/**
+ * Japanese language converter.
+ *
+ * Converts numbers to Japanese kanji numerals using the Sino-Japanese system:
+ * - Uses kanji characters (一, 二, 三, etc.)
+ * - Grouping by 万 (man, 10,000) and 億 (oku, 100,000,000)
+ * - Unique scale units: 兆 (chō, trillion), 京 (kei, 10^16)
+ * - Special rules for 1: omitted before 十 (10), 百 (100), 千 (1000), but kept for 万 and above
+ *
+ * Key Features:
+ * - Sino-Japanese number system (standard for general counting)
+ * - Grouping by powers of 10,000 (万-based system, not 1,000)
+ * - Scale units: 万 (10^4), 億 (10^8), 兆 (10^12), 京 (10^16)
+ * - Special handling of 一 (one) prefix
+ * - Support for very large numbers up to 無量大数 (10^68)
+ *
+ * Algorithm:
+ * 1. Split number into groups of 4 digits (万-based, not 3-digit thousand-based)
+ * 2. Convert each group to kanji using special rules
+ * 3. Append appropriate scale word (万, 億, 兆, etc.)
+ * 4. Join all groups
+ *
+ * Special Rules:
+ * - 10, 100, 1000: Don't use 一 prefix (十, 百, 千 not 一十, 一百, 一千)
+ * - 10,000+: Keep 一 prefix (一万, 一億, 一兆)
+ * - Zero: 零 or 〇 (both acceptable, 零 is more formal)
+ */
+export class Japanese extends AbstractLanguage {
+    scales: string[];
+    /**
+     * Converts a group of up to 4 digits to Japanese kanji.
+     * Handles special rules for omitting 一 before 十, 百, 千.
+     *
+     * Rule: Within a group, omit 一 before 十/百/千 EXCEPT when:
+     * - It's a lower group (not isTopGroup) AND
+     * - It would be the only character in that position
+     *
+     * @param {bigint} num - Number from 0 to 9999
+     * @param {boolean} isTopGroup - Whether this is the highest non-zero group
+     * @returns {string} Japanese kanji representation
+     */
+    convertGroup(num: bigint, isTopGroup?: boolean): string;
+}
+import AbstractLanguage from '../classes/abstract-language.js';

package/typings/languages/kn.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Converts a number to its word representation in Kannada.
+ * @param {number|string|bigint} value - The number to convert
+ * @param {Object} [options={}] - Conversion options
+ * @returns {string} The word representation of the number
+ * @example
+ * convertToWords(42) // 'ನಲವತ್ತೆರಡು'
+ * convertToWords(1000) // 'ಒಂದು ಸಾವಿರ'
+ * convertToWords(100000) // 'ಒಂದು ಲಕ್ಷ'
+ */
+export default function convertToWords(value: number | string | bigint, options?: any): string;

package/typings/languages/ko.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Converts a number to Korean cardinal (written) form.
+ *
+ * @param {number|string|bigint} value The number to convert.
+ * @param {Object} [options] Conversion options (see Korean class options).
+ * @returns {string} The number expressed in Korean words.
+ * @throws {TypeError} If value is NaN or invalid type.
+ * @throws {Error} If value is an invalid number string.
+ *
+ * @example
+ * convertToWords(42); // '사십이'
+ * convertToWords(10001); // '만 일'
+ */
+export default function convertToWords(value: number | string | bigint, options?: any): string;
+/**
+ * Korean language converter.
+ *
+ * Features:
+ * - Space-separated for large numbers (>= 만/10,000)
+ * - Concatenated for smaller numbers
+ * - Omits '일' (1) before multipliers
+ */
+export class Korean extends GreedyScaleLanguage {
+}
+import GreedyScaleLanguage from '../classes/greedy-scale-language.js';