country-codes-list

Module with list of codes per country, including country codes, currency codes, and more.

[!WARNING]
Release v2.0.0 introduces breaking changes with full TypeScript support and automated testing/publishing.

Features

• Country code (ISO 3166-1 alpha-2): Obtained from Wikipedia
• Country Name: Each name in english and in the local country language
• Currency Code (ISO 4217): Obtained from Wikipedia
• Currency Name (ISO 4217): Obtained from Wikipedia
• TIN Code (Taxpayer Identification Number, also known as VAT in some countries): Obtained from Wikipedia
• TIN Name: Obtained from Wikipedia
• Official language code (usually from ISO 639-1, or ISO 639-3 otherwise)): Obtained from Open Street Map. Returns only the first official language code per country
• Official language name: Each name in english and in the local country language
• Country Calling Code: The phone calling code for the country. Obtained from Wikipedia.
• Region: The Regional Classifications are from the International Telecommunications Union. Seen here

Installation

Install the package via npm:

1npm install --save country-codes-list

Build & Test

To compile the package, run:

1npm run build

The compiled output will be in the dist/ folder.

To run tests:

1npm test

Installation

Install the NPM module

1    npm install --save country-codes-list

Migration Guide (v1.x to v2.0)

Breaking Changes

1. TypeScript Types: If you were using types:

   1// Old (v1.x)
   2import { CountryProperty } from "country-codes-list";
   3const prop: CountryProperty = CountryProperty.countryCode;
   4
   5// New (v2.0)
   6import type { CountryProperty } from "country-codes-list";
   7const prop: CountryProperty = "countryCode";

2. Module Imports: Now supports both CommonJS and ES modules:

   1// CommonJS (still works)
   2const countryCodes = require("country-codes-list");
   3
   4// ES Modules (new)
   5import * as countryCodes from "country-codes-list";

3. Stricter Types: Some functions now have stricter type checking:

   1// This now requires valid country property keys
   2countryCodes.filter("invalidKey", "value"); // TypeScript error

Usage

This package can be used in both CommonJS (JavaScript) and TypeScript environments.

CommonJS

1const countryCodes = require("country-codes-list");
2
3const myCountryCodesObject = countryCodes.customList(
4  "countryCode",
5  "[{countryCode}] {countryNameEn}: +{countryCallingCode}"
6);
7
8console.log(myCountryCodesObject);

TypeScript

1import * as countryCodes from "country-codes-list";
2
3const myCountryCodesObject = countryCodes.customList(
4  "countryCode",
5  "[{countryCode}] {countryNameEn}: +{countryCallingCode}"
6);
7console.log(myCountryCodesObject);

API Details – customList Method

• The first parameter is the key used for the returned object's property.
• The second parameter is a string with placeholders (in {placeholder} format) replaced by corresponding country properties.

The available placeholders are:

• countryNameEn
• countryNameLocal
• countryCode
• currencyCode
• currencyNameEn
• tinType
• tinName
• officialLanguageCode
• officialLanguageNameEn
• officialLanguageNameLocal
• countryCallingCode
• region
• globalSouth

Example

1const countryCodes = require("country-codes-list");
2
3const myCountryCodesObject = countryCodes.customList(
4  "countryCode",
5  "[{countryCode}] {countryNameEn}: +{countryCallingCode}"
6);

This will return an object like this one:

1{
2    'AD': '[AD] Andorra: +376',
3    'AE': '[AE] United Arab Emirates: +971',
4    'AF': '[AF] Afghanistan: +93',
5    'AG': '[AG] Antigua and Barbuda: +1',
6    'AI': '[AI] Anguilla: +1',
7    'AL': '[AL] Albania: +355',
8    'AM': '[AM] Armenia: +374',
9    'AO': '[AO] Angola: +244',
10    'AQ': '[AQ] Antarctica: +',
11    'AR': '[AR] Argentina: +54',
12    'AS': '[AS] American Samoa: +1',
13    'AT': '[AT] Austria: +43',
14    'AU': '[AU] Australia: +61',
15    'AW': '[AW] Aruba: +297',
16    ...
17}
18