@scuba-squad/country

Country class definition

Usage no npm install needed!

<script type="module">
  import scubaSquadCountry from 'https://cdn.skypack.dev/@scuba-squad/country';
</script>

README

Country

Status

Build Status Coverage Status

Table of Content

Purpose

Country class definition

Installation

Via npm

npm install @scuba-squad/country

API

Country.getByIso2Code(code: string): Country | false

Added in: v1.0.0

Static method to retrieve and build a Country object from the iso2Code

arguments:

  1. code: string

returns: Country | false

const Country = require('@scuba-squad/country');

let country = Country.getByIso2Code('US'); // Country
let nonExistant = Country.getByIso2Code('AA'); // false

Country.getByIso3Code(code: string): Country | false

Added in: v1.0.0

Static method to retrieve and build a Country object from the iso3Code

arguments:

  1. code: string

returns: Country | false

const Country = require('@scuba-squad/country');

let country = Country.getByIso3Code('USA'); // Country
let nonExistant = Country.getByIso3Code('AAA'); // false

Country.getByIsoNumericCode(code: string): Country | false

Added in: v1.0.0

Static method to retrieve and build a Country object from the isoNumericCode

arguments:

  1. code: string

returns: Country | false

const Country = require('@scuba-squad/country');

let country = Country.getByIsoNumericCode('840'); // Country
let nonExistant = Country.getByIsoNumericCode('000'); // false

Country.getByPostalCode(code: ?string): Country[] | false

Added in: v1.0.0

Static method to retrieve and build an array of Country objects who match the given postal code

arguments:

  1. code: string

returns: Country[] | false

const Country = require('@scuba-squad/country');

let country = Country.getByPostalCode('11111'); // Country[]
let nonExistant = Country.getByPostalCode('this is going to return false'); // false

Country.getByCallingCode(code: ?string): Country[] | false

Added in: v1.0.0

Static method to retrieve and build an array of Country objects who match the given calling code

arguments:

  1. code: string

returns: Country[] | false

const Country = require('@scuba-squad/country');

let country = Country.getByCallingCode('1'); // Country[]
let nonExistant = Country.getByCallingCode('99999999999999'); // false

Country(properties: {name: ?string, iso2Code: ?string, iso3Code: ?string, isoNumericCode: ?string postalCodeRegEx: ?regexp, callingCode: ?string | string[]} = {}): Country

Added in: v1.0.0

Country class constructor

arguments:

  1. properties: object = {}
    • name: string | null | undefined
    • iso2Code: string | null | undefined
    • iso3Code: string | null | undefined
    • isoNumericCode: string | null | undefined
    • postalCodeRegEx: regexp | null | undefined
    • callingCode: string | string[] | null | undefined

returns: Country

throws: TypeError

const Country = require('@scuba-squad/country');

let country = new Country();

alternatively

  • you can create an instance without the new keyword
const Country = require('@scuba-squad/country');

let country = Country();

Country.VERSION: string

Added in: v1.0.0

Semantic version number of class definition

returns: string

const Country = require('@scuba-squad/country');

let country = new Country();
country.VERSION; // 1.0.0

Country.name: string | undefined

Added in: v1.0.0

Property containing the name of the country

returns: string | undefined

throws: TypeError

const Country = require('@scuba-squad/country');

let country = new Country();
// set name via setName()
country.name = 'Petoria';
// get name via getName()
country.name; // 'Petoria'

Country.getName(): string | undefined

Added in: v1.0.0

Getter method for name property

returns: string | undefined

const Country = require('@scuba-squad/country');

let country = new Country();
// set name via setName()
country.name = 'Petoria';
// get name via getName()
country.getName(); // 'Petoria'

Country.setName(name: ?string): Country

Added in: v1.0.0

Setter method for name property

arguments:

  1. name: string | undefined | null

returns: Country

throws: TypeError

const Country = require('@scuba-squad/country');

let country = new Country();
// set name via setName()
country.setName('Petoria');
// get name via getName()
country.name; // 'Petoria'

Country.iso2Code: string | undefined

Added in: v1.0.0

Property containing the ISO 3166-1 alpha-2 code of the country

returns: string | undefined

throws: TypeError

const Country = require('@scuba-squad/country');

let country = new Country();
// set iso2Code via setIso2Code()
country.iso2Code = 'FG';
// get iso2Code via getIso2Code()
country.iso2Code; // 'FG'

Country.getIso2Code(): string | undefined

Added in: v1.0.0

Getter method for iso2Code property

returns: string | undefined

const Country = require('@scuba-squad/country');

let country = new Country();
// set iso2Code via setIso2Code()
country.iso2Code = 'FG';
// get iso2Code via getIso2Code()
country.getIso2Code(); // 'FG'

Country.setIso2Code(code: ?string): Country

Added in: v1.0.

Setter method for iso2Code property

arguments:

  1. code: string | undefined | null

returns: Country

throws: TypeError

const Country = require('@scuba-squad/country');

let country = new Country();
// set iso2Code via setIso2Code()
country.setIso2Code('FG');
// get iso2Code via getIso2Code()
country.iso2Code; // 'FG'

Country.iso3Code: string | undefined

Added in: v1.0.0

Property containing the ISO 3166-1 alpha-3 code of the country

returns: string | undefined

throws: TypeError

const Country = require('@scuba-squad/country');

let country = new Country();
// set iso3Code via setIso3Code()
country.iso3Code = 'GUY';
// get iso3Code via getIso3Code()
country.iso3Code; // 'GUY'

Country.getIso3Code(): string | undefined

Added in: v1.0.0

Getter method for iso3Code property

returns: string | undefined

const Country = require('@scuba-squad/country');

let country = new Country();
// set iso3Code via setIso3Code()
country.iso3Code = 'GUY';
// get iso3Code via getIso3Code()
country.getIso3Code(); // 'GUY'

Country.setIso3Code(code: ?string): Country

Added in: v1.0.0

Setter method for iso3Code property

arguments:

  1. code: string | undefined | null

returns: Country

throws: TypeError

const Country = require('@scuba-squad/country');

let country = new Country();
// set iso3Code via setIso3Code()
country.setIso3Code('GUY');
// get iso3Code via getIso3Code()
country.iso3Code; // 'GUY'

Country.isoNumericCode: string | undefined

Added in: v1.0.0

Property containing the ISO 3166-1 numeric code of the country

returns: string | undefined

throws: TypeError

const Country = require('@scuba-squad/country');

let country = new Country();
// set isoNumericCode via setIsoNumericCode()
country.isoNumericCode = '999';
// get isoNumericCode via getIsoNumericCode()
country.isoNumericCode; // '999'

Country.getIsoNumericCode(): string | undefined

Added in: v1.0.0

Getter method for isoNumericCode property

returns: string | undefined

const Country = require('@scuba-squad/country');

let country = new Country();
// set isoNumericCode via setIsoNumericCode()
country.isoNumericCode = '999';
// get isoNumericCode via getIsoNumericCode()
country.getIsoNumericCode(); // '999'

Country.setIsoNumericCode(code: ?string): Country

Added in: v1.0.0

Setter method for isoNumericCode property

arguments:

  1. code: string | undefined | null

returns: Country

throws: TypeError

const Country = require('@scuba-squad/country');

let country = new Country();
// set isoNumericCode via setIsoNumericCode()
country.setIsoNumericCode('999');
// get isoNumericCode via getIsoNumericCode()
country.isoNumericCode; // '999'

Country.postalCodeRegEx: regexp | undefined | null

Added in: v1.0.0

Property containing the postal code validation regular expression for the country

returns: regexp | undefined | null

throws: TypeError

const Country = require('@scuba-squad/country');

let country = new Country();
// set postalCodeRegEx via setPostalCodeRegEx()
country.postalCodeRegEx = /^\d{5}$/;
// get postalCodeRegEx via getPostalCodeRegEx()
country.postalCodeRegEx; // /^\d{5}$/;

Country.getPostalCodeRegEx(): regexp | undefined | null

Added in: v1.0.0

Getter method for postalCodeRegEx property

returns: regexp | undefined | null

const Country = require('@scuba-squad/country');

let country = new Country();
// set postalCodeRegEx via setPostalCodeRegEx()
country.postalCodeRegEx = /^\d{5}$/;
// get postalCodeRegEx via getPostalCodeRegEx()
country.getPostalCodeRegEx(); // /^\d{5}$/;

Country.setPostalCodeRegEx(regex: ?regexp): Country

Added in: v1.0.0

Setter method for postalCodeRegEx property

arguments:

  1. code: regexp | undefined | null

returns: Country

throws: TypeError

const Country = require('@scuba-squad/country');

let country = new Country();
// set postalCodeRegEx via setPostalCodeRegEx()
country.setPostalCodeRegEx(/^\d{5}$/);
// get postalCodeRegEx via getPostalCodeRegEx()
country.postalCodeRegEx; // /^\d{5}$/;

Country.callingCode: string | string[] | undefined | null

Added in: v1.0.0

Property containing the calling code of the country

returns: string | string[] | undefined | null

throws: TypeError

const Country = require('@scuba-squad/country');

let country = new Country();
// get callingCode via getCallingCode()
country.callingCode; // undefined
// set callingCode via setCallingCode()
country.callingCode = [1, 5];
// get callingCode via getCallingCode()
country.callingCode; // ['+1', '+5']
// set callingCode via setCallingCode()
country.callingCode = null;
// get callingCode via getCallingCode()
country.callingCode; // null

Country.getCallingCode(): string[] | undefined | null

Added in: v1.0.0

Getter method for callingCode property

returns: string[] | undefined | null

const Country = require('@scuba-squad/country');

let country = new Country();
country.getCallingCode(); // undefined
// set callingCode via setCallingCode()
country.callingCode = [1, 5];
country.getCallingCode(); // ['+1', '+5']
// set callingCode via setCallingCode()
country.callingCode = null;
country.getCallingCode(); // null

Country.setCallingCode(code: ?...string | string[]): Country

Added in: v1.0.0

Setter method for callingCode property

arguments:

  1. code: ...string | string[] | undefined | null

returns: Country

throws: TypeError

const Country = require('@scuba-squad/country');

let country = new Country();
country
  .setCallingCode(1) // ['+1']
  .setCallingCode(5, 9) // ['+5', '+9']
  .setCallingCode([6, 9]) // ['+6', '+9']
  .setCallingCode(5, [6, 9], [1], '4 5'); // ['+5', '+6' '+9', '+1', '+4 5']

Country.addCallingCode(code: ?...string | string[]): Country

Added in: v1.0.0

Method to append calling code(s) onto the callingCode property

arguments:

  1. code: ...string | string[] | undefined | null

returns: Country

throws: TypeError

const Country = require('@scuba-squad/country');

let country = new Country();
country
  .addCallingCode(1) // ['+1']
  .addCallingCode(5, 9) // ['+1', '+5', '+9']
  .addCallingCode([6, 9]) // ['+1', '+5', '+9', '+6']
  .addCallingCode(5, [6, 9], [1], '4 5'); // ['+1', '+5', '+9', '+6', '+4 5']

Country.removeCallingCode(code: ?...string | string[]): Country

Added in: v1.0.0

Method to remove calling code(s) from the callingCode property

arguments:

  1. code: ...string | string[] | undefined | null

returns: Country

throws: TypeError

const Country = require('@scuba-squad/country');

let country = new Country();
// set callingCode via setCallingCode()
country.callingCode = [1, 5, '6 7', 9];
country.removeCallingCode(1, 3); // ['+5', '+6 7', '+9']
country.removeCallingCode(1, 5, 9); // ['+6 7']
country.removeCallingCode(1, 5, '+6 7'); // undefined

Country.hasCallingCode(code: ?string): boolean

Added in: v1.0.0

Method to check if the given calling code is set for the country

arguments:

  1. code: string | undefined | null

returns: boolean

throws: TypeError

const Country = require('@scuba-squad/country');

let country = new Country();
// set callingCode via setCallingCode()
country.callingCode = [1, 5, '6 7'];
country.hasCallingCode(3); // false
country.hasCallingCode(1); // true
country.hasCallingCode('+6 7'); // true
country.hasCallingCode('+1 5'); // false
country.hasCallingCode(5); // true

Country.hasAllCallingCodes(codes: ?...string | string[]): boolean

Added in: v1.0.0

Method to check if all the given calling codes are set for the country

arguments:

  1. code: ...string | string[] | undefined | null

returns: Country

throws: TypeError

const Country = require('@scuba-squad/country');

let country = new Country();
// set callingCode via setCallingCode()
country.callingCode = [1, 5, '6 7', 9];
country.hasAllCallingCodes(1, 3); // false
country.hasAllCallingCodes(1, 5, 9); // true
country.hasAllCallingCodes(1, 5, '+6 7'); // true
country.hasAllCallingCodes(1, 5, 3); // false
country.hasAllCallingCodes(1, 5, 9, '6 7'); // true

country.hasAllCallingCodes([1, 3]); // false
country.hasAllCallingCodes([1, 5, 9]); // true
country.hasAllCallingCodes([1, 5, '+6 7']); // true
country.hasAllCallingCodes([1, 5, 3]); // false
country.hasAllCallingCodes([1, 5, 9, '6 7']); // true

country.hasAllCallingCodes(1, [3]); // false
country.hasAllCallingCodes([1], 5, 9); // true
country.hasAllCallingCodes([1, 5], '+6 7'); // true
country.hasAllCallingCodes(1, [5, 3]); // false
country.hasAllCallingCodes(1, [5, 9], '6 7'); // true

Country.hasAnyCallingCodes(codes: ?...string | string[]): boolean

Added in: v1.0.0

Method to check if any of the given calling codes are set for the country

arguments:

  1. code: ...string | string[] | undefined | null

returns: Country

throws: TypeError

const Country = require('@scuba-squad/country');

let country = new Country();
// set callingCode via setCallingCode()
country.callingCode = [1, 5, '6 7', 9];
country.hasAnyCallingCodes(2, 3); // false
country.hasAnyCallingCodes(2, 3, 1); // true
country.hasAnyCallingCodes(2, 3, '+1'); // true
country.hasAnyCallingCodes(2, 3, 67); // false
country.hasAnyCallingCodes(2, 3, '6 7'); // true

country.hasAnyCallingCodes([2, 3]); // false
country.hasAnyCallingCodes([2, 3, 1]); // true
country.hasAnyCallingCodes([2, 3, '+1']); // true
country.hasAnyCallingCodes([2, 3, 67]); // false
country.hasAnyCallingCodes([2, 3, '6 7']); // true

country.hasAnyCallingCodes(2, [3]); // false
country.hasAnyCallingCodes(2, 3, [1]); // true
country.hasAnyCallingCodes(2, [3, '+1']); // true
country.hasAnyCallingCodes(2, [3, 67]); // false
country.hasAnyCallingCodes([2, 3], '6 7'); // true

Country.get(properties: ?...string | string[]): object

Added in: v1.0.0

Method to create an object literal containing the set properties

arguments:

  1. code: ...string | string[] | undefined | null

returns: object

throws: TypeError

const Country = require('@scuba-squad/country');

let country = Country.getByIso2Code('US');
country.get('iso3Code', 'callingCode'); // {iso3Code: 'USA', callingCode: ['+1']}
country.get(['iso3Code', 'callingCode']); // {iso3Code: 'USA', callingCode: ['+1']}
country.get('iso2Code', ['iso3Code', 'callingCode'], 'isoNumericCode'); // {iso2Code: 'US', iso3Code: 'USA', callingCode: ['+1'], isoNumericCode: '840'}

Country.set(properties: {name: ?string, iso2Code: ?string, iso3Code: ?string, isoNumericCode: ?string postalCodeRegEx: ?regexp, callingCode: ?string | string[]} = {}): Country

Added in: v1.0.0

Method to bulk set properties on the country

arguments:

  1. properties: object = {}
    • name: string | null | undefined
    • iso2Code: string | null | undefined
    • iso3Code: string | null | undefined
    • isoNumericCode: string | null | undefined
    • postalCodeRegEx: regexp | null | undefined
    • callingCode: string | string[] | null | undefined

returns: Country

throws: TypeError

const Country = require('@scuba-squad/country');

let country = new Country();
country.set({name: 'Petoria', iso2Code: 'FG', iso3Code: 'GUY'});

Country.isValidPostalCode(postalCode: ?string): boolean

Added in: v1.0.0

Method to check if the given postal code is valid for the country

arguments:

  1. code: string | undefined | null

returns: boolean

throws: TypeError

const Country = require('@scuba-squad/country');

// create new instance of Country without setting postalCodeRegEx
let country = new Country();
country.isValidPostalCode(); // true
country.isValidPostalCode(null); // true
country.isValidPostalCode(NaN); // false
country.isValidPostalCode(0); // false
country.isValidPostalCode(''); // false
country.isValidPostalCode([]); // false
country.isValidPostalCode({}); // false

// set postalCodeRegEx via setPostalCodeRegEx()
country.postalCodeRegEx = /^\d{5}$/;
country.isValidPostalCode('12345'); // true
country.isValidPostalCode('1234'); // false
country.isValidPostalCode('123456'); // false
country.isValidPostalCode('123e5'); // false

Country[Symbol.toStringTag]: string

Added in: v1.1.0

returns: string

const Country = require('@scuba-squad/country');

let country = new Country();
country[Symbol.toStringTag]; // '@scuba-squad/country'
Object.prototype.toString.call(country); // '[object @scuba-squad/country]'

Test

tests

npm install
npm test

License

MIT