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 --- .eslintrc.json | 1 + .gitignore | 1 + package.json | 4 +- south-african-id-parser.js | 157 +++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 162 insertions(+), 1 deletion(-) diff --git a/.eslintrc.json b/.eslintrc.json index dfb64d0..92c421c 100644 --- a/.eslintrc.json +++ b/.eslintrc.json @@ -9,6 +9,7 @@ "parserOptions": { "ecmaVersion": "latest" }, + "ignorePatterns": ["dist/"], "rules": { } } diff --git a/.gitignore b/.gitignore index 807cf47..1401030 100644 --- a/.gitignore +++ b/.gitignore @@ -1,5 +1,6 @@ node_modules /npm-debug.log +/dist # This is a library. package-lock.json \ No newline at end of file diff --git a/package.json b/package.json index 6550f3e..bc15702 100644 --- a/package.json +++ b/package.json @@ -5,7 +5,8 @@ "main": "south-african-id-parser.js", "scripts": { "pretest": "eslint ./", - "test": "mocha" + "test": "mocha", + "docs": "jsdoc *.js --destination dist/docs" }, "keywords": [ "South Africa", @@ -30,6 +31,7 @@ "devDependencies": { "chai": "^4.3.7", "eslint": "^8.42.0", + "jsdoc": "^4.0.2", "mocha": "^10.2.0" } } 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