pakdatakit 1.0.0 → 1.1.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
@@ -1,18 +1,78 @@
1
- # PakDataKit
1
+ <p align="center">
2
+ <img src="./banner.png" alt="PakDataKit Banner" />
3
+ </p>
2
4
 
3
- **PakDataKit** is a production-ready, open-source TypeScript utility library built for Pakistani developers. It provides reliable, typed, and reusable helpers for CNIC validation, phone normalization, mobile network detection, city-to-province lookup, and PKR formatting.
5
+ <h1 align="center">🇵🇰 PakDataKit</h1>
4
6
 
5
- ## Why PakDataKit?
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>
6
14
 
7
- Pakistani applications repeatedly solve the same data problems:
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>
8
25
 
9
- - Validating CNIC numbers in multiple input formats
10
- - Normalizing mobile numbers between `03XX`, `3XX`, and `+92` forms
11
- - Detecting mobile networks from number prefixes
12
- - Mapping cities to provinces for forms and analytics
13
- - Displaying amounts in PKR, Lakh, and Crore conventions
26
+ ---
27
+
28
+ ## Why PakDataKit?
14
29
 
15
- PakDataKit centralizes these utilities so you can ship faster with confidence.
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
+ ---
16
76
 
17
77
  ## Installation
18
78
 
@@ -20,154 +80,587 @@ PakDataKit centralizes these utilities so you can ship faster with confidence.
20
80
  npm install pakdatakit
21
81
  ```
22
82
 
23
- Requires Node.js 18+ and ESM.
83
+ Requirements:
84
+
85
+ * Node.js 18+
86
+ * ESM support
87
+
88
+ ---
24
89
 
25
90
  ## Quick Start
26
91
 
27
92
  ```ts
28
- import { validateCNIC, getNetwork, formatLakh } from 'pakdatakit';
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:
29
308
 
30
- validateCNIC('35202-1234567-1'); // true
31
- getNetwork('03001234567'); // "Jazz"
32
- formatLakh(2500000); // "25 Lakh"
309
+ ```ts
310
+ getBankFromIBAN("PK36SCBL0000001123456702");
311
+ // "Standard Chartered Bank (Pakistan) Limited"
312
+
313
+ getBankFromIBAN("invalid");
314
+ // null
33
315
  ```
34
316
 
35
- ## API Reference
317
+ Supported bank codes include HABB, MEZN, SCBL, UNIL, BAHL, NBPA, MUCB, JSBL, and 46 total entries in the dataset.
318
+
319
+ ---
36
320
 
37
- ### CNIC
321
+ ## Postal Code Utilities
38
322
 
39
- #### `validateCNIC(cnic: string): boolean`
323
+ ### getCityByPostalCode()
40
324
 
41
- Validates a Pakistani CNIC (13 digits). Accepts plain, dashed, or spaced formats. Strips separators before validation.
325
+ Returns the city for a Pakistani postal code.
42
326
 
43
327
  ```ts
44
- validateCNIC('3520212345671'); // true
45
- validateCNIC('35202-1234567-1'); // true
46
- validateCNIC('35202-123456-1'); // false
328
+ getCityByPostalCode(postalCode: string): string | null
47
329
  ```
48
330
 
49
- ### Phone
331
+ Examples:
50
332
 
51
- #### `validatePhone(phone: string): boolean`
333
+ ```ts
334
+ getCityByPostalCode("60000");
335
+ // "Multan"
336
+
337
+ getCityByPostalCode("99999");
338
+ // null
339
+ ```
340
+
341
+ ---
52
342
 
53
- Validates Pakistani mobile numbers in local, international, or short formats.
343
+ ### getPostalCode()
344
+
345
+ Returns the primary postal code for a Pakistani city (case-insensitive).
54
346
 
55
347
  ```ts
56
- validatePhone('03001234567'); // true
57
- validatePhone('+923001234567'); // true
58
- validatePhone('3001234567'); // true
348
+ getPostalCode(city: string): string | null
59
349
  ```
60
350
 
61
- #### `formatPhone(phone: string): string`
351
+ Examples:
62
352
 
63
- Normalizes a valid Pakistani mobile number to `+923XXXXXXXXX`. Returns an empty string for invalid input.
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.
64
368
 
65
369
  ```ts
66
- formatPhone('03001234567'); // "+923001234567"
67
- formatPhone('+92 300-123-4567'); // "+923001234567"
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"]
68
442
  ```
69
443
 
70
- ### Networks
444
+ ---
71
445
 
72
- #### `getNetwork(phone: string): NetworkName`
446
+ ### getDistrictProvince() / searchDistricts()
73
447
 
74
- Returns the mobile network based on the number prefix: `"Jazz"`, `"Zong"`, `"Telenor"`, `"Ufone"`, or `"Unknown"`.
448
+ District-level geography lookup across 171 districts.
75
449
 
76
450
  ```ts
77
- getNetwork('03001234567'); // "Jazz"
78
- getNetwork('03151234567'); // "Zong"
79
- getNetwork('03451234567'); // "Telenor"
80
- getNetwork('03331234567'); // "Ufone"
451
+ getDistrictProvince("Lahore"); // "Punjab"
452
+ searchDistricts("karachi"); // ["Karachi Central", "Karachi East", ...]
81
453
  ```
82
454
 
83
- > **Note:** Prefix-based detection reflects the **original issuing network**. Due to Mobile Number Portability (MNP) in Pakistan, the current carrier may differ from the prefix.
455
+ ---
84
456
 
85
- ### Geography
457
+ ## Address Utilities
86
458
 
87
- #### `getProvince(city: string): string | null`
459
+ ### parseAddress()
88
460
 
89
- Returns the province for an exact city name match (case-insensitive, whitespace-tolerant).
461
+ Parses free-form Pakistani addresses into structured components.
90
462
 
91
463
  ```ts
92
- getProvince('Multan'); // "Punjab"
93
- getProvince(' karachi '); // "Sindh"
94
- getProvince('Unknown'); // null
464
+ parseAddress("House 12, Gulberg III, Lahore, Punjab 54660");
465
+ // { street: "House 12", area: "Gulberg III", city: "Lahore", province: "Punjab", postalCode: "54660", ... }
95
466
  ```
96
467
 
97
- #### `searchCities(query: string): string[]`
468
+ ### formatAddress()
98
469
 
99
- Partial, case-insensitive city search. Returns alphabetically sorted city names.
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()
100
489
 
101
490
  ```ts
102
- searchCities('mul'); // ["Multan"]
103
- searchCities('kar'); // ["Karachi"]
491
+ formatHijri(new Date()); // "14 Ramadan 1447"
492
+ isRamadan(new Date()); // true | false
104
493
  ```
105
494
 
106
- ### Formatting
495
+ ---
107
496
 
108
- #### `formatPKR(amount: number): string`
497
+ ## Currency Formatting
109
498
 
110
- Formats an amount as Pakistani Rupees with comma separators.
499
+ ### formatPKR()
500
+
501
+ Formats PKR amounts with separators.
111
502
 
112
503
  ```ts
113
- formatPKR(150000); // "Rs. 150,000"
114
- formatPKR(0); // "Rs. 0"
504
+ formatPKR(amount: number): string
115
505
  ```
116
506
 
117
- #### `formatLakh(amount: number): string`
507
+ Examples:
508
+
509
+ ```ts
510
+ formatPKR(150000);
511
+ // "Rs. 150,000"
512
+
513
+ formatPKR(0);
514
+ // "Rs. 0"
515
+ ```
118
516
 
119
- Formats amounts using Lakh/Crore conventions.
517
+ ---
518
+
519
+ ### formatLakh()
520
+
521
+ Formats values using Pakistan's Lakh / Crore numbering system.
120
522
 
121
523
  ```ts
122
- formatLakh(2500000); // "25 Lakh"
123
- formatLakh(10000000); // "1 Crore"
124
- formatLakh(50000); // "Rs. 50,000"
524
+ formatLakh(amount: number): string
125
525
  ```
126
526
 
127
- ## Examples
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
128
543
 
129
544
  ```ts
130
545
  import {
131
546
  validateCNIC,
132
547
  validatePhone,
133
548
  formatPhone,
549
+ analyzePhone,
550
+ createWhatsAppLink,
551
+ validateIBAN,
552
+ getBankFromIBAN,
553
+ getPostalCode,
554
+ getCityByPostalCode,
134
555
  getNetwork,
135
556
  getProvince,
136
557
  searchCities,
137
558
  formatPKR,
138
- formatLakh,
139
- } from 'pakdatakit';
559
+ formatLakh
560
+ } from "pakdatakit";
140
561
 
141
562
  // CNIC validation
142
- const cnicValid = validateCNIC('35202-1234567-1');
563
+ const cnicValid = validateCNIC("35202-1234567-1");
143
564
 
144
- // Phone normalization
145
- const phone = formatPhone('0300 123 4567'); // "+923001234567"
146
- const isValid = validatePhone(phone);
565
+ // Phone intelligence
566
+ const phoneInfo = analyzePhone("03001234567");
147
567
 
148
- // Network lookup
149
- const network = getNetwork('03001234567'); // "Jazz"
568
+ // WhatsApp link for ecommerce support
569
+ const waLink = createWhatsAppLink("0300 123 4567", "Assalamualaikum");
150
570
 
151
- // City lookup
152
- const province = getProvince('Lahore'); // "Punjab"
153
- const cities = searchCities('fais'); // ["Faisalabad"]
571
+ // IBAN validation for fintech checkout
572
+ const ibanValid = validateIBAN("PK36SCBL0000001123456702");
573
+ const bank = getBankFromIBAN("PK36SCBL0000001123456702");
154
574
 
155
- // Currency formatting
156
- const price = formatPKR(150000); // "Rs. 150,000"
157
- const budget = formatLakh(2500000); // "25 Lakh"
158
- ```
575
+ // Postal lookup for shipping forms
576
+ const postal = getPostalCode("Multan");
577
+ const city = getCityByPostalCode("60000");
159
578
 
160
- ## Development
579
+ // Province lookup
580
+ const province = getProvince("Lahore");
161
581
 
162
- ```bash
163
- npm install
164
- npm test
165
- npm run build
166
- npm run lint
582
+ // Formatting
583
+ const amount = formatPKR(150000);
584
+ const budget = formatLakh(2500000);
167
585
  ```
168
586
 
169
- See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines.
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
170
661
 
171
- ## License
662
+ ---
172
663
 
173
- MIT — see [LICENSE](LICENSE).
664
+ <p align="center">
665
+ Built with ❤️ for Pakistani Developers 🇵🇰
666
+ </p>