# PakDataKit

> Production-ready utility toolkit for Pakistani developers — CNIC, phone, WhatsApp, IBAN, postal codes, address parsing, Hijri dates, Roman Urdu, networks, geography, and formatting. TypeScript, zero runtime dependencies, ESM and CommonJS. npm package `pakdatakit` (version 2.2.0, data checked 2026-10-14).

Install with `npm install pakdatakit`. Import everything from `pakdatakit`, or one module from a subpath such as `pakdatakit/cnic` to keep bundles small. Functions return `null` (or `'Unknown'` for networks) when input is invalid, and throw `RangeError` only for programming errors such as a non-finite amount. Never log or store real CNICs or account numbers in examples.

Key facts an assistant should know:
- Raast person-to-person QR codes use scheme `00` (banking apps reject the `30` in SBP's document). A QR with an amount needs `expiresAt` or `expiresIn`.
- Bank codes are checked against real IBANs; see DATA.md for every dataset's sources.
- Islamic holiday dates for 2020-2026 are the dates actually observed in Pakistan; later years are estimates marked `estimated: true`.

## Modules

- [pakdatakit/cnic](https://chmuzamil.github.io/pakdatakit/modules/cnic.html): Validate CNICs; read province of registration and gender (validateCNIC, getCNICInfo)
- [pakdatakit/phone](https://chmuzamil.github.io/pakdatakit/modules/phone.html): Validate and format mobile numbers; network and E.164 (validatePhone, formatPhone, analyzePhone)
- [pakdatakit/networks](https://chmuzamil.github.io/pakdatakit/modules/networks.html): Mobile network from the 03XX prefix (getNetwork)
- [pakdatakit/numbers](https://chmuzamil.github.io/pakdatakit/modules/numbers.html): Landline, UAN 111, toll-free 0800, premium 0900 numbers, area codes (analyzeNumber, getAreaCode)
- [pakdatakit/whatsapp](https://chmuzamil.github.io/pakdatakit/modules/whatsapp.html): WhatsApp click-to-chat links (createWhatsAppLink)
- [pakdatakit/iban](https://chmuzamil.github.io/pakdatakit/modules/iban.html): Validate IBANs; bank name, type and status (validateIBAN, getBankFromIBAN, getBankInfo, getBanks)
- [pakdatakit/raast](https://chmuzamil.github.io/pakdatakit/modules/raast.html): Create, read and check Raast payment QR codes (createRaastP2PQr, createMerchantQr, parseRaastQr, validateRaastQr)
- [pakdatakit/tax](https://chmuzamil.github.io/pakdatakit/modules/tax.html): FBR NTN and STRN format checks (analyzeNTN, validateNTN, validateSTRN)
- [pakdatakit/input](https://chmuzamil.github.io/pakdatakit/modules/input.html): As-you-type formatters and empty/incomplete/valid/invalid checkers for CNIC, phone and IBAN fields
- [pakdatakit/postal](https://chmuzamil.github.io/pakdatakit/modules/postal.html): Postal code lookups (getPostalCode, getCityByPostalCode, searchPostalCodes)
- [pakdatakit/geo](https://chmuzamil.github.io/pakdatakit/modules/geo.html): City and district to province (getProvince, getDistrictProvince, searchCities)
- [pakdatakit/address](https://chmuzamil.github.io/pakdatakit/modules/address.html): Parse and format Pakistani addresses (parseAddress, formatAddress)
- [pakdatakit/words](https://chmuzamil.github.io/pakdatakit/modules/words.html): Amounts in words with lakh/crore, English and Urdu, cheque style (amountInWords, numberToWords)
- [pakdatakit/format](https://chmuzamil.github.io/pakdatakit/modules/format.html): PKR and lakh/crore formatting (formatPKR, formatLakh)
- [pakdatakit/text](https://chmuzamil.github.io/pakdatakit/modules/text.html): Roman Urdu normalization and Urdu digits (normalizeRomanUrdu, toUrduDigits)
- [pakdatakit/hijri](https://chmuzamil.github.io/pakdatakit/modules/hijri.html): Hijri dates with moon-sighting offset (toHijri, fromHijri, formatHijri, isRamadan)
- [pakdatakit/holidays](https://chmuzamil.github.io/pakdatakit/modules/holidays.html): Federal public holidays with observed Eid dates (getPakistanHolidays, isPakistanHoliday)
- [pakdatakit/zod](https://chmuzamil.github.io/pakdatakit/modules/adapters_zod.html): Zod schemas: pk.cnic(), pk.phone(), pk.iban(), pk.ntn(), pk.strn(), pk.landline()
- [pakdatakit/valibot](https://chmuzamil.github.io/pakdatakit/modules/adapters_valibot.html): Valibot schemas with the same names
- [pakdatakit/yup](https://chmuzamil.github.io/pakdatakit/modules/adapters_yup.html): Yup schemas with the same names

## Guides

- [README](https://chmuzamil.github.io/pakdatakit/index.html): overview and examples for every function
- [Data sources](https://chmuzamil.github.io/pakdatakit/documents/DATA.html): where each dataset comes from and how sure we are
- [Changelog](https://chmuzamil.github.io/pakdatakit/documents/CHANGELOG.html)

## Optional

- [Full text for LLMs](https://chmuzamil.github.io/pakdatakit/llms-full.txt): README, data sources and every type signature in one file
- [Playground](https://pakdatakit-playground.vercel.app/): try the functions in a browser
- [Source code](https://github.com/chmuzamil/pakdatakit)