country-kit/dist/utils.d.ts

A lightweight TypeScript library providing comprehensive country data including ISO codes, names, calling codes, and flag emojis.

import { Country, CountryCode, CountrySearchOptions } from "./types";
/**
 * Validates if the provided string is a valid ISO 3166-1 alpha-2 country code
 * @param {string} code - The country code to validate (case insensitive)
 * @returns {boolean} Returns true if the code is a valid ISO 3166-1 alpha-2 country code, false otherwise
 * @example
 * isValidCountryCode('US') // returns true
 * isValidCountryCode('XX') // returns false
 * isValidCountryCode('') // returns false
 */
export declare const isValidCountryCode: (code: string) => boolean;
/**
 * Creates a flag emoji from a two-letter country code using Unicode regional indicator symbols
 * @param {string} code - Two-letter country code (case insensitive)
 * @returns {string} Unicode flag emoji representation
 * @example
 * getFlag('US') // returns '🇺🇸'
 * getFlag('gb') // returns '🇬🇧'
 */
export declare const getFlag: (code: string) => string;
/**
* Retrieves the country name for a given ISO 3166-1 alpha-2 country code
* @param {CountryCode} code - The ISO 3166-1 alpha-2 country code (case insensitive)
* @returns {string | undefined} The country name if found, undefined if the code is invalid
* @example
* getCountryName('US') // returns 'United States'
* getCountryName('GB') // returns 'United Kingdom'
* getCountryName('XX') // returns undefined and logs error
*/
export declare const getCountryName: (code: CountryCode) => string | undefined;
/**
 * Retrieves complete country information for a given ISO 3166-1 alpha-2 country code
 * @param {CountryCode} code - The ISO 3166-1 alpha-2 country code (case insensitive)
 * @returns {Country | undefined} Object containing country information if found, undefined if the code is invalid
 * @example
 * getCountryByCode('US')
 * // returns {
 * //   code: 'US',
 * //   name: 'United States',
 * //   alpha3: 'USA',
 * //   callingCode: '+1',
 * //   flag: '🇺🇸'
 * // }
 */
export declare const getCountryByCode: (code: CountryCode) => Country | undefined;
/**
 * Searches for countries by name or code using a case-insensitive match
 * @param {string} query - Search query string to match against country names and codes
 * @param {CountrySearchOptions} options - Search configuration options
 * @returns {Country[]} Array of country objects matching the search query
 * @example
 * searchCountries('united') // returns countries with 'united' in their name
 * searchCountries('us', { includeCodes: true }) // returns United States
 * searchCountries('united', { exact: true }) // returns exact matches only
 * searchCountries('united', { limit: 2 }) // returns max 2 results
 */
export declare const searchCountries: (query?: string | null, options?: CountrySearchOptions) => Country[];
/**
 * Retrieves the international calling code for a given country code
 * @param {CountryCode} code - The ISO 3166-1 alpha-2 country code (case insensitive)
 * @returns {string | undefined} The calling code with '+' prefix if found, undefined if the code is invalid
 * @example
 * getCallingCode('US') // returns '+1'
 * getCallingCode('GB') // returns '+44'
 * getCallingCode('XX') // returns undefined and logs error
 */
export declare const getCallingCode: (code: CountryCode) => string | undefined;
/**
 * Retrieves the ISO 3166-1 alpha-3 code for a given alpha-2 country code
 * @param {CountryCode} code - The ISO 3166-1 alpha-2 country code (case insensitive)
 * @returns {string | undefined} The ISO 3166-1 alpha-3 code if found, undefined if the code is invalid
 * @example
 * getAlpha3Code('US') // returns 'USA'
 * getAlpha3Code('GB') // returns 'GBR'
 * getAlpha3Code('XX') // returns undefined and logs error
 */
export declare const getAlpha3Code: (code: CountryCode) => string | undefined;
/**
 * Retrieves the flag emoji for a given country code
 * @param {CountryCode} code - The ISO 3166-1 alpha-2 country code (case insensitive)
 * @returns {string | undefined} Unicode flag emoji if found, undefined if the code is invalid
 * @example
 * getCountryFlag('US') // returns '🇺🇸'
 * getCountryFlag('GB') // returns '🇬🇧'
 * getCountryFlag('XX') // returns undefined and logs error
 */
export declare const getCountryFlag: (code: CountryCode) => string | undefined;
/**
 * Retrieves an array of all available countries with their complete information
 * @returns {Country[]} Array of country objects containing complete information for all supported countries
 * @example
 * getAllCountries()
 * // returns [
 * //   {
 * //     code: 'AD',
 * //     name: 'Andorra',
 * //     alpha3: 'AND',
 * //     callingCode: '+376',
 * //     flag: '🇦🇩'
 * //   },
 * //   ...
 * // ]
 */
export declare const getAllCountries: () => Country[];
/**
 * Groups all countries by their geographical region/continent
 * @returns {Record<string, Country[]>} Object with region names as keys and arrays of countries as values
 * @example
 * getCountriesByRegion()
 * // returns {
 * //   'Europe': [{ code: 'AD', name: 'Andorra', ... }, ...],
 * //   'Asia': [{ code: 'AF', name: 'Afghanistan', ... }, ...],
 * //   ...
 * // }
 * @todo Implementation pending - requires additional region data
 */
export declare const getCountriesByRegion: () => Record<string, Country[]>;
/**
 * Validates if a string matches the format of an international calling code
 * @param {string} callingCode - The calling code to validate (must start with '+' followed by 1-4 digits)
 * @returns {boolean} True if the calling code format is valid, false otherwise
 * @example
 * isValidCallingCode('+1') // returns true
 * isValidCallingCode('+44') // returns true
 * isValidCallingCode('44') // returns false
 * isValidCallingCode('+12345') // returns false
 */
export declare const isValidCallingCode: (callingCode: string) => boolean;
/**
 * Finds all countries that share a specific calling code
 * @param {string} callingCode - The calling code to search for (must include '+' prefix)
 * @returns {Country[]} Array of countries that use the specified calling code
 * @example
 * getCountriesByCallingCode('+1')
 * // returns [
 * //   { code: 'US', name: 'United States', ... },
 * //   { code: 'CA', name: 'Canada', ... },
 * //   ...
 * // ]
 */
export declare const getCountriesByCallingCode: (callingCode: string) => Country[];