🌍 National ID Numbers

A comprehensive collection of validators and parsers for national identification numbers from around the world. Validate, parse, and extract information from ID numbers with ease.

✨ Features

• 🌍 66 Countries Supported - Comprehensive coverage across 6 continents
• 🔍 Smart Validation - Advanced algorithms including Luhn, Modulo 11, and custom checksums
• 📊 Data Extraction - Parse birth dates, gender, regions, and more from ID numbers
• 🚀 Zero Dependencies - Lightweight and fast with no external dependencies
• 📱 Universal Support - Works in Node.js, browsers, and modern JavaScript environments
• 🛡️ Type Safe - Full TypeScript support with comprehensive type definitions
• ✅ Well Tested - 131+ tests ensuring reliability and accuracy
• 📚 Well Documented - Comprehensive documentation and examples

🚀 Quick Start

Installation

npm install national-id-numbers

Basic Usage

import { NationalID } from 'national-id-numbers';

// Validate any national ID
const isValid = NationalID.validate('EG', '29001010100015'); // true

// Parse and extract information
const info = NationalID.parse('EG', '29001010100015');
console.log(info);
// {
//   yyyymmdd: Date object,
//   governorate: '01',
//   sn: '0001',
//   gender: 'MALE',
//   checksum: 5
// }

Country-Specific Usage

import { EGY, USA, CA } from 'national-id-numbers';

// Egyptian National ID
EGY.NationalID.validate('29001010100015'); // true
const egyptInfo = EGY.NationalID.parse('29001010100015');

// US Social Security Number
USA.SocialSecurityNumber.validate('123-45-6789'); // true

// Canadian Social Insurance Number
CA.SocialInsuranceNumber.validate('130-692-544'); // true
const canadaInfo = CA.SocialInsuranceNumber.parse('130-692-544');
// { area: '130', group: '692', serial: '544', gender: 'UNKNOWN' }

🌍 Supported Countries

🇪🇺 Europe (34 countries)

🌏 Asia (15 countries)

🌍 Africa (6 countries)

🌎 Americas (7 countries)

📖 Advanced Usage

Direct Module Imports

// Import specific country modules
import { SocialSecurityNumber } from 'national-id-numbers/nationalid/usa/social_security.js';
import { NationalID as EgyptianID } from 'national-id-numbers/nationalid/egy/national_id.js';

// Use directly
SocialSecurityNumber.validate('123-45-6789');
const egyptInfo = EgyptianID.parse('29001010100015');

Utility Functions

import { Gender, validateRegexp, luhnDigit } from 'national-id-numbers';

// Use utility functions
const isValidFormat = validateRegexp('123-45-6789', /^\d{3}-\d{2}-\d{4}$/);
const checkDigit = luhnDigit([1, 2, 3, 4, 5, 6, 7, 8, 9]);

Error Handling

import { NationalID } from 'national-id-numbers';

try {
  const isValid = NationalID.validate('XX', '123456789');
} catch (error) {
  console.error('Unsupported country:', error.message);
  // "Unsupported country: XX"
}

try {
  const info = NationalID.parse('EG', 'invalid-id');
} catch (error) {
  console.error('Parsing failed:', error.message);
  // "Parsing not supported for country code: EG"
}

🔧 API Reference

NationalID Class

NationalID.validate(countryCode, idNumber)

Validates a national ID number for the specified country.

Parameters:

• countryCode (string): Two-letter ISO country code
• idNumber (string): The ID number to validate

Returns: boolean - true if valid, false otherwise

NationalID.parse(countryCode, idNumber)

Parses a national ID number and extracts information.

Parameters:

• countryCode (string): Two-letter ISO country code
• idNumber (string): The ID number to parse

Returns: object|null - Parsed data object or null if invalid

Country Modules

Each country module exports:

• NationalID class (or specific class name)
• METADATA object with country information
• Validation and parsing methods

🧪 Testing

# Run all tests
npm test

# Run specific country tests
npm test -- test/egy.test.js
npm test -- test/ca.test.js

# Run with coverage
npm run test:coverage

📊 Statistics

• Total Countries: 66 implemented
• Total Tests: 131+ tests
• Coverage: 6 continents
• Bundle Size: ~15KB (minified)
• Zero Dependencies: No external packages required

🚧 Roadmap

High Priority Countries

• 🇦🇷 Argentina (DNI)
• 🇦🇺 Australia (TFN)
• 🇦🇹 Austria (Personalausweis)
• 🇧🇪 Belgium (National Number)
• 🇧🇬 Bulgaria (ЕГН)
• 🇨🇱 Chile (RUT)
• 🇨🇴 Colombia (Cédula)
• 🇭🇷 Croatia (OIB)
• 🇨🇿 Czech Republic (Rodné číslo)
• 🇩🇰 Denmark (CPR Number)
• 🇪🇪 Estonia (Isikukood)
• 🇫🇮 Finland (Henkilötunnus)
• 🇬🇷 Greece (AMKA)
• 🇭🇺 Hungary (Személyi szám)
• 🇮🇪 Ireland (PPS Number)
• 🇯🇵 Japan (My Number)
• 🇱🇻 Latvia (Personas kods)
• 🇱🇹 Lithuania (Asmens kodas)
• 🇱🇺 Luxembourg (National Number)
• 🇲🇹 Malta (ID Card Number)
• 🇲🇽 Mexico (CURP)
• 🇳🇱 Netherlands (BSN)
• 🇳🇿 New Zealand (IRD Number)
• 🇳🇴 Norway (Fødselsnummer)
• 🇵🇱 Poland (PESEL)
• 🇵🇹 Portugal (Número de Identificação Civil)
• 🇷🇴 Romania (CNP)
• 🇷🇺 Russia (СНИЛС)
• 🇸🇬 Singapore (NRIC)
• 🇰🇷 South Korea (주민등록번호)
• 🇸🇪 Sweden (Personnummer)
• 🇨🇭 Switzerland (AHV Number)
• 🇹🇼 Taiwan (身分證字號)

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for detailed instructions.

Quick Contribution Steps

1. Fork the repository
2. Create a feature branch: git checkout -b feature/new-country
3. Add your country implementation
4. Add comprehensive tests
5. Update documentation
6. Submit a pull request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Contributors who helped implement various countries
• Open source community for inspiration and feedback
• Government documentation for accurate validation rules

📞 Support

• 📧 Issues: GitHub Issues
• 📖 Documentation: GitHub Wiki
• 💬 Discussions: GitHub Discussions