hungarian-validators

hungarian-validators

🇭🇺 Magyarul / Hungarian

A TypeScript/JavaScript library for validating Hungarian identifiers: tax numbers (adóazonosító jel), TAJ numbers (Social Security Numbers), bank accounts, and more.

Installation

npm install hungarian-validators

Zero Dependencies - This library has no runtime dependencies, making it lightweight and fast to install.

Usage

Tax Number (Adóazonosító jel) Validation

import { validateTaxNumber, validateTaxNumberBirthDate } from 'hungarian-validators'

// Basic validation
const result = validateTaxNumber('8123456789')
if (result.isValid) {
  console.log('Valid tax number')
} else {
  console.error(result.error)
}

// Validation with English error messages
const resultEn = validateTaxNumber('8123456789', { language: 'en' })

// Validate tax number with birth date
const resultWithDate = validateTaxNumberBirthDate('8123456789', '1980-01-01', { language: 'en' })

Social Security Number (TAJ) Validation

import { validateSSNumber } from 'hungarian-validators'

// Basic validation
const result = validateSSNumber('111111110')
if (result.isValid) {
  console.log('Valid TAJ number')
} else {
  console.error(result.error)
}

// Validation with English error messages
const resultEn = validateSSNumber('111111110', { language: 'en' })

API

validateTaxNumber(taxNumber: string, options?: TaxNumberValidationOptions): ValidationResult

Validates a Hungarian tax number (adóazonosító jel).

Parameters:

• taxNumber: The tax number to validate (10 digits)
• options: Optional configuration
  • language: 'hu' | 'en' (default: 'hu')

Returns:

• ValidationResult object with:
  • isValid: boolean
  • error?: string (error message if invalid)

Validation Rules:

• Exactly 10 digits
• First digit must be 8 (for private individuals)
• Digits 2-6: Days since 1867-01-01 (birth date encoding)
• Digits 7-9: Random identifier (000-999)
• Digit 10: Checksum (modulo 11 of weighted sum)

validateTaxNumberBirthDate(taxNumber: string, birthDate: string | Date, options?: TaxNumberValidationOptions): ValidationResult

Validates if the birth date encoding in tax number matches the actual birth date.

Parameters:

• taxNumber: The tax number to validate
• birthDate: Birth date in YYYY-MM-DD format or Date object
• options: Optional configuration (same as above)

validateSSNumber(ssNumber: string, options?: SSNumberValidationOptions): ValidationResult

Validates a Hungarian Social Security Number (TAJ - Társadalombiztosítási Azonosító Jel).

Parameters:

• ssNumber: The TAJ number to validate (9 digits)
• options: Optional configuration
  • language: 'hu' | 'en' (default: 'hu')

Returns:

• ValidationResult object with:
  • isValid: boolean
  • error?: string (error message if invalid)

Validation Rules:

Based on 1996. évi XX. law:

• Exactly 9 digits
• Digits 1-8: Unique sequence number
• Digit 9: Control digit (CDV - Check Digit Verification)
• Checksum: Multiply odd positions (1st, 3rd, 5th, 7th) by 3, multiply even positions (2nd, 4th, 6th, 8th) by 7, sum all products, take modulo 10, compare with 9th digit

Examples

import { validateTaxNumber, validateTaxNumberBirthDate, validateSSNumber } from 'hungarian-validators'

// Example 1: Basic validation
const result1 = validateTaxNumber('8123456789')
console.log(result1.isValid) // true or false

// Example 2: Validation with English messages
const result2 = validateTaxNumber('123456789', { language: 'en' })
console.log(result2.error) // "Tax number must be exactly 10 digits"

// Example 3: Validate with birth date
const result3 = validateTaxNumberBirthDate('8123456789', '1980-01-01')

// Example 4: TAJ number validation
import { validateSSNumber } from 'hungarian-validators'
const result4 = validateSSNumber('111111110')
console.log(result4.isValid) // true

Future Validators

This package is designed to be extended with additional Hungarian validators:

• Bank Account Number (Bankszámlaszám)
• Company Tax Number (Adószám)
• And more...

License

MIT

Publishing New Versions

For maintainers, use the following scripts to publish new versions:

Version Bump Scripts

• pnpm run version:patch - Bumps patch version (1.0.0 → 1.0.1), creates git commit/tag, pushes to GitHub, and creates a GitHub release
• pnpm run version:minor - Bumps minor version (1.0.0 → 1.1.0), creates git commit/tag, pushes to GitHub, and creates a GitHub release
• pnpm run version:major - Bumps major version (1.0.0 → 2.0.0), creates git commit/tag, pushes to GitHub, and creates a GitHub release
• pnpm run version:patch:preview - Preview what the next patch version would be

Publish Scripts (Version Bump + Publish)

• pnpm run publish:patch - Bumps patch version, creates GitHub release, and publishes to npm
• pnpm run publish:minor - Bumps minor version, creates GitHub release, and publishes to npm
• pnpm run publish:major - Bumps major version, creates GitHub release, and publishes to npm

Usage examples:

# For a patch release (bug fixes)
pnpm run publish:patch

# For a minor release (new features, backward compatible)
pnpm run publish:minor

# For a major release (breaking changes)
pnpm run publish:major

Note:

• Make sure your git working directory is clean (commit or stash changes) before running these scripts, as they create git commits and tags automatically.
• The scripts automatically push commits and tags to GitHub, and create GitHub releases using the GitHub CLI (gh).
• Ensure you're authenticated with GitHub CLI (gh auth login) before running these scripts.
• Release notes are automatically generated from the commits between releases.

Contributing

Contributions are welcome! We appreciate any help, whether it's reporting bugs, suggesting features, or submitting Pull Requests.

Getting Started

• Fork and clone the repository

  git clone https://github.com/your-username/hungarian-validators.git
  cd hungarian-validators
  

• Install dependencies

  This project uses pnpm for package management.

  pnpm install
  

• Build the project

  pnpm run build
  

• Run tests

  pnpm test
  

• Run tests in watch mode (for development)

  pnpm run test:watch
  

Reporting Issues

Found a bug or have a feature request? Please open an issue on GitHub. Include as much detail as possible to help us understand and reproduce the problem.

Submitting Pull Requests

• Create a branch for your changes
• Make your changes and ensure tests pass
• Add tests for any new functionality
• Update documentation if needed
• Submit a Pull Request with a clear description of your changes

We'll review your PR as soon as possible. Thank you for contributing!