pakdatakit 2.5.0 โ†’ 2.5.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +125 -205
  2. package/dist/cli.js +1 -1
  3. package/package.json +7 -7
package/README.md CHANGED
@@ -5,205 +5,186 @@
5
5
  <h1 align="center">๐Ÿ‡ต๐Ÿ‡ฐ PakDataKit</h1>
6
6
 
7
7
  <p align="center">
8
- <strong>The Standard Utility Toolkit for Pakistani Developers</strong>
8
+ <strong>Pakistani data utilities for TypeScript, Python, Dart/Flutter, .NET and PHP/Laravel, with React, Vue and Angular helpers</strong>
9
9
  </p>
10
10
 
11
11
  <p align="center">
12
- Production-ready TypeScript utilities for CNIC validation, phone parsing, WhatsApp links, IBAN validation, postal lookup, network detection, geographic lookup, and PKR formatting.
12
+ <a href="https://github.com/chmuzamil/pakdatakit/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/chmuzamil/pakdatakit/ci.yml?branch=main&label=CI" alt="CI status"></a>
13
+ <a href="https://www.npmjs.com/package/pakdatakit"><img src="https://img.shields.io/npm/v/pakdatakit?label=npm" alt="npm"></a>
14
+ <a href="https://pypi.org/project/pakdatakit/"><img src="https://img.shields.io/pypi/v/pakdatakit?label=PyPI" alt="PyPI"></a>
15
+ <a href="https://pub.dev/packages/pakdatakit"><img src="https://img.shields.io/pub/v/pakdatakit?label=pub.dev" alt="pub.dev pakdatakit"></a>
16
+ <a href="https://pub.dev/packages/pakdatakit_flutter"><img src="https://img.shields.io/pub/v/pakdatakit_flutter?label=pakdatakit_flutter" alt="pub.dev pakdatakit_flutter"></a>
17
+ <a href="https://www.nuget.org/packages/PakDataKit"><img src="https://img.shields.io/nuget/v/PakDataKit?label=NuGet" alt="NuGet"></a>
18
+ <a href="https://packagist.org/packages/chmuzamil/pakdatakit"><img src="https://img.shields.io/packagist/v/chmuzamil/pakdatakit?label=Packagist" alt="Packagist"></a>
19
+ <a href="./LICENSE"><img src="https://img.shields.io/github/license/chmuzamil/pakdatakit" alt="license"></a>
13
20
  </p>
14
21
 
15
22
  <p align="center">
16
- <a href="https://www.npmjs.com/package/pakdatakit">
17
- <img src="https://img.shields.io/npm/v/pakdatakit" alt="npm version">
18
- </a>
19
- <a href="https://www.npmjs.com/package/pakdatakit">
20
- <img src="https://img.shields.io/npm/dm/pakdatakit" alt="npm downloads">
21
- </a>
22
- <img src="https://img.shields.io/npm/l/pakdatakit" alt="license">
23
- <img src="https://img.shields.io/badge/TypeScript-ready-blue" alt="TypeScript">
24
- <a href="https://pakdatakit-playground.vercel.app/">
25
- <img src="https://img.shields.io/badge/playground-try%20it%20live-brightgreen" alt="Playground">
26
- </a>
27
- <a href="https://chmuzamil.github.io/pakdatakit/">
28
- <img src="https://img.shields.io/badge/docs-API%20reference-blue" alt="API docs">
29
- </a>
23
+ <a href="https://www.npmjs.com/package/pakdatakit-react"><img src="https://img.shields.io/npm/v/pakdatakit-react?label=pakdatakit-react" alt="pakdatakit-react"></a>
24
+ <a href="https://www.npmjs.com/package/pakdatakit-vue"><img src="https://img.shields.io/npm/v/pakdatakit-vue?label=pakdatakit-vue" alt="pakdatakit-vue"></a>
25
+ <a href="https://www.npmjs.com/package/pakdatakit-angular"><img src="https://img.shields.io/npm/v/pakdatakit-angular?label=pakdatakit-angular" alt="pakdatakit-angular"></a>
26
+ <a href="https://www.npmjs.com/package/pakdatakit-faker"><img src="https://img.shields.io/npm/v/pakdatakit-faker?label=pakdatakit-faker" alt="pakdatakit-faker"></a>
27
+ <a href="https://www.npmjs.com/package/pakdatakit-pay"><img src="https://img.shields.io/npm/v/pakdatakit-pay?label=pakdatakit-pay" alt="pakdatakit-pay"></a>
28
+ <a href="https://www.npmjs.com/package/pakdatakit"><img src="https://img.shields.io/npm/dm/pakdatakit?label=downloads" alt="npm downloads"></a>
29
+ <a href="https://www.npmjs.com/package/pakdatakit#provenance"><img src="https://img.shields.io/badge/npm-provenance-2ea44f?logo=npm" alt="npm provenance"></a>
30
+ <a href="https://chmuzamil.github.io/pakdatakit/"><img src="https://img.shields.io/badge/docs-API%20reference-blue" alt="API docs"></a>
30
31
  </p>
31
32
 
32
- ---
33
-
34
- ## ๐ŸŒ Playground
35
-
36
- Try PakDataKit in your browser, no installation needed:
33
+ PakDataKit validates, formats and looks up Pakistani data: CNICs, mobile and landline numbers, IBANs and banks, NTN/STRN, passports and vehicle plates, Raast QR codes, sales tax and salary income tax, FBR digital invoices, electricity and gas bill references, cities, districts, tehsils, postal codes and post offices, Urdu text, Hijri dates and public holidays.
37
34
 
38
- ๐Ÿ‘‰ **[pakdatakit-playground.vercel.app](https://pakdatakit-playground.vercel.app/)**
35
+ - **Five languages, one behaviour.** The TypeScript library has ports for Python, Dart/Flutter, .NET and PHP/Laravel. All five run the same 32,388 shared test vectors, so they give the same answer for the same input.
36
+ - **UI helpers.** React, Vue and Angular inputs that format as you type, plus Flutter formatters and form fields.
37
+ - **Offline and dependency-free.** All data is bundled and no function makes a network call. The npm package has no runtime dependencies and ships ESM, CommonJS and types.
38
+ - **Sourced data.** Every dataset lists its official sources in [DATA.md](./DATA.md).
39
39
 
40
- Validate CNICs, analyze phone numbers, detect networks, build WhatsApp links, check IBANs and banks, look up postal codes, cities and provinces, format PKR amounts, and try the text and Hijri utilities. Use it to preview outputs before you integrate the library.
40
+ **[Try it in the playground](https://pakdatakit-playground.vercel.app/)** ยท **[API reference](https://chmuzamil.github.io/pakdatakit/)** ยท **[llms.txt](https://chmuzamil.github.io/pakdatakit/llms.txt)** / **[llms-full.txt](https://chmuzamil.github.io/pakdatakit/llms-full.txt)** for AI coding assistants
41
41
 
42
42
  ---
43
43
 
44
44
  ## ๐Ÿ“ฆ Packages
45
45
 
46
- | Package | Install | For |
47
- | ------------------------------------------------------------------------------------- | ---------------------------------------- | ---------------------------------------------------------------------------------------------- |
48
- | [`pakdatakit`](https://www.npmjs.com/package/pakdatakit) | `npm install pakdatakit` | JavaScript and TypeScript (Node, browsers, Bun, Deno) |
49
- | [`pakdatakit` (Python)](https://github.com/chmuzamil/pakdatakit/tree/main/python) | `pip install pakdatakit` | Python 3.9+, same functions in snake_case, same data |
50
- | [`pakdatakit-react`](https://github.com/chmuzamil/pakdatakit/tree/main/react) | `npm install pakdatakit-react` | React inputs that format as you type, and a Raast QR component |
51
- | [`pakdatakit-faker`](https://github.com/chmuzamil/pakdatakit/tree/main/faker) | `npm install -D pakdatakit-faker` | Seeded mock data: CNICs, phones, IBANs, addresses and whole personas that pass every validator |
52
- | [`pakdatakit` (Dart)](https://github.com/chmuzamil/pakdatakit/tree/main/dart) | `dart pub add pakdatakit` | Dart and Flutter (including web), same functions and data |
53
- | [`pakdatakit_flutter`](https://github.com/chmuzamil/pakdatakit/tree/main/flutter) | `flutter pub add pakdatakit_flutter` | Flutter input formatters, form fields and a Raast QR widget |
54
- | [`PakDataKit` (.NET)](https://github.com/chmuzamil/pakdatakit/tree/main/dotnet) | Build from `dotnet/` (not on NuGet yet) | .NET 8, same functions and data, with DataAnnotations and FluentValidation packages |
55
- | [`chmuzamil/pakdatakit` (PHP)](https://github.com/chmuzamil/pakdatakit/tree/main/php) | Build from `php/` (not on Packagist yet) | PHP 8.2+, same functions and data, with Laravel rules, rule objects and Eloquent casts |
56
- | [`pakdatakit-vue`](https://github.com/chmuzamil/pakdatakit/tree/main/vue) | Build from `vue/` (not on npm yet) | Vue 3 composables and a `v-pak-input` directive that format as you type |
57
- | [`pakdatakit-angular`](https://github.com/chmuzamil/pakdatakit/tree/main/angular) | Build from `angular/` (not on npm yet) | Angular directives, pipes and form validators |
58
- | [`pakdatakit-pay`](https://github.com/chmuzamil/pakdatakit/tree/main/pay) | Build from `pay/` (not on npm yet) | Server-side JazzCash secure hash: build it and verify responses in constant time |
59
-
60
- The Python, Dart, .NET and PHP packages are checked against the TypeScript library with over 25,000 shared test cases, so all five give the same results.
46
+ | Package | Registry | Install | Version |
47
+ | ---------------------------------------------------------------------------------------------------- | --------- | ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
48
+ | [`pakdatakit`](https://www.npmjs.com/package/pakdatakit) | npm | `npm install pakdatakit` | [![npm](https://img.shields.io/npm/v/pakdatakit?label=)](https://www.npmjs.com/package/pakdatakit) |
49
+ | [`pakdatakit`](https://pypi.org/project/pakdatakit/) ([Python](./python)) | PyPI | `pip install pakdatakit` | [![PyPI](https://img.shields.io/pypi/v/pakdatakit?label=)](https://pypi.org/project/pakdatakit/) |
50
+ | [`pakdatakit`](https://pub.dev/packages/pakdatakit) ([Dart](./dart)) | pub.dev | `dart pub add pakdatakit` | [![pub.dev](https://img.shields.io/pub/v/pakdatakit?label=)](https://pub.dev/packages/pakdatakit) |
51
+ | [`pakdatakit_flutter`](https://pub.dev/packages/pakdatakit_flutter) ([Flutter](./flutter)) | pub.dev | `flutter pub add pakdatakit_flutter` | [![pub.dev](https://img.shields.io/pub/v/pakdatakit_flutter?label=)](https://pub.dev/packages/pakdatakit_flutter) |
52
+ | [`PakDataKit`](https://www.nuget.org/packages/PakDataKit) ([.NET](./dotnet)) | NuGet | `dotnet add package PakDataKit` | [![NuGet](https://img.shields.io/nuget/v/PakDataKit?label=)](https://www.nuget.org/packages/PakDataKit) |
53
+ | [`PakDataKit.DataAnnotations`](https://www.nuget.org/packages/PakDataKit.DataAnnotations) | NuGet | `dotnet add package PakDataKit.DataAnnotations` | [![NuGet](https://img.shields.io/nuget/v/PakDataKit.DataAnnotations?label=)](https://www.nuget.org/packages/PakDataKit.DataAnnotations) |
54
+ | [`PakDataKit.FluentValidation`](https://www.nuget.org/packages/PakDataKit.FluentValidation) | NuGet | `dotnet add package PakDataKit.FluentValidation` | [![NuGet](https://img.shields.io/nuget/v/PakDataKit.FluentValidation?label=)](https://www.nuget.org/packages/PakDataKit.FluentValidation) |
55
+ | [`chmuzamil/pakdatakit`](https://packagist.org/packages/chmuzamil/pakdatakit) ([PHP/Laravel](./php)) | Packagist | `composer require chmuzamil/pakdatakit` | [![Packagist](https://img.shields.io/packagist/v/chmuzamil/pakdatakit?label=)](https://packagist.org/packages/chmuzamil/pakdatakit) |
56
+ | [`pakdatakit-react`](https://www.npmjs.com/package/pakdatakit-react) ([React](./react)) | npm | `npm install pakdatakit-react` | [![npm](https://img.shields.io/npm/v/pakdatakit-react?label=)](https://www.npmjs.com/package/pakdatakit-react) |
57
+ | [`pakdatakit-vue`](https://www.npmjs.com/package/pakdatakit-vue) ([Vue](./vue)) | npm | `npm install pakdatakit-vue` | [![npm](https://img.shields.io/npm/v/pakdatakit-vue?label=)](https://www.npmjs.com/package/pakdatakit-vue) |
58
+ | [`pakdatakit-angular`](https://www.npmjs.com/package/pakdatakit-angular) ([Angular](./angular)) | npm | `npm install pakdatakit-angular` | [![npm](https://img.shields.io/npm/v/pakdatakit-angular?label=)](https://www.npmjs.com/package/pakdatakit-angular) |
59
+ | [`pakdatakit-faker`](https://www.npmjs.com/package/pakdatakit-faker) ([mock data](./faker)) | npm | `npm install -D pakdatakit-faker` | [![npm](https://img.shields.io/npm/v/pakdatakit-faker?label=)](https://www.npmjs.com/package/pakdatakit-faker) |
60
+ | [`pakdatakit-pay`](https://www.npmjs.com/package/pakdatakit-pay) ([JazzCash hash](./pay)) | npm | `npm install pakdatakit-pay` | [![npm](https://img.shields.io/npm/v/pakdatakit-pay?label=)](https://www.npmjs.com/package/pakdatakit-pay) |
61
61
 
62
62
  ---
63
63
 
64
- ## ๐Ÿ“š Documentation
64
+ ## ๐Ÿงฉ Modules
65
65
 
66
- - **[API reference](https://chmuzamil.github.io/pakdatakit/)**: every function, option and return type
67
- - **[llms.txt](https://chmuzamil.github.io/pakdatakit/llms.txt)** and **[llms-full.txt](https://chmuzamil.github.io/pakdatakit/llms-full.txt)**: the library in a form AI coding assistants can read
68
- - **[DATA.md](./DATA.md)**: where every dataset comes from
66
+ Every module is in every port unless noted. In npm, each is also a subpath import (`pakdatakit/cnic`, `pakdatakit/salestax` and so on) to keep bundles small.
69
67
 
70
- ---
68
+ | Area | What it covers | npm modules |
69
+ | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
70
+ | **Identity** | CNIC validation with province and gender, passports, vehicle registration plates | `cnic`, `passport`, `vehicle` |
71
+ | **Phone** | Mobile numbers and their original network, landline, UAN, toll-free and premium numbers, WhatsApp links, phone risk signals for cash on delivery | `phone`, `networks`, `numbers`, `whatsapp`, `quality` |
72
+ | **Banking and payments** | IBAN checksum and bank lookup, Raast QR codes (create, parse, validate), electricity and gas bill references, PKR and lakh/crore formatting, amounts in words; JazzCash secure hash in `pakdatakit-pay` | `iban`, `raast`, `bills`, `format`, `words` |
73
+ | **Tax and FBR** | NTN and STRN, federal and provincial sales tax rates, salary income tax (tax years 2020 to 2027), FBR Digital Invoicing build and offline validation | `tax`, `salestax`, `incometax`, `fbr-invoice` |
74
+ | **Geography and postal** | Provinces, cities, districts, divisions and tehsils (2023 census), postal codes and about 2,560 post offices, address parsing and delivery-address scoring, courier status and city matching (experimental) | `geo`, `postal`, `address`, `quality`, `courier` |
75
+ | **Text and Urdu** | Roman Urdu normalization, Urdu and English digits, Urdu-aware slugs, Urdu alphabetical order, right-to-left detection and bidi isolation | `text` |
76
+ | **Dates** | Hijri dates, Ramadan, public holidays with observed moon-sighting dates | `hijri`, `holidays` |
77
+ | **Forms** | As-you-type formatting and checking; schemas for Zod, Valibot, Yup, Joi and Superstruct; class-validator decorators for NestJS; Laravel rules, DataAnnotations and FluentValidation in the ports; React, Vue, Angular and Flutter inputs | `input`, `zod`, `valibot`, `yup`, `joi`, `superstruct`, `class-validator` |
71
78
 
72
- ## Why PakDataKit?
79
+ ---
73
80
 
74
- Most Pakistani apps validate CNICs, mobile numbers and IBANs with a regex copied from somewhere. A regex checks the shape. PakDataKit checks what the shape can't show:
81
+ ## ๐Ÿš€ Quick start
75
82
 
76
- | Task | Typical regex | PakDataKit |
77
- | ----------------- | ---------------------------- | ----------------------------------------------------------------------------------------------- |
78
- | CNIC | 13 digits, maybe with dashes | Province code, province and gender decoding, Urdu digits |
79
- | Mobile number | `03` + 9 digits | Allocated `03XX` prefixes only, `+92` / `0092` / `0` forms, original network |
80
- | IBAN | `PK` + 22 characters | Mod-97 checksum, bank name and type from the bank code |
81
- | NTN / STRN | Digit count | CNIC-based and business NTNs, display formats |
82
- | Passport, plates | Usually not handled | Common-shape checks, with sources and limits in [DATA.md](./DATA.md) |
83
- | Raast QR | Not possible | Create, parse and check payment QR codes (CRC, IBAN, amount, expiry) |
84
- | Holidays, Hijri | Not possible | Observed Eid/Ashura/Milad dates from official notifications, Hijri conversion |
85
- | Amounts, currency | Not possible | Lakh/crore formatting, amounts in words in English and Urdu |
86
- | Forms | Write each rule per library | Ready rules for Zod, Valibot, Yup, Joi, Superstruct and class-validator (NestJS) |
87
- | Other languages | Rewrite it | Python and Dart packages with the core functions, checked against over 25,000 shared test cases |
88
-
89
- The npm package has no runtime dependencies, ships ESM and CommonJS with TypeScript types, and works offline: all data is bundled. Every dataset lists its sources in [DATA.md](./DATA.md).
83
+ **TypeScript / JavaScript** (Node 20+, browsers, Bun, Deno; `import` or `require`)
90
84
 
91
- ---
85
+ ```ts
86
+ import { validateCNIC, getBankFromIBAN, calculateSalaryTax } from 'pakdatakit';
92
87
 
93
- ## Features
94
-
95
- - โœ… CNIC Validation
96
- - โœ… CNIC Province & Gender Decoding
97
- - โœ… Phone Number Validation
98
- - โœ… Phone Number Normalization
99
- - โœ… Phone Intelligence (`analyzePhone`)
100
- - โœ… WhatsApp Link Generator
101
- - โœ… IBAN Validation
102
- - โœ… Bank Detection from IBAN
103
- - โœ… Postal Code Lookup
104
- - โœ… Address Parsing
105
- - โœ… Roman Urdu Normalization
106
- - โœ… Hijri Date Utilities
107
- - โœ… CLI Tool
108
- - โœ… Mobile Network Detection
109
- - โœ… City โ†’ Province Lookup
110
- - โœ… PKR Formatting
111
- - โœ… Lakh / Crore Formatting
112
- - โœ… Amounts in Words (English & Urdu, cheque style)
113
- - โœ… Zod, Valibot & Yup Form Validation
114
- - โœ… As-You-Type Formatting for CNIC, Phone & IBAN
115
- - โœ… NTN & STRN Validation
116
- - โœ… Landline, UAN (111), Toll-Free (0800) & Premium (0900) Numbers
117
- - โœ… Raast QR Codes (SBP standard)
118
- - โœ… Pakistan Public Holidays (moon-sighting aware)
119
-
120
- ### Developer Friendly
121
-
122
- - Fully Typed (TypeScript)
123
- - Zero Runtime Dependencies (form libraries are optional peers)
124
- - Tree-Shakeable
125
- - Lightweight & Fast
126
- - ESM and CommonJS, with per-module subpath imports
127
- - Production Ready
88
+ validateCNIC('35202-1234567-1'); // true
89
+ getBankFromIBAN('PK36SCBL0000001123456702'); // "Standard Chartered Bank (Pakistan) Limited"
90
+ calculateSalaryTax(5_000_000, { taxYear: 2027 })?.tax; // 802000
91
+ ```
128
92
 
129
- ---
93
+ **Python** (3.9+)
130
94
 
131
- ## Installation
95
+ ```python
96
+ from pakdatakit import validate_cnic, get_bank_from_iban, calculate_salary_tax
132
97
 
133
- ```bash
134
- npm install pakdatakit
98
+ validate_cnic("35202-1234567-1") # True
99
+ get_bank_from_iban("PK36SCBL0000001123456702") # "Standard Chartered Bank (Pakistan) Limited"
100
+ calculate_salary_tax(5_000_000, tax_year=2027).tax # 802000
135
101
  ```
136
102
 
137
- Requirements:
103
+ **Dart / Flutter**
138
104
 
139
- - Node.js 20+
140
- - Works with both `import` and `require()`
105
+ ```dart
106
+ import 'package:pakdatakit/pakdatakit.dart';
141
107
 
142
- Import everything from `pakdatakit`, or a single module to keep bundles small:
108
+ validateCNIC('35202-1234567-1'); // true
109
+ getBankFromIBAN('PK36SCBL0000001123456702'); // Standard Chartered Bank (Pakistan) Limited
110
+ calculateSalaryTax(5000000, taxYear: 2027)?.tax; // 802000
143
111
 
144
- ```ts
145
- import { validateCNIC } from 'pakdatakit/cnic';
146
- const { analyzePhone } = require('pakdatakit/phone');
112
+ // pakdatakit_flutter
113
+ TextFormField(inputFormatters: [CnicInputFormatter()], validator: PakValidators.cnic());
147
114
  ```
148
115
 
149
- Subpaths: `address`, `cnic`, `format`, `geo`, `hijri`, `holidays`, `iban`, `input`, `networks`, `numbers`, `passport`, `phone`, `postal`, `raast`, `tax`, `text`, `vehicle`, `whatsapp`, `words`, plus the form adapters `zod`, `valibot`, `yup`, `joi`, `superstruct` and `class-validator`.
116
+ **.NET** (8+)
150
117
 
151
- ---
118
+ ```csharp
119
+ using PakDataKit;
152
120
 
153
- ## Quick Start
121
+ Cnic.Validate("35202-1234567-1"); // true
122
+ Iban.GetBank("PK36SCBL0000001123456702"); // "Standard Chartered Bank (Pakistan) Limited"
123
+ IncomeTax.CalculateSalaryTax(5_000_000, new SalaryTaxOptions { TaxYear = 2027 })?.Tax; // 802000
154
124
 
155
- ```ts
156
- import {
157
- validateCNIC,
158
- analyzePhone,
159
- createWhatsAppLink,
160
- validateIBAN,
161
- getBankFromIBAN,
162
- getPostalCode,
163
- getCityByPostalCode,
164
- getNetwork,
165
- formatLakh,
166
- } from 'pakdatakit';
125
+ // PakDataKit.DataAnnotations: [Cnic] public string Cnic { get; set; }
126
+ // PakDataKit.FluentValidation: RuleFor(x => x.Cnic).IsCnic();
127
+ ```
167
128
 
168
- validateCNIC('35202-1234567-1');
169
- // true
129
+ **PHP / Laravel** (8.2+)
170
130
 
171
- analyzePhone('03001234567');
172
- // { valid: true, formatted: "+923001234567", network: "Jazz" }
131
+ ```php
132
+ use PakDataKit\Cnic;
133
+ use PakDataKit\Iban;
134
+ use PakDataKit\IncomeTax;
173
135
 
174
- createWhatsAppLink('03001234567', 'Assalamualaikum');
175
- // "https://wa.me/923001234567?text=Assalamualaikum"
136
+ Cnic::validate('35202-1234567-1'); // true
137
+ Iban::getBank('PK36SCBL0000001123456702'); // "Standard Chartered Bank (Pakistan) Limited"
138
+ IncomeTax::calculateSalary(5000000, ['taxYear' => 2027])?->tax; // 802000
176
139
 
177
- validateIBAN('PK36SCBL0000001123456702');
178
- // true
140
+ // Laravel: $request->validate(['cnic' => ['required', 'pk_cnic'], 'phone' => 'pk_phone']);
141
+ ```
179
142
 
180
- getBankFromIBAN('PK36SCBL0000001123456702');
181
- // "Standard Chartered Bank (Pakistan) Limited"
143
+ **React, Vue and Angular**
182
144
 
183
- getPostalCode('Multan');
184
- // "60000"
185
-
186
- getCityByPostalCode('60000');
187
- // "Multan"
145
+ ```tsx
146
+ // React
147
+ import { CNICInput } from 'pakdatakit-react';
148
+ <CNICInput onValueChange={(value, state, info) => {}} />;
149
+ ```
188
150
 
189
- getNetwork('03001234567');
190
- // "Jazz"
151
+ ```vue
152
+ <!-- Vue -->
153
+ <input v-model="cnic" v-pak-input:cnic />
154
+ ```
191
155
 
192
- formatLakh(2500000);
193
- // "25 Lakh"
156
+ ```html
157
+ <!-- Angular: import PakCnicInputDirective; validate with PakValidators.cnic -->
158
+ <input pakCnicInput [formControl]="cnic" />
194
159
  ```
195
160
 
196
- ### CLI
161
+ **CLI**
197
162
 
198
163
  ```bash
199
164
  npx pakdatakit validate-cnic 35202-1234567-1
200
165
  npx pakdatakit analyze-phone 03001234567
201
166
  npx pakdatakit parse-address "House 12, Gulberg III, Lahore, Punjab 54660"
202
- npx pakdatakit hijri
203
- npx pakdatakit normalize-urdu "ap kia ker rhe ho"
204
167
  ```
205
168
 
206
- The CLI exits with status 0 when the input is valid or found, 1 when it is invalid or not found, and 2 for usage errors, so it can be used in scripts. Run `npx pakdatakit --help` for all commands.
169
+ The CLI exits with 0 when the input is valid or found, 1 when it is not, and 2 for usage errors. Run `npx pakdatakit --help` for every command.
170
+
171
+ ---
172
+
173
+ ## Why PakDataKit?
174
+
175
+ Most Pakistani apps validate CNICs, mobile numbers and IBANs with a regex copied from somewhere. A regex checks the shape. PakDataKit checks what the shape can't show:
176
+
177
+ | Task | Typical regex | PakDataKit |
178
+ | --------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------- |
179
+ | CNIC | 13 digits, maybe with dashes | Province code, province and gender decoding, Urdu digits |
180
+ | Mobile number | `03` + 9 digits | Allocated `03XX` prefixes only, `+92` / `0092` / `0` forms, original network |
181
+ | IBAN | `PK` + 22 characters | Mod-97 checksum, bank name and type from the bank code |
182
+ | NTN / STRN | Digit count | CNIC-based and business NTNs, display formats |
183
+ | Sales tax, income tax | Hard-coded rates | Rates by authority and date with their legal source; exact amounts in whole paisa |
184
+ | FBR invoices | Found out at submission | Offline validation with FBR's own error codes |
185
+ | Raast QR | Not possible | Create, parse and check payment QR codes (CRC, IBAN, amount, expiry) |
186
+ | Holidays, Hijri | Not possible | Observed Eid/Ashura/Milad dates from official notifications, Hijri conversion |
187
+ | Forms | Write each rule per library | Ready rules for Zod, Valibot, Yup, Joi, Superstruct, class-validator, Laravel, DataAnnotations and FluentValidation |
207
188
 
208
189
  ---
209
190
 
@@ -1334,67 +1315,6 @@ const budget = formatLakh(2500000);
1334
1315
 
1335
1316
  ---
1336
1317
 
1337
- # Roadmap
1338
-
1339
- ### v0.2 โœ…
1340
-
1341
- - Phone Intelligence (`analyzePhone`)
1342
- - WhatsApp Link Generator
1343
- - IBAN Validation
1344
- - Bank Detection from IBAN
1345
- - Postal Code Lookup
1346
- - Expanded datasets (cities, districts, postal codes, banks)
1347
-
1348
- ### v0.3 โœ…
1349
-
1350
- - Address Parsing (`parseAddress`, `formatAddress`)
1351
- - Expanded Postal Data (`getPostalAreas`, `searchPostalCodes`)
1352
-
1353
- ### v0.4 โœ…
1354
-
1355
- - Roman Urdu Utilities (`normalizeRomanUrdu`)
1356
- - Text Normalization (`normalizeText`, `toUrduDigits`, `toEnglishDigits`)
1357
-
1358
- ### v0.5 โœ…
1359
-
1360
- - Islamic Calendar Utilities (`toHijri`, `fromHijri`, `formatHijri`)
1361
- - Hijri Date Helpers (`getHijriMonthName`, `isRamadan`)
1362
-
1363
- ### v1.0 โœ…
1364
-
1365
- - CLI Tool (`pakdatakit` command)
1366
- - Dataset-backed lookup APIs
1367
- - Community Contributions (see CONTRIBUTING.md)
1368
-
1369
- ### v1.1 โœ…
1370
-
1371
- - Interactive Playground ([pakdatakit-playground.vercel.app](https://pakdatakit-playground.vercel.app/))
1372
-
1373
- ### v2.0 โœ…
1374
-
1375
- - Bug-fix release; see [CHANGELOG.md](./CHANGELOG.md) for breaking changes
1376
- - CommonJS build and subpath imports
1377
- - Corrected Hijri dates, datasets and validation
1378
-
1379
- ### v2.1 โœ…
1380
-
1381
- - CNIC province & gender decoding (`getCNICInfo`)
1382
- - Amounts in words in English and Urdu (`amountInWords`, `numberToWords`)
1383
- - Zod, Valibot and Yup adapters
1384
- - NTN and STRN validation
1385
- - Landline, UAN, toll-free and premium numbers
1386
- - Raast QR codes
1387
- - Public holidays with observed moon-sighting dates
1388
-
1389
- ### v2.2 โœ…
1390
-
1391
- - Python package on PyPI, Dart package on pub.dev
1392
- - `pakdatakit-react` form inputs, `pakdatakit-faker` test data and
1393
- `pakdatakit_flutter` widgets
1394
- - Bank details (`getBankInfo`, `getBanks`), API docs and `llms.txt`
1395
-
1396
- ---
1397
-
1398
1318
  # Contributing
1399
1319
 
1400
1320
  Contributions are welcome.
package/dist/cli.js CHANGED
@@ -2,7 +2,7 @@
2
2
  import { normalizeRomanUrdu, formatHijri, toHijri, formatPKR, formatLakh, parseAddress, getCityByPostalCode, getPostalCode, getProvince, getBankFromIBAN, validateIBAN, analyzePhone, validatePhone, validateCNIC } from 'pakdatakit';
3
3
 
4
4
  // package.json
5
- var version = "2.5.0";
5
+ var version = "2.5.1";
6
6
  var EXIT_OK = 0;
7
7
  var EXIT_NEGATIVE = 1;
8
8
  var EXIT_USAGE = 2;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "pakdatakit",
3
- "version": "2.5.0",
3
+ "version": "2.5.1",
4
4
  "description": "Pakistani data utilities for TypeScript and JavaScript: validate CNIC, mobile, IBAN, NTN/STRN, passport and vehicle numbers; Raast QR codes, banks, mobile networks, postal codes, districts, holidays, Hijri dates and amounts in words. No dependencies, with Zod, Valibot, Yup, Joi, Superstruct and class-validator adapters.",
5
5
  "type": "module",
6
6
  "main": "./dist/index.cjs",
@@ -434,21 +434,21 @@
434
434
  "devDependencies": {
435
435
  "@eslint/js": "^10.0.1",
436
436
  "@types/node": "^26.6.5",
437
- "@typescript-eslint/eslint-plugin": "^8.72.0",
437
+ "@typescript-eslint/eslint-plugin": "^8.72.2",
438
438
  "@typescript-eslint/parser": "^8.72.0",
439
439
  "class-validator": "^0.15.1",
440
- "eslint": "^10.13.0",
440
+ "eslint": "^10.15.0",
441
441
  "eslint-config-prettier": "^10.1.5",
442
- "globals": "^17.6.0",
442
+ "globals": "^17.14.0",
443
443
  "joi": "^18.3.2",
444
- "libphonenumber-js": "^1.13.15",
445
- "prettier": "^3.9.10",
444
+ "libphonenumber-js": "^1.13.16",
445
+ "prettier": "^3.10.1",
446
446
  "superstruct": "^2.0.2",
447
447
  "tsup": "^9.0.0",
448
448
  "typedoc": "^0.28.20",
449
449
  "typescript": "^5.8.3",
450
450
  "valibot": "^1.5.0",
451
- "vitest": "^5.0.5",
451
+ "vitest": "^5.1.0",
452
452
  "yup": "^1.7.1",
453
453
  "zod": "^4.6.7"
454
454
  },