Features

Installation

npm install nino-validator

Quick Start

CommonJS (Node.js)

const{ validateNINO}=require('nino-validator');// Simple validationconsole.log(validateNINO('AB123456C'));// trueconsole.log(validateNINO('invalid'));// false

ES Modules (ESM)

import{validateNINO}from'nino-validator';// Simple validationconsole.log(validateNINO('AB123456C'));// trueconsole.log(validateNINO('invalid'));// false

TypeScript

import{validateNINO,ValidationOptions}from'nino-validator';constoptions:ValidationOptions={requireSuffix:true};constisValid:boolean=validateNINO('AB123456C',options);

Complete Usage Guide

Basic Validation

const{ validateNINO, formatNINO, parseNINO, generateRandomNINO}=require('nino-validator');

import{validateNINO,formatNINO,parseNINO,generateRandomNINO}from'nino-validator';

// Validate different NINO formatsvalidateNINO('AB123456C');// true - standard formatvalidateNINO('AB123456');// true - suffix optional by defaultvalidateNINO('ab123456c');// true - case insensitivevalidateNINO('AB 12 34 56 C');// true - spaces allowed by defaultvalidateNINO('  AB123456C  ');// true - whitespace trimmedvalidateNINO('invalid-nino');// false - invalid format

Advanced Validation Options

// Require suffix lettervalidateNINO('AB123456',{requireSuffix:true});// false - no suffixvalidateNINO('AB123456C',{requireSuffix:true});// true - has suffix// Strict formatting (no spaces allowed)validateNINO('AB 12 34 56 C',{allowSpaces:false});// false - contains spacesvalidateNINO('AB123456C',{allowSpaces:false});// true - no spaces// Combine optionsvalidateNINO('AB123456C',{requireSuffix:true,allowSpaces:false});// true

Formatting NINOs

// Standard formatting with spacesformatNINO('AB123456C');// 'AB 12 34 56 C'formatNINO('ab123456c');// 'AB 12 34 56 C' (normalized)formatNINO('AB123456');// 'AB 12 34 56' (no suffix)formatNINO('invalid');// null (invalid NINO)// Clean up user inputconstuserInput='  ab 12 34 56 c  ';constformatted=formatNINO(userInput);// 'AB 12 34 56 C'

Parsing NINO Components

// Extract all componentsconstresult=parseNINO('AB123456C');console.log(result);// Output:// {//   prefix: 'AB',//   numbers: '123456',//   suffix: 'C',//   formatted: 'AB 12 34 56 C',//   original: 'AB123456C'// }// Handle NINOs without suffixconstnoSuffix=parseNINO('AB123456');console.log(noSuffix.suffix);// null// Invalid NINOs return nullparseNINO('invalid');// null

Generate Test Data

// Generate random valid NINOs for testingconsttestNINO=generateRandomNINO();console.log(testNINO);// e.g., 'JG123789A'console.log(validateNINO(testNINO));// always true// Generate multiple test casesconsttestCases=Array.from({length:10},()=>generateRandomNINO());console.log(testCases);// ['AB123456C', 'JK789012G', 'MN345678P', ...]

API Reference

validateNINO(nino, options?)

validateNINO('AB123456C');// truevalidateNINO('AB123456',{requireSuffix:true});// false

formatNINO(nino)

formatNINO('AB123456C');// 'AB 12 34 56 C'formatNINO('invalid');// null

parseNINO(nino)

{  prefix:string;// Two-letter prefix (e.g., 'AB')  numbers:string;// Six-digit number (e.g., '123456')  suffix:string|null;// Single suffix letter or null  formatted:string;// Standardized format  original:string;// Original input}

generateRandomNINO()

consttestNINO=generateRandomNINO();// 'JK789012M'

validateNINOWithDetails(nino, options?)

{  isValid:boolean;  error:string|null;// Localized error message  errorCode:string|null;// Machine-readable error code  suggestion:string|null;// Localized suggestion}

constresult=validateNINOWithDetails('AB123');console.log(result);// {//   isValid: false,//   error: 'NINO too short (5 characters). Minimum 8 characters required',//   errorCode: 'TOO_SHORT',//   suggestion: 'Ensure the NINO has 2 letters, 6 digits, and optionally 1 letter'// }

Internationalization (i18n)

Language Management

const{   setLanguage,   getCurrentLanguage,   getSupportedLanguages,  isLanguageSupported}=require('nino-validator');// Check supported languagesconsole.log(getSupportedLanguages());// { en: 'English', el: 'Ελληνικά (Greek)' }// Switch to GreeksetLanguage('el');console.log(getCurrentLanguage());// 'el'// Validate with Greek error messagesconstresult=validateNINOWithDetails('invalid');console.log(result.error);// 'Μη έγκυρη μορφή NINO. Αναμενόμενη μορφή: XX123456X (το επίθημα είναι προαιρετικό)'// Switch back to EnglishsetLanguage('en');

Auto-Detection and Initialization

const{ detectLanguage, initializeI18n}=require('nino-validator');// Auto-detect language from environmentconstdetected=detectLanguage();console.log(detected);// 'el' if Greek locale detected// Initialize with auto-detectionconstlanguage=initializeI18n({autoDetect:true});console.log(`Language set to:${language}`);// Initialize with fallbackinitializeI18n({autoDetect:true,fallbackLanguage:'el'});

Language Support Features

Adding New Languages

NINO Validation Rules

✅ Valid Format

❌ Invalid Patterns

Examples

// ✅ Valid NINOs'AB123456C'// Standard format'AB123456'// Without suffix'JG103759A'// Real-world example'AB 12 34 56 C'// With spaces// ❌ Invalid NINOs'BG123456C'// Invalid prefix 'BG''AB111111C'// All digits the same'AB123456D'// Invalid suffix 'D''DA123456C'// Invalid first letter 'D''AB12345'// Too few digits'A1234567'// Wrong format

Error Handling

// Type safetyvalidateNINO(null);// falsevalidateNINO(undefined);// falsevalidateNINO(123456789);// falsevalidateNINO('');// false// Invalid formats return nullformatNINO('invalid');// nullparseNINO('invalid');// null// Options validationvalidateNINO('AB123456C',{invalidOption:true});// Works (ignores invalid options)

Performance

Performance Benchmarks

# Full benchmark suite with detailed analysisnpm run benchmark# Quick CI-friendly performance checknpm run benchmark:ci# Memory-focused benchmarks with GC controlnpm run benchmark:memory

⚡ NINO Validator CI Benchmarks===============================✅ validateNINO (valid)           | 2,350,000 ops/sec |    0.4μs/op✅ validateNINO (invalid)         | 5,150,000 ops/sec |    0.2μs/op  ✅ formatNINO                     |   915,000 ops/sec |    1.1μs/op✅ parseNINO                      |   800,000 ops/sec |    1.2μs/op✅ generateRandomNINO             |   575,000 ops/sec |    1.7μs/op✅ Bulk validation                | 3,000,000 ops/sec |    0.3μs/op🎯 Performance check: ✅ PASS

Typical Performance Results

Performance Ratings Scale

Browser Usage

<!DOCTYPE html><html><head><scriptsrc="https://unpkg.com/nino-validator@latest/index.js"></script></head><body><script>// Use the global ninoValidator objectconsole.log(ninoValidator.validateNINO('AB123456C'));// true</script></body></html>

TypeScript Support

import{validateNINO,formatNINO,parseNINO,generateRandomNINO}from'nino-validator';constisValid:boolean=validateNINO('AB123456C');constformatted:string|null=formatNINO('AB123456C');

Testing

# Run testsnpmtest# Run tests with coveragenpm run test:coverage# Run lintingnpm run lint

Real-World Examples

Form Validation

functionvalidateNINOInput(input){constnino=input.trim();if(!nino){return{valid:false,error:'NINO is required'};}if(!validateNINO(nino)){return{valid:false,error:'Invalid NINO format'};}return{valid:true,formatted:formatNINO(nino)};}// Usageconstresult=validateNINOInput('  ab 12 34 56 c  ');console.log(result);// { valid: true, formatted: 'AB 12 34 56 C' }

Database Storage

functionnormalizeNINO(input){constparsed=parseNINO(input);if(!parsed)returnnull;return{prefix:parsed.prefix,numbers:parsed.numbers,suffix:parsed.suffix,display:parsed.formatted};}

Test Data Generation

functioncreateTestUser(){return{id:Math.random().toString(36),nino:generateRandomNINO(),name:'Test User'};}

Changelog

Contributing

Development Setup

git clone https://github.com/icodenet/nino-validator.gitcd nino-validatornpm installnpmtest

License

Support