npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

zod-india

v0.5.1

Published

Zod schemas for Indian formats: GSTIN, PAN, CIN, IFSC, UPI, Aadhaar, PIN, with checksums and ₹ lakh/crore formatting.

Readme

zod-india

npm CI coverage 100% bundle size downloads

Zod schemas and zero-dependency validators for Indian identifiers and formats: GSTIN, CIN, PAN, TAN, IFSC, UPI ID, mobile number, PIN code, Aadhaar, Udyam registration and vehicle registration.

  • Real checksums where they exist: GSTIN mod-36 and Aadhaar Verhoeff, not just regexes.
  • Normalises messy input (" 27aapfu0939f1zv " → 27AAPFU0939F1ZV, 098765 43210 → +919876543210).
  • Works with Zod v3 and v4 (peer dependency). No other runtime dependencies.
  • Pure functions are importable without Zod from zod-india/validators.
  • Indian display helpers: ₹12,34,567.50, ₹1.5 Cr, amounts in words (one crore twenty-three lakh…), PAN/mobile/Aadhaar masking.
  • Offline lookups: state + RTO from a vehicle number, postal zone from a PIN, bank code from an IFSC.
  • Checksum-valid fake data for tests (zod-india/testing), seedable.
  • ESM + CJS, fully typed, tree-shakeable (sideEffects: false), Node 18+.

Limits. Every check is offline: format rules plus the published checksum where one exists. A value that passes is well-formed. It is not proof that the number was issued, is active, or belongs to the person submitting it. For that you need the relevant government or bank API.

Install

npm install zod-india zod

Usage

import { z } from 'zod';
import { zGSTIN, zPAN, zMobile, zAadhaar, zUdyam, maskAadhaar } from 'zod-india';

const Merchant = z.object({
  gstin: zGSTIN(),
  pan: zPAN(),
  phone: zMobile(),
  aadhaar: zAadhaar().transform((v) => maskAadhaar(v)), // store only the masked form
  udyam: zUdyam(),
});

Merchant.parse({
  gstin: '27aapfu0939f1zv',
  pan: 'aapfu0939f',
  phone: '+91 98765 43210',
  aadhaar: '2341 2341 2346',
  udyam: 'udyam mh 26 0012345',
});
// { gstin: '27AAPFU0939F1ZV', pan: 'AAPFU0939F', phone: '+919876543210', aadhaar: 'XXXX XXXX 2346', udyam: 'UDYAM-MH-26-0012345' }

Every schema factory takes the same options:

zGSTIN({ message: 'Enter a valid GSTIN' }); // custom error message
zGSTIN({ normalize: false }); // no cleaning; input must already be canonical and is returned as-is

Without Zod:

import { isValidGSTIN, normalizeGSTIN, parseGSTIN, panEntityType } from 'zod-india/validators';

isValidGSTIN(normalizeGSTIN(' 27aapfu0939f1zv ')); // true
parseGSTIN('27AAPFU0939F1ZV'); // { stateCode: '27', state: 'Maharashtra', pan: 'AAPFU0939F', entityNumber: '1', checkChar: 'V' }
panEntityType('AAPFU0939F'); // 'Firm / LLP'

isValidX functions expect normalised input. Call the matching normalizeX first, or use the schema.

Validators

| Format | Schema | Function | How it is checked | Normalised output | | ------------ | ------------------ | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- | | CIN | zCIN() | isValidCIN | 21 characters; L/U listing status, 5-digit industry code, known 2-letter state code, 4-digit year, 3-letter company type and 6-digit registration number | L17110MH1973PLC019786 | | GSTIN | zGSTIN() | isValidGSTIN | 15 chars; known GST state code (01–38, 97, 99); characters 3–12 a valid PAN; 13th 1–9/A–Z; 14th Z; 15th the GSTN mod-36 check character | 27AAPFU0939F1ZV | | PAN | zPAN() | isValidPAN | AAAPA9999A; 4th char a holder type (A B C F G H J L P T). PAN has no public checksum | ABCPD1234E | | TAN | zTAN() | isValidTAN | AAAA99999A | DELA12345B | | IFSC | zIFSC() | isValidIFSC | 4 letters, a 0, 6 alphanumerics (RBI format) | SBIN0000001 | | UPI ID (VPA) | zUPI() | isValidUPI | handle@psp syntax only. Does not check that the PSP handle exists | name@okaxis | | Mobile | zMobile() | isValidMobile | Optional +91 / 91 / 0091 / 0, then 10 digits starting 6–9. Spaces, dashes, brackets allowed | +919876543210 (E.164) | | PIN code | zPincode() | isValidPincode | 6 digits, first 1–9 | 110001 | | Aadhaar | zAadhaar() | isValidAadhaar | 12 digits, not starting 0 or 1, valid Verhoeff check digit | 234123412346 | | Udyam (MSME) | zUdyam() | isValidUdyam | UDYAM-SS-DD-NNNNNNN: prefix, 2-letter state, 2-digit district and 7-digit serial | UDYAM-MH-26-0012345 | | Vehicle reg. | zVehicleNumber() | isValidVehicleNumber | SS NN X(XX) NNNN with a known state/UT code, or Bharat series YY BH NNNN XX | DL01AB1234 |

CIN validation

The CIN state-code list follows the Ministry of Corporate Affairs' published state abbreviations. Validation checks the format only; it does not verify a company against the MCA register.

Helpers

  • maskAadhaar(value, maskChar = 'X') → XXXX XXXX 1234. Keeps only the last 4 digits.
  • verhoeffValidate(digits) / verhoeffGenerate(digits): general-purpose Verhoeff.
  • gstinCheckChar(first14): compute the GSTIN check character.
  • parseGSTIN, panEntityType, and the tables GST_STATE_CODES, PAN_ENTITY_TYPES, VEHICLE_STATE_CODES.

Formatting (lakh / crore)

import { formatINR, formatINRCompact, toIndianWords, rupeesInWords } from 'zod-india/validators';

formatINR(1234567.5); // '₹12,34,567.50'
formatINR(1500, { decimals: 0, symbol: 'Rs ' }); // 'Rs 1,500'
formatINRCompact(15000000); // '₹1.5 Cr'   (also '₹12 L', '₹45.3K')
toIndianWords(12345678); // 'one crore twenty-three lakh forty-five thousand six hundred seventy-eight'
rupeesInWords(1250.5); // 'Rupees one thousand two hundred fifty and fifty paise only'

No Intl / ICU dependency, so the output is identical on Node, browsers, Bun, Deno and edge runtimes.

Masking and display: maskPAN('ABCPE1234F') → AB******4F, maskMobile('9876543210') → +91 ******3210, formatMobile('09876543210') → +91 98765 43210, formatAadhaar(…) → 2345 6789 0123.

Lookups (offline)

import { parseVehicleNumber, pincodeZone, parseIFSC, parseGSTIN } from 'zod-india/validators';

parseVehicleNumber('DL 1C AB 1234'); // { series: 'state', stateCode: 'DL', state: 'Delhi', rto: '01' }
parseVehicleNumber('22 BH 1234 AB'); // { series: 'BH', year: '22' }
pincodeZone('560001'); // { zone: 'Southern', regions: ['Andhra Pradesh', 'Telangana', 'Karnataka'] }
parseIFSC('HDFC0001234'); // { bank: 'HDFC', branch: '001234' }
parseGSTIN('27AAPFU0939F1ZV').state; // 'Maharashtra'

For full branch/bank names from an IFSC, use Razorpay's ifsc dataset; this package stays tiny and offline.

Test data

import { fakeGSTIN, fakePAN, fakeAadhaar, createFaker, seededRandom } from 'zod-india/testing';

fakeGSTIN(); // random, checksum-valid, e.g. '07ABCCD1234E1Z5'
fakeGSTIN('27'); // Maharashtra
const f = createFaker(seededRandom(42)); // reproducible fixtures for snapshots
f.aadhaar(); // passes Verhoeff

Generated values are random and synthetic. Use them only in tests, seeds and demos.

With react-hook-form / Hono

// react-hook-form
import { zodResolver } from '@hookform/resolvers/zod';
const schema = z.object({ gstin: zGSTIN({ message: 'Check your GSTIN' }), phone: zMobile() });
useForm({ resolver: zodResolver(schema) });

// Hono
import { zValidator } from '@hono/zod-validator';
app.post('/kyc', zValidator('json', z.object({ pan: zPAN(), ifsc: zIFSC() })), (c) =>
  c.json(c.req.valid('json')),
);

Notes and known limits

  • GSTIN: only regular PAN-based registrations are accepted. Special registrations (UN bodies with a UIN, non-resident OIDAR, TAN-based TDS/TCS) use a different structure in characters 3–12 and are rejected; { checksum: false } only skips the 15th-character check, it does not accept those formats.
  • Aadhaar: the Verhoeff check catches all single-digit typos and adjacent swaps, but random 12-digit numbers still pass about 1 time in 10. Never log or store full Aadhaar numbers; mask them (see UIDAI guidance).
  • Vehicle numbers: state-series formats vary by RTO; the rule here is deliberately permissive within a known state prefix.
  • Mobile: Indian mobile numbers only, not landlines.

Comparison

| Package | Zod schemas | GSTIN checksum | Aadhaar Verhoeff | Normalisation | Types | Zod v3 + v4 | | ------------------------------------------------------------------ | ----------- | --------------- | ---------------- | ------------- | ------ | ----------- | | zod-india | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | single-format packages (gstin-validator, aadhaar-validator, …) | ❌ | one format each | one format each | ❌ | varies | ❌ |

Contributing

See CONTRIBUTING.md. Please never put a real person's identifiers in issues or tests.

Sibling packages

Other tools by the same author:

License

MIT © Krrish Kumar