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 +156 -207
- package/dist/chunk-NDW52ZK3.js +85 -0
- package/dist/chunk-NLSIAPZG.cjs +90 -0
- package/dist/{chunk-IDTRFOQW.js → chunk-QG5T7YQ5.js} +5 -0
- package/dist/{chunk-XCFZKCV2.cjs → chunk-YSRYWZCQ.cjs} +5 -0
- package/dist/class-validator.cjs +7 -3
- package/dist/class-validator.d.cts +7 -1
- package/dist/class-validator.d.ts +7 -1
- package/dist/class-validator.js +6 -3
- package/dist/cli.js +1 -1
- package/dist/format.cjs +11 -3
- package/dist/format.d.cts +57 -1
- package/dist/format.d.ts +57 -1
- package/dist/format.js +1 -1
- package/dist/index.cjs +11 -3
- package/dist/index.d.cts +1 -1
- package/dist/index.d.ts +1 -1
- package/dist/index.js +1 -1
- package/dist/joi.cjs +5 -3
- package/dist/joi.d.cts +1 -0
- package/dist/joi.d.ts +1 -0
- package/dist/joi.js +4 -2
- package/dist/superstruct.cjs +5 -3
- package/dist/superstruct.d.cts +1 -0
- package/dist/superstruct.d.ts +1 -0
- package/dist/superstruct.js +4 -2
- package/dist/valibot.cjs +5 -3
- package/dist/valibot.d.cts +1 -0
- package/dist/valibot.d.ts +1 -0
- package/dist/valibot.js +4 -2
- package/dist/yup.cjs +5 -3
- package/dist/yup.d.cts +1 -0
- package/dist/yup.d.ts +1 -0
- package/dist/yup.js +4 -2
- package/dist/zod.cjs +5 -3
- package/dist/zod.d.cts +1 -0
- package/dist/zod.d.ts +1 -0
- package/dist/zod.js +4 -2
- package/package.json +8 -8
- package/dist/chunk-6TSKA2PH.js +0 -38
- package/dist/chunk-LVHTH4P7.cjs +0 -41
package/README.md
CHANGED
|
@@ -5,205 +5,186 @@
|
|
|
5
5
|
<h1 align="center">🇵🇰 PakDataKit</h1>
|
|
6
6
|
|
|
7
7
|
<p align="center">
|
|
8
|
-
<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
|
-
|
|
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
|
-
|
|
18
|
-
|
|
19
|
-
<a href="https://www.npmjs.com/package/pakdatakit">
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
<img src="https://img.shields.io/npm
|
|
23
|
-
<img src="https://img.shields.io/badge/
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
47
|
-
|
|
|
48
|
-
| [`pakdatakit`](https://www.npmjs.com/package/pakdatakit)
|
|
49
|
-
| [`pakdatakit` (Python
|
|
50
|
-
| [`pakdatakit
|
|
51
|
-
| [`
|
|
52
|
-
| [`
|
|
53
|
-
| [`
|
|
54
|
-
| [`PakDataKit`
|
|
55
|
-
| [`chmuzamil/pakdatakit` (PHP
|
|
56
|
-
| [`pakdatakit-
|
|
57
|
-
| [`pakdatakit-
|
|
58
|
-
| [`pakdatakit-
|
|
59
|
-
|
|
60
|
-
|
|
46
|
+
| Package | Registry | Install | Version |
|
|
47
|
+
| ---------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
|
|
48
|
+
| [`pakdatakit`](https://www.npmjs.com/package/pakdatakit) | npm | `npm install pakdatakit` | [](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` | [](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` | [](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` | [](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` | [](https://www.nuget.org/packages/PakDataKit) |
|
|
53
|
+
| [`PakDataKit.DataAnnotations`](https://www.nuget.org/packages/PakDataKit.DataAnnotations) | NuGet | `dotnet add package PakDataKit.DataAnnotations` | [](https://www.nuget.org/packages/PakDataKit.DataAnnotations) |
|
|
54
|
+
| [`PakDataKit.FluentValidation`](https://www.nuget.org/packages/PakDataKit.FluentValidation) | NuGet | `dotnet add package PakDataKit.FluentValidation` | [](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` | [](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` | [](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` | [](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` | [](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` | [](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` | [](https://www.npmjs.com/package/pakdatakit-pay) |
|
|
61
61
|
|
|
62
62
|
---
|
|
63
63
|
|
|
64
|
-
##
|
|
64
|
+
## 🧩 Modules
|
|
65
65
|
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
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
|
-
##
|
|
81
|
+
## 🚀 Quick start
|
|
73
82
|
|
|
74
|
-
|
|
83
|
+
**TypeScript / JavaScript** (Node 20+, browsers, Bun, Deno; `import` or `require`)
|
|
75
84
|
|
|
76
|
-
|
|
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
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
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
|
-
|
|
95
|
+
```python
|
|
96
|
+
from pakdatakit import validate_cnic, get_bank_from_iban, calculate_salary_tax
|
|
132
97
|
|
|
133
|
-
|
|
134
|
-
|
|
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
|
-
|
|
103
|
+
**Dart / Flutter**
|
|
138
104
|
|
|
139
|
-
|
|
140
|
-
|
|
105
|
+
```dart
|
|
106
|
+
import 'package:pakdatakit/pakdatakit.dart';
|
|
141
107
|
|
|
142
|
-
|
|
108
|
+
validateCNIC('35202-1234567-1'); // true
|
|
109
|
+
getBankFromIBAN('PK36SCBL0000001123456702'); // Standard Chartered Bank (Pakistan) Limited
|
|
110
|
+
calculateSalaryTax(5000000, taxYear: 2027)?.tax; // 802000
|
|
143
111
|
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
const { analyzePhone } = require('pakdatakit/phone');
|
|
112
|
+
// pakdatakit_flutter
|
|
113
|
+
TextFormField(inputFormatters: [CnicInputFormatter()], validator: PakValidators.cnic());
|
|
147
114
|
```
|
|
148
115
|
|
|
149
|
-
|
|
116
|
+
**.NET** (8+)
|
|
150
117
|
|
|
151
|
-
|
|
118
|
+
```csharp
|
|
119
|
+
using PakDataKit;
|
|
152
120
|
|
|
153
|
-
|
|
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
|
-
|
|
156
|
-
|
|
157
|
-
|
|
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
|
-
|
|
169
|
-
// true
|
|
129
|
+
**PHP / Laravel** (8.2+)
|
|
170
130
|
|
|
171
|
-
|
|
172
|
-
|
|
131
|
+
```php
|
|
132
|
+
use PakDataKit\Cnic;
|
|
133
|
+
use PakDataKit\Iban;
|
|
134
|
+
use PakDataKit\IncomeTax;
|
|
173
135
|
|
|
174
|
-
|
|
175
|
-
// "
|
|
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
|
-
|
|
178
|
-
|
|
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
|
-
|
|
184
|
-
// "60000"
|
|
143
|
+
**React, Vue and Angular**
|
|
185
144
|
|
|
186
|
-
|
|
187
|
-
//
|
|
145
|
+
```tsx
|
|
146
|
+
// React
|
|
147
|
+
import { CNICInput } from 'pakdatakit-react';
|
|
148
|
+
<CNICInput onValueChange={(value, state, info) => {}} />;
|
|
149
|
+
```
|
|
188
150
|
|
|
189
|
-
|
|
190
|
-
|
|
151
|
+
```vue
|
|
152
|
+
<!-- Vue -->
|
|
153
|
+
<input v-model="cnic" v-pak-input:cnic />
|
|
154
|
+
```
|
|
191
155
|
|
|
192
|
-
|
|
193
|
-
|
|
156
|
+
```html
|
|
157
|
+
<!-- Angular: import PakCnicInputDirective; validate with PakValidators.cnic -->
|
|
158
|
+
<input pakCnicInput [formControl]="cnic" />
|
|
194
159
|
```
|
|
195
160
|
|
|
196
|
-
|
|
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
|
|
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()
|
|
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 `
|
|
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 };
|