pakdatakit 1.1.0 → 2.1.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 (127) hide show
  1. package/LICENSE +21 -21
  2. package/README.md +909 -666
  3. package/dist/address.cjs +17 -0
  4. package/dist/address.d.cts +36 -0
  5. package/dist/address.d.ts +36 -0
  6. package/dist/address.js +4 -0
  7. package/dist/chunk-3COX5FSL.cjs +1650 -0
  8. package/dist/chunk-432ZYMYV.js +31 -0
  9. package/dist/chunk-43ULDYUP.cjs +235 -0
  10. package/dist/chunk-44YRK7WO.js +231 -0
  11. package/dist/chunk-4EUKCSLW.js +221 -0
  12. package/dist/chunk-4VVFS6FN.cjs +715 -0
  13. package/dist/chunk-6TSKA2PH.js +38 -0
  14. package/dist/chunk-APXP7OK7.cjs +226 -0
  15. package/dist/chunk-AUATLZA5.cjs +168 -0
  16. package/dist/chunk-BSS4Z7NI.cjs +422 -0
  17. package/dist/chunk-CEPNSHIC.js +33 -0
  18. package/dist/chunk-CYJJ7KGC.cjs +108 -0
  19. package/dist/chunk-E47SNBWQ.cjs +224 -0
  20. package/dist/chunk-E7GAK72W.js +20 -0
  21. package/dist/chunk-EEVNLTB4.js +32 -0
  22. package/dist/chunk-ENQ7O7VW.js +32 -0
  23. package/dist/chunk-H6M6L26S.cjs +37 -0
  24. package/dist/chunk-HBOZIITD.js +351 -0
  25. package/dist/chunk-HTCSHHOR.cjs +35 -0
  26. package/dist/chunk-JKE4AMSZ.js +47 -0
  27. package/dist/chunk-JNP27XW2.cjs +22 -0
  28. package/dist/chunk-K6CZFCX6.js +1642 -0
  29. package/dist/chunk-KEHCTYLO.cjs +52 -0
  30. package/dist/chunk-KQKW2ZEK.cjs +18 -0
  31. package/dist/chunk-L2BDDM2W.js +165 -0
  32. package/dist/chunk-L45UXUWX.js +21 -0
  33. package/dist/chunk-LIYNKIKS.js +709 -0
  34. package/dist/chunk-LVHTH4P7.cjs +41 -0
  35. package/dist/chunk-P4CGOJEM.js +16 -0
  36. package/dist/chunk-PHHKIMO2.cjs +35 -0
  37. package/dist/chunk-QQQKISXT.js +223 -0
  38. package/dist/chunk-T3E4B5MJ.js +417 -0
  39. package/dist/chunk-VPBMIYO2.cjs +38 -0
  40. package/dist/chunk-XCXFGTHW.cjs +355 -0
  41. package/dist/chunk-Y6BUGLXU.js +95 -0
  42. package/dist/chunk-YLWZGSFY.cjs +99 -0
  43. package/dist/chunk-YS7MOLK2.cjs +23 -0
  44. package/dist/chunk-Z5JEIQVW.js +102 -0
  45. package/dist/cli.js +78 -2654
  46. package/dist/cnic.cjs +15 -0
  47. package/dist/cnic.d.cts +35 -0
  48. package/dist/cnic.d.ts +35 -0
  49. package/dist/cnic.js +2 -0
  50. package/dist/format.cjs +14 -0
  51. package/dist/format.d.cts +27 -0
  52. package/dist/format.d.ts +27 -0
  53. package/dist/format.js +1 -0
  54. package/dist/geo.cjs +27 -0
  55. package/dist/geo.d.cts +43 -0
  56. package/dist/geo.d.ts +43 -0
  57. package/dist/geo.js +2 -0
  58. package/dist/hijri.cjs +26 -0
  59. package/dist/hijri.d.cts +62 -0
  60. package/dist/hijri.d.ts +62 -0
  61. package/dist/hijri.js +1 -0
  62. package/dist/holidays.cjs +19 -0
  63. package/dist/holidays.d.cts +72 -0
  64. package/dist/holidays.d.ts +72 -0
  65. package/dist/holidays.js +2 -0
  66. package/dist/iban.cjs +15 -0
  67. package/dist/iban.d.cts +21 -0
  68. package/dist/iban.d.ts +21 -0
  69. package/dist/iban.js +2 -0
  70. package/dist/index.cjs +211 -0
  71. package/dist/index.d.cts +16 -0
  72. package/dist/index.d.ts +16 -300
  73. package/dist/index.js +18 -2764
  74. package/dist/networks.cjs +12 -0
  75. package/dist/networks.d.cts +20 -0
  76. package/dist/networks.d.ts +20 -0
  77. package/dist/networks.js +3 -0
  78. package/dist/numbers.cjs +24 -0
  79. package/dist/numbers.d.cts +53 -0
  80. package/dist/numbers.d.ts +53 -0
  81. package/dist/numbers.js +3 -0
  82. package/dist/phone.cjs +29 -0
  83. package/dist/phone.d.cts +56 -0
  84. package/dist/phone.d.ts +56 -0
  85. package/dist/phone.js +4 -0
  86. package/dist/postal.cjs +27 -0
  87. package/dist/postal.d.cts +40 -0
  88. package/dist/postal.d.ts +40 -0
  89. package/dist/postal.js +2 -0
  90. package/dist/raast.cjs +20 -0
  91. package/dist/raast.d.cts +125 -0
  92. package/dist/raast.d.ts +125 -0
  93. package/dist/raast.js +3 -0
  94. package/dist/rules-GxgPiVws.d.cts +7 -0
  95. package/dist/rules-GxgPiVws.d.ts +7 -0
  96. package/dist/tax.cjs +20 -0
  97. package/dist/tax.d.cts +47 -0
  98. package/dist/tax.d.ts +47 -0
  99. package/dist/tax.js +3 -0
  100. package/dist/text.cjs +23 -0
  101. package/dist/text.d.cts +34 -0
  102. package/dist/text.d.ts +34 -0
  103. package/dist/text.js +2 -0
  104. package/dist/valibot.cjs +47 -0
  105. package/dist/valibot.d.cts +22 -0
  106. package/dist/valibot.d.ts +22 -0
  107. package/dist/valibot.js +25 -0
  108. package/dist/whatsapp.cjs +12 -0
  109. package/dist/whatsapp.d.cts +12 -0
  110. package/dist/whatsapp.d.ts +12 -0
  111. package/dist/whatsapp.js +3 -0
  112. package/dist/words.cjs +14 -0
  113. package/dist/words.d.cts +49 -0
  114. package/dist/words.d.ts +49 -0
  115. package/dist/words.js +1 -0
  116. package/dist/yup.cjs +32 -0
  117. package/dist/yup.d.cts +22 -0
  118. package/dist/yup.d.ts +22 -0
  119. package/dist/yup.js +30 -0
  120. package/dist/zod.cjs +27 -0
  121. package/dist/zod.d.cts +22 -0
  122. package/dist/zod.d.ts +22 -0
  123. package/dist/zod.js +25 -0
  124. package/package.json +309 -77
  125. package/dist/cli.d.ts +0 -1
  126. package/dist/cli.js.map +0 -1
  127. package/dist/index.js.map +0 -1
package/README.md CHANGED
@@ -1,666 +1,909 @@
1
- <p align="center">
2
- <img src="./banner.png" alt="PakDataKit Banner" />
3
- </p>
4
-
5
- <h1 align="center">🇵🇰 PakDataKit</h1>
6
-
7
- <p align="center">
8
- <strong>The Standard Utility Toolkit for Pakistani Developers</strong>
9
- </p>
10
-
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.
13
- </p>
14
-
15
- <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
- </p>
25
-
26
- ---
27
-
28
- ## Why PakDataKit?
29
-
30
- Every Pakistani application eventually needs to solve the same problems:
31
-
32
- * Validate CNIC numbers
33
- * Normalize mobile numbers
34
- * Detect mobile networks
35
- * Generate WhatsApp click-to-chat links
36
- * Validate Pakistani IBANs and detect banks
37
- * Look up postal codes and cities
38
- * Map cities to provinces
39
- * Format PKR values in Lakh and Crore conventions
40
-
41
- Most teams implement these repeatedly.
42
-
43
- PakDataKit provides a single, typed, reusable solution so you can focus on building your product instead of rebuilding common utilities.
44
-
45
- ---
46
-
47
- ## Features
48
-
49
- ✅ CNIC Validation
50
- ✅ Phone Number Validation
51
- ✅ Phone Number Normalization
52
- ✅ Phone Intelligence (`analyzePhone`)
53
- ✅ WhatsApp Link Generator
54
- ✅ IBAN Validation
55
- ✅ Bank Detection from IBAN
56
- ✅ Postal Code Lookup
57
- ✅ Address Parsing
58
- ✅ Roman Urdu Normalization
59
- ✅ Hijri Date Utilities
60
- ✅ CLI Tool
61
- ✅ Mobile Network Detection
62
- ✅ City → Province Lookup
63
- ✅ PKR Formatting
64
- ✅ Lakh / Crore Formatting
65
-
66
- ### Developer Friendly
67
-
68
- * Fully Typed (TypeScript)
69
- * Zero Runtime Dependencies
70
- * Tree-Shakeable
71
- * Lightweight & Fast
72
- * ESM Ready
73
- * Production Ready
74
-
75
- ---
76
-
77
- ## Installation
78
-
79
- ```bash
80
- npm install pakdatakit
81
- ```
82
-
83
- Requirements:
84
-
85
- * Node.js 18+
86
- * ESM support
87
-
88
- ---
89
-
90
- ## Quick Start
91
-
92
- ```ts
93
- import {
94
- validateCNIC,
95
- analyzePhone,
96
- createWhatsAppLink,
97
- validateIBAN,
98
- getBankFromIBAN,
99
- getPostalCode,
100
- getCityByPostalCode,
101
- getNetwork,
102
- formatLakh
103
- } from "pakdatakit";
104
-
105
- validateCNIC("35202-1234567-1");
106
- // true
107
-
108
- analyzePhone("03001234567");
109
- // { valid: true, formatted: "+923001234567", network: "Jazz" }
110
-
111
- createWhatsAppLink("03001234567", "Assalamualaikum");
112
- // "https://wa.me/923001234567?text=Assalamualaikum"
113
-
114
- validateIBAN("PK36SCBL0000001123456702");
115
- // true
116
-
117
- getBankFromIBAN("PK36SCBL0000001123456702");
118
- // "Standard Chartered Bank (Pakistan) Limited"
119
-
120
- getPostalCode("Multan");
121
- // "60000"
122
-
123
- getCityByPostalCode("60000");
124
- // "Multan"
125
-
126
- getNetwork("03001234567");
127
- // "Jazz"
128
-
129
- formatLakh(2500000);
130
- // "25 Lakh"
131
- ```
132
-
133
- ### CLI
134
-
135
- ```bash
136
- npx pakdatakit validate-cnic 35202-1234567-1
137
- npx pakdatakit analyze-phone 03001234567
138
- npx pakdatakit parse-address "House 12, Gulberg III, Lahore, Punjab 54660"
139
- npx pakdatakit hijri
140
- npx pakdatakit normalize-urdu "ap kia ker rhe ho"
141
- ```
142
-
143
- ---
144
-
145
- # API Reference
146
-
147
- ## CNIC
148
-
149
- ### validateCNIC()
150
-
151
- Validates Pakistani CNIC numbers.
152
-
153
- ```ts
154
- validateCNIC(cnic: string): boolean
155
- ```
156
-
157
- Examples:
158
-
159
- ```ts
160
- validateCNIC("3520212345671");
161
- // true
162
-
163
- validateCNIC("35202-1234567-1");
164
- // true
165
-
166
- validateCNIC("35202-123456-1");
167
- // false
168
- ```
169
-
170
- Supports:
171
-
172
- * Plain format
173
- * Dashed format
174
- * Space-separated format
175
-
176
- ---
177
-
178
- ## Phone Utilities
179
-
180
- ### validatePhone()
181
-
182
- Validates Pakistani mobile numbers.
183
-
184
- ```ts
185
- validatePhone(phone: string): boolean
186
- ```
187
-
188
- Examples:
189
-
190
- ```ts
191
- validatePhone("03001234567");
192
- // true
193
-
194
- validatePhone("+923001234567");
195
- // true
196
-
197
- validatePhone("3001234567");
198
- // true
199
- ```
200
-
201
- ---
202
-
203
- ### formatPhone()
204
-
205
- Converts valid Pakistani mobile numbers to E.164 format.
206
-
207
- ```ts
208
- formatPhone(phone: string): string
209
- ```
210
-
211
- Examples:
212
-
213
- ```ts
214
- formatPhone("03001234567");
215
- // "+923001234567"
216
-
217
- formatPhone("+92 300-123-4567");
218
- // "+923001234567"
219
- ```
220
-
221
- ---
222
-
223
- ### analyzePhone()
224
-
225
- Runs validation, formatting, and network detection in one call.
226
-
227
- ```ts
228
- analyzePhone(phone: string): PhoneAnalysis
229
- ```
230
-
231
- Returns:
232
-
233
- ```ts
234
- {
235
- valid: boolean;
236
- formatted: string | null;
237
- network: "Jazz" | "Zong" | "Telenor" | "Ufone" | "Unknown";
238
- }
239
- ```
240
-
241
- Examples:
242
-
243
- ```ts
244
- analyzePhone("03001234567");
245
- // { valid: true, formatted: "+923001234567", network: "Jazz" }
246
-
247
- analyzePhone("invalid");
248
- // { valid: false, formatted: null, network: "Unknown" }
249
- ```
250
-
251
- ---
252
-
253
- ## WhatsApp Utilities
254
-
255
- ### createWhatsAppLink()
256
-
257
- Generates a WhatsApp click-to-chat link for Pakistani mobile numbers.
258
-
259
- ```ts
260
- createWhatsAppLink(phone: string, message?: string): string
261
- ```
262
-
263
- Examples:
264
-
265
- ```ts
266
- createWhatsAppLink("03001234567");
267
- // "https://wa.me/923001234567"
268
-
269
- createWhatsAppLink("03001234567", "Assalamualaikum");
270
- // "https://wa.me/923001234567?text=Assalamualaikum"
271
- ```
272
-
273
- Returns an empty string for invalid phone numbers.
274
-
275
- ---
276
-
277
- ## IBAN Utilities
278
-
279
- ### validateIBAN()
280
-
281
- Validates Pakistani IBANs using format and ISO 13616 mod-97 checksum.
282
-
283
- ```ts
284
- validateIBAN(iban: string): boolean
285
- ```
286
-
287
- Examples:
288
-
289
- ```ts
290
- validateIBAN("PK36SCBL0000001123456702");
291
- // true
292
-
293
- validateIBAN("PK37SCBL0000001123456702");
294
- // false
295
- ```
296
-
297
- ---
298
-
299
- ### getBankFromIBAN()
300
-
301
- Returns the bank name from a valid Pakistani IBAN's 4-letter bank code.
302
-
303
- ```ts
304
- getBankFromIBAN(iban: string): string | null
305
- ```
306
-
307
- Examples:
308
-
309
- ```ts
310
- getBankFromIBAN("PK36SCBL0000001123456702");
311
- // "Standard Chartered Bank (Pakistan) Limited"
312
-
313
- getBankFromIBAN("invalid");
314
- // null
315
- ```
316
-
317
- Supported bank codes include HABB, MEZN, SCBL, UNIL, BAHL, NBPA, MUCB, JSBL, and 46 total entries in the dataset.
318
-
319
- ---
320
-
321
- ## Postal Code Utilities
322
-
323
- ### getCityByPostalCode()
324
-
325
- Returns the city for a Pakistani postal code.
326
-
327
- ```ts
328
- getCityByPostalCode(postalCode: string): string | null
329
- ```
330
-
331
- Examples:
332
-
333
- ```ts
334
- getCityByPostalCode("60000");
335
- // "Multan"
336
-
337
- getCityByPostalCode("99999");
338
- // null
339
- ```
340
-
341
- ---
342
-
343
- ### getPostalCode()
344
-
345
- Returns the primary postal code for a Pakistani city (case-insensitive).
346
-
347
- ```ts
348
- getPostalCode(city: string): string | null
349
- ```
350
-
351
- Examples:
352
-
353
- ```ts
354
- getPostalCode("Multan");
355
- // "60000"
356
-
357
- getPostalCode("karachi");
358
- // "74200"
359
- ```
360
-
361
- ---
362
-
363
- ## Mobile Networks
364
-
365
- ### getNetwork()
366
-
367
- Detects network using the original mobile prefix.
368
-
369
- ```ts
370
- getNetwork(phone: string): string
371
- ```
372
-
373
- Returns:
374
-
375
- * Jazz
376
- * Zong
377
- * Ufone
378
- * Telenor
379
- * Unknown
380
-
381
- Examples:
382
-
383
- ```ts
384
- getNetwork("03001234567");
385
- // Jazz
386
-
387
- getNetwork("03151234567");
388
- // Zong
389
-
390
- getNetwork("03331234567");
391
- // Ufone
392
-
393
- getNetwork("03451234567");
394
- // Telenor
395
- ```
396
-
397
- > Note: Pakistan supports Mobile Number Portability (MNP). The current carrier may differ from the original prefix.
398
-
399
- ---
400
-
401
- ## Geography
402
-
403
- ### getProvince()
404
-
405
- Returns province for a city.
406
-
407
- ```ts
408
- getProvince(city: string): string | null
409
- ```
410
-
411
- Examples:
412
-
413
- ```ts
414
- getProvince("Multan");
415
- // Punjab
416
-
417
- getProvince("Karachi");
418
- // Sindh
419
-
420
- getProvince("Unknown");
421
- // null
422
- ```
423
-
424
- ---
425
-
426
- ### searchCities()
427
-
428
- Case-insensitive city search.
429
-
430
- ```ts
431
- searchCities(query: string): string[]
432
- ```
433
-
434
- Examples:
435
-
436
- ```ts
437
- searchCities("mul");
438
- // ["Multan"]
439
-
440
- searchCities("kar");
441
- // ["Karachi"]
442
- ```
443
-
444
- ---
445
-
446
- ### getDistrictProvince() / searchDistricts()
447
-
448
- District-level geography lookup across 171 districts.
449
-
450
- ```ts
451
- getDistrictProvince("Lahore"); // "Punjab"
452
- searchDistricts("karachi"); // ["Karachi Central", "Karachi East", ...]
453
- ```
454
-
455
- ---
456
-
457
- ## Address Utilities
458
-
459
- ### parseAddress()
460
-
461
- Parses free-form Pakistani addresses into structured components.
462
-
463
- ```ts
464
- parseAddress("House 12, Gulberg III, Lahore, Punjab 54660");
465
- // { street: "House 12", area: "Gulberg III", city: "Lahore", province: "Punjab", postalCode: "54660", ... }
466
- ```
467
-
468
- ### formatAddress()
469
-
470
- Formats structured components back into a mailing address string.
471
-
472
- ---
473
-
474
- ## Text Utilities
475
-
476
- ### normalizeRomanUrdu()
477
-
478
- Normalizes informal Roman Urdu spellings (`ap kia ker` → `aap kya kar`).
479
-
480
- ### toUrduDigits() / toEnglishDigits()
481
-
482
- Convert between English, Urdu, and Arabic-Indic digits.
483
-
484
- ---
485
-
486
- ## Hijri Calendar
487
-
488
- ### toHijri() / formatHijri() / isRamadan()
489
-
490
- ```ts
491
- formatHijri(new Date()); // "14 Ramadan 1447"
492
- isRamadan(new Date()); // true | false
493
- ```
494
-
495
- ---
496
-
497
- ## Currency Formatting
498
-
499
- ### formatPKR()
500
-
501
- Formats PKR amounts with separators.
502
-
503
- ```ts
504
- formatPKR(amount: number): string
505
- ```
506
-
507
- Examples:
508
-
509
- ```ts
510
- formatPKR(150000);
511
- // "Rs. 150,000"
512
-
513
- formatPKR(0);
514
- // "Rs. 0"
515
- ```
516
-
517
- ---
518
-
519
- ### formatLakh()
520
-
521
- Formats values using Pakistan's Lakh / Crore numbering system.
522
-
523
- ```ts
524
- formatLakh(amount: number): string
525
- ```
526
-
527
- Examples:
528
-
529
- ```ts
530
- formatLakh(2500000);
531
- // "25 Lakh"
532
-
533
- formatLakh(10000000);
534
- // "1 Crore"
535
-
536
- formatLakh(50000);
537
- // "Rs. 50,000"
538
- ```
539
-
540
- ---
541
-
542
- # Real-World Example
543
-
544
- ```ts
545
- import {
546
- validateCNIC,
547
- validatePhone,
548
- formatPhone,
549
- analyzePhone,
550
- createWhatsAppLink,
551
- validateIBAN,
552
- getBankFromIBAN,
553
- getPostalCode,
554
- getCityByPostalCode,
555
- getNetwork,
556
- getProvince,
557
- searchCities,
558
- formatPKR,
559
- formatLakh
560
- } from "pakdatakit";
561
-
562
- // CNIC validation
563
- const cnicValid = validateCNIC("35202-1234567-1");
564
-
565
- // Phone intelligence
566
- const phoneInfo = analyzePhone("03001234567");
567
-
568
- // WhatsApp link for ecommerce support
569
- const waLink = createWhatsAppLink("0300 123 4567", "Assalamualaikum");
570
-
571
- // IBAN validation for fintech checkout
572
- const ibanValid = validateIBAN("PK36SCBL0000001123456702");
573
- const bank = getBankFromIBAN("PK36SCBL0000001123456702");
574
-
575
- // Postal lookup for shipping forms
576
- const postal = getPostalCode("Multan");
577
- const city = getCityByPostalCode("60000");
578
-
579
- // Province lookup
580
- const province = getProvince("Lahore");
581
-
582
- // Formatting
583
- const amount = formatPKR(150000);
584
- const budget = formatLakh(2500000);
585
- ```
586
-
587
- ---
588
-
589
- # Playground
590
-
591
- 🚧 Interactive Playground Coming Soon
592
-
593
- The PakDataKit Playground will provide:
594
-
595
- * Live CNIC validation
596
- * Phone number analysis
597
- * Network detection
598
- * City lookups
599
- * PKR formatting tools
600
-
601
- ---
602
-
603
- # Roadmap
604
-
605
- ### v0.2 ✅
606
-
607
- * Phone Intelligence (`analyzePhone`)
608
- * WhatsApp Link Generator
609
- * IBAN Validation
610
- * Bank Detection from IBAN
611
- * Postal Code Lookup
612
- * Expanded datasets (150 cities, 171 districts, 109 postal codes, 46 banks)
613
-
614
- ### v0.3 ✅
615
-
616
- * Address Parsing (`parseAddress`, `formatAddress`)
617
- * Expanded Postal Data (`getPostalAreas`, `searchPostalCodes`)
618
-
619
- ### v0.4 ✅
620
-
621
- * Roman Urdu Utilities (`normalizeRomanUrdu`)
622
- * Text Normalization (`normalizeText`, `toUrduDigits`, `toEnglishDigits`)
623
-
624
- ### v0.5 ✅
625
-
626
- * Islamic Calendar Utilities (`toHijri`, `fromHijri`, `formatHijri`)
627
- * Hijri Date Helpers (`getHijriMonthName`, `isRamadan`)
628
-
629
- ### v1.0 ✅
630
-
631
- * CLI Tool (`pakdatakit` command)
632
- * Dataset-backed lookup APIs
633
- * Community Contributions (see CONTRIBUTING.md)
634
-
635
- ### v1.1+
636
-
637
- * Interactive Playground
638
- * CNIC checksum validation
639
- * Mobile Number Portability lookup API
640
-
641
- ---
642
-
643
- # Contributing
644
-
645
- Contributions are welcome.
646
-
647
- Ideas, bug reports, improvements, and pull requests help make PakDataKit better for everyone.
648
-
649
- Let's build the standard toolkit for Pakistani developers 🇵🇰
650
-
651
- See:
652
-
653
- * CONTRIBUTING.md
654
- * CODE_OF_CONDUCT.md
655
-
656
- ---
657
-
658
- # License
659
-
660
- MIT License
661
-
662
- ---
663
-
664
- <p align="center">
665
- Built with ❤️ for Pakistani Developers 🇵🇰
666
- </p>
1
+ <p align="center">
2
+ <img src="./banner.png" alt="PakDataKit Banner" />
3
+ </p>
4
+
5
+ <h1 align="center">🇵🇰 PakDataKit</h1>
6
+
7
+ <p align="center">
8
+ <strong>The Standard Utility Toolkit for Pakistani Developers</strong>
9
+ </p>
10
+
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.
13
+ </p>
14
+
15
+ <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
+ </p>
28
+
29
+ ---
30
+
31
+ ## 🌐 Playground
32
+
33
+ Try PakDataKit in your browser, no installation needed:
34
+
35
+ 👉 **[pakdatakit-playground.vercel.app](https://pakdatakit-playground.vercel.app/)**
36
+
37
+ 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.
38
+
39
+ ---
40
+
41
+ ## Why PakDataKit?
42
+
43
+ Every Pakistani application eventually needs to solve the same problems:
44
+
45
+ - Validate CNIC numbers
46
+ - Normalize mobile numbers
47
+ - Detect mobile networks
48
+ - Generate WhatsApp click-to-chat links
49
+ - Validate Pakistani IBANs and detect banks
50
+ - Look up postal codes and cities
51
+ - Map cities to provinces
52
+ - Format PKR values in Lakh and Crore conventions
53
+
54
+ Most teams implement these repeatedly.
55
+
56
+ PakDataKit provides a single, typed, reusable solution so you can focus on building your product instead of rebuilding common utilities.
57
+
58
+ ---
59
+
60
+ ## Features
61
+
62
+ - ✅ CNIC Validation
63
+ - ✅ CNIC Province & Gender Decoding
64
+ - ✅ Phone Number Validation
65
+ - ✅ Phone Number Normalization
66
+ - ✅ Phone Intelligence (`analyzePhone`)
67
+ - ✅ WhatsApp Link Generator
68
+ - ✅ IBAN Validation
69
+ - ✅ Bank Detection from IBAN
70
+ - ✅ Postal Code Lookup
71
+ - ✅ Address Parsing
72
+ - ✅ Roman Urdu Normalization
73
+ - ✅ Hijri Date Utilities
74
+ - ✅ CLI Tool
75
+ - ✅ Mobile Network Detection
76
+ - ✅ City → Province Lookup
77
+ - ✅ PKR Formatting
78
+ - ✅ Lakh / Crore Formatting
79
+ - ✅ Amounts in Words (English & Urdu, cheque style)
80
+ - ✅ Zod, Valibot & Yup Form Validation
81
+ - ✅ NTN & STRN Validation
82
+ - ✅ Landline, UAN (111), Toll-Free (0800) & Premium (0900) Numbers
83
+ - ✅ Raast QR Codes (SBP standard)
84
+ - ✅ Pakistan Public Holidays (moon-sighting aware)
85
+
86
+ ### Developer Friendly
87
+
88
+ - Fully Typed (TypeScript)
89
+ - Zero Runtime Dependencies (form libraries are optional peers)
90
+ - Tree-Shakeable
91
+ - Lightweight & Fast
92
+ - ESM and CommonJS, with per-module subpath imports
93
+ - Production Ready
94
+
95
+ ---
96
+
97
+ ## Installation
98
+
99
+ ```bash
100
+ npm install pakdatakit
101
+ ```
102
+
103
+ Requirements:
104
+
105
+ - Node.js 20+
106
+ - Works with both `import` and `require()`
107
+
108
+ Import everything from `pakdatakit`, or a single module to keep bundles small:
109
+
110
+ ```ts
111
+ import { validateCNIC } from 'pakdatakit/cnic';
112
+ const { analyzePhone } = require('pakdatakit/phone');
113
+ ```
114
+
115
+ Subpaths: `address`, `cnic`, `format`, `geo`, `hijri`, `holidays`, `iban`, `networks`, `numbers`, `phone`, `postal`, `raast`, `tax`, `text`, `whatsapp`, `words`, plus the form adapters `zod`, `valibot` and `yup`.
116
+
117
+ ---
118
+
119
+ ## Quick Start
120
+
121
+ ```ts
122
+ import {
123
+ validateCNIC,
124
+ analyzePhone,
125
+ createWhatsAppLink,
126
+ validateIBAN,
127
+ getBankFromIBAN,
128
+ getPostalCode,
129
+ getCityByPostalCode,
130
+ getNetwork,
131
+ formatLakh,
132
+ } from 'pakdatakit';
133
+
134
+ validateCNIC('35202-1234567-1');
135
+ // true
136
+
137
+ analyzePhone('03001234567');
138
+ // { valid: true, formatted: "+923001234567", network: "Jazz" }
139
+
140
+ createWhatsAppLink('03001234567', 'Assalamualaikum');
141
+ // "https://wa.me/923001234567?text=Assalamualaikum"
142
+
143
+ validateIBAN('PK36SCBL0000001123456702');
144
+ // true
145
+
146
+ getBankFromIBAN('PK36SCBL0000001123456702');
147
+ // "Standard Chartered Bank (Pakistan) Limited"
148
+
149
+ getPostalCode('Multan');
150
+ // "60000"
151
+
152
+ getCityByPostalCode('60000');
153
+ // "Multan"
154
+
155
+ getNetwork('03001234567');
156
+ // "Jazz"
157
+
158
+ formatLakh(2500000);
159
+ // "25 Lakh"
160
+ ```
161
+
162
+ ### CLI
163
+
164
+ ```bash
165
+ npx pakdatakit validate-cnic 35202-1234567-1
166
+ npx pakdatakit analyze-phone 03001234567
167
+ npx pakdatakit parse-address "House 12, Gulberg III, Lahore, Punjab 54660"
168
+ npx pakdatakit hijri
169
+ npx pakdatakit normalize-urdu "ap kia ker rhe ho"
170
+ ```
171
+
172
+ 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.
173
+
174
+ ---
175
+
176
+ # API Reference
177
+
178
+ ## CNIC
179
+
180
+ ### validateCNIC()
181
+
182
+ Validates Pakistani CNIC numbers.
183
+
184
+ ```ts
185
+ validateCNIC(cnic: string): boolean
186
+ ```
187
+
188
+ Examples:
189
+
190
+ ```ts
191
+ validateCNIC('3520212345671');
192
+ // true
193
+
194
+ validateCNIC('35202-1234567-1');
195
+ // true
196
+
197
+ validateCNIC('35202-123456-1');
198
+ // false
199
+ ```
200
+
201
+ Supports:
202
+
203
+ - Plain format
204
+ - Dashed format (hyphens or en-dashes)
205
+ - Space- or dot-separated format
206
+ - Urdu digits
207
+
208
+ Separators must sit between the 5-7-1 digit groups, and the first digit must be a province code (1–8). NADRA does not publish a check-digit algorithm, so this checks structure only.
209
+
210
+ ### getCNICInfo()
211
+
212
+ Reads the province of registration and gender encoded in a CNIC.
213
+
214
+ ```ts
215
+ getCNICInfo(cnic: string): CNICInfo | null
216
+ ```
217
+
218
+ ```ts
219
+ getCNICInfo('35202-1234567-1');
220
+ // { digits: "3520212345671", formatted: "35202-1234567-1", province: "Punjab", gender: "male" }
221
+
222
+ getCNICInfo('invalid');
223
+ // null
224
+ ```
225
+
226
+ The first digit is the province where the CNIC was first registered, which is not necessarily where the holder lives now. The last digit is odd for male and even for female.
227
+
228
+ ---
229
+
230
+ ## Phone Utilities
231
+
232
+ ### validatePhone()
233
+
234
+ Validates Pakistani mobile numbers. Accepts `03…`, `+92…`, `0092…`, `+92 (0) 3…` and short `3…` forms with spaces, dashes, dots or Urdu digits. The `03XX` prefix must belong to a mobile operator.
235
+
236
+ ```ts
237
+ validatePhone(phone: string): boolean
238
+ ```
239
+
240
+ Examples:
241
+
242
+ ```ts
243
+ validatePhone('03001234567');
244
+ // true
245
+
246
+ validatePhone('+923001234567');
247
+ // true
248
+
249
+ validatePhone('3001234567');
250
+ // true
251
+ ```
252
+
253
+ ---
254
+
255
+ ### formatPhone()
256
+
257
+ Converts valid Pakistani mobile numbers to E.164 format.
258
+
259
+ ```ts
260
+ formatPhone(phone: string): string | null
261
+ ```
262
+
263
+ Examples:
264
+
265
+ ```ts
266
+ formatPhone('03001234567');
267
+ // "+923001234567"
268
+
269
+ formatPhone('+92 300-123-4567');
270
+ // "+923001234567"
271
+
272
+ formatPhone('03601234567');
273
+ // null (unallocated prefix)
274
+ ```
275
+
276
+ ---
277
+
278
+ ### analyzePhone()
279
+
280
+ Runs validation, formatting, and network detection in one call.
281
+
282
+ ```ts
283
+ analyzePhone(phone: string): PhoneAnalysis
284
+ ```
285
+
286
+ Returns:
287
+
288
+ ```ts
289
+ {
290
+ valid: boolean;
291
+ formatted: string | null;
292
+ network: 'Jazz' | 'Zong' | 'Telenor' | 'Ufone' | 'SCO' | 'Unknown';
293
+ }
294
+ ```
295
+
296
+ Examples:
297
+
298
+ ```ts
299
+ analyzePhone('03001234567');
300
+ // { valid: true, formatted: "+923001234567", network: "Jazz" }
301
+
302
+ analyzePhone('invalid');
303
+ // { valid: false, formatted: null, network: "Unknown" }
304
+ ```
305
+
306
+ ---
307
+
308
+ ## WhatsApp Utilities
309
+
310
+ ### createWhatsAppLink()
311
+
312
+ Generates a WhatsApp click-to-chat link for Pakistani mobile numbers.
313
+
314
+ ```ts
315
+ createWhatsAppLink(phone: string, message?: string): string | null
316
+ ```
317
+
318
+ Examples:
319
+
320
+ ```ts
321
+ createWhatsAppLink('03001234567');
322
+ // "https://wa.me/923001234567"
323
+
324
+ createWhatsAppLink('03001234567', 'Assalamualaikum');
325
+ // "https://wa.me/923001234567?text=Assalamualaikum"
326
+ ```
327
+
328
+ Returns `null` for invalid phone numbers.
329
+
330
+ ---
331
+
332
+ ## IBAN Utilities
333
+
334
+ ### validateIBAN()
335
+
336
+ Validates Pakistani IBANs using format and ISO 13616 mod-97 checksum.
337
+
338
+ ```ts
339
+ validateIBAN(iban: string): boolean
340
+ ```
341
+
342
+ Examples:
343
+
344
+ ```ts
345
+ validateIBAN('PK36SCBL0000001123456702');
346
+ // true
347
+
348
+ validateIBAN('PK37SCBL0000001123456702');
349
+ // false
350
+ ```
351
+
352
+ ---
353
+
354
+ ### getBankFromIBAN()
355
+
356
+ Returns the bank name from a valid Pakistani IBAN's 4-letter bank code.
357
+
358
+ ```ts
359
+ getBankFromIBAN(iban: string): string | null
360
+ ```
361
+
362
+ Examples:
363
+
364
+ ```ts
365
+ getBankFromIBAN('PK36SCBL0000001123456702');
366
+ // "Standard Chartered Bank (Pakistan) Limited"
367
+
368
+ getBankFromIBAN('invalid');
369
+ // null
370
+ ```
371
+
372
+ Supported bank codes include HABB, MEZN, SCBL, UNIL, BAHL, NBPA, MUCB, JSBL, SADA (SadaPay), and 44 total entries in the dataset. Merged or renamed banks are labelled with their current name, e.g. `SAUD` → "Silkbank Limited (merged into United Bank Limited)".
373
+
374
+ ---
375
+
376
+ ## Postal Code Utilities
377
+
378
+ ### getCityByPostalCode()
379
+
380
+ Returns the city for a Pakistani postal code.
381
+
382
+ ```ts
383
+ getCityByPostalCode(postalCode: string): string | null
384
+ ```
385
+
386
+ Examples:
387
+
388
+ ```ts
389
+ getCityByPostalCode('60000');
390
+ // "Multan"
391
+
392
+ getCityByPostalCode('99999');
393
+ // null
394
+ ```
395
+
396
+ ---
397
+
398
+ ### getPostalCode()
399
+
400
+ Returns the primary postal code for a Pakistani city (case-insensitive).
401
+
402
+ ```ts
403
+ getPostalCode(city: string): string | null
404
+ ```
405
+
406
+ Examples:
407
+
408
+ ```ts
409
+ getPostalCode('Multan');
410
+ // "60000"
411
+
412
+ getPostalCode('karachi');
413
+ // "74200"
414
+ ```
415
+
416
+ ---
417
+
418
+ ## Mobile Networks
419
+
420
+ ### getNetwork()
421
+
422
+ Detects network using the original mobile prefix.
423
+
424
+ ```ts
425
+ getNetwork(phone: string): NetworkName
426
+ ```
427
+
428
+ Returns:
429
+
430
+ - Jazz
431
+ - Zong
432
+ - Ufone
433
+ - Telenor
434
+ - SCO (0355, AJK and Gilgit-Baltistan)
435
+ - Unknown
436
+
437
+ Examples:
438
+
439
+ ```ts
440
+ getNetwork('03001234567');
441
+ // Jazz
442
+
443
+ getNetwork('03151234567');
444
+ // Zong
445
+
446
+ getNetwork('03331234567');
447
+ // Ufone
448
+
449
+ getNetwork('03451234567');
450
+ // Telenor
451
+ ```
452
+
453
+ > Note: This is the operator the prefix was originally allocated to. With Mobile Number Portability (MNP), and Telenor Pakistan's 2026 merger into PTML (Ufone), the current carrier may differ.
454
+
455
+ ---
456
+
457
+ ## Landline, UAN & Service Numbers
458
+
459
+ ### analyzeNumber() / getNumberType() / validateLandline() / getAreaCode()
460
+
461
+ Identifies any Pakistani number: mobile, landline, UAN (`111`), toll-free (`0800`), premium-rate (`0900`) or personal (`0122`). Uses the same number patterns as Google's libphonenumber, plus PTCL's area-code list.
462
+
463
+ ```ts
464
+ analyzeNumber('021-111-825-888');
465
+ // { type: 'uan', formatted: '021-111-825-888', e164: '+9221111825888', areaCode: '021', cities: ['Karachi'] }
466
+
467
+ analyzeNumber('042 35761234');
468
+ // { type: 'landline', formatted: '042-35761234', e164: '+924235761234', areaCode: '042', cities: ['Lahore'] }
469
+
470
+ getNumberType('0800-12345'); // 'toll-free'
471
+ validateLandline('051-9260138'); // true
472
+ getAreaCode('Mardan'); // '0937'
473
+ ```
474
+
475
+ ---
476
+
477
+ ## Geography
478
+
479
+ ### getProvince()
480
+
481
+ Returns province for a city.
482
+
483
+ ```ts
484
+ getProvince(city: string): string | null
485
+ ```
486
+
487
+ Examples:
488
+
489
+ ```ts
490
+ getProvince('Multan');
491
+ // Punjab
492
+
493
+ getProvince('Karachi');
494
+ // Sindh
495
+
496
+ getProvince('Unknown');
497
+ // null
498
+ ```
499
+
500
+ ---
501
+
502
+ ### searchCities()
503
+
504
+ Case-insensitive city search.
505
+
506
+ ```ts
507
+ searchCities(query: string): string[]
508
+ ```
509
+
510
+ Examples:
511
+
512
+ ```ts
513
+ searchCities('mul');
514
+ // ["Multan"]
515
+
516
+ searchCities('kar');
517
+ // ["Karachi"]
518
+ ```
519
+
520
+ ---
521
+
522
+ ### getDistrictProvince() / searchDistricts()
523
+
524
+ District-level geography lookup across 168 districts.
525
+
526
+ ```ts
527
+ getDistrictProvince('Lahore'); // "Punjab"
528
+ searchDistricts('karachi'); // ["Karachi Central", "Karachi East", ...]
529
+ ```
530
+
531
+ ---
532
+
533
+ ## Address Utilities
534
+
535
+ ### parseAddress()
536
+
537
+ Parses free-form Pakistani addresses into structured components.
538
+
539
+ ```ts
540
+ parseAddress('House 12, Gulberg III, Lahore, Punjab 54660');
541
+ // { street: "House 12", area: "Gulberg III", city: "Lahore", province: "Punjab", postalCode: "54660", warnings: [], ... }
542
+
543
+ parseAddress('12 Model Town Lahore');
544
+ // { street: "12 Model Town", city: "Lahore", province: "Punjab", ... }
545
+
546
+ parseAddress('House 1, Lahore, Sindh').warnings;
547
+ // ["Lahore is in Punjab, but the address says Sindh"]
548
+ ```
549
+
550
+ House, plot, street and PO box numbers are not mistaken for postal codes.
551
+
552
+ ### formatAddress()
553
+
554
+ Formats structured components back into a mailing address string. Only the components you pass are included.
555
+
556
+ ---
557
+
558
+ ## Text Utilities
559
+
560
+ ### normalizeRomanUrdu()
561
+
562
+ Normalizes informal Roman Urdu spellings (`ap kia ker` → `aap kya kar`).
563
+
564
+ ### toUrduDigits() / toEnglishDigits()
565
+
566
+ Convert between English, Urdu, and Arabic-Indic digits.
567
+
568
+ ---
569
+
570
+ ## Hijri Calendar
571
+
572
+ ### toHijri() / formatHijri() / isRamadan()
573
+
574
+ ```ts
575
+ formatHijri(new Date(2025, 5, 7)); // "10 Dhu al-Hijjah 1446"
576
+ isRamadan(new Date()); // true | false
577
+
578
+ // Shift by whole days to match local moon sighting
579
+ formatHijri(new Date(2025, 5, 7), { offset: -1 }); // "9 Dhu al-Hijjah 1446"
580
+ ```
581
+
582
+ Uses the tabular ("islamic-civil") calendar. Dates announced in Pakistan follow moon sighting and can differ by a day; use `offset` to adjust. Invalid dates throw a `RangeError`.
583
+
584
+ ---
585
+
586
+ ## Currency Formatting
587
+
588
+ ### formatPKR()
589
+
590
+ Formats PKR amounts with separators, rounded to whole rupees. Negative amounts keep their sign; `NaN` and `Infinity` throw a `RangeError`.
591
+
592
+ ```ts
593
+ formatPKR(amount: number): string
594
+ ```
595
+
596
+ Examples:
597
+
598
+ ```ts
599
+ formatPKR(150000);
600
+ // "Rs. 150,000"
601
+
602
+ formatPKR(0);
603
+ // "Rs. 0"
604
+
605
+ formatPKR(-1500);
606
+ // "-Rs. 1,500"
607
+ ```
608
+
609
+ ---
610
+
611
+ ### formatLakh()
612
+
613
+ Formats values using Pakistan's Lakh / Crore numbering system.
614
+
615
+ ```ts
616
+ formatLakh(amount: number): string
617
+ ```
618
+
619
+ Examples:
620
+
621
+ ```ts
622
+ formatLakh(2500000);
623
+ // "25 Lakh"
624
+
625
+ formatLakh(10000000);
626
+ // "1 Crore"
627
+
628
+ formatLakh(50000);
629
+ // "Rs. 50,000"
630
+ ```
631
+
632
+ ---
633
+
634
+ ## Amounts in Words
635
+
636
+ ### amountInWords() / numberToWords()
637
+
638
+ Writes numbers and rupee amounts in words using the Pakistani scale (hundred, thousand, lakh, crore, arab, kharab), in English or Urdu. Useful for cheques, invoices and receipts.
639
+
640
+ ```ts
641
+ amountInWords(amount: number, options?: { language?: "en" | "ur"; cheque?: boolean }): string
642
+ numberToWords(n: number, options?: { language?: "en" | "ur" }): string
643
+ ```
644
+
645
+ ```ts
646
+ amountInWords(125000.5);
647
+ // "one lakh twenty-five thousand rupees and fifty paisa"
648
+
649
+ amountInWords(125000, { cheque: true });
650
+ // "Rupees One Lakh Twenty-Five Thousand Only"
651
+
652
+ amountInWords(125000, { language: 'ur' });
653
+ // "ایک لاکھ پچیس ہزار روپے"
654
+
655
+ amountInWords(500.5, { language: 'ur', cheque: true });
656
+ // "پانچ سو روپے اور پچاس پیسے صرف"
657
+
658
+ numberToWords(12_34_56_789);
659
+ // "twelve crore thirty-four lakh fifty-six thousand seven hundred eighty-nine"
660
+ ```
661
+
662
+ Amounts are rounded to the nearest paisa. Negative or non-finite amounts throw a `RangeError`.
663
+
664
+ ---
665
+
666
+ ## Tax Numbers
667
+
668
+ ### analyzeNTN() / validateNTN() / validateSTRN()
669
+
670
+ Validates FBR tax numbers. Individuals use their CNIC as their NTN; companies and AOPs have a 7-digit NTN, often written with a check digit as `1234567-8`. STRNs are 13 digits.
671
+
672
+ ```ts
673
+ analyzeNTN('0622438-9');
674
+ // { type: 'business', digits: '06224389', formatted: '0622438-9' }
675
+
676
+ analyzeNTN('3520212345671');
677
+ // { type: 'individual', digits: '3520212345671', formatted: '35202-1234567-1' }
678
+
679
+ validateSTRN('17-00-3761-882-19'); // true
680
+ ```
681
+
682
+ FBR does not publish its check-digit algorithms, so these check the format only.
683
+
684
+ ---
685
+
686
+ ## Raast QR Codes
687
+
688
+ ### createRaastP2PQr() / createMerchantQr() / parseRaastQr()
689
+
690
+ Builds and reads payment QR codes following the State Bank of Pakistan's QR standard (Circular Letter No. 1 of 2022). Turn the returned string into an image with any QR library.
691
+
692
+ ```ts
693
+ // Person-to-person: anyone can pay this IBAN through Raast
694
+ const payload = createRaastP2PQr({
695
+ iban: 'PK36SCBL0000001123456702',
696
+ amount: 1500,
697
+ });
698
+
699
+ parseRaastQr(payload);
700
+ // { kind: 'p2p', dynamic: true, crcValid: true, iban: 'PK36SCBL0000001123456702', amount: 1500, ... }
701
+
702
+ // Merchant QR (EMVCo), with Pakistan-specific bill due dates
703
+ createMerchantQr({
704
+ merchantAccount: {
705
+ tag: '28',
706
+ fields: {
707
+ /* sub-fields from your bank */
708
+ },
709
+ },
710
+ merchantName: 'Aziz General Store',
711
+ city: 'Karachi',
712
+ amount: 4250,
713
+ billNumber: 'INV-1001',
714
+ dueDate: new Date(2026, 10, 25),
715
+ amountAfterDueDate: 4500,
716
+ });
717
+ ```
718
+
719
+ Person-to-person QR codes use the same layout as QR codes from banking apps (Faysal Bank, easypaisa), and scan in the Easypaisa and JazzCash apps. This is handy for accounts whose app cannot generate a receiving QR, such as SadaPay.
720
+
721
+ SBP reserves merchant-account tags 28–30 for Raast but has shared the layout of the fields inside them only with banks, so `createMerchantQr` takes those sub-fields from you. `parseRaastQr` checks the CRC and finds the IBAN in either kind of QR.
722
+
723
+ ---
724
+
725
+ ## Public Holidays
726
+
727
+ ### getPakistanHolidays() / isPakistanHoliday() / getHolidaysOn()
728
+
729
+ Lists Pakistan's federal public holidays. Eid, Ashura and Milad use the dates actually observed after moon sighting (2020 onwards, from Cabinet Division and SBP notices), not a calculation.
730
+
731
+ ```ts
732
+ getPakistanHolidays(2025).filter((h) => h.id === 'eid-ul-fitr');
733
+ // [{ name: 'Eid ul Fitr', date: '2025-03-31', estimated: false, source: 'https://…' }, … '2025-04-01', '2025-04-02']
734
+
735
+ isPakistanHoliday('2026-08-14'); // true (Independence Day)
736
+
737
+ // Future years are estimated and flagged; apply the official announcement when it comes
738
+ getPakistanHolidays(2027, {
739
+ announced: { 'eid-ul-fitr': ['2027-03-10', '2027-03-11', '2027-03-12'] },
740
+ });
741
+ ```
742
+
743
+ Fixed holidays follow the year they applied in: Iqbal Day was restored in 2022 and Youm-e-Takbeer added in 2024. Pass `includeChristianHolidays: true` for 26 December. Optional holidays such as Shab-e-Barat and Easter are not included.
744
+
745
+ ---
746
+
747
+ ## Form Validation
748
+
749
+ Ready-made schemas for [Zod](https://zod.dev), [Valibot](https://valibot.dev) and [Yup](https://github.com/jquense/yup). Install the library you use; PakDataKit does not depend on any of them.
750
+
751
+ ```ts
752
+ import { z } from 'zod';
753
+ import { pk } from 'pakdatakit/zod';
754
+
755
+ const CheckoutForm = z.object({
756
+ cnic: pk.cnic(),
757
+ phone: pk.phone(),
758
+ iban: pk.iban({ message: 'Please enter a valid IBAN' }),
759
+ });
760
+ ```
761
+
762
+ ```ts
763
+ import * as v from 'valibot';
764
+ import { pk } from 'pakdatakit/valibot';
765
+
766
+ const CheckoutForm = v.object({ cnic: pk.cnic(), phone: pk.phone() });
767
+ ```
768
+
769
+ ```ts
770
+ import { object } from 'yup';
771
+ import { pk } from 'pakdatakit/yup';
772
+
773
+ const CheckoutForm = object({ cnic: pk.cnic().required(), phone: pk.phone() });
774
+ ```
775
+
776
+ Available schemas: `pk.cnic()`, `pk.phone()`, `pk.iban()`, `pk.ntn()`, `pk.strn()` and `pk.landline()`. Every factory accepts `{ message }` to replace the default error. The Yup schemas let empty values pass so `.required()` decides whether a field is mandatory.
777
+
778
+ ---
779
+
780
+ # Real-World Example
781
+
782
+ ```ts
783
+ import {
784
+ validateCNIC,
785
+ validatePhone,
786
+ formatPhone,
787
+ analyzePhone,
788
+ createWhatsAppLink,
789
+ validateIBAN,
790
+ getBankFromIBAN,
791
+ getPostalCode,
792
+ getCityByPostalCode,
793
+ getNetwork,
794
+ getProvince,
795
+ searchCities,
796
+ formatPKR,
797
+ formatLakh,
798
+ } from 'pakdatakit';
799
+
800
+ // CNIC validation
801
+ const cnicValid = validateCNIC('35202-1234567-1');
802
+
803
+ // Phone intelligence
804
+ const phoneInfo = analyzePhone('03001234567');
805
+
806
+ // WhatsApp link for ecommerce support
807
+ const waLink = createWhatsAppLink('0300 123 4567', 'Assalamualaikum');
808
+
809
+ // IBAN validation for fintech checkout
810
+ const ibanValid = validateIBAN('PK36SCBL0000001123456702');
811
+ const bank = getBankFromIBAN('PK36SCBL0000001123456702');
812
+
813
+ // Postal lookup for shipping forms
814
+ const postal = getPostalCode('Multan');
815
+ const city = getCityByPostalCode('60000');
816
+
817
+ // Province lookup
818
+ const province = getProvince('Lahore');
819
+
820
+ // Formatting
821
+ const amount = formatPKR(150000);
822
+ const budget = formatLakh(2500000);
823
+ ```
824
+
825
+ ---
826
+
827
+ # Roadmap
828
+
829
+ ### v0.2 ✅
830
+
831
+ - Phone Intelligence (`analyzePhone`)
832
+ - WhatsApp Link Generator
833
+ - IBAN Validation
834
+ - Bank Detection from IBAN
835
+ - Postal Code Lookup
836
+ - Expanded datasets (cities, districts, postal codes, banks)
837
+
838
+ ### v0.3 ✅
839
+
840
+ - Address Parsing (`parseAddress`, `formatAddress`)
841
+ - Expanded Postal Data (`getPostalAreas`, `searchPostalCodes`)
842
+
843
+ ### v0.4 ✅
844
+
845
+ - Roman Urdu Utilities (`normalizeRomanUrdu`)
846
+ - Text Normalization (`normalizeText`, `toUrduDigits`, `toEnglishDigits`)
847
+
848
+ ### v0.5 ✅
849
+
850
+ - Islamic Calendar Utilities (`toHijri`, `fromHijri`, `formatHijri`)
851
+ - Hijri Date Helpers (`getHijriMonthName`, `isRamadan`)
852
+
853
+ ### v1.0 ✅
854
+
855
+ - CLI Tool (`pakdatakit` command)
856
+ - Dataset-backed lookup APIs
857
+ - Community Contributions (see CONTRIBUTING.md)
858
+
859
+ ### v1.1 ✅
860
+
861
+ - Interactive Playground ([pakdatakit-playground.vercel.app](https://pakdatakit-playground.vercel.app/))
862
+
863
+ ### v2.0 ✅
864
+
865
+ - Bug-fix release; see [CHANGELOG.md](./CHANGELOG.md) for breaking changes
866
+ - CommonJS build and subpath imports
867
+ - Corrected Hijri dates, datasets and validation
868
+
869
+ ### v2.1 ✅
870
+
871
+ - CNIC province & gender decoding (`getCNICInfo`)
872
+ - Amounts in words in English and Urdu (`amountInWords`, `numberToWords`)
873
+ - Zod, Valibot and Yup adapters
874
+ - NTN and STRN validation
875
+ - Landline, UAN, toll-free and premium numbers
876
+ - Raast QR codes
877
+ - Public holidays with observed moon-sighting dates
878
+
879
+ ### Planned
880
+
881
+ - CNIC check-digit validation (pending a publicly documented NADRA algorithm)
882
+ - Mobile Number Portability lookup API
883
+
884
+ ---
885
+
886
+ # Contributing
887
+
888
+ Contributions are welcome.
889
+
890
+ Ideas, bug reports, improvements, and pull requests help make PakDataKit better for everyone.
891
+
892
+ Let's build the standard toolkit for Pakistani developers 🇵🇰
893
+
894
+ See:
895
+
896
+ - CONTRIBUTING.md
897
+ - CODE_OF_CONDUCT.md
898
+
899
+ ---
900
+
901
+ # License
902
+
903
+ MIT License
904
+
905
+ ---
906
+
907
+ <p align="center">
908
+ Built with ❤️ for Pakistani Developers 🇵🇰
909
+ </p>