indian-utils

Validate and format Indian-specific data: PAN, Aadhaar (format check only), GSTIN, IFSC, and PIN code lookup — with zero dependencies.

Install

npm install indian-utils

Usage

const {
  isValidPAN, formatPAN, getPANInfo, maskPAN,
  isValidAadhaarFormat, isValidChecksum, formatAadhaar, maskAadhaar,
  isValidGSTIN, getGSTINInfo,
  isValidIFSC, getIFSCInfo,
  isValidPincode, lookupPincode,
} = require("indian-utils");

// PAN
isValidPAN("ABCDE1234F");        // true
getPANInfo("ABCPE1234F");        // { valid: true, holderCode: 'P', holderType: 'Individual' }
maskPAN("ABCDE1234F");           // "ABCXXXXX4F"

// Aadhaar (format check only — does NOT verify against UIDAI's database)
isValidAadhaarFormat("2345 6789 0123"); // true
isValidChecksum("234567890123");        // Verhoeff checksum check (extra confidence, still not proof of authenticity)
maskAadhaar("234567890123");            // "XXXX XXXX 0123"

// GSTIN
isValidGSTIN("24ABCDE1234F1Z5");
getGSTINInfo("24ABCDE1234F1Z5");
// { valid: true, stateCode: '24', stateName: 'Gujarat', pan: 'ABCDE1234F', entityNumber: '1' }

// IFSC
isValidIFSC("SBIN0001234");      // true
getIFSCInfo("HDFC0000123");      // { valid: true, bankCode: 'HDFC', branchCode: '000123' }

// PIN code (format check, sync)
isValidPincode("395007");        // true

// PIN code lookup (async, hits api.postalpincode.in)
const result = await lookupPincode("395007");
// {
//   valid: true,
//   pincode: '395007',
//   postOffices: [
//     { name: 'Amroli', district: 'Surat', state: 'Gujarat', branchType: 'Sub Post Office' },
//     ...
//   ]
// }

Why this package?

Most existing "India validation" packages on npm only cover one or two of these formats, are unmaintained, or pull in unnecessary dependencies. indian-utils covers five common needs in one lightweight package with:

• Zero runtime dependencies
• Clear, honest docs about what's checked (e.g. Aadhaar is a format check, not a database lookup)
• Extra helper functions beyond simple true/false — masking, formatting, and metadata extraction (state name from GSTIN, bank code from IFSC, etc.)

API Reference

PAN

| Function | Description | |---|---| | isValidPAN(pan) | Returns boolean | | formatPAN(pan) | Returns uppercase canonical form | | getPANInfo(pan) | Returns { valid, holderCode, holderType } | | maskPAN(pan) | Masks middle characters for display |

Aadhaar

| Function | Description | |---|---| | isValidAadhaarFormat(aadhaar) | Format check only (12 digits, doesn't start with 0/1) | | isValidChecksum(aadhaar) | Verhoeff checksum validation | | formatAadhaar(aadhaar) | Groups into 4-4-4 digits | | maskAadhaar(aadhaar) | Shows only last 4 digits |

GSTIN

| Function | Description | |---|---| | isValidGSTIN(gstin) | Returns boolean | | formatGSTIN(gstin) | Returns uppercase canonical form | | getGSTINInfo(gstin) | Returns { valid, stateCode, stateName, pan, entityNumber } |

IFSC

| Function | Description | |---|---| | isValidIFSC(ifsc) | Returns boolean | | formatIFSC(ifsc) | Returns uppercase canonical form | | getIFSCInfo(ifsc) | Returns { valid, bankCode, branchCode } |

PIN code

| Function | Description | |---|---| | isValidPincode(pincode) | Format check (6 digits, doesn't start with 0) | | lookupPincode(pincode) | Async — fetches post office/district/state via api.postalpincode.in |

Important notes

• Aadhaar and GSTIN checks are format/structure checks only. They confirm a string is shaped like a valid number — they do not confirm it's real, active, or belongs to anyone. Never treat a passed format check as identity verification.
• lookupPincode requires internet access and depends on the free postalpincode.in API being available.

Testing

npm test

License

MIT