country-base

Pre-indexed country data for high-load JavaScript and TypeScript projects.

The package avoids repeated Array.find() scans. Countries are stored by ISO-2 code, and every secondary lookup is shipped as a separate importable index.

What is country-base?

country-base is a zero-dependency TypeScript/JavaScript library for fast country lookups.

It provides ready-to-use country data indexed by ISO-2 code, plus optional prebuilt indexes for ISO-3, country names, phone codes, currencies, subregions, and languages.

Best for high-load projects, APIs, validation layers, forms, checkout flows, analytics pipelines, and any code path where repeated Array.find() lookups are too wasteful.

Install

npm install country-base

Basic Usage

import { getCountryByIso2 } from "country-base";

const country = getCountryByIso2("us");

console.log(country?.name.common);
// United States

console.log(country?.cca2, country?.cca3);
// US USA

All Countries

import { countries } from "country-base";

console.log(countries.length);
// 250

for (const country of countries) {
  console.log(country.cca2, country.name.common);
}
// AD Andorra
// AE United Arab Emirates
// AF Afghanistan
// ...

countries is a ready-to-use shared array, so it does not rebuild on every use.

The root import loads the full country dataset keyed by ISO-2 and exposes the shared all-countries array. Secondary lookup indexes are loaded only when you import their country-base/indexes/* entrypoints.

import { iso3 } from "country-base/indexes/iso3";
import { countriesByIso2 } from "country-base/data";

const iso2 = iso3.USA;
const country = iso2 ? countriesByIso2[iso2] : undefined;

console.log(iso2);
// US

console.log(country?.name.official);
// United States of America

Separate Indexes

import { nameSimple } from "country-base/indexes/name-simple";
import { phone } from "country-base/indexes/phone";
import { currency } from "country-base/indexes/currency";
import { normalizeKey } from "country-base";

const byName = nameSimple[normalizeKey("United States")];
const byPhone = phone["+1"];
const byCurrency = currency.USD;

console.log(byName);
// ["US"]

console.log(byPhone);
// ["AG", "AI", "AS", "BB", "BM", "BS", "CA", "DM", "DO", "GD", "GU", "JM", "KN", "KY", "LC", "MP", "MS", "PR", "SX", "TC", "TT", "US", "VC", "VG", "VI"]

console.log(byCurrency);
// ["AS", "BQ", "BS", "EC", "GU", "IO", "KH", "MH", "MP", "PA", "PR", "PW", "SV", "TC", "TL", "UM", "US", "VG", "VI", "ZW"]

Country Object Excerpt

Shortened excerpt from getCountryByIso2("US"):

const country = {
  altSpellings: ["US", "USA", "United States of America"],
  area: 9372610,
  borders: ["CAN", "MEX"],
  capital: ["Washington D.C."],
  cca2: "US",
  cca3: "USA",
  ccn3: "840",
  cioc: "USA",
  currencies: {
    USD: {
      name: "United States dollar",
      symbol: "$"
    }
  },
  demonyms: {
    eng: {
      f: "American",
      m: "American"
    },
    fra: {
      f: "Américaine",
      m: "Américain"
    }
  },
  flag: "🇺🇸",
  idd: {
    root: "+1",
    suffixes: [
      "201",
      "202",
      "203",
      "205"
      // ...more NANP area codes
    ]
  },
  independent: true,
  landlocked: false,
  languages: {
    eng: "English"
  },
  latlng: [38, -97],
  name: {
    common: "United States",
    native: {
      eng: {
        common: "United States",
        official: "United States of America"
      }
    },
    official: "United States of America"
  },
  region: "Americas",
  status: "officially-assigned",
  subregion: "North America",
  tld: [".us"],
  translations: {
    deu: {
      common: "Vereinigte Staaten",
      official: "Vereinigte Staaten von Amerika"
    },
    fra: {
      common: "États-Unis",
      official: "Les états-unis d'Amérique"
    },
    rus: {
      common: "Соединённые Штаты Америки",
      official: "Соединенные Штаты Америки"
    },
    zho: {
      common: "美国",
      official: "美利坚合众国"
    }
    // Also includes: ara, bre, ces, est, fin, hrv, hun, ita, jpn,
    // kor, nld, per, pol, por, slk, spa, srp, swe, tur, urd
  },
  unMember: true,
  unRegionalGroup: "Western European and Others Group"
};

Available indexes:

Import	Key format	Value
country-base/indexes/iso2	ISO-2 code, for example US	CountryCodeIso2
country-base/indexes/iso3	ISO-3 code, for example USA	CountryCodeIso2
country-base/indexes/name-full	normalizeKey(...) result	CountryCodeIso2[]
country-base/indexes/name-simple	normalizeKey(...) result	CountryCodeIso2[]
country-base/indexes/phone	exact calling code with or without +	CountryCodeIso2[]
country-base/indexes/currency	currency code, for example USD	CountryCodeIso2[]
country-base/indexes/subregion	normalizeKey(...) result	CountryCodeIso2[]
country-base/indexes/language-code	language code, for example eng	CountryCodeIso2[]
country-base/indexes/language-name	normalizeKey(...) result	CountryCodeIso2[]

country-base/indexes imports all indexes at once.

Countries without a subregion value are not included in the subregion index.

TypeScript

Types are included. No extra @types/* package is required.

import type { Country, CountryCodeIso2 } from "country-base";
import type { MultiCountryIndex } from "country-base/indexes/currency";

Key Features

• ISO-2 country lookup in O(1)
• Prebuilt indexes for ISO-3, names, phone codes, currencies, subregions, and languages
• Separate index imports so unused lookup maps are not loaded
• TypeScript-first API with bundled types
• Works in Node.js and package-aware runtimes/bundlers, including Bun, Deno via npm:, and browser bundlers
• ESM and CommonJS support
• Zero runtime dependencies

Performance

country-base uses object-map lookups instead of repeated full-array scans. The Array.find() row below is a baseline for raw array datasets, not the internal implementation of country-base.

Scenario	Example	Strategy	Complexity
country-base ISO-2 lookup	getCountryByIso2("US")	Object map	O(1)
Raw array dataset lookup	countries.find((c) => c.cca2 === "US")	Full-array scan	O(n)
country-base currency lookup	currency.USD	Prebuilt index	O(1) map access

Benchmarks were run on Node.js 24, Apple M2, May 2026.

Scenario	Result
country-base ISO-2 object-map lookup	40,143,970 ops/sec
Baseline manual Array.find() lookup	4,498,170 ops/sec
country-base currency prebuilt-index lookup	133,276,618 ops/sec

Run locally:

npm run build
npm run benchmark

Compared to Alternatives

Package style	ISO-2 lookup	Secondary lookups	TypeScript	Bundle strategy
country-base	O(1) object map	Prebuilt indexes	Yes	Separate importable indexes
Raw country array packages	Usually Array.find() / manual scan	Usually manual filtering	Varies	Usually full dataset
Country/state/city datasets	Varies	Often optimized for hierarchy, not country-only lookup	Varies	Larger data surface

country-base vs countries-list

Use country-base when you need fast ISO-2 lookups and prebuilt secondary indexes for names, phone codes, currencies, subregions, and languages.

Use countries-list when you prefer its specific data shape or already depend on its exported country records.

country-base vs world-countries

Use country-base when lookup speed and TypeScript-friendly indexed access are the priority.

Use world-countries when you need a raw country dataset in its format and do not need prebuilt lookup maps.

country-base vs country-state-city

Use country-base when you only need country-level metadata.

Use country-state-city when you need states, provinces, and cities in addition to countries.

When should I use country-base?

Use country-base when you need:

• O(1) ISO-2 country lookup
• Separate importable indexes instead of loading every lookup map at once
• TypeScript types bundled with the package
• Country-level metadata for APIs, forms, checkout flows, validation, analytics, or high-load services

Use another dataset when you need city-level data, administrative subdivisions, or a different raw data schema.