CountryLib Documentation

Overview

CountryLib provides configuration management with a built-in caching layer. It uses the cache-manager package along with the cache-manager-fs-hash disk store to handle caching on the filesystem.

Installation

Install the package via npm or yarn:

1npm install --save countrylib

Sources

• https://github.com/khkwan0/countryCityStateJson
• https://github.com/mledoze/countries
• https://github.com/harpreetkhalsagtbit/country-state-city

File Details

CountryLib Class

The CountryLib class provides an interface to manage and retrieve country data. It can asynchronously load country data from the cache or refresh it from an online source.

Constructor Behavior:

• The constructor accepts an optional configuration object and does not automatically load data. Instead, you must call the loadData() method to initialize the data (which will check the cache and refresh if needed).

Methods:

• getByCode(code: string): CountryData | null
  Retrieves country data matching the given two-letter (cca2) or three-letter (cca3) country code.

• getByName(name: string): CountryData | null
  Retrieves country data for a country matching the given common or official name.

• hasCachedData(): Promise<CountryData[] | null>
  Checks whether country data is cached and returns the cached data if available.

• refreshData(): Promise<boolean>
  Fetches the latest country data from an online source, processes it using CountryData.fromMledoze, caches it, and updates the internal data array.

Example Usage:

1import { CountryLib } from 'countrylib';
2
3async function testCountryLib() {
4  // Instantiate the class (optionally pass a custom configuration)
5  const countryLib = new CountryLib();
6  // Load and initialize country data (from cache or online)
7  await countryLib.loadData();
8
9  const countryUS = countryLib.getByCode('US');
10  if (countryUS) {
11    console.log('Found country by code (US):', countryUS);
12  } else {
13    console.log('Country with code "US" not found.');
14  }
15
16  const countryCanada = countryLib.getByName('Canada');
17  if (countryCanada) {
18    console.log('Found country by name:', countryCanada);
19  } else {
20    console.log('Country with name "Canada" not found.');
21  }
22}
23
24testCountryLib();

CountryData Class

Example Data

1CountryData {
2  data: {
3    name: { common: 'United States', official: 'United States of America' },
4    tld: [ '.us' ],
5    cca2: 'US',
6    ccn3: 840,
7    cca3: 'USA',
8    cioc: 'USA',
9    independent: true,
10    currencies: [ WorldCurrency { code: 'USD', symbol: '$' } ],
11    continent: WorldContinent {
12      code: 'NA',
13      name: 'North America',
14      translations: {
15        en: 'North America',
16        de: 'Nordamerika',
17        es: 'América del Norte',
18        fr: 'Amérique du Nord',
19        ja: '北アメリカ',
20        zh: '北美洲',
21        ru: 'Северная Америка',
22        tr: 'Kuzey Amerika',
23        vi: 'Bắc Mỹ',
24        ar: 'أمريكا الشمالية',
25        nl: 'Noord-Amerika',
26        pl: 'Ameryka Północna',
27        pt: 'América do Norte',
28        ro: 'America de Nord',
29        it: 'America del Nord'
30      }
31    },
32    capital: [ 'Washington D.C.' ],
33    status: 'officially-assigned',
34    languages: [ WorldLanguage { name: 'eng', code: 'English' } ],
35    lat: 38,
36    lng: -97,
37    flag: '🇺🇸',
38    area: 9372610,
39    timezones: [
40      'America/Chicago',
41      'America/Los_Angeles',
42      'America/New_York',
43      'America/Phoenix',
44      'America/Boise',
45      'America/Kentucky/Louisville',
46      'America/Indiana/Indianapolis',
47      'America/Denver',
48      'America/Detroit',
49      'Pacific/Honolulu',
50      'America/Menominee',
51      'America/Indiana/Vevay',
52      'America/Indiana/Vincennes',
53      'America/Anchorage',
54      'America/North_Dakota/New_Salem',
55      'America/Indiana/Tell_City',
56      'America/Indiana/Knox',
57      'America/Indiana/Winamac',
58      'America/Indiana/Marengo',
59      'America/Sitka',
60      'America/Juneau',
61      'America/Kentucky/Monticello',
62      'America/Indiana/Petersburg',
63      'America/North_Dakota/Beulah',
64      'America/Nome',
65      'America/Metlakatla',
66      'America/North_Dakota/Center'
67    ],
68    coordinates: [
69      { latitude: 37.751, longitude: -97.822 },
70      { latitude: 41.8835, longitude: -87.6305 },
71      { latitude: 42.5584, longitude: -71.269 },
72      { latitude: 47.6109, longitude: -122.3303 },
73      { latitude: 33.42, longitude: -111.9128 },
74      { latitude: 39.0469, longitude: -77.4903 },
75      { latitude: 40.7126, longitude: -74.0066 },
76      { latitude: 37.3388, longitude: -121.8916 },
77      { latitude: 34.0544, longitude: -118.244 },
78      { latitude: 31.5718, longitude: -85.2505 },
79      { latitude: 29.1779, longitude: -95.446 },
80      { latitude: 30.5183, longitude: -82.9482 },
81      { latitude: 27.7889, longitude: -82.7192 },
82      { latitude: 21.3195, longitude: -157.8525 },
83      { latitude: 48.799, longitude: -122.4499 },
84      { latitude: 26.9372, longitude: -82.2386 },
85      { latitude: 21.9036, longitude: -159.4666 },
86      { latitude: 64.7511, longitude: -147.3494 },
87      { latitude: 61.1901, longitude: -149.9361 },
88      { latitude: 25.4785, longitude: -80.4844 },
89      { latitude: 61.5883, longitude: -149.3959 },
90      { latitude: 64.0382, longitude: -145.7508 },
91      { latitude: 66.9007, longitude: -162.6058 },
92      { latitude: 59.0397, longitude: -158.4575 },
93      { latitude: 53.8865, longitude: -166.5387 },
94      { latitude: 63.3403, longitude: -142.9853 },
95      { latitude: 68.1297, longitude: -145.5334 }
96    ]
97  }
98}