num-to-text-hun

Convert numbers to Hungarian text representation.

Installation

pnpm add num-to-text-hun
# or
npm install num-to-text-hun

Usage

import {
  numToText, numToTextSafe, isConvertible,
  numToOrdinal, numToOrdinalSafe,
  numToDecimal, numToDecimalSafe,
  numToCurrency, numToCurrencySafe,
  numToDate, numToDateSafe,
  numToApproximate,
  numToCheck,
  numToRoman, numToRomanSafe, romanToNum, romanToNumSafe
} from 'num-to-text-hun';

// Basic usage
numToText(0);        // 'nulla'
numToText(42);       // 'negyvenkettő'
numToText(200);      // 'kétszáz'
numToText(1000);     // 'ezer'
numToText(2000);     // 'kétezer'
numToText(123456);   // 'százhuszonháromezer-négyszázötvenhat'
numToText(-100);     // 'mínusz száz'

// Safe version (returns null instead of throwing)
numToTextSafe(42);     // 'negyvenkettő'
numToTextSafe(3.14);   // null
numToTextSafe(NaN);    // null

// Ordinal numbers
numToOrdinal(1);       // 'első'
numToOrdinal(2);       // 'második'
numToOrdinal(21);      // 'huszonegyedik'
numToOrdinal(100);     // 'századik'

// Decimal numbers
numToDecimal(3.14);                         // 'három egész tizennégy'
numToDecimal(3.14, { style: 'fraction' });  // 'három egész tizennégy század'
numToDecimal(-0.5);                         // 'mínusz nulla egész öt'

// Currency formatting
numToCurrency(1500, { currency: 'HUF' });   // 'ezer-ötszáz forint'
numToCurrency(12.50, { currency: 'EUR' });  // 'tizenkettő euró ötven cent'
numToCurrency(99.99, { currency: 'USD' });  // 'kilencvenkilenc dollár kilencvenkilenc cent'
numToCurrency(50, { currency: 'GBP' });     // 'ötven font'
numToCurrency(25.50, { currency: 'CHF' });  // 'huszonöt frank ötven centime'

// Date formatting
numToDate(2025, 12, 24);                     // 'kétezer-huszonöt december huszonnegyedike'
numToDate(2025, 3, 15, { style: 'monthDay' }); // 'március tizenötödike'

// Approximate numbers
numToApproximate(100);              // 'körülbelül száz'
numToApproximate(1000, 'almost');   // 'majdnem ezer'
numToApproximate(500, 'moreThan');  // 'több mint ötszáz'

// Written check format
numToCheck(1500, { currency: 'HUF' });    // 'EZER-ÖTSZÁZ FORINT'
numToCheck(1234.56, { currency: 'HUF' }); // 'EZERKÉTSZÁZHARMINCNÉGY FORINT ÉS 56/100'

// Roman numerals
numToRoman(2025);     // 'MMXXV'
numToRoman(1999);     // 'MCMXCIX'
romanToNum('XIV');    // 14
romanToNum('MMXXV');  // 2025

// Type guard
if (isConvertible(userInput)) {
  console.log(numToText(userInput));
}

API

numToText(num: number): string

Converts an integer to its Hungarian text representation.

• Parameters: num - The integer to convert (supports negative numbers)
• Returns: The Hungarian text representation
• Throws: InvalidNumberError if the input is NaN, Infinity, or a non-integer

numToTextSafe(num: number): string | null

Safe version that returns null instead of throwing on invalid input.

isConvertible(value: unknown): value is number

Type guard to check if a value can be converted to Hungarian text.

InvalidNumberError

Custom error class thrown for invalid inputs.

numToOrdinal(num: number): string

Converts a positive integer to its Hungarian ordinal form.

• Parameters: num - The positive integer to convert
• Returns: The Hungarian ordinal (első, második, harmadik...)
• Throws: InvalidNumberError if the input is invalid or not positive

numToOrdinalSafe(num: number): string | null

Safe version that returns null instead of throwing on invalid input.

numToDecimal(num: number, options?: DecimalOptions): string

Converts a decimal number to Hungarian text.

• Parameters:
  • num - The decimal number to convert
  • options.style - 'simple' (default) or 'fraction'
• Returns: The Hungarian text representation

numToDecimal(3.14);                         // 'három egész tizennégy'
numToDecimal(3.14, { style: 'fraction' });  // 'három egész tizennégy század'

numToDecimalSafe(num: number, options?: DecimalOptions): string | null

Safe version that returns null instead of throwing on invalid input.

numToCurrency(num: number, options: CurrencyOptions): string

Converts a number to Hungarian currency text.

• Parameters:
  • num - The amount to convert (must be non-negative)
  • options.currency - One of: 'HUF', 'EUR', 'USD', 'GBP', 'CHF'
• Returns: The Hungarian currency text
• Throws: InvalidNumberError if the input is invalid or negative

| Currency | Main Unit | Sub Unit | |----------|-----------|----------| | HUF | forint | fillér | | EUR | euró | cent | | USD | dollár | cent | | GBP | font | penny | | CHF | frank | centime |

numToCurrencySafe(num: number, options: CurrencyOptions): string | null

Safe version that returns null instead of throwing on invalid input.

numToDate(year: number, month: number, day: number, options?: DateOptions): string

Converts a date to Hungarian text with possessive ordinal day.

• Parameters:
  • year - The year (or a Date object)
  • month - The month (1-12)
  • day - The day (1-31)
  • options.style - 'full' (default) or 'monthDay'
• Returns: The Hungarian date text

numToDate(2025, 12, 24);                       // 'kétezer-huszonöt december huszonnegyedike'
numToDate(2025, 3, 15, { style: 'monthDay' }); // 'március tizenötödike'
numToDate(new Date('2025-01-01'));             // 'kétezer-huszonöt január elseje'

numToDateSafe(year: number, month: number, day: number, options?: DateOptions): string | null

Safe version that returns null instead of throwing on invalid input.

numToApproximate(num: number, type?: ApproximationType): string

Adds an approximation prefix to a number.

• Parameters:
  • num - The number to convert
  • type - Approximation type (default: 'about')
• Returns: The number with approximation prefix

| Type | Hungarian | |------|-----------| | about | körülbelül | | almost | majdnem | | moreThan | több mint | | lessThan | kevesebb mint | | roughly | nagyjából | | around | mintegy |

numToApproximate(100);              // 'körülbelül száz'
numToApproximate(1000, 'almost');   // 'majdnem ezer'
numToApproximate(500, 'moreThan');  // 'több mint ötszáz'

numToCheck(amount: number, options?: CheckOptions): string

Formats a number for written bank checks (uppercase by default).

• Parameters:
  • amount - The amount to format
  • options.currency - Optional currency code
  • options.uppercase - Use uppercase (default: true)
• Returns: The check format text

numToCheck(1500);                          // 'EZER-ÖTSZÁZ'
numToCheck(1500, { currency: 'HUF' });     // 'EZER-ÖTSZÁZ FORINT'
numToCheck(1234.56, { currency: 'HUF' });  // 'EZERKÉTSZÁZHARMINCNÉGY FORINT ÉS 56/100'
numToCheck(100, { uppercase: false });     // 'száz'

numToRoman(num: number): string

Converts a number (1-3999) to Roman numerals.

• Parameters: num - The number to convert
• Returns: The Roman numeral representation
• Throws: InvalidNumberError if input is out of range

numToRoman(1);      // 'I'
numToRoman(4);      // 'IV'
numToRoman(2025);   // 'MMXXV'
numToRoman(3999);   // 'MMMCMXCIX'

numToRomanSafe(num: number): string | null

Safe version that returns null instead of throwing on invalid input.

romanToNum(roman: string): number

Parses a Roman numeral string to a number.

• Parameters: roman - The Roman numeral string
• Returns: The numeric value
• Throws: InvalidNumberError if input is invalid

romanToNum('XIV');   // 14
romanToNum('MMXXV'); // 2025
romanToNum('iv');    // 4 (case-insensitive)

romanToNumSafe(roman: string): number | null

Safe version that returns null instead of throwing on invalid input.

Hungarian Number Rules

This library follows Hungarian number grammar:

• Hyphens: Used between major groups (thousands and above)
  • 2001 -> "kétezer-egy"
• "egy" omission: Omitted before "száz" (100)
  • 100 -> "száz" (not "egyszáz")
  • 1000000 -> "egymillió" (included for million/billion)
• "ezer" alone: 1000 is just "ezer"
  • 1000 -> "ezer" (not "egyezer")
• "két" prefix: "két" is used before place values, "kettő" is used standalone
  • 2 -> "kettő"
  • 200 -> "kétszáz"
  • 2000 -> "kétezer"
• Special prefixes: "tizen-" and "huszon-" when followed by ones
  • 11 -> "tizenegy" (not "tízegy")
  • 20 -> "húsz" (but 21 -> "huszonegy")

Limitations

• numToText() only supports integers (use numToDecimal() for decimal numbers)
• Maximum safe integer: Number.MAX_SAFE_INTEGER (9,007,199,254,740,991)
• numToOrdinal() only supports positive integers
• numToRoman() only supports 1-3999 (standard Roman numeral range)

Development

# Install dependencies
pnpm install

# Run tests
pnpm test

# Run tests with coverage
pnpm run test:coverage

# Build
pnpm run build

# Lint
pnpm run lint

# Format
pnpm run format

License

ISC