country-phone-codes/dist/index.d.ts

[DEPRECATED] A modern, TypeScript-first library providing ISO 3166-1 alpha-2 country codes to international calling codes mapping

/**
 * ISO 3166-1 alpha-2 country code (e.g., 'US', 'IN')
 */
type CountryCodeA2 = string;
/**
 * International phone code with '+' prefix (e.g., '+1', '+91')
 */
type InternationalPhoneCode = string;
/**
 * Map of ISO 3166-1 alpha-2 country codes to their international phone codes
 */
interface CountryPhoneCodeMapData {
    [countryCode: CountryCodeA2]: InternationalPhoneCode;
}
/**
 * Reverse map of international phone codes to the countries that use them
 */
type ReversePhoneCodeMap = Record<InternationalPhoneCode, CountryCodeA2[]>;

/**
 * Map of ISO 3166-1 alpha-2 country codes to their international phone codes.
 * This dataset is based on ITU-T E.164 assignments.
 */
declare const countryPhoneCodesMap: Readonly<CountryPhoneCodeMapData>;

/**
 * Normalizes a phone code to ensure it has the proper format.
 *
 * This function attempts to clean the input by removing common non-digit
 * characters (spaces, hyphens, parentheses), ensuring it starts with a '+',
 * and contains only digits after the '+'.
 *
 * @param code The phone code string to normalize
 * @returns The normalized phone code or undefined if it can't be reasonably normalized
 *
 * @example
 * normalizePhoneCode('1') // returns '+1'
 * normalizePhoneCode('+44') // returns '+44'
 * normalizePhoneCode('(0049) 123') // returns '+49123'
 * normalizePhoneCode('49 123-456') // returns '+49123456'
 * normalizePhoneCode('abc') // returns undefined
 */
declare function normalizePhoneCode(code: string): InternationalPhoneCode | undefined;
/**
 * Gets the international phone code for a given country code.
 *
 * @param countryCode ISO 3166-1 alpha-2 country code (case-insensitive)
 * @returns The international phone code or undefined if the country code is not found
 *
 * @example
 * getPhoneCode('US') // returns '+1'
 * getPhoneCode('in') // returns '+91'
 * getPhoneCode('XX') // returns undefined
 */
declare function getPhoneCode(countryCode: string): InternationalPhoneCode | undefined;
/**
 * Gets all countries that use a specific phone code.
 *
 * @param phoneCode The international phone code to look up
 * @returns An array of country codes that use this phone code, or an empty array if none
 *
 * @example
 * getCountriesByPhoneCode('+1') // returns ['US', 'CA', 'AG', ...]
 * getCountriesByPhoneCode('44') // returns ['GB', 'IM']
 * getCountriesByPhoneCode('+999') // returns []
 */
declare function getCountriesByPhoneCode(phoneCode: string): CountryCodeA2[];
/**
 * Gets an array of all unique international phone codes.
 *
 * @returns Array of all unique phone codes in the dataset
 *
 * @example
 * getAllPhoneCodes() // returns ['+1', '+7', '+20', '+27', ...]
 */
declare function getAllPhoneCodes(): InternationalPhoneCode[];
/**
 * Checks if the provided string is a valid international phone code.
 *
 * @param phoneCode The phone code to validate
 * @returns True if the phone code is valid, false otherwise
 *
 * @example
 * isValidPhoneCode('+1') // returns true
 * isValidPhoneCode('44') // returns true (normalized to '+44')
 * isValidPhoneCode('+999') // returns false
 */
declare function isValidPhoneCode(phoneCode: string): boolean;

export { type CountryCodeA2, type CountryPhoneCodeMapData, type InternationalPhoneCode, type ReversePhoneCodeMap, countryPhoneCodesMap, getAllPhoneCodes, getCountriesByPhoneCode, getPhoneCode, isValidPhoneCode, normalizePhoneCode };