V3

.travis.yml

@@ -2,12 +2,9 @@ language: node_js
 os:
   - 'linux'
 node_js:
+  - '14'
   - '12'
   - '10'
-  - '8'
-  - '6'
-  - '5'
-  - '4'
 install:
   - npm install
 script:

README.md

@@ -7,17 +7,17 @@ Provides javascript postal code validation for [all  countries](https://en.wikip
 
 
 ### Validation rules
-1. Characters " " (space) and "-" (dash) are removed from the input string.
-2. Input is case insensitive.
-3. Supports both [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) and [ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) country codes.
-4. Validates optional n-digit extention seperated by a space or hyphen.
+1. Characters " " (space) and "-" (dash) are removed from the input string, if the postal code format allowes it.
+2. Input is case-insensitive.
+3. Supports ISO 3166-1 [alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2), [alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) and [numeric-3](https://en.wikipedia.org/wiki/ISO_3166-1_numeric) country codes.
+4. Validates optional n-digit extension separated by a space or hyphen.
 
 ### Usage
 ```
 const postalCodes = require('postal-codes-js');
-const countryCode = 'CH'; // ISO 3166-1 alpha-2 or alpha-3 country code as string.
+const countryCode = 'CH'; // ISO 3166-1 alpha-2, alpha-3 or numeric-3 country code as string.
 const postalCode = '8008'; // Postal code as string or number.
-postalCodes.validate(countryCode, postalCode); // Returns 'true' if valid, error message as string otherwise.
+postalCodes.validate(countryCode, postalCode); // Returns true if valid, false otherwise.
 
 // All the calls below returns true
 postalCodes.validate('bg', '1003');
@@ -32,15 +32,19 @@ postalCodes.validate('TUR', '33150');
 postalCodes.validate('us', '22313');
 postalCodes.validate('USA', '91746-2302');
 
-// All the calls below return a string
+// All the calls below return false
 postalCodes.validate('UK', 'EC1A 1BB');
- > Unknown alpha2/alpha3 country code: UK
+ > false
 
 postalCodes.validate('PL', '9999');
- > Postal code 9999 is not valid for country PL
+ > false
 
+// Invalid input throws an error.
 postalCodes.validate('CH');
- > Missing postal code.
+ > Uncaught Error: Missing postal code.
+
+postalCodes.validate('nope', '1234');
+ > Uncaught Error: No data for [nope].
 ```
 
 ### Testing with mocha
@@ -50,5 +54,7 @@ postalCodes.validate('CH');
 ## Contribution
 Contributions are more than welcome, just fork the repo and create a pull-request ;)
 
+For information about the adding or changing countries, see [data.md](data.md)
+
 ## Contact
 [email protected]

build/make-lookup.js

@@ -0,0 +1,17 @@
+const fs = require('fs');
+const countries = require('../data/countries.json');
+
+const lookup = {};
+
+Object
+  .values(countries)
+  .forEach(({alpha2, alpha3, numeric3}, index) => {
+    lookup[alpha2] = index;
+    lookup[alpha3] = index;
+    lookup[numeric3] = index;
+  });
+
+fs.writeFileSync(
+  `${__dirname}/../data/lookup.json`,
+  JSON.stringify(lookup, null, 2)
+);

data.md

@@ -0,0 +1,90 @@
+All the data that supports this library lives the `data` folder.
+
+# To add/edit a format:
+1. Add or edit the format in `formats.json`.
+2. Add or edit the corresponding tests in `tests.json`.
+3. Add or edit the country/countries in `countries.json`.
+4. Build the lookup: `npm run build:lookup`.
+5. Run the tests: `npm run test`.
+
+# countries.json
+countries.json holds an array of each of the supported countries.
+## Format
+```json
+{
+  "alpha2": "NL",
+  "alpha3": "NLD",
+  "numeric3": "528",
+  "postalCodeFormat": "NL"
+}
+```
+- alpha2: The ISO-3166-1 Alpha-2 country code.
+- alpha3: The ISO-3166-1 Alpha-3 country code.
+- numeric3: The ISO-3166-1 Numeric country code.
+- postalCodeFormat: The key of a format. Can also be `false` if the country does
+ not have postal codes.
+
+_Special note about Canary Islands: it does not have an alpha 3 nor numeric code._
+
+# formats.json
+formats.json holds a dictionary of format names to their definition. If multiple
+countries have a format in common, the key should be a descriptive name. For
+example: `5Digits`.
+
+If the format is particular to a specific country, then the alpha 2 code of the
+country should be used. For example: `NL`.
+
+## Format
+```json
+{
+  "NL": {
+    "redundantCharacters": " -",
+    "validationRegex": "^[1-9][0-9]{3}(?!SA|SD|SS)[A-Z]{2}$"
+  }
+}
+```
+- redundantCharacters: characters that should be removed from the postal code
+ before validation.
+- validationRegex: regex to validate the input. The regex is used case-insensitive,
+ so it does not need to account for casing. It should be anchored to prevent
+ false positives.
+
+# lookup.json
+lookup.json holds a dictionary of keys to the index in the countries array. It is
+used to quickly find countries by a number of keys.
+
+**This file is generated by `build/make-lookup.js`**
+
+## Format
+```json
+{
+  "NL": 165,
+  "NLD": 165,
+  "528": 165
+}
+```
+The keys are the alpha 2, alpha 3 and numeric code of all countries.
+
+# tests.json
+tests.json holds the test data for each format. It is a dictionary of the name
+of a format to the test data. This powers the unit tests to ensure the validity
+of each regex.
+
+## Format
+```json
+{
+  "5Digits": {
+    "valid": [
+      "12345",
+      "56785"
+    ],
+    "invalid": [
+      "123456",
+      "1233s",
+      "123x3"
+    ]
+  }
+}
+```
+- valid: array of postal codes that are valid for the format.
+- invalid: array of postal codes that are not valid for the format.