Add typescript types to the package

This doesn't change any internal workings, but makes this package easier to use
by anyone using Typescript.

Fix #12

6 files changed, 101 insertions, 35 deletions

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 092d6af..ef9e1a6 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -12,7 +12,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-### Changed
+### Added
+
+- The package now includes typescript type definitions.
+
+### Breaking Changes
 
 - Updated license to be dual licensed MIT or Apache 2.0. This isn't intended to
   restrict any use cases, I'm just standardising my licensing across multiple
diff --git a/package.json b/package.json
index bdc383e..83aed06 100644
--- a/package.json
+++ b/package.json
@@ -3,10 +3,11 @@
   "version": "1.1.0",
   "description": "A library for parsing and validating South African ID Numbers.",
   "main": "south-african-id-parser.js",
+  "types": "south-african-id-parser.d.ts",
   "scripts": {
     "pretest": "eslint ./",
     "test": "mocha",
-    "docs": "jsdoc --configure .jsdocrc.json"
+    "docs": "tsc && jsdoc --configure .jsdocrc.json"
   },
   "keywords": [
     "South Africa",
@@ -33,6 +34,7 @@
     "eslint": "^8.42.0",
     "jsdoc": "^4.0.2",
     "mocha": "^10.2.0",
-    "requirejs": "^2.3.6"
+    "requirejs": "^2.3.6",
+    "typescript": "^5.1.6"
   }
 }
diff --git a/south-african-id-parser.d.ts b/south-african-id-parser.d.ts
new file mode 100644
index 0000000..b401e7b
--- /dev/null
+++ b/south-african-id-parser.d.ts
@@ -0,0 +1,34 @@
+export function parse(idNumber: string): {
+    /**
+     * - true
+     */
+    isValid: boolean;
+    /**
+     * - The date of birth from the ID number.
+     */
+    dateOfBirth: Date;
+    /**
+     * - The sex from the ID number - true if male, false if female.
+     */
+    isMale: boolean;
+    /**
+     * - The sex from the ID number - true if female, false if male.
+     */
+    isFemale: boolean;
+    /**
+     * - Citizenship status from the ID
+     * number, true if it indicates South African citizenship.
+     */
+    isSouthAfricanCitizen: boolean;
+} | {
+    /**
+     * - false
+     */
+    isValid: boolean;
+};
+export function validate(idNumber: string): boolean;
+export function parseDateOfBirth(idNumber: string): Date;
+export function parseIsMale(idNumber: string): boolean;
+export function parseIsFemale(idNumber: string): boolean;
+export function parseIsSouthAfricanCitizen(idNumber: string): boolean;
+//# sourceMappingURL=south-african-id-parser.d.ts.map
\ No newline at end of file
diff --git a/south-african-id-parser.d.ts.map b/south-african-id-parser.d.ts.map
new file mode 100644
index 0000000..83d2c91
--- /dev/null
+++ b/south-african-id-parser.d.ts.map
@@ -0,0 +1 @@
+{"version":3,"file":"south-african-id-parser.d.ts","sourceRoot":"","sources":["south-african-id-parser.js"],"names":[],"mappings":"AAkEW;;;;;;;;;;;;;;;;;;;;;;;;;;;EAeN;AAoBS,oDAET;AAmCiB,yDAEjB;AAoBY,uDAEZ;AAmBc,yDAEd;AAqB2B,sEAE3B"}
\ No newline at end of file
diff --git a/south-african-id-parser.js b/south-african-id-parser.js
index 983647a..75637bb 100644
--- a/south-african-id-parser.js
+++ b/south-african-id-parser.js
@@ -17,11 +17,11 @@
    * Parsing result for a valid South African ID number.
    *
    * @typedef {Object} ValidIDParseResult
-   * @property {bool} isValid - true
+   * @property {boolean} 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
+   * @property {boolean} isMale - The sex from the ID number - true if male, false if female.
+   * @property {boolean} isFemale - The sex from the ID number - true if female, false if male.
+   * @property {boolean} isSouthAfricanCitizen - Citizenship status from the ID
    *   number, true if it indicates South African citizenship.
    */
 
@@ -29,7 +29,7 @@
    * Parsing result for a invalid South African ID number.
    *
    * @typedef {Object} InvalidIDParseResult
-   * @property {bool} isValid - false
+   * @property {boolean} isValid - false
    */
 
   return {
@@ -64,7 +64,22 @@
      * //   isValid: false
      * // }
      */
-    parse: parse,
+    parse: function(idNumber) {
+      var isValid = validate(idNumber);
+      if (!isValid) {
+        return {
+          isValid: false
+        };
+      }
+
+      return {
+        isValid: isValid,
+        dateOfBirth: parseDateOfBirth(idNumber),
+        isMale: parseIsMale(idNumber),
+        isFemale: parseIsFemale(idNumber),
+        isSouthAfricanCitizen: parseIsSouthAfricanCitizen(idNumber)
+      };
+    },
 
     /**
      * Validates an ID number.
@@ -75,7 +90,7 @@
      *
      * @function
      * @param {string} idNumber - The ID number to be validated.
-     * @return {bool} True if the ID number is a valid South African ID number.
+     * @return {boolean} True if the ID number is a valid South African ID number.
      *
      * @example
      * var saIdParser = require('south-african-id-parser');
@@ -84,7 +99,9 @@
      *
      * // valid === true
      */
-    validate: validate,
+    validate: function(idNumber) {
+      return validate(idNumber);
+    },
 
     /**
      * Parses the date of birth out of an ID number.
@@ -119,7 +136,9 @@
      *
      * // dateOfBirth === new Date(1990, 0, 4)
      */
-    parseDateOfBirth: parseDateOfBirth,
+    parseDateOfBirth: function(idNumber) {
+      return parseDateOfBirth(idNumber);
+    },
 
     /**
      * Parses the sex out of the ID number and returns true it is male.
@@ -129,7 +148,7 @@
      *
      * @function
      * @param {string} idNumber - The ID number to be parsed.
-     * @return {?bool} True if male, false if female. Returns undefined if the
+     * @return {?boolean} True if male, false if female. Returns undefined if the
      *   ID number is not a 13 digit number.
      *
      * @example
@@ -139,7 +158,9 @@
      *
      * // isMale === true
      */
-    parseIsMale: parseIsMale,
+    parseIsMale: function(idNumber) {
+      return parseIsMale(idNumber);
+    },
 
     /**
      * Parses the sex out of the ID number and returns true it is female.
@@ -149,7 +170,7 @@
      *
      * @function
      * @param {string} idNumber - The ID number to be parsed.
-     * @return {?bool} True if female, false if male. Returns undefined if the
+     * @return {?boolean} 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');
@@ -158,7 +179,9 @@
      *
      * // isFemale === false
      */
-    parseIsFemale: parseIsFemale,
+    parseIsFemale: function(idNumber) {
+      return parseIsFemale(idNumber);
+    },
 
     /**
      * Parses the citizenship status out of an ID number and returns true if it
@@ -169,7 +192,7 @@
      *
      * @function
      * @param {string} idNumber - The ID number to be parsed.
-     * @return {?bool} True if the ID number belongs to a South African
+     * @return {?boolean} True if the ID number belongs to a South African
      *   citizen. Returns undefined if the ID number is not a 13 digit number.
      *
      * @example
@@ -179,25 +202,10 @@
      *
      * // isSouthAfricanCitizen === true
      */
-    parseIsSouthAfricanCitizen: parseIsSouthAfricanCitizen
-  };
-
-  function parse(idNumber) {
-    var isValid = validate(idNumber);
-    if (!isValid) {
-      return {
-        isValid: false
-      };
+    parseIsSouthAfricanCitizen: function(idNumber) {
+      return parseIsSouthAfricanCitizen(idNumber);
     }
-
-    return {
-      isValid: isValid,
-      dateOfBirth: parseDateOfBirth(idNumber),
-      isMale: parseIsMale(idNumber),
-      isFemale: parseIsFemale(idNumber),
-      isSouthAfricanCitizen: parseIsSouthAfricanCitizen(idNumber)
-    };
-  }
+  };
 
   function validate(idNumber) {
     if (!regexpValidate(idNumber) || !datePartValidate(idNumber) || !controlDigitValidate(idNumber)) {
diff --git a/tsconfig.json b/tsconfig.json
new file mode 100644
index 0000000..34dd6f7
--- /dev/null
+++ b/tsconfig.json
@@ -0,0 +1,17 @@
+{
+  // Change this to match your project
+  "include": ["*.js"],
+  "compilerOptions": {
+    // Tells TypeScript to read JS files, as
+    // normally they are ignored as source files
+    "allowJs": true,
+    // Generate d.ts files
+    "declaration": true,
+    // This compiler run should
+    // only output d.ts files
+    "emitDeclarationOnly": true,
+    // go to js file when using IDE functions like
+    // "Go to Definition" in VSCode
+    "declarationMap": true
+  }
+}