zimbabwean-id-number-validator 1.0.1

package/README.md

@@ -0,0 +1,61 @@
+# Zimbabwean ID Number Validator
+
+The ID numbers issued in Zimbabwe consist of either 11 or 12 alphanumeric characters. Each ID contains one alphabetic letter, while the remaining characters are numeric digits. Various systems may capture ID numbers in different formats, with the most common formats including:
+- 082047823Q29  
+- 08-2047823-Q-29
+- 08-2047823Q29
+
+| ID | Description                                                               |
+|------|---------------------------------------------------------------------------|
+| 08   | District Code                   |
+| 2047823 | 6 or 7 digit sequence|
+| Q    | Alphabetic letter                                                              |
+| 29   | District Code  |
+-----------------------------------------------------------------------------------
+
+This package uses regular expressions to validate the input against the established patterns. It also includes a lookup of District Codes to ensure the correctness of the ID number.
+The three possible responses are as follows:
+```javascript
+    {
+        isIdNumberValid: false,
+        description: "id number must be in one of the formats: (082047823Q29), (08-2047823Q29), or (08-2047823-Q-29)"
+    },
+    
+    {
+        isIdNumberValid: false,
+        description: "id number is invalid"
+    },
+
+    {
+        isIdNumberValid: true,
+        description: "id number is valid"
+    }
+
+```
+
+District Codes used in the validation procedures were acquired from the following [source](https://ntjwg.uwazi.io/entity/seif769joed?file=15512639038111am2iqd21an.pdf&page=9).
+
+
+## Usage
+
+Install the package using the following command:
+
+```bash
+npm install zimbabwean-id-number-validator
+```
+
+### Usage In ES6
+
+```javascript
+import validateIdNumber from 'zimbabwean-id-number-validator'
+const validationResults = validateIdNumber("082047823Q21")
+```
+
+### Usage in CommonJS
+
+```javascript
+const validateIdNumber = require('zimbabwean-id-number-validator');
+const validationResults = validateIdNumber("082047823Q21")
+```
+
+

package/constants.js

@@ -0,0 +1,92 @@
+const validLetters = {
+    0: "Z",
+    1: "A",
+    2: "B",
+    3: "C",
+    4: "D",
+    5: "E",
+    6: "F",
+    7: "G",
+    8: "H",
+    9: "J", 
+    10: "K",
+    11: "L",
+    12: "M",
+    13: "N",
+    14: "P",
+    15: "Q",
+    16: "R",
+    17: "S",
+    18: "T",
+    19: "V",
+    20: "W",
+    21: "X",
+    22: "Y",
+}
+
+const validDistrictCodes = [
+    "08",
+    "63",
+    "07",
+    "44",
+    "13",
+    "42",
+    "75",
+    "50",
+    "34",
+    "05",
+    "71",
+    "15",
+    "45",
+    "11",
+    "61",
+    "68",
+    "18",
+    "25",
+    "80",
+    "43",
+    "49",
+    "47",
+    "48",
+    "59",
+    "85",
+    "32",
+    "38",
+    "24",
+    "37",
+    "70",
+    "86",
+    "04",
+    "14",
+    "13",
+    "27",
+    "22",
+    "54",
+    "83",
+    "06",
+    "35",
+    "79",
+    "41",
+    "53",
+    "73",
+    "84",
+    "02",
+    "56",
+    "28",
+    "21",
+    "39",
+    "19",
+    "77",
+    "26",
+    "23",
+    "29",
+    "58",
+    "03",
+    "66",
+    "67",
+]
+
+module.exports = {
+    validLetters,
+    validDistrictCodes
+}

package/index.js

@@ -0,0 +1,47 @@
+const { validLetters, validDistrictCodes } = require("./constants")
+
+const idNumberRegex = /^\d{2}-?\d{6,7}-?[A-HJ-NP-Z]-?\d{2}$/g;
+
+const validateIdNumber = (idNumber) => {
+    // initialize id validation results
+    const idValidationResults = {
+        isIdNumberValid: false,
+        description: "id number must be in one of the formats: (082047823Q29), (08-2047823Q29), or (08-2047823-Q-29)"
+    }
+
+    // check if the id number is formatted correctly
+    const isIdFormatCorrect = idNumberRegex.test(idNumber)
+
+    if (isIdFormatCorrect) {
+        // check if the id number is valid
+        // extract the letter and application centre district code
+        const idLetter = idNumber.match(/[A-Z]/)[0]
+        const applicationCentreCode = idNumber.slice(0, 2)
+
+        // replace all hyphens and split the id number into an array using the id letter
+        const idNumberArray = idNumber.replace(/-/g, "").split(idLetter)
+        const placeOfOriginCode = idNumberArray[1]
+
+        // convert the id number digits before the letter into a number
+        const idDigitsBeforeLetter = parseInt(idNumberArray[0])
+        const numericLetterValue = idDigitsBeforeLetter % 23 // represents a key in the validLetters object
+
+        if (
+            validDistrictCodes.includes(applicationCentreCode) &&
+            idLetter === validLetters[numericLetterValue] &&
+            validDistrictCodes.includes(placeOfOriginCode)
+        ) {
+            // update idValidationResults and set the id number to valid
+            idValidationResults["isIdNumberValid"] = true
+            idValidationResults["description"] = "id number is valid"
+        }
+        else {
+            // update the invalid id number's description
+            idValidationResults["description"] = "id number is invalid"
+        }
+    }
+
+    return idValidationResults
+}
+
+module.exports = validateIdNumber

package/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "zimbabwean-id-number-validator",
+  "version": "1.0.1",
+  "description": "Zimbabwean national id number validator",
+  "main": "index.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "author": "Wellington Mpofu",
+  "license": "ISC"
+}