pakdatakit 1.0.0 → 1.0.2

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,74 @@
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>
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
+ ---
4
27
 
5
28
  ## Why PakDataKit?
6
29
 
7
- Pakistani applications repeatedly solve the same data problems:
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.
8
42
 
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
43
+ PakDataKit provides a single, typed, reusable solution so you can focus on building your product instead of rebuilding common utilities.
14
44
 
15
- PakDataKit centralizes these utilities so you can ship faster with confidence.
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
+ ✅ Mobile Network Detection
58
+ ✅ City → Province Lookup
59
+ ✅ PKR Formatting
60
+ ✅ Lakh / Crore Formatting
61
+
62
+ ### Developer Friendly
63
+
64
+ * Fully Typed (TypeScript)
65
+ * Zero Runtime Dependencies
66
+ * Tree-Shakeable
67
+ * Lightweight & Fast
68
+ * ESM Ready
69
+ * Production Ready
70
+
71
+ ---
16
72
 
17
73
  ## Installation
18
74
 
@@ -20,154 +76,522 @@ PakDataKit centralizes these utilities so you can ship faster with confidence.
20
76
  npm install pakdatakit
21
77
  ```
22
78
 
23
- Requires Node.js 18+ and ESM.
79
+ Requirements:
80
+
81
+ * Node.js 18+
82
+ * ESM support
83
+
84
+ ---
24
85
 
25
86
  ## Quick Start
26
87
 
27
88
  ```ts
28
- import { validateCNIC, getNetwork, formatLakh } from 'pakdatakit';
89
+ import {
90
+ validateCNIC,
91
+ analyzePhone,
92
+ createWhatsAppLink,
93
+ validateIBAN,
94
+ getBankFromIBAN,
95
+ getPostalCode,
96
+ getCityByPostalCode,
97
+ getNetwork,
98
+ formatLakh
99
+ } from "pakdatakit";
100
+
101
+ validateCNIC("35202-1234567-1");
102
+ // true
103
+
104
+ analyzePhone("03001234567");
105
+ // { valid: true, formatted: "+923001234567", network: "Jazz" }
106
+
107
+ createWhatsAppLink("03001234567", "Assalamualaikum");
108
+ // "https://wa.me/923001234567?text=Assalamualaikum"
109
+
110
+ validateIBAN("PK36SCBL0000001123456702");
111
+ // true
112
+
113
+ getBankFromIBAN("PK36SCBL0000001123456702");
114
+ // "Standard Chartered Bank (Pakistan) Limited"
115
+
116
+ getPostalCode("Multan");
117
+ // "60000"
118
+
119
+ getCityByPostalCode("60000");
120
+ // "Multan"
121
+
122
+ getNetwork("03001234567");
123
+ // "Jazz"
124
+
125
+ formatLakh(2500000);
126
+ // "25 Lakh"
127
+ ```
128
+
129
+ ---
130
+
131
+ # API Reference
132
+
133
+ ## CNIC
134
+
135
+ ### validateCNIC()
136
+
137
+ Validates Pakistani CNIC numbers.
138
+
139
+ ```ts
140
+ validateCNIC(cnic: string): boolean
141
+ ```
142
+
143
+ Examples:
144
+
145
+ ```ts
146
+ validateCNIC("3520212345671");
147
+ // true
148
+
149
+ validateCNIC("35202-1234567-1");
150
+ // true
151
+
152
+ validateCNIC("35202-123456-1");
153
+ // false
154
+ ```
155
+
156
+ Supports:
157
+
158
+ * Plain format
159
+ * Dashed format
160
+ * Space-separated format
161
+
162
+ ---
163
+
164
+ ## Phone Utilities
165
+
166
+ ### validatePhone()
167
+
168
+ Validates Pakistani mobile numbers.
169
+
170
+ ```ts
171
+ validatePhone(phone: string): boolean
172
+ ```
173
+
174
+ Examples:
175
+
176
+ ```ts
177
+ validatePhone("03001234567");
178
+ // true
179
+
180
+ validatePhone("+923001234567");
181
+ // true
29
182
 
30
- validateCNIC('35202-1234567-1'); // true
31
- getNetwork('03001234567'); // "Jazz"
32
- formatLakh(2500000); // "25 Lakh"
183
+ validatePhone("3001234567");
184
+ // true
33
185
  ```
34
186
 
35
- ## API Reference
187
+ ---
36
188
 
37
- ### CNIC
189
+ ### formatPhone()
38
190
 
39
- #### `validateCNIC(cnic: string): boolean`
191
+ Converts valid Pakistani mobile numbers to E.164 format.
40
192
 
41
- Validates a Pakistani CNIC (13 digits). Accepts plain, dashed, or spaced formats. Strips separators before validation.
193
+ ```ts
194
+ formatPhone(phone: string): string
195
+ ```
196
+
197
+ Examples:
42
198
 
43
199
  ```ts
44
- validateCNIC('3520212345671'); // true
45
- validateCNIC('35202-1234567-1'); // true
46
- validateCNIC('35202-123456-1'); // false
200
+ formatPhone("03001234567");
201
+ // "+923001234567"
202
+
203
+ formatPhone("+92 300-123-4567");
204
+ // "+923001234567"
47
205
  ```
48
206
 
49
- ### Phone
207
+ ---
208
+
209
+ ---
50
210
 
51
- #### `validatePhone(phone: string): boolean`
211
+ ### analyzePhone()
52
212
 
53
- Validates Pakistani mobile numbers in local, international, or short formats.
213
+ Runs validation, formatting, and network detection in one call.
54
214
 
55
215
  ```ts
56
- validatePhone('03001234567'); // true
57
- validatePhone('+923001234567'); // true
58
- validatePhone('3001234567'); // true
216
+ analyzePhone(phone: string): PhoneAnalysis
59
217
  ```
60
218
 
61
- #### `formatPhone(phone: string): string`
219
+ Returns:
220
+
221
+ ```ts
222
+ {
223
+ valid: boolean;
224
+ formatted: string | null;
225
+ network: "Jazz" | "Zong" | "Telenor" | "Ufone" | "Unknown";
226
+ }
227
+ ```
62
228
 
63
- Normalizes a valid Pakistani mobile number to `+923XXXXXXXXX`. Returns an empty string for invalid input.
229
+ Examples:
64
230
 
65
231
  ```ts
66
- formatPhone('03001234567'); // "+923001234567"
67
- formatPhone('+92 300-123-4567'); // "+923001234567"
232
+ analyzePhone("03001234567");
233
+ // { valid: true, formatted: "+923001234567", network: "Jazz" }
234
+
235
+ analyzePhone("invalid");
236
+ // { valid: false, formatted: null, network: "Unknown" }
68
237
  ```
69
238
 
70
- ### Networks
239
+ ---
240
+
241
+ ## WhatsApp Utilities
242
+
243
+ ### createWhatsAppLink()
244
+
245
+ Generates a WhatsApp click-to-chat link for Pakistani mobile numbers.
71
246
 
72
- #### `getNetwork(phone: string): NetworkName`
247
+ ```ts
248
+ createWhatsAppLink(phone: string, message?: string): string
249
+ ```
73
250
 
74
- Returns the mobile network based on the number prefix: `"Jazz"`, `"Zong"`, `"Telenor"`, `"Ufone"`, or `"Unknown"`.
251
+ Examples:
75
252
 
76
253
  ```ts
77
- getNetwork('03001234567'); // "Jazz"
78
- getNetwork('03151234567'); // "Zong"
79
- getNetwork('03451234567'); // "Telenor"
80
- getNetwork('03331234567'); // "Ufone"
254
+ createWhatsAppLink("03001234567");
255
+ // "https://wa.me/923001234567"
256
+
257
+ createWhatsAppLink("03001234567", "Assalamualaikum");
258
+ // "https://wa.me/923001234567?text=Assalamualaikum"
81
259
  ```
82
260
 
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.
261
+ Returns an empty string for invalid phone numbers.
84
262
 
85
- ### Geography
263
+ ---
86
264
 
87
- #### `getProvince(city: string): string | null`
265
+ ## IBAN Utilities
88
266
 
89
- Returns the province for an exact city name match (case-insensitive, whitespace-tolerant).
267
+ ### validateIBAN()
268
+
269
+ Validates Pakistani IBANs using format and ISO 13616 mod-97 checksum.
90
270
 
91
271
  ```ts
92
- getProvince('Multan'); // "Punjab"
93
- getProvince(' karachi '); // "Sindh"
94
- getProvince('Unknown'); // null
272
+ validateIBAN(iban: string): boolean
95
273
  ```
96
274
 
97
- #### `searchCities(query: string): string[]`
275
+ Examples:
98
276
 
99
- Partial, case-insensitive city search. Returns alphabetically sorted city names.
277
+ ```ts
278
+ validateIBAN("PK36SCBL0000001123456702");
279
+ // true
280
+
281
+ validateIBAN("PK37SCBL0000001123456702");
282
+ // false
283
+ ```
284
+
285
+ ---
286
+
287
+ ### getBankFromIBAN()
288
+
289
+ Returns the bank name from a valid Pakistani IBAN's 4-letter bank code.
290
+
291
+ ```ts
292
+ getBankFromIBAN(iban: string): string | null
293
+ ```
294
+
295
+ Examples:
100
296
 
101
297
  ```ts
102
- searchCities('mul'); // ["Multan"]
103
- searchCities('kar'); // ["Karachi"]
298
+ getBankFromIBAN("PK36SCBL0000001123456702");
299
+ // "Standard Chartered Bank (Pakistan) Limited"
300
+
301
+ getBankFromIBAN("invalid");
302
+ // null
104
303
  ```
105
304
 
106
- ### Formatting
305
+ Supported bank codes include HABB, MEZN, SCBL, UNIL, BAHL, NBPA, MUCB, JSBL, and 46 total entries in the dataset.
107
306
 
108
- #### `formatPKR(amount: number): string`
307
+ ---
109
308
 
110
- Formats an amount as Pakistani Rupees with comma separators.
309
+ ## Postal Code Utilities
310
+
311
+ ### getCityByPostalCode()
312
+
313
+ Returns the city for a Pakistani postal code.
111
314
 
112
315
  ```ts
113
- formatPKR(150000); // "Rs. 150,000"
114
- formatPKR(0); // "Rs. 0"
316
+ getCityByPostalCode(postalCode: string): string | null
115
317
  ```
116
318
 
117
- #### `formatLakh(amount: number): string`
319
+ Examples:
118
320
 
119
- Formats amounts using Lakh/Crore conventions.
321
+ ```ts
322
+ getCityByPostalCode("60000");
323
+ // "Multan"
324
+
325
+ getCityByPostalCode("99999");
326
+ // null
327
+ ```
328
+
329
+ ---
330
+
331
+ ### getPostalCode()
332
+
333
+ Returns the primary postal code for a Pakistani city (case-insensitive).
120
334
 
121
335
  ```ts
122
- formatLakh(2500000); // "25 Lakh"
123
- formatLakh(10000000); // "1 Crore"
124
- formatLakh(50000); // "Rs. 50,000"
336
+ getPostalCode(city: string): string | null
125
337
  ```
126
338
 
127
- ## Examples
339
+ Examples:
340
+
341
+ ```ts
342
+ getPostalCode("Multan");
343
+ // "60000"
344
+
345
+ getPostalCode("karachi");
346
+ // "74200"
347
+ ```
348
+
349
+ ---
350
+
351
+ ## Mobile Networks
352
+
353
+ ### getNetwork()
354
+
355
+ Detects network using the original mobile prefix.
356
+
357
+ ```ts
358
+ getNetwork(phone: string): string
359
+ ```
360
+
361
+ Returns:
362
+
363
+ * Jazz
364
+ * Zong
365
+ * Ufone
366
+ * Telenor
367
+ * Unknown
368
+
369
+ Examples:
370
+
371
+ ```ts
372
+ getNetwork("03001234567");
373
+ // Jazz
374
+
375
+ getNetwork("03151234567");
376
+ // Zong
377
+
378
+ getNetwork("03331234567");
379
+ // Ufone
380
+
381
+ getNetwork("03451234567");
382
+ // Telenor
383
+ ```
384
+
385
+ > Note: Pakistan supports Mobile Number Portability (MNP). The current carrier may differ from the original prefix.
386
+
387
+ ---
388
+
389
+ ## Geography
390
+
391
+ ### getProvince()
392
+
393
+ Returns province for a city.
394
+
395
+ ```ts
396
+ getProvince(city: string): string | null
397
+ ```
398
+
399
+ Examples:
400
+
401
+ ```ts
402
+ getProvince("Multan");
403
+ // Punjab
404
+
405
+ getProvince("Karachi");
406
+ // Sindh
407
+
408
+ getProvince("Unknown");
409
+ // null
410
+ ```
411
+
412
+ ---
413
+
414
+ ### searchCities()
415
+
416
+ Case-insensitive city search.
417
+
418
+ ```ts
419
+ searchCities(query: string): string[]
420
+ ```
421
+
422
+ Examples:
423
+
424
+ ```ts
425
+ searchCities("mul");
426
+ // ["Multan"]
427
+
428
+ searchCities("kar");
429
+ // ["Karachi"]
430
+ ```
431
+
432
+ ---
433
+
434
+ ## Currency Formatting
435
+
436
+ ### formatPKR()
437
+
438
+ Formats PKR amounts with separators.
439
+
440
+ ```ts
441
+ formatPKR(amount: number): string
442
+ ```
443
+
444
+ Examples:
445
+
446
+ ```ts
447
+ formatPKR(150000);
448
+ // "Rs. 150,000"
449
+
450
+ formatPKR(0);
451
+ // "Rs. 0"
452
+ ```
453
+
454
+ ---
455
+
456
+ ### formatLakh()
457
+
458
+ Formats values using Pakistan's Lakh / Crore numbering system.
459
+
460
+ ```ts
461
+ formatLakh(amount: number): string
462
+ ```
463
+
464
+ Examples:
465
+
466
+ ```ts
467
+ formatLakh(2500000);
468
+ // "25 Lakh"
469
+
470
+ formatLakh(10000000);
471
+ // "1 Crore"
472
+
473
+ formatLakh(50000);
474
+ // "Rs. 50,000"
475
+ ```
476
+
477
+ ---
478
+
479
+ # Real-World Example
128
480
 
129
481
  ```ts
130
482
  import {
131
483
  validateCNIC,
132
484
  validatePhone,
133
485
  formatPhone,
486
+ analyzePhone,
487
+ createWhatsAppLink,
488
+ validateIBAN,
489
+ getBankFromIBAN,
490
+ getPostalCode,
491
+ getCityByPostalCode,
134
492
  getNetwork,
135
493
  getProvince,
136
494
  searchCities,
137
495
  formatPKR,
138
- formatLakh,
139
- } from 'pakdatakit';
496
+ formatLakh
497
+ } from "pakdatakit";
140
498
 
141
499
  // CNIC validation
142
- const cnicValid = validateCNIC('35202-1234567-1');
500
+ const cnicValid = validateCNIC("35202-1234567-1");
143
501
 
144
- // Phone normalization
145
- const phone = formatPhone('0300 123 4567'); // "+923001234567"
146
- const isValid = validatePhone(phone);
502
+ // Phone intelligence
503
+ const phoneInfo = analyzePhone("03001234567");
147
504
 
148
- // Network lookup
149
- const network = getNetwork('03001234567'); // "Jazz"
505
+ // WhatsApp link for ecommerce support
506
+ const waLink = createWhatsAppLink("0300 123 4567", "Assalamualaikum");
150
507
 
151
- // City lookup
152
- const province = getProvince('Lahore'); // "Punjab"
153
- const cities = searchCities('fais'); // ["Faisalabad"]
508
+ // IBAN validation for fintech checkout
509
+ const ibanValid = validateIBAN("PK36SCBL0000001123456702");
510
+ const bank = getBankFromIBAN("PK36SCBL0000001123456702");
154
511
 
155
- // Currency formatting
156
- const price = formatPKR(150000); // "Rs. 150,000"
157
- const budget = formatLakh(2500000); // "25 Lakh"
158
- ```
512
+ // Postal lookup for shipping forms
513
+ const postal = getPostalCode("Multan");
514
+ const city = getCityByPostalCode("60000");
159
515
 
160
- ## Development
516
+ // Province lookup
517
+ const province = getProvince("Lahore");
161
518
 
162
- ```bash
163
- npm install
164
- npm test
165
- npm run build
166
- npm run lint
519
+ // Formatting
520
+ const amount = formatPKR(150000);
521
+ const budget = formatLakh(2500000);
167
522
  ```
168
523
 
169
- See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines.
524
+ ---
525
+
526
+ # Playground
527
+
528
+ 🚧 Interactive Playground Coming Soon
529
+
530
+ The PakDataKit Playground will provide:
531
+
532
+ * Live CNIC validation
533
+ * Phone number analysis
534
+ * Network detection
535
+ * City lookups
536
+ * PKR formatting tools
537
+
538
+ ---
539
+
540
+ # Roadmap
541
+
542
+ ### v0.2 ✅
543
+
544
+ * Phone Intelligence (`analyzePhone`)
545
+ * WhatsApp Link Generator
546
+ * IBAN Validation
547
+ * Bank Detection from IBAN
548
+ * Postal Code Lookup
549
+ * Expanded datasets (150 cities, 171 districts, 109 postal codes, 46 banks)
550
+
551
+ ### v0.3
552
+
553
+ * Address Parsing
554
+ * Expanded Postal Data
555
+
556
+ ### v0.4
557
+
558
+ * Roman Urdu Utilities
559
+ * Text Normalization
560
+
561
+ ### v0.5
562
+
563
+ * Islamic Calendar Utilities
564
+ * Hijri Date Helpers
565
+
566
+ ### v1.0
567
+
568
+ * CLI Tool
569
+ * Dataset API
570
+ * Community Contributions
571
+
572
+ ---
573
+
574
+ # Contributing
575
+
576
+ Contributions are welcome.
577
+
578
+ Ideas, bug reports, improvements, and pull requests help make PakDataKit better for everyone.
579
+
580
+ Let's build the standard toolkit for Pakistani developers 🇵🇰
581
+
582
+ See:
583
+
584
+ * CONTRIBUTING.md
585
+ * CODE_OF_CONDUCT.md
586
+
587
+ ---
588
+
589
+ # License
590
+
591
+ MIT License
170
592
 
171
- ## License
593
+ ---
172
594
 
173
- MIT — see [LICENSE](LICENSE).
595
+ <p align="center">
596
+ Built with ❤️ for Pakistani Developers 🇵🇰
597
+ </p>