@yusifaliyevpro/countries/dist/index.d.ts

TypeScript wrapper for Rest Countries API to fetch country data by codes, capitals, or all countries with full typings.

import { Capital, Code, Country, CountryPicker, Currency, Lang, Region, Subregion } from "./index-DZKnf4Hx.js";

//#region src/functions/getCountries.d.ts

/**
 * Fetches all countries, optionally filtered by independence status,
 * and including only the specified fields.
 *
 * > **Note:** The `fields` parameter is required and you can only specify upto 10 fields,
 * as mandated by Alejandro Matos See: {@link https://gitlab.com/restcountries/restcountries/-/issues/265}.
 *
 * @param params - An object containing:
 *   - `fields`: A required array of field names (keys from the `Country` type) to include in the response.
 *   - `independent`: If true, only includes independent countries; if false, only dependent ones.
 *
 * @param fetchOptions - Optional `RequestInit` object to customize the `fetch` request.
 *
 * @returns A promise that resolves to an array of `CountryPicker<T>` objects with the requested fields,
 *          or `null` if the request fails or no countries match the criteria.
 *
 * @example
 * // Get all countries with only the `name` and `area` fields
 * const countries = await getCountries({ fields: ["name", "area"] });
 *
 * @example
 * // Get all independent countries with only the `name` and `area` fields
 * const independentCountries = await getCountries({
 *   independent: true,
 *   fields: ["name", "area"]
 * });
 */
declare function getCountries<T extends readonly (keyof Country)[] & {
  length: 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10;
}>({
  independent,
  fields
}: {
  independent?: boolean;
  fields: T;
}, fetchOptions?: RequestInit): Promise<CountryPicker<T>[] | null>;
//#endregion
//#region src/functions/getCountriesByCodes.d.ts
/**
 * Fetches countries by their codes (e.g., CCA2, CCA3, or CIOC), optionally including only the specified fields.
 *
 * > **Note:** If `fields` is not provided, all available fields will be returned.
 *
 * @param params - An object containing:
 *   - `codes`: An array of country codes to fetch data for. CCA3 is recommended for precision.
 *   - `fields`: An optional array of field names (keys from the `Country` type) to include in the response.
 *
 * @param fetchOptions - Optional `RequestInit` object to customize the `fetch` request.
 *
 * @returns A promise that resolves to an array of `CountryPicker<T>` objects with the requested fields,
 *          or `null` if the request fails or the countries are not found.
 *
 * @example
 * // Get countries by CCA3 codes with only `name` and `flags` fields
 * const countries = await getCountriesByCodes({
 *   codes: ["USA", "FRA", "JPN"],
 *   fields: ["name", "flags"]
 * });
 *
 * @example
 * // Get countries by CCA2 codes with all fields
 * const countries = await getCountriesByCodes({ codes: ["US", "FR", "JP"] });
 */
declare function getCountriesByCodes<T extends readonly (keyof Country)[]>({
  codes,
  fields
}: {
  codes: Code[];
  fields?: T;
}, fetchOptions?: RequestInit): Promise<CountryPicker<T>[] | null>;
//#endregion
//#region src/functions/getCountriesByCurrency.d.ts
/**
 * Fetches countries that use the specified currency, optionally including only the specified fields.
 *
 * > **Note:** If `fields` is not provided, all available fields will be returned.
 *
 * @param params - An object containing:
 *   - `currency`: The currency code (e.g., "USD", "EUR", "JPY") used to filter countries.
 *   - `fields`: An optional array of field names (keys from the `Country` type) to include in the response.
 *
 * @param fetchOptions - Optional `RequestInit` object to customize the `fetch` request.
 *
 * @returns A promise that resolves to an array of `CountryPicker<T>` objects with the requested fields,
 *          or `null` if the request fails or no countries use the specified currency.
 *
 * @example
 * // Get countries using the Euro with only `name` and `flags` fields
 * const euroCountries = await getCountriesByCurrency({
 *   currency: "EUR",
 *   fields: ["name", "flags"]
 * });
 *
 * @example
 * // Get countries using the Japanese Yen with all fields
 * const yenCountries = await getCountriesByCurrency({ currency: "JPY" });
 */
declare function getCountriesByCurrency<T extends readonly (keyof Country)[]>({
  currency,
  fields
}: {
  currency: Currency;
  fields?: T;
}, fetchOptions?: RequestInit): Promise<CountryPicker<T>[] | null>;
//#endregion
//#region src/functions/getCountriesByLang.d.ts
/**
 * Fetches countries where the specified language is officially or widely spoken,
 * optionally including only the specified fields.
 *
 * > **Note:** If `fields` is not provided, all available fields will be returned.
 *
 * @param params - An object containing:
 *   - `lang`: (e.g., "Spanish", "English", "Azerbaijani").
 *   - `fields`: An optional array of field names (keys from the `Country` type) to include in the response.
 *
 * @param fetchOptions - Optional `RequestInit` object to customize the `fetch` request.
 *
 * @returns A promise that resolves to an array of `CountryPicker<T>` objects with the requested fields,
 *          or `null` if the request fails or no countries match the language criteria.
 *
 * @example
 * // Get countries where Spanish is spoken with `name` and `region` fields
 * const spanishSpeakingCountries = await getCountriesByLang({
 *   lang: "spa",
 *   fields: ["name", "region"]
 * });
 *
 * @example
 * // Get countries where English is spoken with all fields
 * const englishSpeakingCountries = await getCountriesByLang({ lang: "en" });
 */
declare function getCountriesByLang<T extends readonly (keyof Country)[]>({
  lang,
  fields
}: {
  lang: Lang;
  fields?: T;
}, fetchOptions?: RequestInit): Promise<CountryPicker<T>[] | null>;
//#endregion
//#region src/functions/getCountriesByName.d.ts
/**
 * Fetches countries that match a given name or partial name,
 * optionally including only the specified fields.
 *
 * > **Note:** If `fields` is not provided, all available fields will be returned.
 * > Set `fullText` to `true` to require an exact, full-name match.
 *
 * @param params - An object containing:
 *   - `name`: The country name or partial name to search for (e.g., "united").
 *   - `fullText`: Optional boolean to indicate whether to match full names exactly.
 *   - `fields`: An optional array of field names (keys from the `Country` type) to include in the response.
 *
 * @param fetchOptions - Optional `RequestInit` object to customize the `fetch` request.
 *
 * @returns A promise that resolves to an array of `CountryPicker<T>` objects with the requested fields,
 *          or `null` if the request fails or no countries match the name.
 *
 * @example
 * // Search countries containing "united" with only `name` and `flags` fields
 * const results = await getCountriesByName({
 *   name: "united",
 *   fields: ["name", "flags"]
 * });
 *
 * @example
 * // Search for exact match of "Finland" with all fields
 * const country = await getCountriesByName({ name: "Finland", fullText: true });
 */
declare function getCountriesByName<T extends readonly (keyof Country)[]>({
  name,
  fullText,
  fields
}: {
  name: string;
  fullText?: boolean;
  fields?: T;
}, fetchOptions?: RequestInit): Promise<CountryPicker<T>[] | null>;
//#endregion
//#region src/functions/getCountriesByRegion.d.ts
/**
 * Fetches countries which belong to the specified world region,
 * optionally including only the specified fields.
 *
 * > **Note:** If `fields` is not provided, all available fields will be returned.
 *
 * @param params - An object containing:
 *   - `region`: The name of the region (e.g., "Asia", "Europe", "Africa") to filter countries by.
 *   - `fields`: An optional array of field names (keys from the `Country` type) to include in the response.
 *
 * @param fetchOptions - Optional `RequestInit` object to customize the `fetch` request.
 *
 * @returns A promise that resolves to an array of `CountryPicker<T>` objects with the requested fields,
 *          or `null` if the request fails or the region is not found.
 *
 * @example
 * // Get Asian countries with only `name` and `population` fields
 * const asianCountries = await getCountriesByRegion({
 *   region: "Asia",
 *   fields: ["name", "population"]
 * });
 *
 * @example
 * // Get all fields for countries in Europe
 * const europeanCountries = await getCountriesByRegion({ region: "Europe" });
 */
declare function getCountriesByRegion<T extends readonly (keyof Country)[]>({
  region,
  fields
}: {
  region: Region;
  fields?: T;
}, fetchOptions?: RequestInit): Promise<CountryPicker<T>[] | null>;
//#endregion
//#region src/functions/getCountriesBySubregion.d.ts
/**
 * Fetches countries that belong to the specified subregion,
 * optionally including only the specified fields.
 *
 * > **Note:** If `fields` is not provided, all available fields will be returned.
 *
 * @param params - An object containing:
 *   - `subregion`: The subregion name (e.g., "Southern Asia", "Northern Europe") to filter countries by.
 *   - `fields`: An optional array of field names (keys from the `Country` type) to include in the response.
 *
 * @param fetchOptions - Optional `RequestInit` object to customize the `fetch` request.
 *
 * @returns A promise that resolves to an array of `CountryPicker<T>` objects with the requested fields,
 *          or `null` if the request fails or no countries match the subregion.
 *
 * @example
 * // Get countries in Northern Europe with only `name` and `population` fields
 * const nordicCountries = await getCountriesBySubregion({
 *   subregion: "Northern Europe",
 *   fields: ["name", "population"]
 * });
 *
 * @example
 * // Get all fields for countries in Southern Asia
 * const southAsianCountries = await getCountriesBySubregion({ subregion: "Southern Asia" });
 */
declare function getCountriesBySubregion<T extends readonly (keyof Country)[]>({
  subregion,
  fields
}: {
  subregion: Subregion;
  fields?: T;
}, fetchOptions?: RequestInit): Promise<CountryPicker<T>[] | null>;
//#endregion
//#region src/functions/getCountryByCapital.d.ts
/**
 * Fetches a single country by its capital city,
 * optionally including only the specified fields.
 *
 * > **Note:** If `fields` is not provided, all available fields will be returned.
 * > Returns the first matching country or `null` if none is found.
 *
 * @param params - An object containing:
 *   - `capital`: The name of the capital city to search for.
 *   - `fields`: An optional array of field names (keys from the `Country` type) to include in the response.
 *
 * @param fetchOptions - Optional `RequestInit` object to customize the `fetch` request.
 *
 * @returns A promise that resolves to a single `CountryPicker<T>` object with the requested fields,
 *          or `null` if the request fails or no country matches the capital city.
 *
 * @example
 * // Get country by capital "Paris" with only `name` and `region` fields
 * const country = await getCountryByCapital({
 *   capital: "Paris",
 *   fields: ["name", "region"]
 * });
 *
 * @example
 * // Get all fields for the country with capital "Tokyo"
 * const japan = await getCountryByCapital({ capital: "Tokyo" });
 */
declare function getCountryByCapital<T extends readonly (keyof Country)[]>({
  capital,
  fields
}: {
  capital: Capital;
  fields?: T;
}, fetchOptions?: RequestInit): Promise<CountryPicker<T> | null>;
//#endregion
//#region src/functions/getCountryByCode.d.ts
/**
 * Fetches a single country by its code (e.g., CCA2, CCA3, or CIOC),
 * optionally including only the specified fields.
 *
 * > **Note:** If `fields` is not provided, all available fields will be returned.
 * > Returns the first matching country or `null` if none is found.
 *
 * @param params - An object containing:
 *   - `code`: The country code to fetch data for. CCA3 is recommended for precision.
 *   - `fields`: An optional array of field names (keys from the `Country` type) to include in the response.
 *
 * @param fetchOptions - Optional `RequestInit` object to customize the `fetch` request.
 *
 * @returns A promise that resolves to a single `CountryPicker<T>` object with the requested fields,
 *          or `null` if the request fails or no country matches the code.
 *
 * @example
 * // Get country by CCA3 code "USA" with only `name` and `flags` fields
 * const usa = await getCountryByCode({
 *   code: "USA",
 *   fields: ["name", "flags"]
 * });
 *
 * @example
 * // Get all fields for the country with code "FRA"
 * const france = await getCountryByCode({ code: "FRA" });
 */
declare function getCountryByCode<T extends readonly (keyof Country)[]>({
  code,
  fields
}: {
  code: Code;
  fields?: T;
}, fetchOptions?: RequestInit): Promise<CountryPicker<T> | null>;
//#endregion
//#region src/functions/getCountryByDemonym.d.ts
/**
 * Fetches a single country by its demonym (the name for its residents),
 * optionally including only the specified fields.
 *
 * > **Note:** If `fields` is not provided, all available fields will be returned.
 * > Returns the first matching country or `null` if none is found.
 *
 * @param params - An object containing:
 *   - `demonym`: The demonym string to search for (e.g., "American", "French").
 *   - `fields`: An optional array of field names (keys from the `Country` type) to include in the response.
 *
 * @param fetchOptions - Optional `RequestInit` object to customize the `fetch` request.
 *
 * @returns A promise that resolves to a single `CountryPicker<T>` object with the requested fields,
 *          or `null` if the request fails or no country matches the demonym.
 *
 * @example
 * // Get country by demonym "Canadian" with only `name` and `region` fields
 * const canada = await getCountryByDemonym({
 *   demonym: "Canadian",
 *   fields: ["name", "region"]
 * });
 *
 * @example
 * // Get all fields for the country with demonym "Brazilian"
 * const brazil = await getCountryByDemonym({ demonym: "Brazilian" });
 */
declare function getCountryByDemonym<T extends readonly (keyof Country)[]>({
  demonym,
  fields
}: {
  demonym: string;
  fields?: T;
}, fetchOptions?: RequestInit): Promise<CountryPicker<T> | null>;
//#endregion
//#region src/functions/getCountryByTranslation.d.ts
/**
 * Fetches a single country by a translated country name,
 * optionally including only the specified fields.
 *
 * > **Note:** If `fields` is not provided, all available fields will be returned.
 * > Returns the first matching country or `null` if none is found.
 *
 * @param params - An object containing:
 *   - `translation`: The translated name of the country to search for.
 *   - `fields`: An optional array of field names (keys from the `Country` type) to include in the response.
 *
 * @param fetchOptions - Optional `RequestInit` object to customize the `fetch` request.
 *
 * @returns A promise that resolves to a single `CountryPicker<T>` object with the requested fields,
 *          or `null` if the request fails or no country matches the translation.
 *
 * @example
 * // Get country by translation "Alemania" (German for Germany) with only `name` and `region` fields
 * const germany = await getCountryByTranslation({
 *   translation: "Alemania",
 *   fields: ["name", "region"]
 * });
 *
 * @example
 * // Get all fields for the country with translation "Espagne" (French for Spain)
 * const spain = await getCountryByTranslation({ translation: "Espagne" });
 */
declare function getCountryByTranslation<T extends readonly (keyof Country)[]>({
  translation,
  fields
}: {
  translation: string;
  fields?: T;
}, fetchOptions?: RequestInit): Promise<CountryPicker<T> | null>;
//#endregion
//#region src/index.d.ts
declare const defineFields: <T extends (keyof Country)[]>(fields: readonly [...T]) => readonly [...T];
//#endregion
export { defineFields, getCountries, getCountriesByCodes, getCountriesByCurrency, getCountriesByLang, getCountriesByName, getCountriesByRegion, getCountriesBySubregion, getCountryByCapital, getCountryByCode, getCountryByDemonym, getCountryByTranslation };
//# sourceMappingURL=index.d.ts.map