From c3557a37cc9e4d23db0f14f669e72c7aaff5d4c1 Mon Sep 17 00:00:00 2001 From: Justin Wernick Date: Fri, 9 Jun 2023 13:07:05 +0200 Subject: Add JSDoc comments to the public interface --- south-african-id-parser.js | 157 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 157 insertions(+) (limited to 'south-african-id-parser.js') diff --git a/south-african-id-parser.js b/south-african-id-parser.js index 8e233e7..73450ea 100644 --- a/south-african-id-parser.js +++ b/south-african-id-parser.js @@ -11,12 +11,169 @@ }(this, function () { 'use strict'; + /** + * Parsing result for a valid South African ID number. + * + * @typedef {Object} ValidIDParseResult + * @property {bool} isValid - true + * @property {Date} dateOfBirth - The date of birth from the ID number. + * @property {bool} isMale - The sex from the ID number - true if male, false if female. + * @property {bool} isFemale - The sex from the ID number - true if female, false if male. + * @property {bool} isSouthAfricanCitizen - Citizenship status from the ID + * number, true if it indicates South African citizenship. + */ + + /** + * Parsing result for a invalid South African ID number. + * + * @typedef {Object} InvalidIDParseResult + * @property {bool} isValid - false + */ + return { + /** + * Validates and ID number and parses out all information from it. + * + * This is a combination of the other parsing and validation functions, so + * refer to their documentation for any details. + * + * @function + * @param {string} idNumber - The ID number to be parsed. + * @return {ValidIDParseResult|InvalidIDParseResult} An object with all of + * the parsing results. If the ID is invalid, the result is an object with + * just an `isValid` property set to false. + * + * @example + * var saIdParser = require('south-african-id-parser'); + * var validIdNumber = '9001049818080'; + * + * var info = saIdParser.parse(validIdNumber); + * // info === { + * // isValid: true, + * // dateOfBirth: new Date(1990, 01, 04), + * // isMale: true, + * // isFemale: false, + * // isSouthAfricanCitizen: true + * // } + * + * var invalidIdNumber = '1234567'; + * info = saIdParser.parse(invalidIdNumber); + * // info === { + * // isValid: false + * // } + */ parse: parse, + + /** + * Validates an ID number. + * + * This includes making sure that it follows the expected 13 digit pattern, + * checking that the control digit is correct, and checking that the date of + * birth is a valid date. + * + * @function + * @param {string} idNumber - The ID number to be validated. + * @return {bool} True if the ID number is a valid South African ID number. + * + * @example + * var saIdParser = require('south-african-id-parser'); + * var validIdNumber = '9001049818080'; + * var isValid = saIdParser.validate(validIdNumber); + * + * // valid === true + */ validate: validate, + + /** + * Parses the date of birth out of an ID number. + * + * Minimal validation of the ID number is performed, requiring only that + * it's 13 digits long. + * + * The date of birth included in the ID number has a two digit year. For + * example, 90 instead of 1990. This is converted to a full date by + * comparing the date of birth to the current date, and choosing the century + * that gives the person the lowest age, while still putting their age in + * the past. + * + * For example, assuming that the current date is 10 December 2015. If the + * date of birth parsed is 10 December 15, it will be interpreted as 10 + * December 2015. If, on the other hand, the date of birth is parsed as 11 + * December 15, that will be interpreted as 10 December 1915. + * + * @function + * @param {string} idNumber - The ID number to be parsed. + * @return {?Date} The date of birth from the ID number, or undefined if the + * ID number is not formatted correctly or does not have a valid date of + * birth. + * + * @example + * var saIdParser = require('south-african-id-parser'); + * var validIdNumber = '9001049818080'; + * var dateOfBirth = saIdParser.parseDateOfBirth(validIdNumber); + * + * // dateOfBirth === new Date(1990, 01, 04) + */ parseDateOfBirth: parseDateOfBirth, + + /** + * Parses the sex out of the ID number and returns true it is male. + * + * Minimal validation of the ID number is performed, requiring only that + * it's 13 digits long. + * + * @function + * @param {string} idNumber - The ID number to be parsed. + * @return {?bool} True if male, false if female. Returns undefined if the + * ID number is not a 13 digit number. + * + * @example + * var saIdParser = require('south-african-id-parser'); + * var validIdNumber = '9001049818080'; + * var isMale = saIdParser.parseIsMale(validIdNumber); + * + * // isMale === true + */ parseIsMale: parseIsMale, + + /** + * Parses the sex out of the ID number and returns true it is female. + * + * Minimal validation of the ID number is performed, requiring only that + * it's 13 digits long. + * + * @function + * @param {string} idNumber - The ID number to be parsed. + * @return {?bool} True if female, false if male. Returns undefined if the + * ID number is not a 13 digit number. + * @example + * var saIdParser = require('south-african-id-parser'); + * var validIdNumber = '9001049818080'; + * var isFemale = saIdParser.parseIsFemale(validIdNumber); + * + * // isFemale === false + */ parseIsFemale: parseIsFemale, + + /** + * Parses the citizenship status out of an ID number and returns true if it + * indicates South African citizen. + * + * Minimal validation of the ID number is performed, requiring only that + * it's 13 digits long. + * + * @function + * @param {string} idNumber - The ID number to be parsed. + * @return {?bool} True if the ID number belongs to a South African + * citizen. Returns undefined if the ID number is not a 13 digit number. + * + * @example + * var saIdParser = require('south-african-id-parser'); + * var validIdNumber = '9001049818080'; + * var isSouthAfricanCitizen = saIdParser.parseIsSouthAfricanCitizen(validIdNumber); + * + * // isSouthAfricanCitizen === true + */ parseIsSouthAfricanCitizen: parseIsSouthAfricanCitizen }; -- cgit v1.2.3