Added basic documentation

5 files changed, 141 insertions, 9 deletions

diff --git a/LICENSE b/LICENSE
new file mode 100644
index 0000000..e8099ae
--- /dev/null
+++ b/LICENSE
@@ -0,0 +1,5 @@
+Copyright (c) 2015, Justin Worthe
+
+Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
\ No newline at end of file
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..b16cab2
--- /dev/null
+++ b/README.md
@@ -0,0 +1,115 @@
+South African ID Number Parser
+==============================
+
+The ID Numbers issued in South Africa follow a regular format that you
+can use to derive some information about them. The following
+information is available:
+
+* Date of Birth
+* Sex
+* Citizenship
+
+This library can also check if the ID number supplied is a valid South
+African ID number.
+
+More information on the ID number format can be found
+[here](http://geekswithblogs.net/willemf/archive/2005/10/30/58561.aspx)
+and [here](http://knowles.co.za/generating-south-african-id-numbers/).
+
+Usage
+-----
+
+### Parse Everything
+
+The package exposes the `.parse(idNumber)` method for calling all of
+the validation and parsing in one.
+
+If validation fails, the resulting object only has the isValid property.
+
+```
+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
+//}
+```
+
+### Only Validate
+
+`.validate(idNumber)` only checks if the ID number is valid.
+
+```
+var saIdParser = require('south-african-id-parser');
+var validIdNumber = '9001049818080';
+var isValid = saIdParser.validate(validIdNumber);
+
+//valid === true
+```
+
+### Only Parse Date of Birth
+
+The method does not do a full validation on the ID number, but it will
+return undefined if either the number supplied is not a 13 digit
+number string or the date section of the ID number is invalid.
+
+```
+var saIdParser = require('south-african-id-parser');
+var validIdNumber = '9001049818080';
+var dateOfBirth = saIdParser.parseDateOfBirth(validIdNumber);
+
+//dateOfBirth === new Date(1990, 01, 04)
+```
+
+The date of birth included in the ID number has a two digit year. For
+example, 90 instead of 1990.
+
+This is handled 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.
+
+### Only Parse Sex
+
+The method does not do a full validation on the ID number, but it will
+return undefined if the number supplied is not a 13 digit number
+string.
+
+```
+var saIdParser = require('south-african-id-parser');
+var validIdNumber = '9001049818080';
+var isFemale = saIdParser.parseIsFemale(validIdNumber);
+var isMale = saIdParser.parseIsMale(validIdNumber);
+
+//isFamale === false
+//isMale === true
+```
+
+### Only Parse Citizenship
+
+The method does not do a full validation on the ID number, but it will
+return undefined if the number supplied is not a 13 digit number
+string.
+
+```
+var saIdParser = require('south-african-id-parser');
+var validIdNumber = '9001049818080';
+var isSouthAfricanCitizen = saIdParser.parseIsSouthAfricanCitizen(validIdNumber);
+
+//isSouthAfricanCitizen === true
+```
diff --git a/index.js b/index.js
index b05f2e1..462177e 100644
--- a/index.js
+++ b/index.js
@@ -8,14 +8,10 @@ module.exports = {
 };
 
 function parse(idNumber) {
-    if (typeof(idNumber) !== 'string') {
-        return undefined;
-    }
-
     var isValid = validate(idNumber);
     if (!isValid) {
         return {
-            valid: false
+            isValid: false
         };
     }
 
diff --git a/package.json b/package.json
index 5517a4f..2dd2def 100644
--- a/package.json
+++ b/package.json
@@ -7,10 +7,8 @@
     "test": "mocha"
   },
   "keywords": [
-    "South",
-    "Africa",
-    "ID",
-    "Number"
+    "South Africa",
+    "ID Number"
   ],
   "author": "Justin Worthe <justin.worthe@gmail.com>",
   "license": "ISC",
diff --git a/test/test.js b/test/test.js
index b4b481d..f0417ab 100644
--- a/test/test.js
+++ b/test/test.js
@@ -57,4 +57,22 @@ describe('South African ID Number Parsing', function() {
                 .to.equal(validIdNumber.isSouthAfricanCitizen);
         });
     });
+
+    it('should correctly parse valid ID numbers', function() {
+        validIdNumbers.forEach(function(validIdNumber) {
+            var info = saIdParser.parse(validIdNumber.idNumber);
+            expect(info.isValid).to.equal(true);
+            expect(info.dateOfBirth.getTime()).to.equal(validIdNumber.dateOfBirth.getTime());
+            expect(info.isMale).to.equal(validIdNumber.isMale);
+            expect(info.isFemale).to.equal(validIdNumber.isFemale);
+            expect(info.isSouthAfricanCitizen).to.equal(validIdNumber.isSouthAfricanCitizen);
+        });
+    });
+
+    it('should correctly parse invalid ID numbers', function() {
+        invalidIdNumbers.forEach(function(invalidIdNumber) {
+            var info = saIdParser.parse(invalidIdNumbers.idNumber);
+            expect(info).to.deep.equal({isValid: false});
+        });
+    });
 });