pakistani-cnic-formatter-aroma 1.0.0

package/cnic.js

@@ -0,0 +1,110 @@
+/**
+ * @fileoverview Pakistan CNIC Utility Module providing validation, formatting, masking, 
+ * and data extraction (province and gender) based on NADRA CNIC specifications.
+ * @module pakistani-cnic-formatter
+ * @author Aroma Areej
+ * @license ISC
+ */
+
+/**
+ * Removes all non-digit characters from the provided CNIC input.
+ * 
+ * @private
+ * @param {string|number} input - The raw CNIC input string or number.
+ * @returns {string} A string containing only numeric digits.
+ */
+function cleanCNIC(input) {
+  return String(input || '').replace(/\D/g, '');
+}
+
+/**
+ * Formats a raw CNIC string into the standard Pakistani format (XXXXX-XXXXXXX-X).
+ * 
+ * @public
+ * @param {string|number} input - The raw CNIC input to format.
+ * @returns {string} The formatted CNIC string, or the original input if it does not contain exactly 13 digits.
+ */
+function format(input) {
+  const cleaned = cleanCNIC(input);
+  if (cleaned.length !== 13) return input;
+  return `${cleaned.slice(0, 5)}-${cleaned.slice(5, 12)}-${cleaned.slice(12)}`;
+}
+
+/**
+ * Masks the middle 7 digits of a CNIC for privacy and security purposes.
+ * 
+ * @public
+ * @param {string|number} input - The raw CNIC input to mask.
+ * @param {string} [maskChar='*'] - The character used for masking the middle section.
+ * @returns {string} The masked CNIC string (e.g., 35202-*******-1), or the original input if invalid.
+ */
+function mask(input, maskChar = '*') {
+  const cleaned = cleanCNIC(input);
+  if (cleaned.length !== 13) return input;
+
+  const prefix = cleaned.slice(0, 5);
+  const middleMask = maskChar.repeat(7);
+  const suffix = cleaned.slice(12);
+
+  return `${prefix}-${middleMask}-${suffix}`;
+}
+
+/**
+ * Validates a CNIC number and extracts regional and demographic information 
+ * such as the issuing province/region and gender based on the national numbering scheme.
+ * 
+ * @public
+ * @param {string|number} input - The CNIC input string or number to validate and analyze.
+ * @returns {Object} An object containing validation status, error messages, raw/formatted/masked values, province, and gender.
+ */
+function validate(input) {
+  const cleaned = cleanCNIC(input);
+
+  // Validate that the CNIC strictly contains 13 numeric digits
+  if (cleaned.length !== 13) {
+    return {
+      isValid: false,
+      error: 'CNIC must be exactly 13 digits long.',
+      raw: cleaned,
+      formatted: null,
+      masked: null,
+      province: null,
+      gender: null
+    };
+  }
+
+  // Map the first digit of the CNIC to its respective administrative region or province
+  const provinceMap = {
+    '1': 'Khyber Pakhtunkhwa',
+    '2': 'FATA',
+    '3': 'Punjab',
+    '4': 'Sindh',
+    '5': 'Balochistan',
+    '6': 'Islamabad',
+    '7': 'Gilgit-Baltistan',
+    '8': 'Azad Jammu & Kashmir'
+  };
+
+  const firstDigit = cleaned[0];
+  const province = provinceMap[firstDigit] || 'Unknown Region';
+
+  // Determine gender from the final 13th digit (Even = Female, Odd = Male)
+  const lastDigit = parseInt(cleaned[12], 10);
+  const gender = (lastDigit % 2 === 0) ? 'Female' : 'Male';
+
+  return {
+    isValid: true,
+    error: null,
+    raw: cleaned,
+    formatted: format(cleaned),
+    masked: mask(cleaned),
+    province: province,
+    gender: gender
+  };
+}
+
+module.exports = {
+  validate,
+  format,
+  mask
+};

package/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "pakistani-cnic-formatter-aroma",
+  "version": "1.0.0",
+  "description": "",
+  "main": "cnic.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [],
+  "author": "Aroma Areej",
+  "license": "ISC",
+  "type": "commonjs"
+}