pakdatakit 2.5.0 → 2.6.0

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.
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://pakdatakit.dev/api/typescript/"><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
+ **[pakdatakit.dev](https://pakdatakit.dev/)** · **[Try it in the playground](https://pakdatakit.dev/playground/)** · **[API reference](https://pakdatakit.dev/api/typescript/)** · **[llms.txt](https://pakdatakit.dev/llms.txt)** / **[llms-full.txt](https://pakdatakit.dev/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](https://github.com/chmuzamil/pakdatakit/tree/main/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](https://github.com/chmuzamil/pakdatakit/tree/main/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](https://github.com/chmuzamil/pakdatakit/tree/main/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](https://github.com/chmuzamil/pakdatakit/tree/main/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](https://github.com/chmuzamil/pakdatakit/tree/main/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](https://github.com/chmuzamil/pakdatakit/tree/main/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](https://github.com/chmuzamil/pakdatakit/tree/main/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](https://github.com/chmuzamil/pakdatakit/tree/main/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](https://github.com/chmuzamil/pakdatakit/tree/main/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](https://github.com/chmuzamil/pakdatakit/tree/main/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.
67
+
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` |
69
78
 
70
79
  ---
71
80
 
72
- ## Why PakDataKit?
81
+ ## 🚀 Quick start
73
82
 
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:
83
+ **TypeScript / JavaScript** (Node 20+, browsers, Bun, Deno; `import` or `require`)
75
84
 
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).
90
-
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
179
-
180
- getBankFromIBAN('PK36SCBL0000001123456702');
181
- // "Standard Chartered Bank (Pakistan) Limited"
140
+ // Laravel: $request->validate(['cnic' => ['required', 'pk_cnic'], 'phone' => 'pk_phone']);
141
+ ```
182
142
 
183
- getPostalCode('Multan');
184
- // "60000"
143
+ **React, Vue and Angular**
185
144
 
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
 
@@ -829,6 +810,35 @@ formatLakh(50000);
829
810
  // "Rs. 50,000"
830
811
  ```
831
812
 
813
+ ### parseAmount() / formatAmountInput()
814
+
815
+ Reads a rupee amount the way people type it in Pakistan, rounded half-up to
816
+ the paisa. Returns `null` for anything that is not exactly one non-negative
817
+ amount; it never throws.
818
+
819
+ ```ts
820
+ parseAmount(input: string): { value: number; raw: string } | null
821
+ formatAmountInput(input: string): string | null
822
+ ```
823
+
824
+ ```ts
825
+ parseAmount('Rs. 1,50,000/-'); // { value: 150000, raw: 'Rs. 1,50,000/-' }
826
+ parseAmount('2.25cr'); // { value: 22500000, raw: '2.25cr' }
827
+ parseAmount('۱٫۵ لاکھ'); // { value: 150000, ... }
828
+ parseAmount('1.005'); // { value: 1.01, ... }: exact, on the digits
829
+ parseAmount('5-10k'); // null: a range
830
+ formatAmountInput('1.5 lakh'); // "Rs. 150,000"
831
+ ```
832
+
833
+ Accepted: `150,000` and `1,50,000` grouping with decimals; Urdu and
834
+ Arabic-Indic digits; `Rs`, `Rs.`, `PKR` or `₨` before or after the number and
835
+ a trailing `/-`; `k`, `thousand(s)`, `hazar`, `ہزار`, `lakh(s)`, `lac(s)`,
836
+ `لاکھ`, `crore(s)`, `cr` and `کروڑ`, also with decimals (`1.5 lakh`);
837
+ whitespace around and between the parts. Rejected: negatives, ranges, more
838
+ than one number, leftover letters, broken or ambiguous grouping (`1,50`,
839
+ `1.500,00`) and amounts over Rs. 50 trillion. Every form is listed on
840
+ [pakdatakit.dev/docs/amount](https://pakdatakit.dev/docs/amount/).
841
+
832
842
  ---
833
843
 
834
844
  ## Amounts in Words
@@ -1228,7 +1238,7 @@ import { pk } from 'pakdatakit/superstruct';
1228
1238
  const CheckoutForm = object({ cnic: pk.cnic(), phone: optional(pk.phone()) });
1229
1239
  ```
1230
1240
 
1231
- Available schemas: `pk.cnic()`, `pk.phone()`, `pk.iban()`, `pk.ntn()`, `pk.strn()`, `pk.landline()`, `pk.passport()`, `pk.vehiclePlate()` and `pk.codPhone()` (a mobile number with no `phoneRiskSignals` flags). Every factory accepts `{ message }` to replace the default error. The Yup schemas let empty values pass so `.required()` decides whether a field is mandatory.
1241
+ Available schemas: `pk.cnic()`, `pk.phone()`, `pk.iban()`, `pk.ntn()`, `pk.strn()`, `pk.landline()`, `pk.passport()`, `pk.vehiclePlate()`, `pk.codPhone()` (a mobile number with no `phoneRiskSignals` flags) and `pk.amount()` (an amount `parseAmount()` reads, such as `1.5 lakh`; convert it with `parseAmount` on submit). Every factory accepts `{ message }` to replace the default error. The Yup schemas let empty values pass so `.required()` decides whether a field is mandatory.
1232
1242
 
1233
1243
  ### class-validator and NestJS
1234
1244
 
@@ -1251,7 +1261,7 @@ export class CreateCustomerDto {
1251
1261
  }
1252
1262
  ```
1253
1263
 
1254
- Decorators: `IsCNIC`, `IsPakPhone`, `IsPakIBAN` (named so it doesn't clash with class-validator's own `IsIBAN`), `IsNTN`, `IsSTRN`, `IsPakLandline`, `IsPakPassport`, `IsVehiclePlate` and `IsCodPhone`, also available as `pk.cnic()` and so on. They accept class-validator's options (`message`, `groups`, `each`, `always`); use `@IsOptional()` for optional fields. Values that are not strings fail.
1264
+ Decorators: `IsCNIC`, `IsPakPhone`, `IsPakIBAN` (named so it doesn't clash with class-validator's own `IsIBAN`), `IsNTN`, `IsSTRN`, `IsPakLandline`, `IsPakPassport`, `IsVehiclePlate`, `IsCodPhone` and `IsPakAmount`, also available as `pk.cnic()` and so on. They accept class-validator's options (`message`, `groups`, `each`, `always`); use `@IsOptional()` for optional fields. Values that are not strings fail.
1255
1265
 
1256
1266
  ### As-you-type helpers
1257
1267
 
@@ -1334,67 +1344,6 @@ const budget = formatLakh(2500000);
1334
1344
 
1335
1345
  ---
1336
1346
 
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
1347
  # Contributing
1399
1348
 
1400
1349
  Contributions are welcome.
@@ -0,0 +1,85 @@
1
+ // src/format.ts
2
+ var LAKH = 1e5;
3
+ var CRORE = 1e7;
4
+ var pkrFormatter = new Intl.NumberFormat("en-PK", {
5
+ maximumFractionDigits: 0
6
+ });
7
+ function assertFinite(amount) {
8
+ if (typeof amount !== "number" || !Number.isFinite(amount)) {
9
+ throw new RangeError(
10
+ `Amount must be a finite number, received ${String(amount)}`
11
+ );
12
+ }
13
+ }
14
+ function roundTo2(value) {
15
+ return Math.round(value * 100) / 100;
16
+ }
17
+ function formatPKR(amount) {
18
+ assertFinite(amount);
19
+ const rounded = Math.round(Math.abs(amount));
20
+ const sign = amount < 0 && rounded !== 0 ? "-" : "";
21
+ return `${sign}Rs. ${pkrFormatter.format(rounded)}`;
22
+ }
23
+ function formatLakh(amount) {
24
+ assertFinite(amount);
25
+ const sign = amount < 0 ? "-" : "";
26
+ const absolute = Math.abs(amount);
27
+ const crores = roundTo2(absolute / CRORE);
28
+ if (crores >= 1) {
29
+ return `${sign}${crores} Crore`;
30
+ }
31
+ const lakhs = roundTo2(absolute / LAKH);
32
+ if (lakhs >= 1) {
33
+ return `${sign}${lakhs} Lakh`;
34
+ }
35
+ return formatPKR(amount);
36
+ }
37
+ var SPACE = /[ \t\n\r\u00A0\u202F]/.source;
38
+ var TRIM = new RegExp(`^${SPACE}+|${SPACE}+$`, "g");
39
+ var CURRENCY = /(rs\.?|pkr|\u20A8)/.source;
40
+ var NUMBER = /(\d{1,3}(?:,\d{3})+|\d{1,2}(?:,\d{2})+,\d{3}|\d+)?(?:\.(\d*))?/.source;
41
+ var THOUSAND = /k|thousands?|hazar|\u06C1\u0632\u0627\u0631/.source;
42
+ var LAKH_UNIT = /lakhs?|lacs?|\u0644\u0627\u06A9\u06BE/.source;
43
+ var CRORE_UNIT = /crores?|cr|\u06A9\u0631\u0648\u0691/.source;
44
+ var AMOUNT = new RegExp(
45
+ `^(?:${CURRENCY}${SPACE}*)?${NUMBER}(?:${SPACE}*(${THOUSAND}|${LAKH_UNIT}|${CRORE_UNIT}))?(?:${SPACE}*${CURRENCY})?(?:${SPACE}*(\\/-))?$`
46
+ );
47
+ function unitExponent(unit) {
48
+ if (unit === void 0) return 0;
49
+ if (new RegExp(`^(?:${THOUSAND})$`).test(unit)) return 3;
50
+ if (new RegExp(`^(?:${LAKH_UNIT})$`).test(unit)) return 5;
51
+ return 7;
52
+ }
53
+ var MAX_PAISA = 5000000000000000n;
54
+ function parseAmount(input) {
55
+ if (typeof input !== "string") return null;
56
+ const raw = input.replace(TRIM, "");
57
+ const text = raw.replace(/[\u06F0-\u06F9]/g, (d) => String(d.charCodeAt(0) - 1776)).replace(/[\u0660-\u0669]/g, (d) => String(d.charCodeAt(0) - 1632)).replace(/\u066B/g, ".").replace(/\u066C/g, ",").replace(/[A-Z]/g, (c) => c.toLowerCase());
58
+ const match = AMOUNT.exec(text);
59
+ if (!match) return null;
60
+ const [, before, whole = "", fraction, unit, after] = match;
61
+ if (before !== void 0 && after !== void 0) return null;
62
+ if (whole === "" && (fraction === void 0 || fraction === "")) return null;
63
+ const digits = whole.replace(/,/g, "") + (fraction ?? "");
64
+ const point = whole.replace(/,/g, "").length + unitExponent(unit);
65
+ const padded = digits.padEnd(point + 3, "0");
66
+ const rupees = padded.slice(0, point) || "0";
67
+ const paisa = padded.slice(point, point + 2);
68
+ let cents = BigInt(rupees + paisa);
69
+ if (padded.charCodeAt(point + 2) >= 53) cents += 1n;
70
+ if (cents > MAX_PAISA) return null;
71
+ return { value: Number(cents) / 100, raw };
72
+ }
73
+ function formatAmountInput(input) {
74
+ const parsed = parseAmount(input);
75
+ if (parsed === null) return null;
76
+ const cents = Math.round(parsed.value * 100);
77
+ const rupees = String(Math.floor(cents / 100)).replace(
78
+ /\B(?=(\d{3})+(?!\d))/g,
79
+ ","
80
+ );
81
+ const paisa = cents % 100;
82
+ return `Rs. ${rupees}${paisa ? `.${String(paisa).padStart(2, "0")}` : ""}`;
83
+ }
84
+
85
+ export { formatAmountInput, formatLakh, formatPKR, parseAmount };