id-parser-sa

A simple JavaScript library for parsing and validating South African ID numbers. It helps you extract useful information like the date of birth, gender, and citizenship status from a valid ID number.

Features

• Validate South African ID numbers: Check if the ID is valid.
• Extract Date of Birth: Get the person's birth date in YYYY-MM-DD format.
• Determine Gender: Identify if the person is male or female based on the ID.
• Citizenship Status: Determine if the person is a South African citizen or a Permanent Resident.

Installation

To install the library, you can use npm (Node Package Manager).

npm install id-parser-sa

Usage

To use this library in your project, follow these steps:

    1. Import the library

    import { parseID } from 'id-parser-sa';


    2. Call the parseID function with a South African ID number (13 digits):

    const idNumber = '9702095859080'; // Example ID number
    const result = parseID(idNumber);

    if (result.error) {
        console.error(result.error);  // If the ID is invalid, show an error
    } else {
        console.log(`Date of Birth: ${result.dob}`);    // Outputs: 1997-02-09
        console.log(`Gender: ${result.gender}`);         // Outputs: Male
        console.log(`Citizenship: ${result.citizenship}`); // Outputs: South African
    }

    parseID(idNumber: string)

    * Parameters:
        idNumber: A string of 13 digits representing the South African ID number.

    * Returns:
        An object with the following properties:
            - error: A string if the ID number is invalid (e.g., "Invalid South African ID number"),        otherwise it’s undefined.
            - dob: The extracted Date of Birth in YYYY-MM-DD format.
            - gender: The gender extracted from the ID number ("Male" or "Female").
            - citizenship: The citizenship status ("South African" or "Permanent Resident").

Validation
    * This library validates the following:

        - Ensures the ID number is exactly 13 digits.
        - Checks if the date of birth (from the first 6 digits) is a valid date.
        - Validates the gender digits (determines male or female).
        - Validates the citizenship status (0 for South African citizen, 1 for Permanent Resident).
        - Performs a Luhn check to ensure the ID number is mathematically valid.

License
    * This project is licensed under the ISC License.

Acknowledgments
    * This library is built for educational purposes and may not cover all edge cases. Feel free to verify or enhance the logic as needed for your use case.