🌐 @worldkit/countries

Fast, tree-shakeable country dataset for JavaScript, TypeScript, Cloudflare Workers, and Node.js.

Lookup 250+ countries and territories by ISO2, ISO3, numeric ID, or country name with instant $O(1)$ hash map performance.

📚 Full Documentation: https://worldkit.in/docs/countries

⚡ Features

• 🌍 250+ Countries & Territories: Covers ISO 3166-1 standard codes.
• 🚀 Ultra-Fast $O(1)$ Lookups: Instantly retrieve metadata with zero network requests.
• 📦 Tiny & Tree-Shakeable: Compact ES modules under 2 KB gzipped.
• 🛡️ Zero Dependencies: Pure JavaScript logic runs everywhere (Node.js, Browsers, Cloudflare Workers, Edge Runtimes).
• 🏷️ Rich Data: Native names, capitals, currency codes, phone codes, flag emojis, timezones, languages, and postal format regexes.

📦 Install

npm install @worldkit/countries
# or
pnpm add @worldkit/countries
# or
yarn add @worldkit/countries

💡 Usage

import { country, countries, countryByName, exists } from "@worldkit/countries";

// 1. O(1) Lookup by ISO2 ("JP"), ISO3 ("JPN"), or Numeric ID (392)
const japan = country("JP");
console.log(japan);
/*
{
  id: 392,
  iso2: "JP",
  iso3: "JPN",
  numeric: "392",
  name: "Japan",
  nativeName: "日本",
  capital: "Tokyo",
  continent: "Asia",
  currency: "JPY",
  phone: 81,
  emoji: "🇯🇵",
  timezones: ["Asia/Tokyo"],
  languages: ["ja"]
}
*/

// 2. Lookup by full country name (case-insensitive)
const india = countryByName("India");

// 3. Get all supported countries array
const all = countries();
console.log(`Total countries: ${all.length}`); // 250+

// 4. Fast existence check
if (exists("FR")) {
  console.log("France is a valid country code!");
}

📖 API Reference

country(query: string | number): Country | undefined

Look up country metadata by ISO2 code (e.g. "US"), ISO3 code (e.g. "USA"), or numeric ID (e.g. 840).

countries(): Country[]

Returns an array of all 250+ countries.

countryByName(name: string): Country | undefined

Look up country metadata by full country name (case-insensitive).

exists(code: string): boolean

Returns true if the provided ISO2 or ISO3 code is valid.

📐 TypeScript Support

This package is written in 100% strict TypeScript and includes complete type definitions out of the box:

import type { Country } from "@worldkit/countries";

🔗 Related Packages

Explore the rest of the WorldKit ecosystem:

• @worldkit/core - Unified toolkit facade for all WorldKit modules.
• @worldkit/currencies - ISO-4217 currencies and symbols.
• @worldkit/cities - Major world cities lookup.
• @worldkit/states - 4,000+ states and provinces.
• @worldkit/phone - E.164 phone formatting & validation rules.
• @worldkit/flags - Unicode flag emojis and SVG flag helpers.
• @worldkit/react - React select dropdown components.

📜 License

MIT © WorldKit