or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

code-conversion.mdindex.mdlistings-validation.mdlocale-management.mdname-retrieval.mdname-to-code.md
tile.json

listings-validation.mddocs/

Code Listings and Validation

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
  };
}