@martince/countries

Canonical country data - ISO 3166-1 codes, names, regions, and domains

Installation

npm install @martince/countries

Usage

Lookup Functions

import {
  getByISO2,
  getByISO3,
  getByNumeric,
  getByName,
  searchByName,
  getAllCountries,
} from '@martince/countries';

// Get by ISO 3166-1 Alpha-2 (case-insensitive)
const usa = getByISO2('US');
const uk = getByISO2('gb');

// Get by ISO 3166-1 Alpha-3
const germany = getByISO3('DEU');

// Get by numeric code
const japan = getByNumeric('392');

// Search by name
const results = searchByName('united');
// Returns: [United Arab Emirates, United Kingdom, United States, ...]

Individual Country Imports (Tree-Shakable)

// Maximum tree-shaking - only includes US and DE data
import { US, DE } from '@martince/countries/countries';

console.log(US.name); // "United States of America"
console.log(DE.callingCode); // "+49"

Region Queries

import {
  getCountriesByRegion,
  getCountriesBySubregion,
  EU_MEMBERS,
  NATO_MEMBERS,
  SCHENGEN_AREA,
  isEUMember,
  isNATOMember,
} from '@martince/countries/regions';

// Get countries by region
const europeanCountries = getCountriesByRegion('Europe');
const westernEurope = getCountriesBySubregion('Western Europe');

// Check membership
isEUMember('DE'); // true
isEUMember('GB'); // false

// Use grouping arrays directly
console.log(EU_MEMBERS.length); // 27

Validation

import {
  isValidISO2,
  isValidISO3,
  isValidNumeric,
} from '@martince/countries';

isValidISO2('US'); // true
isValidISO2('XX'); // false

Country Object

interface Country {
  iso2: string;        // "US"
  iso3: string;        // "USA"
  isoNumeric: string;  // "840"
  name: string;        // "United States of America"
  region: Region;      // "Americas"
  subregion: Subregion; // "Northern America"
  tld: string[];       // [".us"]
  callingCode: string; // "+1"
  independent: boolean; // true
  unMember: boolean;   // true
}

Data Sources

• Country codes: ISO 3166-1
• Regions/Subregions: UN M49
• Domains: IANA
• Phone prefixes: ITU E.164

License

MIT