matools-validate 🇮🇳

A comprehensive TypeScript validation library for Indian identifiers including Phone numbers, IFSC codes, PAN, GSTIN, Aadhaar, and Pincodes.

Features

• ✅ Phone Number Validation: Validates Indian mobile numbers with operator detection
• ✅ IFSC Code Validation: Validates Indian Financial System Codes with bank identification
• ✅ PAN Validation: Validates Permanent Account Numbers
• ✅ GSTIN Validation: Validates Goods and Services Tax Identification Numbers with state detection
• ✅ Aadhaar Validation: Validates Aadhaar numbers (format validation)
• ✅ Pincode Lookup: Validates and looks up postal codes with location data
• ✅ TypeScript Support: Full TypeScript definitions included
• ✅ Zero Dependencies: Lightweight with minimal external dependencies

Installation

npm install matools-validate

Usage

ES6/TypeScript

import { 
  validatePhone, 
  validateIFSC, 
  validatePAN, 
  validateGSTIN, 
  validateAadhaar, 
  lookupPincode 
} from 'matools-validate';

// Phone validation
const phoneResult = validatePhone('+919876543210');
console.log(phoneResult);
// { valid: true, operator: 'Airtel', type: 'mobile', formatted: '+91 98765 43210' }

// IFSC validation
const ifscResult = validateIFSC('SBIN0001234');
console.log(ifscResult);
// { valid: true, bankCode: 'SBIN', branchCode: '001234', bankName: 'State Bank of India', formatted: 'SBIN0001234' }

// PAN validation
const panResult = validatePAN('ABCDP1234A');
console.log(panResult);
// { valid: true }

// GSTIN validation
const gstinResult = validateGSTIN('27ABCDP1234A1Z1');
console.log(gstinResult);
// { valid: true, stateCode: '27', stateName: 'Maharashtra', panNumber: 'ABCDP1234A', ... }

// Aadhaar validation
const aadhaarResult = validateAadhaar('123456789012');
console.log(aadhaarResult);
// { valid: true }

// Pincode lookup
const pincodeResult = lookupPincode('560001');
console.log(pincodeResult);
// { valid: true, district: 'Bangalore Urban', state: 'Karnataka' }

CommonJS

const { validatePhone, validateIFSC, validatePAN } = require('matools-validate');

const result = validatePhone('9876543210');
console.log(result);

API Reference

Phone Validation

validatePhone(number: string): PhoneValidationResult

Parameters:

• number (string): Phone number to validate (with or without country code)

Returns:

{
  valid: boolean;
  operator?: string;        // 'Airtel', 'Jio', 'Vi', 'Unknown'
  type?: string;           // Phone number type
  formatted?: string;      // Formatted phone number
}

IFSC Validation

validateIFSC(ifsc: string): IFSCValidationResult

Parameters:

• ifsc (string): IFSC code to validate

Returns:

{
  valid: boolean;
  bankCode?: string;       // 4-letter bank code
  branchCode?: string;     // 6-character branch code
  bankName?: string;       // Full bank name
  formatted?: string;      // Formatted IFSC code
}

PAN Validation

validatePAN(pan: string): ValidationResult

Parameters:

• pan (string): PAN number to validate

Returns:

{
  valid: boolean;
}

GSTIN Validation

validateGSTIN(gstin: string): GSTINValidationResult

Parameters:

• gstin (string): GSTIN to validate

Returns:

{
  valid: boolean;
  stateCode?: string;      // 2-digit state code
  stateName?: string;      // Full state name
  panNumber?: string;      // Embedded PAN number
  entityNumber?: string;   // Entity number
  checkDigit?: string;     // Check digit
  formatted?: string;      // Formatted GSTIN
}

Aadhaar Validation

validateAadhaar(aadhaar: string): ValidationResult

Parameters:

• aadhaar (string): Aadhaar number to validate

Returns:

{
  valid: boolean;
}

Pincode Lookup

lookupPincode(pincode: string): PincodeResult

Parameters:

• pincode (string): Pincode to lookup

Returns:

{
  valid: boolean;
  district?: string;       // District name
  state?: string;         // State name
}

Supported Banks (IFSC)

• State Bank of India (SBIN)
• HDFC Bank (HDFC)
• ICICI Bank (ICIC)
• Axis Bank (AXIS)
• Punjab National Bank (PUNB)
• Union Bank of India (UBIN)
• Canara Bank (CNRB)
• Bank of Baroda (BARB)

Development

# Install dependencies
npm install

# Build the project
npm run build

# Run tests
npm run test

# Development mode with watch
npm run dev

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

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

Disclaimer

This library provides format validation only. For production use with sensitive data like Aadhaar numbers, additional verification through official APIs is recommended.

Support

If you find this library useful, please ⭐ star the repository!

For issues and feature requests, please use the GitHub Issues page.