Universal ID Validator

A comprehensive, extensible JavaScript library for generating and validating various types of identification numbers from around the world, following SOLID, DRY, and KISS principles.

🚀 Features

• 19 ID Types: Support for identification numbers from 15+ countries/regions
• Validation & Generation: Both validate existing IDs and generate valid ones
• Auto-detection: Automatically detect ID type from format
• TypeScript Ready: Full TypeScript support with type definitions
• Extensible: Easy to add new ID types following established patterns
• Well-tested: Comprehensive test suite with high coverage
• Clean Architecture: Follows SOLID, DRY, KISS principles
• Tree-shakeable: Import only what you need

📦 Installation

npm install universal-id-validator

🔧 Quick Start

import UniversalIdValidator from 'universal-id-validator';

const validator = new UniversalIdValidator();

// Validate with explicit type
const result = validator.validate('A1234560', 'HKID');
console.log(result.isValid); // true/false
console.log(result.message); // Validation message

// Auto-detect and validate
const autoResult = validator.validate('A1234560');
console.log(autoResult.isValid);

// Generate valid ID
const newHkid = validator.generate('HKID');
console.log(newHkid); // e.g., "B7654321"

// Detect ID type
const type = validator.detectType('A1234567');
console.log(type); // "HKID"

📋 Supported ID Types

| Type | Country/Region | Description | Format | Example | |------|----------------|-------------|--------|---------| | HKID | 🇭🇰 Hong Kong | Identity Card | 1-2 letters + 6 digits + check char | A1234560 | | TWID | 🇹🇼 Taiwan | Identity Card | Letter + 1/2 + 8 digits | A123456789 | | AADHAAR | 🇮🇳 India | Aadhaar Card | 12 digits | 123456789012 | | PAN | 🇮🇳 India | Permanent Account Number | 5 letters + 4 digits + 1 letter | ABCDE1234F | | NRIC | 🇸🇬 Singapore | National Registration IC | S/T + 7 digits + letter | S1234567A | | FIN | 🇸🇬 Singapore | Foreign Identification Number | F/G + 7 digits + letter | F1234567A | | SSN | 🇺🇸 United States | Social Security Number | XXX-XX-XXXX | 123-45-6789 | | SIN | 🇨🇦 Canada | Social Insurance Number | XXX XXX XXX | 123 456 789 | | NINO | 🇬🇧 United Kingdom | National Insurance Number | 2 letters + 6 digits + letter | AB123456C | | BSN | 🇳🇱 Netherlands | Burgerservicenummer | 9 digits | 123456789 | | CPF | 🇧🇷 Brazil | Cadastro de Pessoas Físicas | XXX.XXX.XXX-XX | 123.456.789-01 | | RUT | 🇨🇱 Chile | Rol Único Tributario | XX.XXX.XXX-X | 12.345.678-9 | | CUIL | 🇦🇷 Argentina | Código Único de Identificación | XX-XXXXXXXX-X | 20-12345678-9 | | RFC | 🇲🇽 Mexico | Registro Federal de Contribuyentes | 3-4 letters + 6 digits + 3 chars | ABC123456DEF | | PERSONNUMMER | 🇸🇪 Sweden | Personal Identity Number | YYMMDD-XXXX | 901201-1234 | | PERSONALNUMMER | 🇳🇴 Norway | Personal Identity Number | 11 digits | 12345678901 | | CPR | 🇩🇰 Denmark | Central Person Register | DDMMYY-XXXX | 120190-1234 | | PESEL | 🇵🇱 Poland | Powszechny Elektroniczny System | 11 digits | 90120112345 | | CNP | 🇷🇴 Romania | Cod Numeric Personal | 13 digits | 1901201123456 |

🏗️ Architecture

The library follows clean architecture principles:

Core Components

• UniversalIdValidator: Main facade class (KISS principle)
• BaseValidator: Template method pattern for consistent validation
• ValidatorFactory: Factory pattern for creating validators (Open/Closed)
• GeneratorFactory: Factory pattern for creating generators
• IdDetector: Strategy pattern for ID type detection
• ChecksumCalculator: Utility class for checksum algorithms (Single Responsibility)

Design Principles Applied

SOLID Principles

• Single Responsibility: Each class has one reason to change
• Open/Closed: Easy to extend with new ID types without modifying existing code
• Liskov Substitution: All validators are interchangeable
• Interface Segregation: Minimal, focused interfaces
• Dependency Inversion: Depend on abstractions, not concretions

DRY (Don't Repeat Yourself)

• Common validation logic in BaseValidator
• Shared checksum algorithms in ChecksumCalculator
• Reusable helper methods

KISS (Keep It Simple, Stupid)

• Simple, intuitive API
• Clear method names and purposes
• Minimal configuration required

🔍 Advanced Usage

Direct Validator Access

import { HkidValidator, TwidValidator } from 'universal-id-validator/validators';

const hkidValidator = new HkidValidator();
const result = hkidValidator.validate('A1234560');

Custom Validators

import { ValidatorFactory, BaseValidator } from 'universal-id-validator';

class CustomValidator extends BaseValidator {
  validateFormat(id) {
    // Your format validation logic
  }
  
  validateChecksum(id) {
    // Your checksum validation logic
  }
}

const factory = new ValidatorFactory();
factory.register('CUSTOM', CustomValidator);

Generation Options

// HKID with double prefix
const hkid = validator.generate('HKID', { doublePrefix: true });

// TWID with specific gender
const twid = validator.generate('TWID', { gender: 1 }); // 1=male, 2=female

// PAN for specific entity type
const pan = validator.generate('PAN', { entityType: 'C' }); // Company

// SSN with formatting
const ssn = validator.generate('SSN', { formatted: true }); // XXX-XX-XXXX

// NRIC with birth year
const nric = validator.generate('NRIC', { birthYear: 1990 });

Entity Type Detection (PAN)

import { PanValidator } from 'universal-id-validator/validators';

const panValidator = new PanValidator();
const entityType = panValidator.getEntityType('ABCPE1234F');
console.log(entityType); // "Individual"

🧪 Testing

npm test                # Run all tests
npm run test:watch      # Watch mode
npm run test:coverage   # Coverage report

📊 Validation Results

All validation methods return a ValidationResult object:

{
  isValid: boolean,     // Whether the ID is valid
  message: string,      // Human-readable message
  details: object       // Additional validation details
}

🌍 Regional Coverage

• Asia-Pacific: Hong Kong, Taiwan, India, Singapore
• North America: United States, Canada
• Europe: United Kingdom, Netherlands, Sweden, Norway, Denmark, Poland, Romania
• South America: Brazil, Chile, Argentina
• Central America: Mexico

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for detailed guidelines on:

• Setting up the development environment
• Adding new ID types
• Running tests and builds
• Publishing to NPM

Adding New ID Types

1. Create validator class extending BaseValidator
2. Create generator class extending BaseGenerator
3. Add checksum algorithm to ChecksumCalculator
4. Register in factories
5. Add detection pattern to IdDetector
6. Write comprehensive tests

📄 License

MIT License - see LICENSE file for details.

🔗 Links

• GitHub Repository
• NPM Package
• Contributing Guide
• Changelog

📈 Stats

• 19 ID Types supported
• 15+ Countries/Regions covered
• 100% Test Coverage maintained
• Tree-shakeable for optimal bundle size
• TypeScript definitions included

Built with ❤️ following clean code principles and international standards.