tessl/npm-i18n-iso-countries

i18n for ISO 3166-1 country codes with support for 79 languages and bidirectional conversion between Alpha-2, Alpha-3, and Numeric codes

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Code Listings and Validation

Name: tessl/npm-i18n-iso-countries
Author: tessl

Access complete mappings of country codes and validate country code formats and existence. Provides comprehensive reference data and validation utilities for all ISO 3166-1 country codes.

Capabilities

Get Alpha-2 Code Mappings

Retrieves a complete mapping of Alpha-2 codes to their corresponding Alpha-3 codes.

/**
 * Get mapping of Alpha-2 codes to Alpha-3 codes
 * @returns Object where keys are Alpha-2 codes and values are Alpha-3 codes
 */
function getAlpha2Codes(): { [alpha2Key: string]: string };

Usage Examples:

const countries = require("i18n-iso-countries");

const alpha2Mappings = countries.getAlpha2Codes();

// Access specific mappings
console.log(alpha2Mappings.US);    // "USA"
console.log(alpha2Mappings.DE);    // "DEU"
console.log(alpha2Mappings.GB);    // "GBR"
console.log(alpha2Mappings.JP);    // "JPN"

// Iterate through all mappings
Object.entries(alpha2Mappings).forEach(([alpha2, alpha3]) => {
  console.log(`${alpha2} -> ${alpha3}`);
});
// Output: AF -> AFG, AL -> ALB, DZ -> DZA, ...

// Check if a code exists
if (alpha2Mappings.hasOwnProperty('US')) {
  console.log('US is a valid Alpha-2 code');
}

// Get all Alpha-2 codes
const allAlpha2Codes = Object.keys(alpha2Mappings);
console.log(allAlpha2Codes.length); // 249 countries
console.log(allAlpha2Codes.slice(0, 5)); // ["AF", "AL", "DZ", "AS", "AD"]

Get Alpha-3 Code Mappings

Retrieves a complete mapping of Alpha-3 codes to their corresponding Alpha-2 codes.

/**
 * Get mapping of Alpha-3 codes to Alpha-2 codes
 * @returns Object where keys are Alpha-3 codes and values are Alpha-2 codes
 */
function getAlpha3Codes(): { [alpha3Key: string]: string };

Usage Examples:

const countries = require("i18n-iso-countries");

const alpha3Mappings = countries.getAlpha3Codes();

// Access specific mappings
console.log(alpha3Mappings.USA);    // "US"
console.log(alpha3Mappings.DEU);    // "DE"
console.log(alpha3Mappings.GBR);    // "GB"
console.log(alpha3Mappings.JPN);    // "JP"

// Iterate through all mappings
Object.entries(alpha3Mappings).forEach(([alpha3, alpha2]) => {
  console.log(`${alpha3} -> ${alpha2}`);
});
// Output: AFG -> AF, ALB -> AL, DZA -> DZ, ...

// Check if a code exists
if (alpha3Mappings.hasOwnProperty('USA')) {
  console.log('USA is a valid Alpha-3 code');
}

// Get all Alpha-3 codes
const allAlpha3Codes = Object.keys(alpha3Mappings);
console.log(allAlpha3Codes.length); // 249 countries
console.log(allAlpha3Codes.slice(0, 5)); // ["AFG", "ALB", "DZA", "ASM", "AND"]

Get Numeric Code Mappings

Retrieves a complete mapping of Numeric codes to their corresponding Alpha-2 codes.

/**
 * Get mapping of Numeric codes to Alpha-2 codes
 * @returns Object where keys are 3-digit Numeric codes (strings) and values are Alpha-2 codes
 */
function getNumericCodes(): { [numericKey: string]: string };

Usage Examples:

const countries = require("i18n-iso-countries");

const numericMappings = countries.getNumericCodes();

// Access specific mappings
console.log(numericMappings["840"]);  // "US"
console.log(numericMappings["276"]);  // "DE"
console.log(numericMappings["826"]);  // "GB"
console.log(numericMappings["392"]);  // "JP"

// Note: All numeric codes are 3-digit padded strings
console.log(numericMappings["004"]);  // "AF" (Afghanistan)
console.log(numericMappings["008"]);  // "AL" (Albania)
console.log(numericMappings["012"]);  // "DZ" (Algeria)

// Iterate through all mappings
Object.entries(numericMappings).forEach(([numeric, alpha2]) => {
  console.log(`${numeric} -> ${alpha2}`);
});
// Output: 004 -> AF, 008 -> AL, 012 -> DZ, ...

// Get all numeric codes
const allNumericCodes = Object.keys(numericMappings);
console.log(allNumericCodes.length); // 249 countries
console.log(allNumericCodes.slice(0, 5)); // ["004", "008", "012", "016", "020"]

// Convert to numbers if needed
const numericAsNumbers = allNumericCodes.map(code => parseInt(code, 10));
console.log(numericAsNumbers.slice(0, 5)); // [4, 8, 12, 16, 20]

Country Code Validation

Validates whether a given code is a valid country code in any format (Alpha-2, Alpha-3, or Numeric).

/**
 * Validate if a code is a valid country code
 * @param code - Country code to validate (any format)
 * @returns true if valid, false otherwise
 */
function isValid(code: string | number): boolean;

Usage Examples:

const countries = require("i18n-iso-countries");

// Valid Alpha-2 codes
console.log(countries.isValid("US"));    // true
console.log(countries.isValid("DE"));    // true
console.log(countries.isValid("GB"));    // true

// Valid Alpha-3 codes
console.log(countries.isValid("USA"));   // true
console.log(countries.isValid("DEU"));   // true
console.log(countries.isValid("GBR"));   // true

// Valid Numeric codes (string)
console.log(countries.isValid("840"));   // true
console.log(countries.isValid("276"));   // true
console.log(countries.isValid("004"));   // true

// Valid Numeric codes (number)
console.log(countries.isValid(840));     // true
console.log(countries.isValid(276));     // true
console.log(countries.isValid(4));       // true (treated as "004")

// Case insensitive for strings
console.log(countries.isValid("us"));    // true
console.log(countries.isValid("USA"));   // true
console.log(countries.isValid("deu"));   // true

// Invalid codes
console.log(countries.isValid("XX"));    // false
console.log(countries.isValid("XXX"));   // false
console.log(countries.isValid("999"));   // false
console.log(countries.isValid(999));     // false
console.log(countries.isValid(""));      // false
console.log(countries.isValid(null));    // false
console.log(countries.isValid(undefined)); // false

// Validation for form input
function validateCountryInput(input) {
  if (!input) {
    return { valid: false, message: 'Country code is required' };
  }
  
  if (countries.isValid(input)) {
    return { valid: true, code: input.toString().toUpperCase() };
  }
  
  return { valid: false, message: 'Invalid country code format' };
}

console.log(validateCountryInput("us"));    // { valid: true, code: "US" }
console.log(validateCountryInput("xyz"));   // { valid: false, message: "Invalid country code format" }

Data Structure and Coverage

Country Code Coverage

The library provides complete coverage of ISO 3166-1 country codes:

249 Countries: All officially assigned ISO 3166-1 entries
Alpha-2 Codes: 2-character codes (e.g., "US", "DE", "GB")
Alpha-3 Codes: 3-character codes (e.g., "USA", "DEU", "GBR")
Numeric Codes: 3-digit numeric codes (e.g., "840", "276", "826")

Code Format Standards

Alpha-2: Uppercase letters only, exactly 2 characters
Alpha-3: Uppercase letters only, exactly 3 characters
Numeric: Zero-padded 3-digit strings ("004", "008", etc.)
Case Handling: All validation is case-insensitive, automatically converted to uppercase

Relationship Integrity

All code mappings maintain perfect bidirectional relationships:

const countries = require("i18n-iso-countries");

// Verify bidirectional consistency
const alpha2Codes = countries.getAlpha2Codes();
const alpha3Codes = countries.getAlpha3Codes();
const numericCodes = countries.getNumericCodes();

// For any Alpha-2 code, the relationship is consistent
Object.entries(alpha2Codes).forEach(([alpha2, alpha3]) => {
  // Alpha-2 -> Alpha-3 -> Alpha-2 should be identity
  console.log(alpha3Codes[alpha3] === alpha2); // Always true
  
  // Find corresponding numeric code
  const numeric = Object.keys(numericCodes).find(num => numericCodes[num] === alpha2);
  if (numeric) {
    console.log(countries.numericToAlpha2(numeric) === alpha2); // Always true
    console.log(countries.numericToAlpha3(numeric) === alpha3); // Always true
  }
});

Performance Characteristics

Lookup Performance

getAlpha2Codes(): O(1) - Returns pre-built object reference
getAlpha3Codes(): O(1) - Returns pre-built object reference
getNumericCodes(): O(1) - Returns pre-built object reference
isValid(): O(1) - Direct hash table lookups

Memory Usage

Shared Data: All functions share the same underlying data structures
No Duplication: Code mappings are stored once and referenced multiple ways
Efficient Storage: Uses JavaScript object properties for O(1) access

Initialization

Node.js: All data pre-loaded during module initialization
Browser: Data available immediately after locale registration
No Lazy Loading: All mappings are available synchronously

Integration Examples

Form Validation

function validateCountryForm(formData) {
  const { countryCode, countryName, language } = formData;
  
  // Validate country code format
  if (!countries.isValid(countryCode)) {
    return { valid: false, field: 'countryCode', message: 'Invalid country code' };
  }
  
  // Validate country name matches code
  const expectedCode = countries.getAlpha2Code(countryName, language);
  const normalizedCode = countries.toAlpha2(countryCode);
  
  if (expectedCode !== normalizedCode) {
    return { valid: false, field: 'countryName', message: 'Country name does not match code' };
  }
  
  return { valid: true };
}

Data Export/Import

function exportCountryData() {
  return {
    alpha2Mappings: countries.getAlpha2Codes(),
    alpha3Mappings: countries.getAlpha3Codes(),
    numericMappings: countries.getNumericCodes(),
    supportedLanguages: countries.getSupportedLanguages(),
    exportDate: new Date().toISOString()
  };
}

function validateImportedCountryCodes(codes) {
  const invalidCodes = codes.filter(code => !countries.isValid(code));
  return {
    valid: invalidCodes.length === 0,
    invalidCodes: invalidCodes,
    validCount: codes.length - invalidCodes.length
  };
}