country-info-data/dist/index.d.cts

This library helps manage and retrieve continent and country information. It provides methods to fetch details about continents, find countries by continent, and get detailed information about specific countries.

type ContinentName = "Africa" | "Antarctica" | "Asia" | "Europe" | "North America" | "Oceania" | "South America";
type ContinentRegionsMap = {
    AF: [
        "NorthernAfrica",
        "SouthernAfrica",
        "EasternAfrica",
        "WesternAfrica",
        "CentralAfrica"
    ];
    AS: ["EastAsia", "CentralAsia", "SouthAsia", "SoutheastAsia", "WesternAsia"];
    EU: [
        "NorthernEurope",
        "SouthernEurope",
        "EasternEurope",
        "WesternEurope",
        "CentralEurope"
    ];
    NA: ["Caribbean", "CentralAmerica", "NorthAmericaMainland"];
    OC: ["AustraliaAndNewZealand", "Melanesia", "Micronesia", "Polynesia"];
    SA: ["AmazonBasin", "SouthernCone", "AndeanStates"];
};
type RegionCode = ContinentRegionsMap[keyof ContinentRegionsMap][number] | "SubSaharanAfrica";
type ContinentCode = "AF" | "AN" | "AS" | "EU" | "NA" | "OC" | "SA";
type CountryCode = string;
interface CountryDetails {
    name: string;
    code: CountryCode;
    continent?: {
        name: ContinentName;
        code: ContinentCode;
    };
    region?: RegionCode;
}

/**
 * Class to query and filter country information based on various criteria such as continent, region, country code, etc.
 */
declare class CountryInfoQuery {
    private continentCodes;
    private regionCodes;
    private countryCodes;
    private excludeContinents;
    private excludeRegions;
    private excludeCountryCodes;
    private excludeCountryNames;
    private countryNameFilter;
    private sortBy;
    private limitResults;
    private includeDetails;
    private fields;
    /**
     * Filters countries by the specified continent codes.
     * @param continentCodes The continent codes to filter by.
     * @returns The current query instance for method chaining.
     */
    continent(continentCodes: ContinentCode[]): this;
    /**
     * Filters countries by the specified region or regions.
     * @param regionOrRegions The region code or an array of region codes to filter by.
     * @returns The current query instance for method chaining.
     */
    region(regionOrRegions: RegionCode | RegionCode[]): this;
    /**
     * Filters countries by the specified country codes.
     * @param countryCodes The country codes to filter by.
     * @returns The current query instance for method chaining.
     */
    country(countryCodes: string[]): this;
    /**
     * Excludes countries from the result based on the specified continent codes.
     * @param continentCodes The continent codes to exclude.
     * @returns The current query instance for method chaining.
     */
    excludeContinent(continentCodes: ContinentCode[]): this;
    /**
     * Excludes countries from the result based on the specified region codes.
     * @param regionCodes The region codes to exclude.
     * @returns The current query instance for method chaining.
     */
    excludeRegion(regionCodes: RegionCode[]): this;
    /**
     * Filters countries by the specified country name.
     * @param name The country name to filter by.
     * @returns The current query instance for method chaining.
     */
    countryName(name: string): this;
    /**
     * Excludes countries from the result based on the specified country codes.
     * @param countryCodes The country codes to exclude.
     * @returns The current query instance for method chaining.
     */
    excludeCountryCode(countryCodes: string[]): this;
    /**
     * Excludes countries from the result based on the specified country names.
     * @param countryNames The country names to exclude.
     * @returns The current query instance for method chaining.
     */
    excludeCountryName(countryNames: string[]): this;
    /**
     * Sorts the results by country name.
     * @returns The current query instance for method chaining.
     */
    sortByName(): this;
    /**
     * Sorts the results by continent name.
     * @returns The current query instance for method chaining.
     */
    sortByContinent(): this;
    /**
     * Sorts the results by region name.
     * @returns The current query instance for method chaining.
     */
    sortByRegion(): this;
    /**
     * Limits the number of results returned.
     * @param limit The maximum number of results to return.
     * @returns The current query instance for method chaining.
     */
    limit(limit: number): this;
    /**
     * Selects specific fields from the result set to include in the response.
     * @param fields The fields of the `CountryDetails` to include in the result.
     * @returns The current query instance for method chaining.
     */
    selectFields(fields: Array<keyof CountryDetails>): this;
    /**
     * Includes additional details for each country in the result.
     * @returns The current query instance for method chaining.
     */
    withDetails(): this;
    /**
     * Executes the query and returns the filtered and sorted list of countries, either as country names or with full details.
     * @returns A list of country names or full country details based on the applied filters and configurations.
     */
    execute(): (string | CountryDetails)[] | undefined;
}

/**
 * Class representing country and continent data.
 * Provides methods for continent and country lookups.
 */
declare class CountryInfoData {
    /**
     * A record of continent codes and their corresponding names.
     * @private
     */
    private static continents;
    /**
     * Starts a new country info query.
     * @returns A new `CountryInfoQuery` instance.
     */
    static query(): CountryInfoQuery;
    /**
     * A record of continent codes and their corresponding country codes.
     * @private
     */
    private static continentCountries;
    /**
     * A record of country codes and their corresponding country names.
     * @private
     */
    private static countryNames;
    /**
     * A record of country codes and their corresponding continent codes.
     * @private
     */
    private static countryToContinent;
    /**
     * A record of region codes and their corresponding country codes.
     * @private
     */
    private static regionCountries;
    /**
     * Updates country data with new country details.
     * @param countries - The list of country details to update.
     */
    static updateCountryData(countries: CountryDetails[]): void;
    /**
     * Gets the country name by its country code.
     * @param countryCode - The country code to lookup.
     * @returns The country name, or undefined if not found.
     */
    static getCountryNameByCode(countryCode: CountryCode): string | undefined;
    /**
     * Gets the country code by its country name.
     * @param name - The name of the country to lookup.
     * @returns The country code, or undefined if not found.
     */
    static getCountryCodeByName(name: string): CountryCode | undefined;
    /**
     * Gets a list of all country names.
     * @returns An array of country names.
     */
    static getAllCountryNames(): string[];
    /**
     * Gets a list of all country codes.
     * @returns An array of country codes.
     */
    static getAllCountryCodes(): CountryCode[];
    /**
     * Gets a list of all country details (code, name, continent, and region).
     * @returns An array of country details.
     */
    static getAllCountryDetails(): CountryDetails[];
    /**
     * Gets the continent name by its continent code.
     * @param code - The continent code to lookup.
     * @returns The continent name, or undefined if not found.
     */
    static getContinentNameByCode(code: ContinentCode): ContinentName | undefined;
    /**
     * Gets a list of all continent codes.
     * @returns An array of continent codes.
     */
    static getAllContinentCodes(): ContinentCode[];
    /**
     * Gets a list of country codes for a given continent code.
     * @param continentCode - The continent code to lookup.
     * @returns An array of country codes in the continent.
     */
    static getCountryCodesByContinent(continentCode: ContinentCode): CountryCode[];
    /**
     * Gets the continent code for a given country code.
     * @param countryCode - The country code to lookup.
     * @returns The continent code corresponding to the country.
     */
    static getContinentCodeByCountryCode(countryCode: CountryCode): ContinentCode;
    /**
     * Gets a list of country codes for a given continent name.
     * @param continentName - The continent name to lookup.
     * @returns An array of country codes in the continent.
     */
    static getCountryCodesByContinentName(continentName: ContinentName): CountryCode[];
    /**
     * Gets a list of country names for a given continent name.
     * @param continentName - The continent name to lookup.
     * @returns An array of country names in the continent.
     */
    static getCountryNamesByContinentName(continentName: ContinentName): string[];
    /**
     * Gets the continent code for a given continent name.
     * @private
     * @param name - The name of the continent to lookup.
     * @returns The continent code, or undefined if not found.
     */
    private static getContinentCodeByName;
    /**
     * Gets a list of country codes for a given region code.
     * @param region - The region code to lookup.
     * @returns An array of country codes in the region.
     */
    static getCountryCodesByRegion(region: RegionCode): CountryCode[];
    /**
     * Gets a list of country names for a given region code.
     * @param region - The region code to lookup.
     * @returns An array of country names in the region.
     */
    static getCountryNamesByRegion(region: RegionCode): string[];
    /**
     * Gets the region code for a given country name.
     * @param countryName - The country name to lookup.
     * @returns The region code corresponding to the country, or undefined if not found.
     */
    static getRegionByCountryName(countryName: string): RegionCode | undefined;
    /**
     * Checks if a country belongs to a specific continent.
     * @param countryCode - The country code to check.
     * @param continentCode - The continent code to check against.
     * @returns True if the country is in the continent, otherwise false.
     */
    static isCountryInContinent(countryCode: CountryCode, continentCode: ContinentCode): boolean;
    /**
     * Checks if a region belongs to a specific continent.
     * @param region - The region code to check.
     * @param continentCode - The continent code to check against.
     * @returns True if the region belongs to the continent, otherwise false.
     */
    static isRegionInContinent(region: RegionCode, continentCode: ContinentCode): boolean;
    /**
     * Gets the region codes associated with a given continent.
     * @param continentCode - The continent code to lookup.
     * @returns A list of region codes in the continent.
     */
    static getRegionByContinent(continentCode: ContinentCode): RegionCode[];
    /**
     * Searches for countries by a partial country name.
     * @param partialName - The partial country name to search for.
     * @returns An array of country names matching the search.
     */
    static searchCountriesByName(partialName: string): string[];
    /**
     * Gets a list of countries from multiple continents or regions.
     * @param continentCodes - An array of continent codes to include.
     * @param regionCodes - An array of region codes to include.
     * @returns An array of country codes from the specified continents or regions.
     */
    static getCountriesFromMultipleContinentsOrRegions(continentCodes?: ContinentCode[], regionCodes?: RegionCode[]): CountryCode[];
    /**
     * Gets all continent data, including all countries in each continent.
     * @returns A record of continent names and their corresponding country names.
     */
    static getAllContinentData(): Record<string, string[]>;
    /**
     * Gets the region code for a given country code.
     * @param countryCode - The country code to lookup.
     * @returns The region code corresponding to the country.
     */
    static getRegionByCountryCode(countryCode: CountryCode): RegionCode;
    /**
     * Finds country details by location.
     * @param location - The continent name, region name, country name, or country code to search for.
     * @returns An array of country details including code, name, continent (name and code), and region code.
     */
    static findCountryDetailsByLocation(location: string): CountryDetails[];
}

export { type ContinentCode, type ContinentName, type CountryCode, type CountryDetails, CountryInfoQuery, type RegionCode, CountryInfoData as default };