@syniol/iso-3166/README.md

ISO-3166 Standard for Country codes

# ISO-3166
The purpose of ISO 3166 is to define internationally recognized codes of letters and/or 
numbers that we can use when we refer to countries and their subdivisions. However, it 
does not define the names of countries – this information comes from United Nations sources 
(Terminology Bulletin Country Names and the Country and Region Codes for Statistical Use 
maintained by the United Nations Statistics Divisions).


## Background
Using codes saves time and avoids errors as instead of using a country’s name (which will 
change depending on the language), we can use a combination of letters and/or 
numbers that are understood all over the world. This library contains both `ISO 3166-1` 
and `ISO 3166-2` without the subdivisions in English.


## Motivation
Create a light ISO-3166 node package for internal software development at Syniol that is 
matching our coding standards.


## Quick Guide
Below is a quick example of Country ISO-3166 Node library in JavaScript.

```javascript
    const country = require('iso-3166')
    const britain = country.CreateFromName('britain')

    console.log(britain.name) // Output: United Kingdom of Great Britain and Northern Ireland
    console.log(britain.alpha2Code) // Output: GB
    console.log(britain.alpha3Code) // Output: GBR
    console.log(britain.numeric) // Output: 826
```

```javascript
    import { Country } from 'iso-3166'
    const britain = Country.CreateFromName('britain')

    console.log(britain.name) // Output: United Kingdom of Great Britain and Northern Ireland
    console.log(britain.alpha2Code) // Output: GB
    console.log(britain.alpha3Code) // Output: GBR
    console.log(britain.numeric) // Output: 826
```


### API
Available Methods are:

* __CountryList:__ accepts no parameters, and it returns an array of countries. This could be used 
for dropdown menu or when you need to display country's name as a title and `alpha-2/3` as a value. 
 
```javascript
const countries = Country.CountryList()

for (const country of countries) {
    console.log(country.name)
    console.log(country.alpha2Code)
    console.log(country.alpha3Code)
    console.log(country.numeric)
}
```

* __CreateFromName:__ accept a single parameter, as long as name contains the most relevant name 
it will find and create a `Country` object.

```javascript
let country = Country.CreateFromName('Great Britain')
const country = Country.CreateFromName('Britain')
const countr = Country.CreateFromName('britain')
```

* __CreateFromAlpha2Code:__ accepts a single parameter, it should match the `alpha-2` code to find 
and create a `Country` object.

```javascript
const country = Country.CreateFromAlpha2Code('GB')
const country = Country.CreateFromAlpha2Code('gb')
```

* __CreateFromAlpha3Code:__ accepts a single parameter, it should match the 
`alpha-3` code to find and create a `Country` object.

```javascript
const country = Country.CreateFromAlpha3Code('GBR')
const country = Country.CreateFromAlpha3Code('gbr')
```

* __CreateFromNumeric:__ accepts a single parameter, it should match the `numeric` 
code ( Country Code to find and create a `Country` object.

```javascript
const country = Country.CreateFromNumeric(826)
```


#### Credits
Built with ❤️ & ☕ in Beautiful London. Copyright © Syniol Limited.