@greycode/country_utils

A high-performance, lightweight utility for working with country-related data. Optimized for both Node.js and Browser environments with full TypeScript support.

• Blazing Fast: O(1) lookups using optimized Maps.
• Comprehensive Data: Includes ~250 countries with ISO codes (Alpha-2, Alpha-3), numeric codes, phone codes, currencies, capitals, continents, and flag emojis.
• Maintainable Architecture: Data is modularized by continent for easy updates and smaller bundles.
• Modern: Built with ESM and CommonJS support (dual-build).
• Type-Safe: Comprehensive TypeScript definitions included.
• Zero Dependencies: Pure, lightweight logic.

npm install @greycode/country_utils

import { getByCountryCode, getAllCountries, getByPhoneCode } from '@greycode/country_utils';

// Get a country by ISO Alpha-2 code
const code = getByCountryCode('ZW');

if (code.isValid) {
  console.log(code.country);   // Zimbabwe
  console.log(code.phoneCode); // +263
  console.log(code.flag);      // 🇿🇼
}

const { CountryUtil } = require('@greycode/country_utils');

const uk = CountryUtil.getByCountryCode('GB');
console.log(uk.capital); // London

Lookup a country by its ISO 3166-1 alpha-2 code. Returns a LookupResult.

Lookup a country by its ISO 3166-1 alpha-3 code. Returns a LookupResult.

Lookup a country by its phone dialing code (e.g., +1 or +263).

Returns the total number of countries in the database.

Returns a unique, sorted list of all continents.

Returns the count of countries for a given continent.

Returns the full array of all 250+ country objects.

Returns all countries belonging to a specific continent (e.g., "Africa", "Europe").

If you're using a bundler (Vite, Webpack) or a modern browser with ESM support:

<script type="module">
  import { getAllCountries } from 'https://cdn.jsdelivr.net/npm/@greycode/country_utils/+esm';
  
  const list = getAllCountries();
  console.log(`Loaded ${list.length} countries!`);
</script>

A simple country selector component:

import React, { useState } from 'react';
import { getAllCountries, Country } from '@greycode/country_utils';

export const CountrySelector = () => {
  const [selected, setSelected] = useState<string>('');
  const countries = getAllCountries();

  return (
    <select value={selected} onChange={(e) => setSelected(e.target.value)}>
      <option value="">Select a country</option>
      {countries.map((c: Country) => (
        <option key={c.countryCode} value={c.countryCode}>
          {c.flag} {c.country}
        </option>
      ))}
    </select>
  );
};

Filtering countries by continent in a composition API component:

<script setup>
import { getByContinent } from '@greycode/country_utils';
import { computed } from 'vue';

const africanCountries = computed(() => getByContinent('Africa'));
</script>

<template>
  <ul>
    <li v-for="c in africanCountries" :key="c.countryCode">
      {{ c.flag }} {{ c.country }} ({{ c.phoneCode }})
    </li>
  </ul>
</template>

Using analytic functions in a Server Component:

import { getCountryCount, getContinents } from '@greycode/country_utils';

export default function Dashboard() {
  const total = getCountryCount();
  const continents = getContinents();

  return (
    <div>
      <h1>Global Stats</h1>
      <p>Tracking {total} countries across {continents.length} continents.</p>
    </div>
  );
}

The package now uses a modular data structure located in src/data/. Each continent has its own JSON file:

• africa.json
• asia.json
• europe.json
• north_america.json
• south_america.json
• oceania.json
• antarctic.json

This makes it easier to keep the data updated and allows for better maintenance.

interface Country {
  country: string;
  countryCode: string; // ISO Alpha-2
  alpha3: string;      // ISO Alpha-3
  numeric: string;
  phoneCode: string;
  currency: string;
  capital: string;
  continent: string;
  flag: string;        // Emoji flag
}

This package is fully tested with Vitest.

npm test

MIT © Kudzai Munyama