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

code-conversion.mddocs/

Code Conversion

Convert between different country code formats including Alpha-2, Alpha-3, and Numeric codes with intelligent auto-detection. All conversions are based on ISO 3166-1 standard mappings.

Capabilities

Alpha-2 to Alpha-3 Conversion

Converts ISO 3166-1 Alpha-2 codes to Alpha-3 codes.

/**
 * Convert Alpha-2 to Alpha-3 code
 * @param code - Alpha-2 country code (e.g., "US")
 * @returns Alpha-3 code or undefined if invalid
 */
function alpha2ToAlpha3(code: string | Alpha2Code): string | undefined;

Usage Examples:

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

// Standard conversions
console.log(countries.alpha2ToAlpha3("US"));  // "USA"
console.log(countries.alpha2ToAlpha3("DE"));  // "DEU"
console.log(countries.alpha2ToAlpha3("GB"));  // "GBR"
console.log(countries.alpha2ToAlpha3("JP"));  // "JPN"

// Case insensitive
console.log(countries.alpha2ToAlpha3("us"));  // "USA"
console.log(countries.alpha2ToAlpha3("Us"));  // "USA"

// Invalid codes
console.log(countries.alpha2ToAlpha3("XX"));  // undefined
console.log(countries.alpha2ToAlpha3(""));    // undefined

Alpha-3 to Alpha-2 Conversion

Converts ISO 3166-1 Alpha-3 codes to Alpha-2 codes.

/**
 * Convert Alpha-3 to Alpha-2 code
 * @param code - Alpha-3 country code (e.g., "USA")
 * @returns Alpha-2 code or undefined if invalid
 */
function alpha3ToAlpha2(code: string | Alpha3Code): string | undefined;

Usage Examples:

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

// Standard conversions
console.log(countries.alpha3ToAlpha2("USA"));  // "US"
console.log(countries.alpha3ToAlpha2("DEU"));  // "DE"
console.log(countries.alpha3ToAlpha2("GBR"));  // "GB"
console.log(countries.alpha3ToAlpha2("JPN"));  // "JP"

// Case insensitive
console.log(countries.alpha3ToAlpha2("usa"));  // "US"
console.log(countries.alpha3ToAlpha2("Deu"));  // "DE"

// Invalid codes
console.log(countries.alpha3ToAlpha2("XXX"));  // undefined
console.log(countries.alpha3ToAlpha2(""));     // undefined

Alpha-2 to Numeric Conversion

Converts ISO 3166-1 Alpha-2 codes to Numeric codes.

/**
 * Convert Alpha-2 to Numeric code
 * @param code - Alpha-2 country code (e.g., "US")
 * @returns Numeric code as string or undefined if invalid
 */
function alpha2ToNumeric(code: string | Alpha2Code): string | undefined;

Usage Examples:

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

// Standard conversions
console.log(countries.alpha2ToNumeric("US"));  // "840"
console.log(countries.alpha2ToNumeric("DE"));  // "276"
console.log(countries.alpha2ToNumeric("SE"));  // "752"
console.log(countries.alpha2ToNumeric("AF"));  // "004"

// Returns padded 3-digit strings
console.log(countries.alpha2ToNumeric("DZ"));  // "012"
console.log(countries.alpha2ToNumeric("AD"));  // "020"

// Invalid codes
console.log(countries.alpha2ToNumeric("XX"));  // undefined

Alpha-3 to Numeric Conversion

Converts ISO 3166-1 Alpha-3 codes to Numeric codes.

/**
 * Convert Alpha-3 to Numeric code
 * @param code - Alpha-3 country code (e.g., "USA")
 * @returns Numeric code as string or undefined if invalid
 */
function alpha3ToNumeric(code: string | Alpha3Code): string | undefined;

Usage Examples:

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

// Standard conversions
console.log(countries.alpha3ToNumeric("USA"));  // "840"
console.log(countries.alpha3ToNumeric("DEU"));  // "276"
console.log(countries.alpha3ToNumeric("SWE"));  // "752"
console.log(countries.alpha3ToNumeric("DJI"));  // "262"

// Invalid codes
console.log(countries.alpha3ToNumeric("XXX"));  // undefined

Numeric to Alpha-2 Conversion

Converts ISO 3166-1 Numeric codes to Alpha-2 codes.

/**
 * Convert Numeric to Alpha-2 code
 * @param code - Numeric country code (number or string)
 * @returns Alpha-2 code or undefined if invalid
 */
function numericToAlpha2(code: number | string): string | undefined;

Usage Examples:

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

// Standard conversions (string)
console.log(countries.numericToAlpha2("840"));  // "US"
console.log(countries.numericToAlpha2("276"));  // "DE"
console.log(countries.numericToAlpha2("752"));  // "SE"

// Standard conversions (number)
console.log(countries.numericToAlpha2(840));    // "US"
console.log(countries.numericToAlpha2(276));    // "DE"

// Handles leading zeros and padding
console.log(countries.numericToAlpha2("004"));  // "AF"
console.log(countries.numericToAlpha2("012"));  // "DZ"  
console.log(countries.numericToAlpha2(4));      // "AF"
console.log(countries.numericToAlpha2(12));     // "DZ"

// Invalid codes
console.log(countries.numericToAlpha2("999"));  // undefined
console.log(countries.numericToAlpha2(999));    // undefined

Numeric to Alpha-3 Conversion

Converts ISO 3166-1 Numeric codes to Alpha-3 codes.

/**
 * Convert Numeric to Alpha-3 code
 * @param code - Numeric country code (number or string)
 * @returns Alpha-3 code or undefined if invalid
 */
function numericToAlpha3(code: number | string): string | undefined;

Usage Examples:

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

// Standard conversions
console.log(countries.numericToAlpha3("840"));  // "USA"
console.log(countries.numericToAlpha3("276"));  // "DEU"
console.log(countries.numericToAlpha3(840));    // "USA"
console.log(countries.numericToAlpha3(276));    // "DEU"

// Handles leading zeros
console.log(countries.numericToAlpha3("004"));  // "AFG"
console.log(countries.numericToAlpha3(4));      // "AFG"

// Invalid codes
console.log(countries.numericToAlpha3("999"));  // undefined

Smart Code Conversion

Intelligent conversion functions that auto-detect input format and convert to the desired output format.

/**
 * Convert any country code format to Alpha-2
 * @param code - Alpha-2, Alpha-3, or Numeric code (string or number)
 * @returns Alpha-2 code or undefined if invalid
 */
function toAlpha2(code: string | number | Alpha2Code | Alpha3Code): string | undefined;

/**
 * Convert any country code format to Alpha-3
 * @param code - Alpha-2, Alpha-3, or Numeric code (string or number)
 * @returns Alpha-3 code or undefined if invalid
 */
function toAlpha3(code: string | number | Alpha2Code | Alpha3Code): string | undefined;

Usage Examples:

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

// toAlpha2 - Auto-detects input format
console.log(countries.toAlpha2("US"));    // "US" (Alpha-2 passthrough)
console.log(countries.toAlpha2("USA"));   // "US" (Alpha-3 to Alpha-2)
console.log(countries.toAlpha2("840"));   // "US" (Numeric string to Alpha-2)
console.log(countries.toAlpha2(840));     // "US" (Numeric number to Alpha-2)

// toAlpha3 - Auto-detects input format
console.log(countries.toAlpha3("US"));    // "USA" (Alpha-2 to Alpha-3)
console.log(countries.toAlpha3("USA"));   // "USA" (Alpha-3 passthrough)
console.log(countries.toAlpha3("840"));   // "USA" (Numeric string to Alpha-3)
console.log(countries.toAlpha3(840));     // "USA" (Numeric number to Alpha-3)

// Works with all supported codes
console.log(countries.toAlpha2("DEU"));   // "DE"
console.log(countries.toAlpha3("DE"));    // "DEU"
console.log(countries.toAlpha2(276));     // "DE"
console.log(countries.toAlpha3(276));     // "DEU"

// Invalid inputs return undefined
console.log(countries.toAlpha2("XX"));    // undefined
console.log(countries.toAlpha3("XXX"));   // undefined
console.log(countries.toAlpha2(999));     // undefined
console.log(countries.toAlpha3(true));    // undefined

Input Format Detection

The smart conversion functions (

toAlpha2()
and 
toAlpha3()
) use the following logic to detect input format:

  • Numeric Detection: String containing only digits or numeric type
  • Alpha-2 Detection: String with exactly 2 characters
  • Alpha-3 Detection: String with exactly 3 characters
  • Case Handling: All string inputs are converted to uppercase before processing
  • Invalid Types: Non-string, non-number inputs return 
    undefined

Error Handling

All conversion functions handle errors gracefully:

  • Invalid country codes return 
    undefined
  • Invalid input types return 
    undefined
  • No exceptions are thrown for invalid inputs
  • Case-insensitive string matching (automatically converted to uppercase)

Performance Notes

  • All conversions use pre-built lookup tables for O(1) performance
  • No external API calls or file system access during conversion
  • Smart conversion functions have minimal overhead for format detection
  • All functions are synchronous