@resk/core/build/countries/index.d.ts

An innovative TypeScript framework that empowers developers to build applications with a fully decorator-based architecture for efficient resource management. By combining the power of decorators with a resource-oriented design, DecorRes enhances code cla

import { ICurrency } from "../currency/types";
import countries from "./countries";
/****
 * @typedef ICountryCode
 * The type of the country code.
 * example: US, FR, IN
 * @see {@link CountryCode}, for more information about the CountryCode type.
 */
export type ICountryCode = keyof typeof countries;
/**
 * Interface representing a country with its associated properties.
 *
 * @extends Record<string, any>
 *
 * @example
 * ```typescript
 * const country: ICountry = {
 *   code: 'US',
 *   dialCode: '+1',
 *   phoneNumberExample: '(123) 456-7890',
 *   flag: '🇺🇸'
 * };
 * ```
 */
export interface ICountry extends Record<string, any> {
    /**
     * The unique code of the country.
     *
     * @type {ICountryCode}
     * @example 'US'
     */
    code: ICountryCode;
    /***
     * The name of the country.
     */
    name: string;
    /****
     * The currency of the country.
     */
    currency?: ICurrency;
    /**
     * The dial code of the country.
     *
     * @type {string}
     * @example '+1'
     */
    dialCode: string;
    /**
     * An example of a phone number in the country.
     *
     * @type {string}
     * @example '(123) 456-7890'
     */
    phoneNumberExample: string;
    /**
     * The flag of the country (optional).
     * This string can be a Unicode emoji, or a data URI or a URL to an image file.
     *
     * @type {string}
     * @optional
     * @example '🇺🇸'
     */
    flag?: string;
}
/**
 * Class representing a collection of countries with their associated properties.
 *
 * @example
 * ```typescript
 * CountriesManager.setCountry({
 *   code: 'US',
 *   dialCode: '+1',
 *   phoneNumberExample: '(123) 456-7890',
 *   flag: '🇺🇸'
 * });
 *
 * const usCountry = CountriesManager.getCountry('US');
 * console.log(usCountry); // { code: 'US', dialCode: '+1', phoneNumberExample: '(123) 456-7890', flag: '🇺🇸' }
 * ```
 */
export declare class CountriesManager {
    /**
     * A private static record of countries, where each key is a country code and each value is an ICountry object.
     *
     * @private
     * @type {Record<ICountryCode, ICountry>}
     */
    private static countries;
    /**
     * Checks if a given country object is valid.
     *
     * A country object is considered valid if it is an object and has a non-null string code.
     *
     * @param {ICountry} country The country object to check.
     * @returns {boolean} True if the country object is valid, false otherwise.
     *
     * @example
     * ```typescript
     * const country: ICountry = {
     *   code: 'US',
     *   dialCode: '+1',
     *   phoneNumberExample: '(123) 456-7890',
     *   flag: '🇺🇸'
     * };
     * console.log(CountriesManager.isValid(country)); // true
     * ```
     */
    static isValid(country: ICountry): boolean;
    /**
     * Gets the phone number example for a given country code.
     *
     * @param {ICountryCode} code The country code.
     * @returns {string} The phone number example for the given country code, or an empty string if the country code is not found.
     *
     * @example
     * ```typescript
     * console.log(CountriesManager.getPhoneNumberExample('US')); // '(123) 456-7890'
     * ```
     */
    static getPhoneNumberExample(code: ICountryCode): string;
    /**
     * Gets the flag for a given country code.
     *
     * @param {ICountryCode} code The country code.
     * @returns {string} The flag for the given country code, or an empty string if the country code is not found.
     *
     * @example
     * ```typescript
     * console.log(CountriesManager.getFlag('US')); // '🇺🇸'
     * ```
     */
    static getFlag(code: ICountryCode): string;
    /**
     * Gets the currency for a given country code.
     *
     * @param {ICountryCode} code The country code.
     * @returns {ICurrency | undefined} The currency for the given country code, or undefined if the country code is not found.
     *
     * @example
     * ```typescript
     * console.log(CountriesManager.getCurrency('US')); // { code: 'USD', symbol: '$' }
     * ```
     */
    static getCurrency(code: ICountryCode): ICurrency | undefined;
    /**
     * Sets a country object in the internal record.
     *
     * The country object must be valid (i.e., it must be an object with a non-null string code).
     *
     * @param {ICountry} country The country object to set.
     *
     * @example
     * ```typescript
     * CountriesManager.setCountry({
     *   code: 'US',
     *   dialCode: '+1',
     *   phoneNumberExample: '(123) 456-7890',
     *   flag: '🇺🇸'
     * });
     * ```
     */
    static setCountry(country: ICountry): void;
    /**
     * Retrieves a country object by its country code.
     *
     * If the provided code is not a non-null string, it returns undefined.
     *
     * @param {ICountryCode} code The country code to look up.
     * @returns {ICountry | undefined} The country object associated with the given code, or undefined if not found.
     *
     * @example
     * ```typescript
     * const country = CountriesManager.getCountry('US');
     * console.log(country); // { code: 'US', dialCode: '+1', phoneNumberExample: '(123) 456-7890', flag: '🇺🇸' }
     * ```
     */
    static getCountry(code: ICountryCode): ICountry | undefined;
    /**
     * Retrieves all countries stored in the internal record.
     *
     * @returns {Record<ICountryCode, ICountry>} A record of all countries, where each key is a country code and each value is an ICountry object.
     *
     * @example
     * ```typescript
     * const allCountries = CountriesManager.getCountries();
     * console.log(allCountries); // { 'US': { code: 'US', ... }, ... }
     * ```
     */
    static getCountries(): Record<ICountryCode, ICountry>;
    /**
     * Sets multiple countries in the internal record.
     *
     * This method merges the provided countries with the existing ones in the internal record.
     *
     * If the provided countries object is not an object, it returns the current internal record of countries.
     *
     * @param {Partial<Record<ICountryCode, ICountry>>} countries A partial record of countries to set.
     * @returns {Record<ICountryCode, ICountry>} The updated internal record of countries.
     *
     * @example
     * ```typescript
     * Country.setCountries({
     *   'US': {
     *     code: 'US',
     *     dialCode: '+1',
     *     phoneNumberExample: '(123) 456-7890',
     *     flag: '🇺🇸'
     *   },
     *   'CA': {
     *     code: 'CA',
     *     dialCode: '+1',
     *     phoneNumberExample: '(123) 456-7890',
     *     flag: '🇨🇦'
     *   }
     * });
     * ```
     */
    static setCountries(countries: Partial<Record<ICountryCode, ICountry>>): Record<ICountryCode, ICountry>;
}